wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs/2026-04/2026-04-23_mp-dashboard-endpoints-timing-guide.md
yaosutu bc43b65dc1 changelog(mp): 订单/行程 5 个聚合接口调用时机梳理 — tab-state 路由决策 + dashboard/pre-trip/today/travel-memory 契约对照 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 16:45:27 +08:00

7.7 KiB
原始文件 Blame 文件历史

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）