# 待支付订单流程状态归入「补全信息」步骤 — 修改接口 — 管理后台

> **变更类型**：修改接口（出参字段值语义变化）
> **端类型**：管理后台
> **生效日期**：2026-06-18
> **影响接口数**：3 个（创建订单 / 订单列表 / 订单详情）

---

## 一、接口背景

撤销 PR #3923「待支付不算流程状态」的处理。

原先（#3923 之后）：待支付订单的流程进度栏显示 `0/6`、文案为空、详情步骤条全灰。
产品口径调整（#3960）：待支付订单属于流程**第 1 步「补全信息」**，因为客人还没补出行人信息，步骤条需高亮第一步，文案显示「待补全信息」。

---

## 二、变更清单

| 序号 | 端点 | 变更类型 | 影响字段 |
|---|---|---|---|
| 1 | `POST /v3/admin/order` | 出参字段值变化 | `flowStep` / `flowDisplayText` / `flowStatusName` |
| 2 | `GET /v3/admin/order/list` | 出参字段值变化 | `flowStep` / `flowDisplayText` / `flowStatusName` / `flowStepCode` |
| 3 | `GET /v3/admin/order/{id}` | 出参字段值变化 | `flowStep` / `flowDisplayText` / `flowStatusName` / `flowStepCode` / `main.flowStepStatus` / `main.progressStepper[0]` |

**只有 `orderStatus = "PENDING_PAY"`（待支付）的订单受影响，其他状态完全不变。**

---

## 三、接口详情

### 3.1 创建订单

| 项目 | 说明 |
|---|---|
| 方法 | `POST` |
| 路径 | `/v3/admin/order` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 否（每次调用创建新订单） |
| 限流 | 无特殊限流 |

### 3.2 订单列表

| 项目 | 说明 |
|---|---|
| 方法 | `GET` |
| 路径 | `/v3/admin/order/list` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 是（纯查询） |
| 限流 | 无特殊限流 |

### 3.3 订单详情

| 项目 | 说明 |
|---|---|
| 方法 | `GET` |
| 路径 | `/v3/admin/order/{id}` |
| 认证 | 需要 JWT Token（管理后台登录态） |
| 幂等性 | 是（纯查询） |
| 限流 | 无特殊限流 |

---

## 四、接口入参

### 4.1 创建订单（POST /v3/admin/order）

本次改动不涉及入参变化，入参契约与原有定义一致。

### 4.2 订单列表（GET /v3/admin/order/list）

本次改动不涉及入参变化，查询参数契约与原有定义一致。

### 4.3 订单详情（GET /v3/admin/order/{id}）

| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `id` | Path | Long（字符串传输） | 是 | 订单 ID |

---

## 五、出参字段

### 5.1 创建订单返回（OrderCreateRespVO）

下表仅列出本次值语义变化的流程字段；其余字段不变。

| 字段名 | 类型 | 说明 | 变化 |
|---|---|---|---|
| `flowStep` | Integer | 当前步号，取值 1-6，总共 6 步；不在流程中时为 `null` | 待支付时由 `0` 改为 `1` |
| `flowStepTotal` | Integer | 总步数，固定 `6` | 不变 |
| `flowDisplayText` | String | 步骤展示文案（纯中文，直接用于前端展示） | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStatusName` | String | 细状态中文名 | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStatus` | String | 流程状态英文枚举原始值 | 不变，仍为 `"AWAITING_PAY"` |

### 5.2 订单列表项返回（PageResult\<OrderListItemRespVO\>）

下表仅列出本次值语义变化的流程字段；其余字段不变。

| 字段名 | 类型 | 说明 | 变化 |
|---|---|---|---|
| `flowStep` | Integer | 当前步号，1-6 | 待支付时由 `0` 改为 `1` |
| `flowStepTotal` | Integer | 总步数，固定 `6` | 不变 |
| `flowDisplayText` | String | 步骤展示文案（纯中文） | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStatusName` | String | 细状态中文名 | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStepCode` | String | 当前步英文编码 | 待支付时由 `null` 改为 `"PROFILE"` |
| `flowStatus` | String | 流程状态英文枚举原始值 | 不变，仍为 `"AWAITING_PAY"` |
| `orderStatus` | String | 订单状态，独立维度 | 不变，仍为 `"PENDING_PAY"` |
| `orderStatusName` | String | 订单状态中文名 | 不变，仍为 `"待支付"` |

