diff --git a/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md b/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md new file mode 100644 index 0000000..c431c72 --- /dev/null +++ b/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md @@ -0,0 +1,155 @@ +# 二期 v3:订单进度模型重构 —— 派生线性 6 步 + 嵌套 progressStepper + +> **服务**: hl-order-service-v3 | **端**: 管理后台 +> **接口**: `GET /v3/admin/order`(列表)、`GET /v3/admin/order/{id}`(详情)、`POST /v3/admin/order`(创建) +> **Issue**: #3365 / #3368 | **PR**: #3366(扁平)+ #3369(嵌套) +> **日期**: 2026-06-03 +> **影响**: ⚠️ **破坏性**——删字段 + 改结构。订单进度展示统一为「派生线性 6 步 + 嵌套 progressStepper」。 + +--- + +## 一、背景 + +订单进度此前两套打架:列表用 8 步 `flowStep`,详情用 10 节点 `progressStepper`,同一订单两页进度刻度对不上。本次统一为**派生双层模型**(底层一份数据派生两视图),并修正了核单/结算判定 bug。 + +--- + +## 二、变更清单 + +| 变更 | 说明 | +|---|---| +| ❌ 删 `flowItems` | 列表不再返回 | +| ❌ 删 `progress`("X/8") | 列表不再返回 | +| 🔄 `flowStep` 语义改 | 8 步指针 → **线性 6 步**当前步序号 | +| 🔄 `flowStepTotal` | 8 → **6** | +| 🆕 `flowStepCode` | 当前步英文枚举(列表+详情) | +| 🆕 `flowStepStatus` | 当前步状态(列表+详情) | +| 🆕 `currentSubFlows`(列表) | 当前步=资源准备时的 4 子流程数组 | +| 🔄 `progressStepper`(详情) | 扁平 9 节点 → **嵌套 6 主节点**,加 `code`/`isCurrent`/`subFlows`,删 `parallel` | + +> `orderStatus`/`orderStatusName`/`flowStatus`/`flowStatusName` **不变**。 + +--- + +## 三、出参字段(进度部分) + +### 列表 `GET /v3/admin/order`(`data.records[]`,当前步散字段) + +| 字段 | 类型 | 说明 | +|---|---|---| +| `flowStep` | Integer | 当前第几步(1-6;待支付=0;已取消=null) | +| `flowStepTotal` | Integer | 总步数,固定 **6** | +| `flowStepCode` | String | 当前步英文枚举(见枚举表) | +| `flowDisplayText` | String | 当前步中文名 | +| `flowStepStatus` | String | 当前步状态:`DONE`/`PROCESSING`/`WAITING` | +| `currentSubFlows` | Array\ | **仅当前步=资源准备时非空**,否则 `null` | + +### 详情 `GET /v3/admin/order/{id}`(`data.main`) + +列表那 6 个散字段**全有**,外加完整 `progressStepper`: + +| 字段 | 类型 | 说明 | +|---|---|---| +| `progressStepper` | Array\ | 完整 6 主节点(嵌套) | + +**Node 结构**:`step`(Integer) / `code`(String) / `name`(String) / `status`(String) / `isCurrent`(Boolean) / `subFlows`(Array\,仅资源准备非空) +**SubFlow 结构**:`code`(String) / `name`(String) / `status`(String) / `label`(String) + +--- + +## 四、枚举 / 数据字典 + +### 主步 `code`(6 步) + +| code | name | 完成判定 | +|---|---|---| +| `PROFILE` | 补全信息 | 已支付 | +| `RESOURCE` | 资源准备 | 配房完成(降级,见业务边界) | +| `CONFIRM` | 确认 | 订单已确认 | +| `DEPART` | 出行 | 已出行 | +| `REVIEW` | 核单 | 已核单 | +| `SETTLE` | 结算 | 已结算 | + +### 子流程 `code`(资源准备下,4 条) + +| code | name | +|---|---| +| `HOTEL` | 配房 | +| `VEHICLE` | 配车 | +| `GUIDE` | 领队 | +| `PHOTOGRAPHER` | 摄影 | + +### `status`(主步 + 子流程通用) + +| status | 含义 | +|---|---| +| `DONE` | 已完成 | +| `PROCESSING` | 处理中 | +| `WAITING` | 待开始 | + +### `flowStep` 序号 + +`0`=待支付(步骤条未开始)|`1-6`=对应主步|`null`=已取消(前端不画进度条) + +--- + +## 五、示例 + +### 列表(定制中、配房完成、配车进行中) + +```jsonc +{ + "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中", + "flowStep": 2, "flowStepTotal": 6, + "flowStepCode": "RESOURCE", "flowDisplayText": "资源准备", "flowStepStatus": "PROCESSING", + "currentSubFlows": [ + {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"}, + {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"}, + {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"}, + {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"} + ] +} +``` + +### 详情 progressStepper(同一订单) + +```jsonc +"progressStepper": [ + {"step":1,"code":"PROFILE","name":"补全信息","status":"DONE","isCurrent":false,"subFlows":null}, + {"step":2,"code":"RESOURCE","name":"资源准备","status":"PROCESSING","isCurrent":true,"subFlows":[ + {"code":"HOTEL","name":"配房","status":"DONE","label":"已完成"}, + {"code":"VEHICLE","name":"配车","status":"PROCESSING","label":"处理中"}, + {"code":"GUIDE","name":"领队","status":"WAITING","label":"待开始"}, + {"code":"PHOTOGRAPHER","name":"摄影","status":"WAITING","label":"待开始"} + ]}, + {"step":3,"code":"CONFIRM","name":"确认","status":"WAITING","isCurrent":false,"subFlows":null}, + {"step":4,"code":"DEPART","name":"出行","status":"WAITING","isCurrent":false,"subFlows":null}, + {"step":5,"code":"REVIEW","name":"核单","status":"WAITING","isCurrent":false,"subFlows":null}, + {"step":6,"code":"SETTLE","name":"结算","status":"WAITING","isCurrent":false,"subFlows":null} +] +``` + +### 已取消订单 + +```jsonc +{ "flowStep": null, "flowStepCode": null, "flowDisplayText": "已取消", + "flowStepStatus": null, "currentSubFlows": null } +// 详情 progressStepper 返回空数组 [] +``` + +--- + +## 六、业务边界 / 前端注意 + +1. **当前步两个口子都能拿**:列表用 `flowStep`;详情用 `isCurrent==true` 的节点(和 `flowStep` 指向同一步)。 +2. **⚠️ 降级现状**:资源准备步现**只判配房**——配车/领队/摄影的子状态回写链路尚未接通,所以 `VEHICLE` 子流程恒 `PROCESSING`、`GUIDE`/`PHOTOGRAPHER` 恒 `WAITING`,暂不会变 `DONE`。资源准备只要配房 `DONE` 即整步完成。回写接通后会纳入 4 线全 DONE。 +3. **⚠️ 进度展示请用 `flowStep`/`flowDisplayText`,不要用 `flowStatusName`**——`flowStatus` 在"定制中"阶段恒为 `AWAITING_PROFILE`(待补全信息)不流转,用它展示进度会一直显示"待补全信息",不准。 +4. `currentSubFlows`/`subFlows` 只在资源准备步有值,其余步为 `null`,前端渲染需判空。 + +--- + +## 七、关联 + +- **Issue**: [#3365](https://git.1814.love:8443/wx/HL/issues/3365)、[#3368](https://git.1814.love:8443/wx/HL/issues/3368) +- **PR**: [#3366](https://git.1814.love:8443/wx/HL/pulls/3366)(派生 6 步 + 修 reviewStatus bug)、[#3369](https://git.1814.love:8443/wx/HL/pulls/3369)(嵌套 progressStepper) +- **设计文档**: ORDER-STATE-MACHINE V1.1 §2.2、API-SPEC v5.56