# 待支付订单流程状态文案返空（与步骤条对齐）— 修改接口 — 管理后台

> 变更类型：🔧 接口行为变更（出参字段值规则调整）
> 端类型：管理后台
> 日期：2026-06-17
> 服务：hl-order-service-v3
> PR：https://git.1814.love:8443/wx/HL/pulls/3926

---

## 1. 接口背景

**功能页面**：管理后台「订单列表」页 + 「订单详情」页。

**用在哪**：
- **订单列表**：每一行订单卡片上显示「业务流程状态」的文字标签（如"资源准备""待出行"等）。
- **订单详情**：详情 main 区域顶部的「当前步文案」（与步骤条联动显示，前端通常拼为"2/6 · 资源准备"格式）。

**修复了什么问题**：待支付订单（`orderStatus=PENDING_PAY`）的流程状态文案之前返回"待支付"，但详情步骤条（`progressStepper`）在待支付时 `flowStep=0`、6 个节点全为 `WAITING`（步骤条未点亮）。两者语义冲突——流程尚未开始，不应在流程状态位置显示文案。

**修复后**：待支付时 `flowStatusName`、`flowDisplayText` 均返 `null`，与步骤条未点亮保持一致。"待支付"由 `orderStatus`/`orderStatusName` 字段表达，语义不丢。

---

## 2. 变更清单

| 接口 | 字段 | 变更前 | 变更后 | 影响范围 |
|---|---|---|---|---|
| `GET /v3/admin/order`（列表） | `flowStatusName` | `"待支付"`（当 PENDING_PAY 时） | `null` | 订单列表行流程状态标签 |
| `GET /v3/admin/order`（列表） | `flowDisplayText` | `"待支付"`（当 PENDING_PAY 时） | `null` | 订单列表行当前步文案 |
| `GET /v3/admin/order/{id}`（详情 main） | `flowStatusName` | `"待支付"`（当 PENDING_PAY 时） | `null` | 详情页流程状态名 |
| `GET /v3/admin/order/{id}`（详情 main） | `flowDisplayText` | `"待支付"`（当 PENDING_PAY 时） | `null` | 详情页当前步文案 |

**其他字段不变**：`flowStep` 仍为 `0`，`flowStatus` 仍为 `"AWAITING_PAY"`，`progressStepper` 仍为 6 节点全 `WAITING`，`orderStatusName` 仍为 `"待支付"`。

---

## 3. 接口详情

### 3.1 订单列表

- **方法 + 路径**：`GET /v3/admin/order`（别名 `GET /v3/admin/order/list`）
- **认证**：需要 JWT（管理后台登录 token，Gateway 注入 `X-Admin-Id`）
- **幂等性**：查询接口，天然幂等
- **限流**：无独立限流规则

### 3.2 订单详情

- **方法 + 路径**：`GET /v3/admin/order/{id}`
- **认证**：需要 JWT（同上）
- **幂等性**：查询接口，天然幂等
- **限流**：无独立限流规则

---

## 4. 接口入参

### 4.1 订单列表 Query 参数（与本次变更无关，无入参改动）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `orderStatus` | String | 否 | 粗状态过滤 |
| `keyword` | String | 否 | 关键字模糊搜索 |
| `departureDateFrom` | LocalDate | 否 | 出发日期起始 |
| `departureDateTo` | LocalDate | 否 | 出发日期结束 |
| `createSource` | String | 否 | 订单来源 |
| `consultantName` | String | 否 | 定制师姓名 |
| `page` | Integer | 否 | 页码，默认 1 |
| `pageSize` | Integer | 否 | 每页条数，默认 10 |

### 4.2 订单详情路径参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | Long | 是 | 订单 ID（雪花 ID 字符串） |

---

## 5. 出参字段（受本次影响的关键字段）

### 5.1 订单列表 OrderListItemRespVO（变更字段）

| 字段 | 类型 | 说明 | 本次变化 |
|---|---|---|---|
| `orderStatus` | String | 粗状态枚举值，如 `PENDING_PAY` | **不变** |
| `orderStatusName` | String | 粗状态中文名，如 `"待支付"` | **不变**，仍返"待支付" |
| `flowStatus` | String | 细状态枚举值，如 `AWAITING_PAY` | **不变** |
| `flowStatusName` | String | 细状态中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` |
| `flowStep` | Integer | 线性 6 步当前步序号（0=待支付未开始） | **不变**，仍为 `0` |
| `flowStepTotal` | Integer | 总步数，固定 `6` | **不变** |
| `flowDisplayText` | String | 当前步中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` |

### 5.2 订单详情 OrderMainVO（变更字段）

| 字段 | 类型 | 说明 | 本次变化 |
|---|---|---|---|
| `orderStatus` | String | 粗状态枚举值 | **不变** |
| `orderStatusName` | String | 粗状态中文名 | **不变**，仍返"待支付" |
| `flowStatusName` | String | 细状态中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` |
| `flowStep` | Integer | 当前步序号 | **不变**，仍为 `0` |
| `flowDisplayText` | String | 步骤展示文案 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` |
| `progressStepper` | List | 6 节点步骤条 | **不变**，仍为 6 节点全 `WAITING` |

---

## 6. 枚举 / 数据字典

### 订单粗状态 orderStatus

| 值 | 中文名 |
|---|---|
| `PENDING_PAY` | 待支付 |
| `CUSTOMIZING` | 定制中 |
| `PENDING_DEPARTURE` | 待出行 |
| `TRAVELLING` | 出行中 |
| `COMPLETED` | 已完成 |
| `CANCELLED` | 已取消 |

