hl-api-changelog/changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md

【修改接口·管理后台】⚠️ currentSubFlows 子流程状态字段重构：删 label + 新增 statusName/displayText (#3983)

PR: #3989 + #3998 + #4024 | 服务: hl-order-service-v3 | 更新时间: 2026-06-19 ⚠️ 含字段删除（label）+ 字段新增（statusName / displayText）。前端若在用 currentSubFlows.label 必须切换；展示推荐直接用 displayText。

1. 接口背景

订单列表/详情「资源准备」节点下的 currentSubFlows（配房/配车/领队/摄影子流程）原先状态展示有问题：control_status 主表是残缺镜像，子流程状态卡在「待配」不动、label 大量返 null、且配车「处理中」错显「配房中」。

本次治理：① 配房/配车状态升级为完整状态机单源；② 删除旧 label，新增 statusName（纯状态中文）+ displayText（name+状态的完整通顺文案）。前端展示直接用 displayText（如「配房已打回」），无需自己拼接。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	订单列表	GET	/v3/admin/order（兼容 /v3/admin/order/list）	出参字段删除+新增	currentSubFlows[] 删 label、加 statusName + displayText
2	订单详情	GET	/v3/admin/order/{id}	出参字段删除+新增	currentSubFlows[] 删 label、加 statusName + displayText

currentSubFlows 仅在订单处于「资源准备」节点时有值（其余节点为 null），是该节点下的子流程数组。

3. 接口详情

3.1 订单列表

• 使用场景：订单列表页渲染每条订单的资源准备子流程进度。
• 认证：JWT（管理员）。幂等：是（只读）。

入参无变化。出参 PageResult<OrderListItemRespVO>，其中 currentSubFlows[] 每个元素删 label、加 statusName+displayText。

3.2 订单详情

• 使用场景：订单详情页资源准备节点的子流程进度展示。
• 认证：JWT（管理员）。幂等：是（只读）。

入参无变化。出参详情 VO 的 currentSubFlows[] 每个元素删 label、加 statusName+displayText（与列表一致）。

4. 接口入参

接口	字段	类型	必填	说明
GET /v3/admin/order	（原列表查询参数，本次无变化）	-	-	-
GET /v3/admin/order/{id}	id	String（Long）	是	路径参数，订单 ID

两个接口入参均无变化。

5. 出参（响应）

5.1 SubFlowVO（currentSubFlows[] 元素）改后字段

字段	类型	变更	说明
code	String	不变	子流程编码：HOTEL / VEHICLE / GUIDE / PHOTOGRAPHER
name	String	不变	子流程对象名：配房 / 配车 / 领队 / 摄影
status	String	不变	三态机器值：WAITING / PROCESSING / DONE（供逻辑判断）
label	String	删除	旧展示文案字段，已删
statusName	String	新增	纯状态中文（不含房/车），见 §6
displayText	String	新增	完整展示文案 = name + statusName，如「配房已打回」，前端直接显示这个

展示直接用 displayText；需拆分时用 name（对象）+ statusName（纯状态）+ status（机器值）。

6. 枚举 / 数据字典

6.1 配房 HOTEL / 配车 VEHICLE（由 room/vehicle_control_status 派生，全 6 态）

statusName 为纯状态、房车一致；displayText = name + statusName：

后端状态	statusName	displayText（配房）	displayText（配车）	含义
待提交需求	待提交需求	配房待提交需求	配车待提交需求	需求还没提交
待审核	待审核	配房待审核	配车待审核	仅团期：定制师已提、管理员未审核
待配	待配	配房待配	配车待配	已进抢单池，房务/车务未接单
处理中	处理中	配房处理中	配车处理中	房务/车务已接单处理中
已打回	已打回	配房已打回	配车已打回	被打回需重新处理（原因见「记录」Tab）
已完成	已完成	配房已完成	配车已完成	资源配置完成

6.2 领队 GUIDE / 摄影 PHOTOGRAPHER（由 guide/photographer_status 派生，两态）

后端状态	statusName	displayText（领队）	displayText（摄影）
未配（null）	待指派	领队待指派	摄影待指派
已完成（DONE）	已完成	领队已完成	摄影已完成

statusName / displayText 均不返回 null（全态都有文案）。打回原因不在本字段，前端去订单「记录」Tab 时间线查看（带时间/操作人）。

7. 错误码

纯出参字段调整，无新增错误码。

code	含义
581201	订单不存在（详情接口 id 无效）
401 / 403	未认证 / 无权限

8. 示例（3 组）

8.1 典型 — 资源准备中（配房处理中、配车待配）

{
  "code": 200,
  "data": {
    "currentSubFlows": [
      { "code": "HOTEL",   "name": "配房", "status": "PROCESSING", "statusName": "处理中", "displayText": "配房处理中" },
      { "code": "VEHICLE", "name": "配车", "status": "WAITING",    "statusName": "待配",   "displayText": "配车待配" }
    ]
  },
  "success": true
}

8.2 边界 — 配房被打回 + 领队待指派

{
  "code": 200,
  "data": {
    "currentSubFlows": [
      { "code": "HOTEL", "name": "配房", "status": "WAITING", "statusName": "已打回", "displayText": "配房已打回" },
      { "code": "GUIDE", "name": "领队", "status": "WAITING", "statusName": "待指派", "displayText": "领队待指派" }
    ]
  },
  "success": true
}

8.3 边界 — 订单不在资源准备节点（currentSubFlows 为 null）

{ "code": 200, "data": { "currentSubFlows": null }, "success": true }

9. 业务边界

• currentSubFlows 仅订单处于「资源准备」节点时有值，其余节点 null。
• 子流程按需求标志过滤：needsHotel/needsVehicle/needsGuide/needsPhotographer 为 true 才出现对应子流程。
• 「待审核」态仅团期订单出现（核心订单无审核环节）。
• 「已打回」只表达状态，具体退回原因在订单「记录」Tab 时间线（不在本接口返回）。

10. 修改前后对比

字段	改前	改后
label	存在，文案不准（配车「处理中」错显「配房中」、待提交态 null）	删除
statusName	无	新增，纯状态中文（待配/处理中…，房车一致）
displayText	无	新增，完整文案（配房已打回/配车处理中），前端直显
status	WAITING/PROCESSING/DONE	保留不变
状态准确性	卡「待配」不动、抢单/打回不反映	抢单→处理中、打回→已打回，实时准确

11. 影响评估 / 回滚

• 破坏向后兼容：部分——删除了 label。前端若读 currentSubFlows[].label 需改读 displayText（或 statusName）。status 保留。
• 前端必须同步：是（若在用 label）。改读 displayText 即可。
• 回滚：revert PR #4024 + #3998 + #3989 并重新部署 hl-order-service-v3。

12. 注意事项

• 前端展示子流程状态直接用 displayText（中文完整文案，开箱即用），不要再依赖 label（已删）。
• 需要按对象/状态分别处理时用 name + statusName；需要机器判断分支用 status。
• 打回原因展示：去订单「记录」Tab 时间线，不在 currentSubFlows。

13. 关联 / 联系人

13.1 链接

• Issue: #3983（单源化）、#3997（字段精简）、#4023（displayText + statusName 纯状态）
• PR: #3989、#3998、#4024

13.2 联系人

• 后端负责人: @yaosutu