# TripDetailVO 扩出发准备清单字段 — 2026-04-20

> **服务** hl-order-service-v2（端口 8094）· **类型** feat · **关联** Issue #1024 / PR #1025
> **前端调用路径**: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094)
> **前端实际请求前缀**: `GET /mp/trip/{orderId}`（**无新接口**，扩字段）

---

## 一、能力概述

补齐原型 **ew2Kk 出发准备页的 prepSec 清单区块**。其余数据（倒计时 / 带队团队 / 行程概览 / 合同保险状态）已经在 `TripDetailVO` 中。

**⚠️ 无新接口**：扩现有 `GET /mp/trip/{orderId}` 的返回体，在 `TripDetailVO` 加一个字段 `preTripChecklist`。

| 触发条件 | 行为 |
| --- | --- |
| `tripPhase == "BEFORE_START"` | `preTripChecklist` 填充 6 项清单 |
| `tripPhase == "IN_PROGRESS"` | `preTripChecklist` 为 `null` |
| `tripPhase == "ENDED"` | `preTripChecklist` 为 `null` |

---

## 二、接口清单

**无新接口**。使用现有：

| 方法 | 路径 | 变化 |
| --- | --- | --- |
| GET | `/mp/trip/{orderId}` | 返回体新增 `preTripChecklist` 字段 |

---

## 三、新增字段结构（`PreTripChecklistVO`）

```jsonc
{
  "preTripChecklist": {
    "completedCount": 3,     // 已完成项数
    "totalCount": 6,         // 总项数
    "items": [
      {
        "key": "CONTRACT_SIGN",        // 项 key
        "title": "签署旅行合同",        // 标题
        "subtitle": "合同已准备,请尽快签署",  // 副标题
        "status": "WARNING",            // DONE / PENDING / WARNING
        "statusLabel": "紧急",
        "actionType": "NAVIGATE",       // NAVIGATE / CONFIRM / CONTACT_CS / null
        "actionPayload": {              // 前端按 actionType 解析
          "pageKey": "contract_sign",
          "orderId": "1000",
          "contractId": "9001"
        }
      },
      {
        "key": "DEPOSIT_PAID",
        "title": "订金已支付",
        "subtitle": "¥2000 已支付",
        "status": "DONE",
        "statusLabel": "已完成",
        "actionType": null,
        "actionPayload": null
      }
      // ...共 6 项
    ]
  }
}
```

---

## 四、清单 6 项 + 状态规则

| Key | 标题 | DONE 条件 | WARNING 条件 | 其他→PENDING |
| --- | --- | --- | --- | --- |
| `DEPOSIT_PAID` | 订金/全款支付 | `paidAmount >= 应付`（FULL→totalPrice / DEPOSIT→depositAmount） | — | 金额不足 |
| `TRAVELER_INFO` | 出行人完整度 | `validateTravelers.isComplete=true` | 有出行人信息缺失 | 人数不够 |
| `ARRIVAL_INFO` | 接送机信息 | arrivals 和 departures 都有 | — | 缺任一方向 |
| `CONTRACT_SIGN` | 合同签署 | contract.status=`SIGNED` | `PREPARING` / `UNSIGNED` | 无合同 |
| `INSURANCE` | 保险承保 | insurance.status=`INSURED` | `FAILED` | `PENDING` / 无保险 |
| `CHECKLIST_CONFIRMED` | 出行清单确认 | `OrderInfo.checklistConfirmed=true` | — | 未确认 |

### actionType 语义

| 值 | 前端应做 |
| --- | --- |
| `NAVIGATE` | 跳转小程序页面（按 `actionPayload.pageKey` 映射） |
| `CONFIRM` | 弹确认对话框（如"确认出行清单"） |
| `CONTACT_CS` | 打开客服会话 |
| `null` | 不可操作（DONE 状态） |

### pageKey 映射建议（前端维护）

| pageKey | 小程序路径 |
| --- | --- |
| `order_pay` | 支付页 |
| `traveler_list` | 出行人列表 |
| `arrival_form` | 到达信息表单 |
| `contract_sign` | 合同签署 |
| `checklist_confirm` | 清单确认 |

### 排序规则

后端已按 **WARNING > PENDING > DONE** 排序（紧急项靠前），前端直接渲染即可。

---

## 五、示例

### BEFORE_START 阶段完整响应（节选）

```jsonc
{
  "code": 200,
  "data": {
    "orderId": "1000",
    "tripPhase": "BEFORE_START",
    "countdownDays": 12,
    "departureDate": "2026-07-01",
    "productName": "草原环线体验",
    "guideName": "巴图",              // 带队团队
    "guidePhone": "138****5678",
    "itinerarySummary": [...],         // 行程概览
    "contracts": [...],
    "insurances": [...],
    "preTripChecklist": {              // ← 新增字段
      "completedCount": 3,
      "totalCount": 6,
      "items": [...]
    }
  }
}
```

### IN_PROGRESS 阶段响应

```jsonc
{
  "code": 200,
  "data": {
    "orderId": "1000",
    "tripPhase": "IN_PROGRESS",
    "todayDayNumber": 3,
    "todayTitle": "莫日格勒河 → 额尔古纳",
    "preTripChecklist": null          // ← 非 BEFORE_START 阶段为 null
  }
}
```

---

## 六、关联

- Issue: [wx/HL#1024](https://git.1814.love:8443/wx/HL/issues/1024)
- PR: [wx/HL#1025](https://git.1814.love:8443/wx/HL/pulls/1025)（已合并到 dev）