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`）

{
  "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 阶段完整响应（节选）

{
  "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 阶段响应

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

六、关联

Issue: wx/HL#1024
PR: wx/HL#1025（已合并到 dev）

4.6 KiB 原始文件 Blame 文件历史 Unescape Escape