changelog(mp): 微信小程序 · 行程 Tab 路由决策接口 tab-state

GET /mp/trip/tab-state

一次返回前端应渲染哪个 Tab 页(IN_PROGRESS/BEFORE_START/RETURNING/NEW)
+ orderId + summary。替代之前 3 次接口决策。

对应原型:ew2Kk 行程前 / sGONt 行程中 / wwWKT 回头客 / eYDt9 空态。
PENDING_PAY 订单不计入 Tab 判定。

PR #1116 (Closes #1115)

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

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<MpTripTabStateVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| 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;订单表变化时依赖式失效