diff --git a/changelogs-v2/2026-06/18_3960_待支付订单流程状态归入补全信息步-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3960_待支付订单流程状态归入补全信息步-修改接口-管理后台.md new file mode 100644 index 0000000..65e6f58 --- /dev/null +++ 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\） + +下表仅列出本次值语义变化的流程字段；其余字段不变。 + +| 字段名 | 类型 | 说明 | 变化 | +|---|---|---|---| +| `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） |