wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(changelog): 子流程加 displayText 完整文案 + statusName 改纯状态 (#4023)

浏览代码 
更新 currentSubFlows changelog：statusName 改纯状态(待配/处理中,房车一致)，
新增 displayText=name+状态完整文案(配房已打回/配车处理中)；明确前端展示直接用 displayText。
这个提交包含在：
yaosutu 2026-06-19 09:50:10 +08:00
父节点 9f1b885bfa
当前提交 321154e5b1
共有 1 个文件被更改，包括 48 次插入 和 50 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

98
changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md
查看文件

@ -1,22 +1,20 @@
# 【修改接口·管理后台】⚠️ currentSubFlows 子流程状态字段重构：删 label + 新增全态 statusName (#3983) # 【修改接口·管理后台】⚠️ currentSubFlows 子流程状态字段重构：删 label + 新增 statusName/displayText (#3983)
> **PR**: #3989 + #3998 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18 > **PR**: #3989 + #3998 + #4024 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-19
> ⚠️ 含**字段删除**（label）+ 字段新增（statusName），前端若在用 currentSubFlows.label 必须切换到 statusName。 > ⚠️ 含**字段删除**（label）+ 字段新增（statusName / displayText）。前端若在用 currentSubFlows.label 必须切换；**展示推荐直接用 `displayText`**。
## 1. 接口背景 ## 1. 接口背景
订单列表/详情「资源准备」节点下的 `currentSubFlows`（配房/配车/领队/摄影子流程）原先状态展示有两个问题： 订单列表/详情「资源准备」节点下的 `currentSubFlows`（配房/配车/领队/摄影子流程）原先状态展示有问题：`control_status` 主表是残缺镜像，子流程状态卡在「待配」不动、`label` 大量返 null、且配车「处理中」错显「配房中」。
1. `control_status` 主表是残缺镜像，子流程状态卡在「待配」不动、`label` 大量返 null（抢单进「处理中」、打回「已打回」从未回写主表）；
2. `label` 字段不准——配车「处理中」错显「配房中」、不分房车、「待提交需求」态返 null。
本次把配房/配车状态升级为完整状态机单源，并用一个准确的全态字段 `statusName` 取代旧的 `label`。**删除 `label`**，新增 `statusName`，前端统一显示 `statusName`。 本次治理：① 配房/配车状态升级为完整状态机单源；② 删除旧 `label`，新增 `statusName`（纯状态中文）+ `displayText`（name+状态的完整通顺文案）。**前端展示直接用 `displayText`**（如「配房已打回」），无需自己拼接。
## 2. 变更清单 ## 2. 变更清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | | # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------| |---|------|------|------|----------|------|
| 1 | 订单列表 | GET | /v3/admin/order（兼容 /v3/admin/order/list） | 出参字段删除+新增 | currentSubFlows[] 元素**删 label**、**加 statusName** | | 1 | 订单列表 | GET | /v3/admin/order（兼容 /v3/admin/order/list） | 出参字段删除+新增 | currentSubFlows[] **删 label**、**加 statusName + displayText** |
| 2 | 订单详情 | GET | /v3/admin/order/{id} | 出参字段删除+新增 | currentSubFlows[] 元素**删 label**、**加 statusName** | | 2 | 订单详情 | GET | /v3/admin/order/{id} | 出参字段删除+新增 | currentSubFlows[] **删 label**、**加 statusName + displayText** |
> currentSubFlows 仅在订单处于「资源准备」节点时有值（其余节点为 null），是该节点下的子流程数组。 > currentSubFlows 仅在订单处于「资源准备」节点时有值（其余节点为 null），是该节点下的子流程数组。
@ -26,13 +24,13 @@
- **使用场景**：订单列表页渲染每条订单的资源准备子流程进度。 - **使用场景**：订单列表页渲染每条订单的资源准备子流程进度。
- **认证**：JWT（管理员）。**幂等**：是（只读）。 - **认证**：JWT（管理员）。**幂等**：是（只读）。
入参无变化。出参 `PageResult<OrderListItemRespVO>`，其中 `currentSubFlows[]` 每个元素删除 `label`、新增 `statusName`。 入参无变化。出参 `PageResult<OrderListItemRespVO>`，其中 `currentSubFlows[]` 每个元素删 `label`、加 `statusName`+`displayText`。
### 3.2 订单详情 ### 3.2 订单详情
- **使用场景**：订单详情页资源准备节点的子流程进度展示。 - **使用场景**：订单详情页资源准备节点的子流程进度展示。
- **认证**：JWT（管理员）。**幂等**：是（只读）。 - **认证**：JWT（管理员）。**幂等**：是（只读）。
入参无变化。出参详情 VO 的 `currentSubFlows[]` 每个元素删除 `label`、新增 `statusName`。 入参无变化。出参详情 VO 的 `currentSubFlows[]` 每个元素删 `label`、加 `statusName`+`displayText`（与列表一致）。
## 4. 接口入参 ## 4. 接口入参
@ -50,38 +48,37 @@
| 字段 | 类型 | 变更 | 说明 | | 字段 | 类型 | 变更 | 说明 |
|------|------|------|------| |------|------|------|------|
| code | String | 不变 | 子流程编码：HOTEL / VEHICLE / GUIDE / PHOTOGRAPHER | | code | String | 不变 | 子流程编码：HOTEL / VEHICLE / GUIDE / PHOTOGRAPHER |
| name | String | 不变 | 子流程名：配房 / 配车 / 领队 / 摄影 | | name | String | 不变 | 子流程对象名：配房 / 配车 / 领队 / 摄影 |
| status | String | 不变 | 三态机器值：WAITING / PROCESSING / DONE（供逻辑判断用）| | status | String | 不变 | 三态机器值：WAITING / PROCESSING / DONE（供逻辑判断）|
| ~~label~~ | ~~String~~ | **删除** | 旧展示文案字段，已删，改用 statusName | | ~~label~~ | ~~String~~ | **删除** | 旧展示文案字段，已删 |
| statusName | String | **新增** | 全态中文展示文案，前端直接显示，见 §6 | | statusName | String | **新增** | 纯状态中文（不含房/车），见 §6 |
| displayText | String | **新增** | 完整展示文案 = name + statusName，如「配房已打回」，**前端直接显示这个** |
> 前端展示子流程状态请直接用 `statusName`；`status` 三态保留供需要机器判断的场景使用。 > 展示直接用 `displayText`；需拆分时用 `name`（对象）+ `statusName`（纯状态）+ `status`（机器值）。
## 6. 枚举 / 数据字典 ## 6. 枚举 / 数据字典
### 6.1 statusName（配房 HOTEL / 配车 VEHICLE） ### 6.1 配房 HOTEL / 配车 VEHICLE（由 room/vehicle_control_status 派生，全 6 态）
由主表 `room_control_status` / `vehicle_control_status` 派生，全 6 态： statusName 为**纯状态、房车一致**；displayText = name + statusName：
| 后端状态 | statusName（配房）| statusName（配车）| 含义 | | 后端状态 | statusName | displayText（配房）| displayText（配车）| 含义 |
|---|---|---|---|---|
| 待提交需求 | 待提交需求 | 配房待提交需求 | 配车待提交需求 | 需求还没提交 |
| 待审核 | 待审核 | 配房待审核 | 配车待审核 | 仅团期：定制师已提、管理员未审核 |
| 待配 | 待配 | 配房待配 | 配车待配 | 已进抢单池，房务/车务未接单 |
| 处理中 | 处理中 | 配房处理中 | 配车处理中 | 房务/车务已接单处理中 |
| 已打回 | 已打回 | 配房已打回 | 配车已打回 | 被打回需重新处理（原因见「记录」Tab）|
| 已完成 | 已完成 | 配房已完成 | 配车已完成 | 资源配置完成 |
### 6.2 领队 GUIDE / 摄影 PHOTOGRAPHER（由 guide/photographer_status 派生，两态）
| 后端状态 | statusName | displayText（领队）| displayText（摄影）|
|---|---|---|---| |---|---|---|---|
| 待提交需求 | 待提交需求 | 待提交需求 | 需求还没提交（needs=true 未发起）| | 未配（null）| 待指派 | 领队待指派 | 摄影待指派 |
| 待审核 | 待审核 | 待审核 | 仅团期：定制师已提、团期管理员未审核 | | 已完成（DONE）| 已完成 | 领队已完成 | 摄影已完成 |
| 待配 | 待配房 | 待配车 | 已进抢单池，房务/车务未接单 |
| 处理中 | 配房中 | 配车中 | 房务/车务已接单处理中 |
| 已打回 | 已打回 | 已打回 | 被打回需重新处理（打回原因见订单「记录」Tab 时间线）|
| 已完成 | 已完成 | 已完成 | 资源配置完成 |
### 6.2 statusName（领队 GUIDE / 摄影 PHOTOGRAPHER） > statusName / displayText 均不返回 null（全态都有文案）。打回原因不在本字段，前端去订单「记录」Tab 时间线查看（带时间/操作人）。
由 `guide_status` / `photographer_status` 派生，两态：
| 后端状态 | statusName | 含义 |
|---|---|---|
| 未配（null）| 待指派 | 尚未指派领队/摄影 |
| 已完成（DONE）| 已完成 | 已指派完成 |
> `statusName` 不返回 null（全态都有文案）。打回原因不在本字段，前端去订单「记录」Tab 时间线查看（带时间/操作人）。
## 7. 错误码 ## 7. 错误码
@ -94,15 +91,15 @@
## 8. 示例（3 组） ## 8. 示例（3 组）
### 8.1 典型 — 资源准备中订单（配房处理中、配车待配） ### 8.1 典型 — 资源准备中（配房处理中、配车待配）
```json ```json
{ {
"code": 200, "code": 200,
"data": { "data": {
"currentSubFlows": [ "currentSubFlows": [
{ "code": "HOTEL", "name": "配房", "status": "PROCESSING", "statusName": "配房中" }, { "code": "HOTEL", "name": "配房", "status": "PROCESSING", "statusName": "处理中", "displayText": "配房处理中" },
{ "code": "VEHICLE", "name": "配车", "status": "PROCESSING", "statusName": "待配车" } { "code": "VEHICLE", "name": "配车", "status": "WAITING", "statusName": "待配", "displayText": "配车待配" }
] ]
}, },
"success": true "success": true
@ -116,8 +113,8 @@
"code": 200, "code": 200,
"data": { "data": {
"currentSubFlows": [ "currentSubFlows": [
{ "code": "HOTEL", "name": "配房", "status": "WAITING", "statusName": "已打回" }, { "code": "HOTEL", "name": "配房", "status": "WAITING", "statusName": "已打回", "displayText": "配房已打回" },
{ "code": "GUIDE", "name": "领队", "status": "WAITING", "statusName": "待指派" } { "code": "GUIDE", "name": "领队", "status": "WAITING", "statusName": "待指派", "displayText": "领队待指派" }
] ]
}, },
"success": true "success": true
@ -134,7 +131,7 @@
- `currentSubFlows` 仅订单处于「资源准备」节点时有值，其余节点 null。 - `currentSubFlows` 仅订单处于「资源准备」节点时有值，其余节点 null。
- 子流程按需求标志过滤：needsHotel/needsVehicle/needsGuide/needsPhotographer 为 true 才出现对应子流程。 - 子流程按需求标志过滤：needsHotel/needsVehicle/needsGuide/needsPhotographer 为 true 才出现对应子流程。
- 「待审核」态仅团期订单会出现（核心订单无审核环节）。 - 「待审核」态仅团期订单出现（核心订单无审核环节）。
- 「已打回」只表达状态，具体退回原因在订单「记录」Tab 时间线（不在本接口返回）。 - 「已打回」只表达状态，具体退回原因在订单「记录」Tab 时间线（不在本接口返回）。
## 10. 修改前后对比 ## 10. 修改前后对比
@ -142,28 +139,29 @@
| 字段 | 改前 | 改后 | | 字段 | 改前 | 改后 |
|------|------|------| |------|------|------|
| label | 存在，文案不准（配车「处理中」错显「配房中」、待提交态 null）| **删除** | | label | 存在，文案不准（配车「处理中」错显「配房中」、待提交态 null）| **删除** |
| statusName | 不存在 | **新增**，全 6 态准确中文（配房/配车分别文案）| | statusName | 无 | **新增**，纯状态中文（待配/处理中…，房车一致）|
| displayText | 无 | **新增**，完整文案（配房已打回/配车处理中），前端直显 |
| status | WAITING/PROCESSING/DONE | 保留不变 | | status | WAITING/PROCESSING/DONE | 保留不变 |
| 配房/配车状态准确性 | 卡「待配」不动、抢单/打回不反映 | 抢单→配房中、打回→已打回，实时准确 | | 状态准确性 | 卡「待配」不动、抢单/打回不反映 | 抢单→处理中、打回→已打回，实时准确 |
## 11. 影响评估 / 回滚 ## 11. 影响评估 / 回滚
- **是否破坏向后兼容**：**部分**——删除了 `label` 字段。前端若读取 `currentSubFlows[].label` 需改为读 `statusName`。`status` 字段保留。 - **破坏向后兼容**：**部分**——删除了 `label`。前端若读 `currentSubFlows[].label` 需改读 `displayText`（或 statusName）。`status` 保留。
- **前端必须同步**：是（若在用 label）。改为读 `statusName` 即可，文案后端已给全。 - **前端必须同步**：是（若在用 label）。改读 `displayText` 即可。
- **回滚**：revert PR #3998 + #3989 并重新部署 hl-order-service-v3。 - **回滚**：revert PR #4024 + #3998 + #3989 并重新部署 hl-order-service-v3。
## 12. 注意事项 ## 12. 注意事项
- 前端展示子流程状态统一读 `statusName`（中文，开箱即用），不要再依赖 `label`（已删）。 - 前端展示子流程状态**直接用 `displayText`**（中文完整文案，开箱即用），不要再依赖 `label`（已删）。
- `status`（WAITING/PROCESSING/DONE）保留，仅用于需要机器判断分支的场景。 - 需要按对象/状态分别处理时用 `name` + `statusName`；需要机器判断分支用 `status`。
- 打回原因展示：去订单「记录」Tab 时间线，不在 currentSubFlows。 - 打回原因展示：去订单「记录」Tab 时间线，不在 currentSubFlows。
## 13. 关联 / 联系人 ## 13. 关联 / 联系人
### 13.1 链接 ### 13.1 链接
- **Issue**: [#3983](https://git.1814.love:8443/wx/HL/issues/3983)（单源化）、[#3997](https://git.1814.love:8443/wx/HL/issues/3997)（字段精简） - **Issue**: [#3983](https://git.1814.love:8443/wx/HL/issues/3983)（单源化）、[#3997](https://git.1814.love:8443/wx/HL/issues/3997)（字段精简）、[#4023](https://git.1814.love:8443/wx/HL/issues/4023)（displayText + statusName 纯状态）
- **PR**: [#3989](https://git.1814.love:8443/wx/HL/pulls/3989)、[#3998](https://git.1814.love:8443/wx/HL/pulls/3998) - **PR**: [#3989](https://git.1814.love:8443/wx/HL/pulls/3989)、[#3998](https://git.1814.love:8443/wx/HL/pulls/3998)、[#4024](https://git.1814.love:8443/wx/HL/pulls/4024)
### 13.2 联系人 ### 13.2 联系人