### 5.3 订单详情返回（OrderDetailRespVO — main 节点 OrderMainVO）

下表仅列出本次值语义变化的流程字段；其余字段不变。

| 字段名 | 类型 | 说明 | 变化 |
|---|---|---|---|
| `flowStep` | Integer | 当前步号，1-6 | 待支付时由 `0` 改为 `1` |
| `flowStepTotal` | Integer | 总步数，固定 `6` | 不变 |
| `flowDisplayText` | String | 步骤展示文案（纯中文） | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStatusName` | String | 细状态中文名 | 待支付时由 `null` 改为 `"待补全信息"` |
| `flowStepCode` | String | 当前步英文编码 | 待支付时由 `null` 改为 `"PROFILE"` |
| `flowStepStatus` | String | 当前步状态枚举 | 待支付时由 `null` 改为 `"PROCESSING"` |
| `flowStatus` | String | 流程状态英文枚举原始值 | 不变，仍为 `"AWAITING_PAY"` |
| `main.progressStepper[0].status` | String | 步骤条「补全信息」节点状态 | 待支付时由 `"WAITING"` 改为 `"PROCESSING"` |
| `main.progressStepper[0].isCurrent` | Boolean | 是否为当前高亮步 | 待支付时由 `false` 改为 `true` |
| `orderStatus` | String | 订单状态，独立维度 | 不变，仍为 `"PENDING_PAY"` |
| `orderStatusName` | String | 订单状态中文名 | 不变，仍为 `"待支付"` |

---

## 六、枚举 / 数据字典

### 6.1 流程 6 步固定编码（flowStepCode）

| 步号（flowStep） | 英文编码（flowStepCode） | 中文文案（flowDisplayText） |
|---|---|---|
| 1 | `PROFILE` | 待补全信息 |
| 2 | `RESOURCE` | 资源准备 |
| 3 | `CONFIRM` | 确认 |
| 4 | `DEPART` | 出行 |
| 5 | `REVIEW` | 核单 |
| 6 | `SETTLE` | 结算 |
| - | - | `null`（已取消等不在流程中的状态） |

> `flowStepTotal` 固定为 `6`，不随状态变化。

### 6.2 步骤节点状态（progressStepper[N].status）

| 值 | 说明 |
|---|---|
| `WAITING` | 未开始（灰色） |
| `PROCESSING` | 进行中 / 当前高亮步 |
| `DONE` | 已完成 |

### 6.3 当前步状态（flowStepStatus）

| 值 | 说明 |
|---|---|
| `PROCESSING` | 当前步进行中 |
| `DONE` | 当前步已完成 |
| `null` | 不在流程中（如已取消） |

---

## 七、错误码

本次改动不引入新错误码，原有错误码契约不变。

---

## 八、示例

### 8.1 典型成功 — 待支付订单列表项（orderStatus = PENDING_PAY）

请求：
```
GET /v3/admin/order/list?orderStatus=PENDING_PAY&pageNo=1&pageSize=10
```

响应（仅展示流程相关字段）：
```json
{
  "code": 200,
  "data": {
    "total": 1,
    "list": [
      {
        "id": "1234567890123456789",
        "orderStatus": "PENDING_PAY",
        "orderStatusName": "待支付",
        "flowStatus": "AWAITING_PAY",
        "flowStatusName": "待补全信息",
        "flowStep": 1,
        "flowStepTotal": 6,
        "flowDisplayText": "待补全信息",
        "flowStepCode": "PROFILE"
      }
    ]
  }
}
```

前端展示建议：步骤进度条可渲染为 `1/6 · 待补全信息`。

### 8.2 边界情况 — 已取消订单（不受本次影响）

响应（流程相关字段）：
```json
{
  "orderStatus": "CANCELLED",
  "orderStatusName": "已取消",
  "flowStatus": null,
  "flowStatusName": null,
  "flowStep": null,
  "flowStepTotal": 6,
  "flowDisplayText": "已取消",
  "flowStepCode": null
}
```

> 已取消订单 `flowStep` 为 `null`，步骤条无需高亮任何步骤。

### 8.3 对比参照 — 付款后定制中订单（不受本次影响）

响应（流程相关字段）：
```json
{
  "orderStatus": "PAID",
  "orderStatusName": "已支付",
  "flowStatus": "CUSTOMIZING",
  "flowStatusName": "资源准备",
  "flowStep": 2,
  "flowStepTotal": 6,
  "flowDisplayText": "资源准备",
  "flowStepCode": "RESOURCE"
}
```

---

## 九、业务边界

**适用**：
- `orderStatus = "PENDING_PAY"`（待支付）的订单，流程步号归入第 1 步「补全信息」。

**不适用**：
- 其他任何 `orderStatus` 值的订单，流程字段完全不受本次变更影响。

**特殊边界**：
- `orderStatus` 和 `flowStatus` 是两个独立维度。本次只改变了 `flowStatus = AWAITING_PAY` 对应的步号与中文名，不影响 `orderStatus = PENDING_PAY` 本身的含义与文案。
- 前端如需同时展示「订单状态」和「流程步骤」两个维度，应分别取 `orderStatusName`（待支付）和 `flowDisplayText`（待补全信息），两者语义不同，不可混用。

---

## 十、修改前后对比

### 10.1 字段级对比（仅 orderStatus = PENDING_PAY 时）

| 字段 | 改前（#3923） | 改后（#3960） | 出现于 |
|---|---|---|---|
| `flowStep` | `0` | `1` | 列表 / 详情 / 创单 |
| `flowDisplayText` | `null` | `"待补全信息"` | 列表 / 详情 / 创单 |
| `flowStatusName` | `null` | `"待补全信息"` | 列表 / 详情 / 创单 |
| `flowStepCode` | `null` | `"PROFILE"` | 列表 / 详情 |
| `main.flowStepStatus` | `null` | `"PROCESSING"` | 仅详情 |
| `main.progressStepper[0].status` | `"WAITING"` | `"PROCESSING"` | 仅详情 |
| `main.progressStepper[0].isCurrent` | `false` | `true` | 仅详情 |

### 10.2 行为级对比

| 场景 | 改前 | 改后 |
|---|---|---|
| 订单列表流程进度栏（待支付订单） | 显示 `0/6`，文案空白 | 显示 `1/6`，文案「待补全信息」 |
| 订单详情步骤条第一步（补全信息）（待支付） | 灰色（WAITING），不高亮 | 高亮（PROCESSING），标记为当前步 |
| 其他状态订单 | 不变 | 不变 |

---

## 十一、影响评估 / 回滚

**是否破坏兼容**：
- 字段名未变，类型未变，仅字段**值**变化（`0` → `1`，`null` → 非 null 字符串）。
- 如前端代码中有 `if (flowStep === 0)` 或 `if (flowDisplayText === null)` 的特判逻辑，需检查并修正。

**前端同步上线要求**：
- 本次为出参值修正，后端已上线，前端无需改动即可展示正确数据（字段名保持不变）。
- 若前端此前已针对 `flowStep = 0` 做过特殊兜底处理，建议清理相关 workaround 逻辑。

**回滚方案**：
- 若需回滚，后端回退到 #3923 版本即可，前端无需操作。

---

## 十二、注意事项

> **前端绑定约定**：流程状态**显示的文字直接绑后端返回的 `flowDisplayText` / `flowStatusName`**（这俩就是中文），**逻辑判断 / 步骤高亮 / 样式 / 埋点用 `flowStep` / `flowStepCode` / `flowStatus`（英文枚举+步号）**。**禁止前端拿英文枚举自己硬编码中文**（如 `if flowStatus === 'AWAITING_PAY' return '待补全信息'`）——文案以后端为唯一来源，避免管理后台 / 小程序两端文案漂移。

---

## 十三、关联 / 联系人

| 项目 | 链接 / 信息 |
|---|---|
| Issue | https://git.1814.love:8443/wx/HL/issues/3960 |
| PR | https://git.1814.love:8443/wx/HL/pulls/3961 |
| commit | https://git.1814.love:8443/wx/HL/commit/db976ed80 |
| 后端负责人 | 腰苏图（yaosutu） |