229561624b
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>
160 行
3.8 KiB
Markdown
160 行
3.8 KiB
Markdown
# 微信小程序 · 行程 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;订单表变化时依赖式失效
|