changelog(mp): 订单/行程 5 个聚合接口调用时机梳理 — tab-state 路由决策 + dashboard/pre-trip/today/travel-memory 契约对照

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changelogs/2026-04/2026-04-23_mp-dashboard-endpoints-timing-guide.md

@@ -0,0 +1,172 @@
+# mp-service: 订单/行程 5 个聚合接口调用时机梳理
+
+> **服务**: hl-mp-service（端口 8085）→ 透传 hl-order-service-v2（端口 8094）
+> **PR**: -（纯契约梳理，无代码变更）
+> **Issue**: -
+> **日期**: 2026-04-23
+> **影响范围**: C 端「订单详情页」+「行程 Tab」的 5 个聚合接口
+
+---
+
+## ⚠️ 关键变化
+
+**无接口变更**。本 changelog 是对现有 5 个聚合接口的调用时机/契约关系做一次性梳理，方便前端对照接入。调用顺序、入参、返回 VO 均未调整。
+
+---
+
+## 一、接口清单
+
+| # | 接口 | 方法 | 路径 | 返回 VO | 缓存 TTL |
+|---|------|------|------|---------|----------|
+| 1 | 订单详情页聚合 | GET | `/mp/order/{orderId}/dashboard` | `MpOrderDashboardVO` | 30s |
+| 2 | 行程 Tab 路由决策 | GET | `/mp/trip/tab-state` | `MpTripTabStateVO` | 15s |
+| 3 | 行程前·出发准备页聚合 | GET | `/mp/trip/{orderId}/pre-trip-dashboard` | `MpPreTripDashboardVO` | 30s |
+| 4 | 行程中·今日页聚合 | GET | `/mp/trip/today-dashboard` | `MpTodayDashboardVO` | 15s |
+| 5 | 旅行回忆列表 | GET | `/mp/order/travel-memory` | `PageResult<MpTravelMemoryVO>` | 60s |
+
+所有接口均需登录，`userId` 由 mp-service 从 token 取出后透传给 order-v2。
+
+---
+
+## 二、两条独立入口
+
+### 入口 A：订单详情页（#1）
+
+来源：我的订单列表点击、支付成功跳转、消息/通知链接。拿到 `orderId` 后直接调 `#1`，与行程 Tab 无关。
+
+### 入口 B：行程 Tab（#2 → #3/#4/#5）
+
+用户切到行程 Tab 时**必须先调 `#2 /mp/trip/tab-state`**，后端根据当前订单情况返回 `state` + `orderId`，前端按 `state` 分支调对应接口。
+
+| `state` | 含义 | 下一步接口 | 是否需要前端传 orderId |
+|---------|------|-----------|------------------------|
+| `NEW` | 从未下过单 | 无（空态） | - |
+| `BEFORE_START` | 有订单未出发 | `#3 /mp/trip/{orderId}/pre-trip-dashboard` | ✅ 用 #2 返回的 orderId |
+| `IN_PROGRESS` | 行程进行中 | `#4 /mp/trip/today-dashboard` | ❌ 后端从 userId 反查 |
+| `RETURNING` | 已完成过行程 | `#5 /mp/order/travel-memory` | ❌ 分页拉列表 |
+
+未支付订单（`PENDING_PAY`）不计入 `tab-state` 判定。
+
+---
+
+## 三、接口定位与返回核心字段
+
+### 1. `GET /mp/order/{orderId}/dashboard` — 订单管理视角
+
+**场景**：用户查看某张订单的履约与售后信息。
+
+**返回**：`MpOrderDashboardVO`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `order` | `MpOrderDetailVO` | 订单主体，含 `serviceItems`（服务包含列表）|
+| `preTripChecklist` | `MpPreTripChecklistVO` | 出发准备清单（顶部待办徽章用；服务降级时 null）|
+| `files` | `FilesVO` | 合同摘要 + 发票摘要 + 保单 PDF 路径 |
+| `insurance` | `MpInsuranceDetailVO` | 保险详情（未投保时 null）|
+| `refund` | `RefundVO` | 退款详情+进度（仅 CANCELLED/REFUNDING/REFUNDED/REFUND_REJECTED/APPEALING 状态有值，其余 null）|
+
+内部并行调 6 个 Feign：order（主，失败 500）+ contract + invoice + insurance + refund-detail + refund-progress。contract/invoice/insurance 失败降级 null。
+
+> **服务包含列表**位置：`MpOrderDashboardVO.order.serviceItems`（`List<MpServiceItemVO>`）
+> 每项字段：`type`（HOTEL/MEAL/VEHICLE/GUIDE/PHOTOGRAPHER/TICKET/INSURANCE）、`title`、`summary`、`hasDetail`（运行态，是否有子详情页可看）
+
+---
+
+### 2. `GET /mp/trip/tab-state` — 行程 Tab 路由决策
+
+**场景**：用户切到行程 Tab 时的第一个调用。
+
+**返回**：`MpTripTabStateVO`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `state` | String | `IN_PROGRESS` / `BEFORE_START` / `RETURNING` / `NEW` |
+| `stateLabel` | String | 状态中文标签 |
+| `orderId` | Long | IN_PROGRESS / BEFORE_START 时有值 |
+| `summary` | `Summary` | 产品名/档位/出发日期/距出发天数 等 |
+
+---
+
+### 3. `GET /mp/trip/{orderId}/pre-trip-dashboard` — 行程前·出发准备
+
+**场景**：`tab-state` 返回 `BEFORE_START` 时调用，订单已确认尚未出发。
+
+**返回**：`MpPreTripDashboardVO`，包含订单头 / 出发准备清单 / 带队团队（领队+摄影师）/ 行程概览 / 客服电话。
+
+内部并行调 3 个 Feign：trip + guide + photographer。guide/photographer 失败降级为 null，不影响主清单。
+
+---
+
+### 4. `GET /mp/trip/today-dashboard` — 行程中·今日页
+
+**场景**：`tab-state` 返回 `IN_PROGRESS` 时调用，用户正在行程中。
+
+**返回**：`MpTodayDashboardVO`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `today` | `MpTodayVO` | 今日行程主体（无行程中订单时 null）|
+| `leader` | `MpGuideInfoVO` | 联系领队卡 |
+| `sosContact` | `SosContactVO` | SOS：领队电话 + 客服电话 + 保险客服电话 |
+| `weather` | `List<MpWeatherDayVO>` | 今日 + 未来 N 天天气（失败降级 null）|
+| `todayProgressPercent` | Integer | 今日进度 0-100（已游览景点 / 总景点）|
+| `dayNav` | `List<MpTripDayNavVO>` | DAY 导航，每天标记 DONE/CURRENT/PENDING |
+| `todayTimeline` | `MpTodayTimelineVO` | 按当前时间切成 completed/current/next 三段 |
+| `todayHotel` | `MpTripHotelArrangementVO` | 今晚住宿（含是否与昨晚换酒店标记）|
+| `tomorrow` | `MpTomorrowPreviewVO` | 明日预告（路线摘要+出发时间）|
+
+**入参仅 userId**（无 orderId），后端自己从 userId 反查进行中订单。无行程中订单时接口正常返回，核心字段全部 null/空列表。
+
+内部并行调 guide + weather，两者失败都降级为 null。
+
+---
+
+### 5. `GET /mp/order/travel-memory` — 回头客态
+
+**场景**：`tab-state` 返回 `RETURNING` 时调用。
+
+**返回**：`PageResult<MpTravelMemoryVO>` — 已完成（COMPLETED）订单分页列表，按出发日倒序。含 `reviewed` / `rating` / `reviewId`（评价服务降级时评分字段为 null）。
+
+---
+
+## 四、契约约束（正确调用方式）
+
+### ✅ 行程 Tab 入口
+
+| 场景 | 正确调用序列 |
+|------|--------------|
+| 用户切行程 Tab | **先 `#2`** → 按 state 分支调 `#3` / `#4` / `#5` 之一 |
+| state=BEFORE_START | `#2` 返回的 `orderId` 传给 `#3` |
+| state=IN_PROGRESS | `#4` 不传 orderId，token 中的 userId 足够 |
+| state=RETURNING | 调 `#5` 拉分页 |
+| state=NEW | 不再调任何接口 |
+
+### ❌ 错误调用
+
+- 切行程 Tab 直接调 `#3` / `#4`（跳过 `#2`）—— 不要自行根据订单状态/时间判断该渲染哪页
+- 并行调 `#3` 和 `#4` —— 同一时刻用户只可能在其中一个状态
+- `#3` 用自己缓存的 orderId —— 必须用 `#2` 本次返回的 orderId（订单可能已切换）
+
+### ✅ 订单详情入口（#1）独立
+
+从任何订单链接进入都直接调 `#1`，不依赖 `#2`，也不影响行程 Tab 的调用。
+
+---
+
+## 五、不影响范围
+
+- `#1 /mp/order/{orderId}/dashboard` 与 `#3 /mp/trip/{orderId}/pre-trip-dashboard` 字段独立，**不要互相替代**
+  - `#1` 关注：合同 / 发票 / 保单 / 保险 / 退款（订单管理视角）
+  - `#3` 关注：准备清单 / 领队+摄影师 / 行程概览（出行准备视角）
+- `#3 pre-trip-dashboard` 与 `#4 today-dashboard` 返回 VO 完全不同，**不要通用一套渲染**
+- 登录态统一从网关 token 解析，所有接口无需前端额外传 `userId`
+
+---
+
+## 六、相关文档
+
+- `MpOrderController.java`、`MpTripController.java`（hl-mp-service）
+- VO：`MpOrderDashboardVO` / `MpTripTabStateVO` / `MpPreTripDashboardVO` / `MpTodayDashboardVO` / `MpTravelMemoryVO`
+- 关联历史 changelog：
+  - `2026-04-22_mp-order-detail-service-items-has-detail.md`（#1234 hasDetail 字段）
+  - `2026-04-23_mp-pre-trip-checklist-split-arrival-departure.md`（#1289 清单拆 ARRIVAL/DEPARTURE）