### 订单细状态 flowStatus（PENDING_PAY 对应值）

| 值 | 中文名（本次改动前） | 中文名（本次改动后） |
|---|---|---|
| `AWAITING_PAY` | 待支付 | `null`（不算流程状态） |

---

## 7. 错误码

本次为出参字段值规则调整，无新增错误码。通用错误码：

| code | 含义 |
|---|---|
| `200` | 成功 |
| `401` | 未登录 / token 过期 |
| `404` | 订单不存在（详情接口） |

---

## 8. 示例

### 8.1 典型成功——待支付订单列表项

```json
GET /v3/admin/order?orderStatus=PENDING_PAY&page=1&pageSize=1

{
  "code": 200,
  "data": {
    "total": 33,
    "list": [
      {
        "id": "1234567890001",
        "orderNo": "HL20260617143025001",
        "orderStatus": "PENDING_PAY",
        "orderStatusName": "待支付",
        "flowStatus": "AWAITING_PAY",
        "flowStatusName": null,
        "flowStep": 0,
        "flowStepTotal": 6,
        "flowDisplayText": null,
        "currentSubFlows": null,
        "productName": "长白山天池3日深度游",
        "customerName": "张三",
        "departureDate": "2026-07-01"
      }
    ]
  }
}
```

### 8.2 边界——其他状态订单（flowStatusName 有值，不受影响）

```json
GET /v3/admin/order?orderStatus=CUSTOMIZING&page=1&pageSize=1

{
  "code": 200,
  "data": {
    "list": [
      {
        "orderStatus": "CUSTOMIZING",
        "orderStatusName": "定制中",
        "flowStatus": "RESOURCE_PREPARING",
        "flowStatusName": "资源准备",
        "flowStep": 1,
        "flowDisplayText": "资源准备"
      }
    ]
  }
}
```

### 8.3 业务失败——订单不存在（详情接口）

```json
GET /v3/admin/order/9999999999999

{
  "code": 404,
  "msg": "订单不存在"
}
```

---

## 9. 业务边界

**适用**：
- 仅影响 `orderStatus=PENDING_PAY` 的订单（即刚创单、尚未完成订金支付的订单）。

**不适用**：
- `CUSTOMIZING`、`PENDING_DEPARTURE`、`TRAVELLING`、`COMPLETED` 状态的订单，`flowStatusName`/`flowDisplayText` 仍正常有值，不受影响。
- `CANCELLED` 状态的订单，`flowDisplayText` 仍为 `"已取消"`，不受影响。

**特殊边界**：
- 前端若之前对 `flowDisplayText=null` 有防空处理，本次直接兼容，无需额外改动。
- 若前端之前硬判 `flowDisplayText === "待支付"` 来识别待支付状态，需改为读 `orderStatus === "PENDING_PAY"` 或 `orderStatusName`。

---

## 10. 修改前后对比

### 字段级对比（仅 PENDING_PAY 状态）

| 字段 | 修改前 | 修改后 |
|---|---|---|
| `flowStatusName`（列表 + 详情） | `"待支付"` | `null` |
| `flowDisplayText`（列表 + 详情） | `"待支付"` | `null` |
| `orderStatusName`（列表 + 详情） | `"待支付"` | `"待支付"`（不变） |
| `flowStep` | `0` | `0`（不变） |
| `progressStepper` | 6 节点全 WAITING | 6 节点全 WAITING（不变） |

### 行为级对比

| 场景 | 修改前 | 修改后 |
|---|---|---|
| 列表行「流程状态」标签 | 显示"待支付"（来自 flowStatusName） | 为 null，前端显示为空或不展示该标签 |
| 详情当前步文案 | "待支付" | null，前端步骤条未点亮，文案区域为空或不展示 |
| "待支付"文字入口 | 同时出现在 orderStatusName 和 flowStatusName | 仅由 orderStatusName 表达，语义唯一 |

---

## 11. 影响评估 / 回滚

**破坏兼容性**：⚠️ 是——`flowStatusName`/`flowDisplayText` 在 PENDING_PAY 时从字符串变为 `null`，前端需要做好 null 防空。

**前端需同步操作**：
1. **订单列表**：渲染「流程状态标签」时判断 `flowStatusName !== null` 再显示；`null` 时不显示标签（或显示空）。
2. **订单详情**：渲染「当前步文案」时判断 `flowDisplayText !== null` 再拼"X/6 · xxx"格式；`null` 时步骤条未点亮、文案区域留空。
3. **若有 `flowDisplayText === "待支付"` 的硬判逻辑**，改为 `orderStatus === "PENDING_PAY"` 判断。

**回滚方案**：后端回退 PR #3926 即可恢复为旧行为（`null` 改回 `"待支付"`）。后端回滚后前端无需改动。

---

## 12. 注意事项

- `flowStatus` 字段本身仍为 `"AWAITING_PAY"`（原始枚举值保留），只是 `flowStatusName`（中文名映射）返 `null`。
- 步骤条 `progressStepper` 6 节点全 `WAITING` 行为不变，本次只影响文案字段。
- 已取消订单（`CANCELLED`）的 `flowDisplayText` 仍为 `"已取消"`，本次不涉及。

---

## 13. 关联 / 联系人

- Issue：https://git.1814.love:8443/wx/HL/issues/3923
- PR：https://git.1814.love:8443/wx/HL/pulls/3926
- Commit：https://git.1814.love:8443/wx/HL/commit/6f0648a28a17daafc4e6ebafdd36fb8c7a3b8e6b
- 后端负责人：腰苏图