diff --git a/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md b/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md new file mode 100644 index 0000000..2f13c85 --- /dev/null +++ b/changelogs/2026-04/2026-04-21_mp-trip-tab-state.md @@ -0,0 +1,159 @@ +# 微信小程序 · 行程 Tab 路由决策接口 + +**日期**:2026-04-21 +**影响**:**微信小程序** 行程 Tab 首屏(对应原型 `ew2Kk` 行程前 / `sGONt` 行程中 / `wwWKT` 回头客 / `eYDt9` 未下单空态) +**PR**:#1116(Closes #1115) + +--- + +## 概述 + +切到"行程" Tab 时一次调用获取应渲染的页面状态,返回 `state + orderId + summary`,替代之前依次调 today-dashboard + upcoming + travel-memory 3 个接口才能决策的流程。 + +--- + +## 接口 + +``` +GET /mp/trip/tab-state +``` + +**鉴权**:Bearer token。 + +### 入参 + +无(userId 由后端从 token 取)。 + +### 出参 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| state | String | `IN_PROGRESS` / `BEFORE_START` / `RETURNING` / `NEW` | +| stateLabel | String | 中文:行程中 / 行程前 / 回头客 / 新客 | +| orderId | Long | IN_PROGRESS 或 BEFORE_START 时有值;其他为 null | +| summary | Summary | IN_PROGRESS 或 BEFORE_START 时有值;其他为 null | + +**`Summary`**: +| 字段 | 类型 | 说明 | +|---|---|---| +| productName | String | 产品名 | +| productSubtitle | String | 产品副标题 | +| tierName | String | 档位名称(未选档时 null)| +| departureDate | LocalDate | 出发日期 | +| daysToDeparture | Integer | 距出发天数(BEFORE_START 有值)| +| currentDayNumber | Integer | 当前第几天(IN_PROGRESS 有值)| +| tripDays | Integer | 行程天数 | + +--- + +## state 判定规则 + +按优先级从高到低判定,命中即返回: + +| 优先级 | state | 条件 | +|---|---|---| +| 1 | `IN_PROGRESS` | `status = TRAVELLING` | +| 2 | `BEFORE_START` | `status ∈ {DEPOSIT_PAID, PAID, CONFIRMED, PENDING_BALANCE, PENDING_DEPARTURE}` **且** `departure_date >= today` | +| 3 | `RETURNING` | 有 `status = COMPLETED` 订单 | +| 4 | `NEW` | 其他 | + +### 重要规则 + +- **`PENDING_PAY`(未支付)订单不计入 Tab 判定**。未支付订单由订单列表入口完成支付,不影响行程 Tab 的状态。 +- `CANCELLED` / `REFUNDING` / `REFUNDED` 不计入 Tab 判定。 +- 多订单时按优先级返回:同时有 COMPLETED + 未出发订单 → 返回 BEFORE_START(不是 RETURNING)。 + +--- + +## 响应示例 + +### 行程中 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "state": "IN_PROGRESS", + "stateLabel": "行程中", + "orderId": "2046501070522228737", + "summary": { + "productName": "草原环线", + "productSubtitle": "6天5晚舒适套餐", + "tierName": "舒适档", + "departureDate": "2026-07-01", + "daysToDeparture": null, + "currentDayNumber": 2, + "tripDays": 6 + } + }, + "success": true +} +``` + +### 行程前 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "state": "BEFORE_START", + "stateLabel": "行程前", + "orderId": "2046501070522228737", + "summary": { + "productName": "草原环线", + "productSubtitle": "6天5晚舒适套餐", + "tierName": "舒适档", + "departureDate": "2026-07-01", + "daysToDeparture": 12, + "currentDayNumber": null, + "tripDays": 6 + } + }, + "success": true +} +``` + +### 回头客 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "state": "RETURNING", + "stateLabel": "回头客", + "orderId": null, + "summary": null + }, + "success": true +} +``` + +### 新客(无任何有效订单) + +```json +{ + "code": 200, + "message": "成功", + "data": { + "state": "NEW", + "stateLabel": "新客", + "orderId": null, + "summary": null + }, + "success": true +} +``` + +--- + +## 边界行为 + +- **未登录**:401(网关拦截) +- **只有 PENDING_PAY 订单**:返回 `NEW`(未支付不计入) +- **只有 CANCELLED/REFUNDING/REFUNDED**:返回 `NEW` +- **多账号混合态**:优先级 IN_PROGRESS > BEFORE_START > RETURNING > NEW +- **服务降级**(Feign 失败):返回 `state=NEW`,接口不 500 +- **缓存**:15 秒短 TTL;订单表变化时依赖式失效