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