新增 changelog：待支付订单流程状态归入补全信息步（管理后台，PR #3961，Issue #3960）

2026-06-18 10:58:37 +08:00 · 2026-06-18 10:58:37 +08:00 · 05fa996c27
--- a/changelogs-v2/2026-06/18_3960_待支付订单流程状态归入补全信息步-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/18_3960_待支付订单流程状态归入补全信息步-修改接口-管理后台.md
@ -0,0 +1,308 @@
+# 待支付订单流程状态归入「补全信息」步骤 — 修改接口 — 管理后台
+
+> **变更类型**：修改接口（出参字段值语义变化）
+> **端类型**：管理后台
+> **生效日期**：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） |