9a63a84f1a
进度统一为派生双层：删 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>
6.4 KiB
6.4 KiB
二期 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=已取消（前端不画进度条）
五、示例
列表（定制中、配房完成、配车进行中）
{
"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（同一订单）
"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}
]
已取消订单
{ "flowStep": null, "flowStepCode": null, "flowDisplayText": "已取消",
"flowStepStatus": null, "currentSubFlows": null }
// 详情 progressStepper 返回空数组 []
六、业务边界 / 前端注意
- 当前步两个口子都能拿：列表用
flowStep；详情用isCurrent==true的节点（和flowStep指向同一步）。 - ⚠️ 降级现状：资源准备步现只判配房——配车/领队/摄影的子状态回写链路尚未接通，所以
VEHICLE子流程恒PROCESSING、GUIDE/PHOTOGRAPHER恒WAITING，暂不会变DONE。资源准备只要配房DONE即整步完成。回写接通后会纳入 4 线全 DONE。 - ⚠️ 进度展示请用
flowStep/flowDisplayText，不要用flowStatusName——flowStatus在"定制中"阶段恒为AWAITING_PROFILE（待补全信息）不流转，用它展示进度会一直显示"待补全信息"，不准。 currentSubFlows/subFlows只在资源准备步有值，其余步为null，前端渲染需判空。