docs(order-v3): 订单进度模型重构 changelog（派生 6 步 + 嵌套 progressStepper，管理后台）

进度统一为派生双层：删 flowItems/progress；flowStep 改线性 6 步、flowStepTotal 8→6； progressStepper 扁平 9 节点 → 嵌套 6 主节点(code/isCurrent/subFlows，删 parallel)；列表加 flowStepCode/flowStepStatus/currentSubFlows。含降级说明(资源准备只判配房)。 Issue #3365 #3368 / PR #3366 #3369 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-03 09:27:19 +08:00 · 2026-06-03 09:27:19 +08:00 · 9a63a84f1a
--- a/changelogs-v2/2026-06/03_3365-3368_订单进度模型重构-修改接口-管理后台.md
+++ 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\<SubFlow\> | **仅当前步=资源准备时非空**，否则 `null` |
+
+### 详情 `GET /v3/admin/order/{id}`（`data.main`）
+
+列表那 6 个散字段**全有**，外加完整 `progressStepper`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `progressStepper` | Array\<Node\> | 完整 6 主节点（嵌套） |
+
+**Node 结构**：`step`(Integer) / `code`(String) / `name`(String) / `status`(String) / `isCurrent`(Boolean) / `subFlows`(Array\<SubFlow\>，仅资源准备非空)
+**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