changelog(mp): 微信小程序 · 行程前出发准备页 + 订单详情页聚合接口 V1+V3

- 新接口 GET /mp/trip/{orderId}/pre-trip-dashboard (V1) - 新接口 GET /mp/order/{orderId}/dashboard (V3) - PR #1074/#1087/#1090/#1078/#1096 合集交付 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 16:18:52 +08:00 · 2026-04-21 16:18:52 +08:00 · f4f767863d
--- a/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md
+++ b/changelogs/2026-04/2026-04-21_mp-dashboard-v1-v3.md
@ -0,0 +1,330 @@
+# 微信小程序 · 行程前出发准备页 + 订单详情页 聚合接口
+
+**日期**:2026-04-21
+**影响**:**微信小程序** 行程 Tab(行程前态)与订单详情页(5 态)
+**PR**:#1074 · #1087 · #1090(V1) / #1078 · #1096(V3)
+**Issue**:#1073 · #1086 · #1089(V1) / #1076 · #1095(V3)
+
+---
+
+## 概述
+
+新增两个页面级聚合接口,一次拉全该页所需全部数据,替代前端分别调用 3~6 个细粒度接口的方案:
+
+| 接口 | 对应页面 |
+|---|---|
+| V1 `GET /mp/trip/{orderId}/pre-trip-dashboard` | 行程前·出发准备(订单已确认、未出发) |
+| V3 `GET /mp/order/{orderId}/dashboard` | 订单详情页(待付款/行程中/已完成/已取消/退款中 5 态) |
+
+> V2 `GET /mp/trip/today-dashboard`(行程中页)另外交付,本文档只覆盖 V1 + V3。
+
+---
+
+## V1. 行程前出发准备页聚合
+
+### 接口
+
+```
+GET /mp/trip/{orderId}/pre-trip-dashboard
+```
+
+**鉴权**:需要 Bearer token(登录小程序用户)。
+
+### 入参
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| orderId | Path | Long | ✅ | 订单 ID |
+
+### 出参 `Result<MpPreTripDashboardVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| orderHeader | OrderHeader | 订单头(倒计时卡片) |
+| preTripChecklist | MpPreTripChecklistVO | 出发准备清单 |
+| team | TeamVO | 带队团队 |
+| tripOverview | `List<DayItem>` | 行程概览(每天一行) |
+| customerServicePhone | String | 客服电话,如 `0470-8871922` |
+
+**`OrderHeader`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| orderId | Long | 订单ID |
+| orderNo | String | 订单编号 |
+| productName | String | 产品名称 |
+| productSubtitle | String | 产品副标题 |
+| tierName | String | 档位名称,如 `舒适档`(未选档为 null) |
+| tierDescription | String | 档位描述 |
+| productCoverUrl | String | 产品封面 URL |
+| departureDate | LocalDate | 出发日期 |
+| tripDays | Integer | 行程天数 |
+| tripNights | Integer | 行程晚数 |
+| dateRange | String | 日期范围文字,如 `2026年7月1日 — 7月6日` |
+| daysToDeparture | Integer | 距出发天数 |
+| totalPeople | Integer | 总人数 |
+| adultCount | Integer | 成人数 |
+| childCount | Integer | 儿童数 |
+| tripPhase | String | `BEFORE_START` / `IN_PROGRESS` / `ENDED` |
+
+**`MpPreTripChecklistVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| totalCount | Integer | 总项数 |
+| completedCount | Integer | 已完成项数 |
+| items | `List<MpChecklistItemVO>` | 清单项,按 WARNING > PENDING > DONE 排序 |
+
+**`MpChecklistItemVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| key | String | `DEPOSIT_PAID` / `TRAVELER_INFO` / `ARRIVAL_INFO` / `CONTRACT_SIGN` / `INSURANCE` / `CHECKLIST_CONFIRMED` |
+| title | String | 标题 |
+| subtitle | String | 副标题说明 |
+| status | String | `DONE` / `PENDING` / `WARNING` |
+| statusLabel | String | 状态中文标签 |
+| actionType | String | `NAVIGATE` / `CONFIRM` / `CONTACT_CS`;null 表示纯展示 |
+| actionPayload | `Map<String, Object>` | 动作参数载荷,如 `{pageKey: "arrival_form", orderId: "..."}` |
+
+**`TeamVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| leader | MpGuideInfoVO | 领队(未分配为 null) |
+| photographer | MpPhotographerInfoVO | 摄影师(未分配为 null) |
+| driver | MpVehicleDetailVO | 司机(原型暂不展示,保持 null) |
+
+`MpGuideInfoVO` / `MpPhotographerInfoVO` 字段:`staffId / name / avatarUrl / role / roleLabel / phone(脱敏) / remark / assigned`
+
+**`DayItem`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| dayNumber | Integer | 第几天 |
+| date | LocalDate | 当天日期 |
+| title | String | 当天标题 |
+
+### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderHeader": {
+      "orderId": 20439,
+      "orderNo": "HL20260701123",
+      "productName": "草原环线",
+      "productSubtitle": "6天5晚舒适套餐",
+      "tierName": "舒适档",
+      "tierDescription": "升级双早+SPA",
+      "productCoverUrl": "https://cdn.1814.love/cover.png",
+      "departureDate": "2026-07-01",
+      "tripDays": 6,
+      "tripNights": 5,
+      "dateRange": "2026年7月1日 — 7月6日",
+      "daysToDeparture": 12,
+      "totalPeople": 2,
+      "adultCount": 2,
+      "childCount": 0,
+      "tripPhase": "BEFORE_START"
+    },
+    "preTripChecklist": {
+      "totalCount": 6,
+      "completedCount": 3,
+      "items": [
+        {"key":"DEPOSIT_PAID","title":"订金已支付","status":"DONE","statusLabel":"已完成"},
+        {"key":"ARRIVAL_INFO","title":"填写接送机信息","subtitle":"司机将根据此信息接送","status":"PENDING","statusLabel":"待处理","actionType":"NAVIGATE","actionPayload":{"pageKey":"arrival_form","orderId":"20439"}}
+      ]
+    },
+    "team": {
+      "leader": {"name":"巴图","roleLabel":"领队","phone":"138****5678","remark":"10年呼伦贝尔带队经验","assigned":true},
+      "photographer": {"name":"李维","roleLabel":"摄影师","phone":"139****1234","assigned":true},
+      "driver": null
+    },
+    "tripOverview": [
+      {"dayNumber":1,"date":"2026-07-01","title":"海拉尔集合·接机入住"},
+      {"dayNumber":2,"date":"2026-07-02","title":"呼籁营地 → 莫日格勒河 → 额尔古纳"}
+    ],
+    "customerServicePhone": "0470-8871922"
+  },
+  "success": true
+}
+```
+
+### 边界行为
+
+- `team.leader / photographer / driver` 任意一个字段可能为 null(未分配)
+- `orderHeader.tierName / tierDescription` 未选档或下单时未绑定档位则为 null
+- 订单不存在或无权限访问:HTTP 500,`message` 含 `orderId` 和错误原因
+- `guide / photographer` 底层接口失败:对应字段置 null,主数据仍返回(降级)
+
+---
+
+## V3. 订单详情页聚合
+
+### 接口
+
+```
+GET /mp/order/{orderId}/dashboard
+```
+
+**鉴权**:需要 Bearer token。
+
+### 入参
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| orderId | Path | Long | ✅ | 订单 ID |
+
+### 出参 `Result<MpOrderDashboardVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| order | MpOrderDetailVO | 订单主体,字段同 `GET /mp/order/{orderId}` 返回值 |
+| files | FilesVO | 重要文件三合一 |
+| insurance | MpInsuranceDetailVO | 保险详情(未投保为 null) |
+| refund | RefundVO | 退款模块(非退款状态为 null) |
+
+`order` 为完整的订单详情,常用字段:`orderId / orderNo / status / statusLabel / productName / productSubtitle / tierSeq / tierName / tierDescription / productCoverUrl / tripDays / totalPrice / paidAmount / depositAmount / paymentType / travelers / supplies / equipmentAdvice` 等。完整字段以 `GET /mp/order/{orderId}` 为准。
+
+**`FilesVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| contract | MpContractSummaryVO | 合同(无合同为 null) |
+| invoice | MpInvoiceSummaryVO | 发票(未开票为 null) |
+| insurancePolicyPdfUrl | String | 保单 PDF 下载路径,如 `/mp/insurance/policy-pdf/20439` |
+
+**`MpContractSummaryVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| contractId | Long | 合同ID |
+| contractNo | String | 合同编号 |
+| status | String | `PREPARING` / `UNSIGNED` / `SIGNED` / `VOID` 等 |
+| statusLabel | String | 状态中文 |
+| contractType | String | `TOUR` / `INSURANCE` |
+| signedAt | LocalDateTime | 签署时间 |
+| downloadUrl | String | 合同 PDF 下载链接 |
+
+**`MpInvoiceSummaryVO`**:
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| invoiceId | Long | 发票ID |
+| invoiceNo | String | 发票号 |
+| status | String | `PENDING` / `ISSUED` / `FAILED` 等 |
+| statusLabel | String | 状态中文 |
+| titleType | String | `PERSONAL` / `COMPANY` |
+| invoiceTitle | String | 发票抬头 |
+| taxNumber | String | 税号 |
+| amount | BigDecimal | 金额 |
+| email | String | 接收邮箱 |
+| issuedAt | LocalDateTime | 开票时间 |
+| pdfUrl | String | 电子发票 PDF URL |
+
+**`MpInsuranceDetailVO`**:字段见 `GET /mp/order/{orderId}/insurance`。含 `schemeId / schemeName / description / isOverseas / totalDays / notice / segments[] / policies[]`。
+
+**`RefundVO`**(只在订单状态为 `CANCELLED` / `REFUNDING` / `REFUNDED` / `REFUND_REJECTED` / `APPEALING` 时有值,否则整个字段为 null):
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| detail | MpRefundDetailVO | 退款申请详情 |
+| progress | MpRefundProgressVO | 退款进度时间线 |
+
+`MpRefundDetailVO` 字段见 `GET /mp/order/{orderId}/refund-detail`。
+`MpRefundProgressVO` 字段:`steps[] / currentStep / refundAmount / refundMethod / refundArrivalTime`。
+
+### 响应示例
+
+**已确认订单(无退款)**:
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "order": {
+      "orderId": 20439,
+      "status": "CONFIRMED",
+      "statusLabel": "已确认",
+      "productName": "草原环线",
+      "productSubtitle": "6天5晚舒适套餐",
+      "tierName": "舒适档",
+      "tierDescription": "升级双早+SPA",
+      "totalPrice": 5800.00,
+      "travelers": [],
+      "supplies": []
+    },
+    "files": {
+      "contract": {"contractId":8001,"contractNo":"HL-2026-070128","status":"SIGNED","statusLabel":"已签署","contractType":"TOUR","downloadUrl":"https://cdn.1814.love/contract-8001.pdf"},
+      "invoice": null,
+      "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439"
+    },
+    "insurance": {
+      "schemeName": "旅行意外险",
+      "policies": [{"policyNo":"PA20260628****5512","status":"INSURED","statusLabel":"已承保"}]
+    },
+    "refund": null
+  },
+  "success": true
+}
+```
+
+**已取消订单(含退款进度)**:
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "order": {"orderId":20439,"status":"CANCELLED","statusLabel":"已取消"},
+    "files": {
+      "contract": null,
+      "invoice": null,
+      "insurancePolicyPdfUrl": "/mp/insurance/policy-pdf/20439"
+    },
+    "insurance": null,
+    "refund": {
+      "detail": {
+        "applicationId": 6001,
+        "status": "REFUNDING",
+        "statusLabel": "退款中",
+        "actualAmount": 1000.00,
+        "refundType": "DEPOSIT",
+        "refundTypeLabel": "订金退款"
+      },
+      "progress": {
+        "currentStep": 2,
+        "refundAmount": 1000.00,
+        "refundMethod": "原路返回·微信",
+        "steps": [
+          {"title":"提交退款申请","status":"COMPLETED","time":"2026-04-15 10:30:00"},
+          {"title":"商家审核","status":"ACTIVE","time":"2026-04-16 09:10:00"},
+          {"title":"退款处理","status":"PENDING","time":null},
+          {"title":"退款到账","status":"PENDING","time":null}
+        ]
+      }
+    }
+  },
+  "success": true
+}
+```
+
+### 边界行为
+
+- 订单不存在或无权限:HTTP 500,`message` 含 `orderId`
+- `contract / invoice / insurance` 底层接口失败:对应字段置 null,不影响订单主体
+- 非退款状态订单:`refund = null`(不调用退款相关底层接口)
+- 退款状态订单两个退款接口都返 null 时:`refund = null`(不返回 `{detail:null, progress:null}` 的壳子)
+
+---
+
+## 单测
+
+| 测试类 | 覆盖用例 | 结果 |
+|---|---|---|
+| `PreTripDashboardAggregationServiceTest` | 正常路径 + guide 降级 + photographer 降级 + trip 错误码 + trip 空数据 + itinerarySummary 缺失 | 6/6 通过 |
+| `OrderDashboardAggregationServiceTest` | 非退款状态 + 已取消状态(refund 填充) + 退款中但退款接口返 null + contract 降级 + invoice errorCode + order 错误码 / 空数据 / 异常 | 8/8 通过 |
+
+---
+
+## 规范注记
+
+- 返回字段除 `MpChecklistItemVO.actionPayload`(任意 key 跳转载荷)外,**全部强类型 VO**,无 `Map<String, Object>`
+- 所有 VO 用 `@JsonIgnoreProperties(ignoreUnknown = true)`,后端字段扩展不会影响前端反序列化
+- 短 TTL 缓存:V1 30 秒 / V3 30 秒