From a0c5c92ba47d1d595cd0a3f44cd26d1f3aacf036 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 18 Jun 2026 17:10:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20currentSubFlows=20=E5=AD=90?= =?UTF-8?q?=E6=B5=81=E7=A8=8B=E7=8A=B6=E6=80=81=E5=88=A0=20label=20?= =?UTF-8?q?=E5=8A=A0=E5=85=A8=E6=80=81=20statusName=20(#3983=20#3997)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 管理后台订单列表+详情 currentSubFlows[] 出参：删除 label、新增 statusName（全态中文）。 配房/配车 6 态(待提交需求/待审核/待配房/配房中/已打回/已完成)，领队/摄影(待指派/已完成)。 前端统一读 statusName。 --- ...子流程状态全态statusName-修改接口-管理后台.md | 170 ++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md b/changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md new file mode 100644 index 0000000..18c59d9 --- /dev/null +++ b/changelogs-v2/2026-06/18_3983_配房配车子流程状态全态statusName-修改接口-管理后台.md @@ -0,0 +1,170 @@ +# 【修改接口·管理后台】⚠️ currentSubFlows 子流程状态字段重构：删 label + 新增全态 statusName (#3983) + +> **PR**: #3989 + #3998 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18 +> ⚠️ 含**字段删除**（label）+ 字段新增（statusName），前端若在用 currentSubFlows.label 必须切换到 statusName。 + +## 1. 接口背景 + +订单列表/详情「资源准备」节点下的 `currentSubFlows`（配房/配车/领队/摄影子流程）原先状态展示有两个问题： +1. `control_status` 主表是残缺镜像，子流程状态卡在「待配」不动、`label` 大量返 null（抢单进「处理中」、打回「已打回」从未回写主表）； +2. `label` 字段不准——配车「处理中」错显「配房中」、不分房车、「待提交需求」态返 null。 + +本次把配房/配车状态升级为完整状态机单源，并用一个准确的全态字段 `statusName` 取代旧的 `label`。**删除 `label`**，新增 `statusName`，前端统一显示 `statusName`。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 订单列表 | GET | /v3/admin/order（兼容 /v3/admin/order/list） | 出参字段删除+新增 | currentSubFlows[] 元素**删 label**、**加 statusName** | +| 2 | 订单详情 | GET | /v3/admin/order/{id} | 出参字段删除+新增 | currentSubFlows[] 元素**删 label**、**加 statusName** | + +> currentSubFlows 仅在订单处于「资源准备」节点时有值（其余节点为 null），是该节点下的子流程数组。 + +## 3. 接口详情 + +### 3.1 订单列表 +- **使用场景**：订单列表页渲染每条订单的资源准备子流程进度。 +- **认证**：JWT（管理员）。**幂等**：是（只读）。 + +入参无变化。出参 `PageResult`，其中 `currentSubFlows[]` 每个元素删除 `label`、新增 `statusName`。 + +### 3.2 订单详情 +- **使用场景**：订单详情页资源准备节点的子流程进度展示。 +- **认证**：JWT（管理员）。**幂等**：是（只读）。 + +入参无变化。出参详情 VO 的 `currentSubFlows[]` 每个元素删除 `label`、新增 `statusName`。 + +## 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 | +| statusName | String | **新增** | 全态中文展示文案，前端直接显示，见 §6 | + +> 前端展示子流程状态请直接用 `statusName`；`status` 三态保留供需要机器判断的场景使用。 + +## 6. 枚举 / 数据字典 + +### 6.1 statusName（配房 HOTEL / 配车 VEHICLE） + +由主表 `room_control_status` / `vehicle_control_status` 派生，全 6 态： + +| 后端状态 | statusName（配房）| statusName（配车）| 含义 | +|---|---|---|---| +| 待提交需求 | 待提交需求 | 待提交需求 | 需求还没提交（needs=true 未发起）| +| 待审核 | 待审核 | 待审核 | 仅团期：定制师已提、团期管理员未审核 | +| 待配 | 待配房 | 待配车 | 已进抢单池，房务/车务未接单 | +| 处理中 | 配房中 | 配车中 | 房务/车务已接单处理中 | +| 已打回 | 已打回 | 已打回 | 被打回需重新处理（打回原因见订单「记录」Tab 时间线）| +| 已完成 | 已完成 | 已完成 | 资源配置完成 | + +### 6.2 statusName（领队 GUIDE / 摄影 PHOTOGRAPHER） + +由 `guide_status` / `photographer_status` 派生，两态： + +| 后端状态 | statusName | 含义 | +|---|---|---| +| 未配（null）| 待指派 | 尚未指派领队/摄影 | +| 已完成（DONE）| 已完成 | 已指派完成 | + +> `statusName` 不返回 null（全态都有文案）。打回原因不在本字段，前端去订单「记录」Tab 时间线查看（带时间/操作人）。 + +## 7. 错误码 + +纯出参字段调整，无新增错误码。 + +| code | 含义 | +|------|------| +| 581201 | 订单不存在（详情接口 id 无效）| +| 401 / 403 | 未认证 / 无权限 | + +## 8. 示例（3 组） + +### 8.1 典型 — 资源准备中订单（配房处理中、配车待配） + +```json +{ + "code": 200, + "data": { + "currentSubFlows": [ + { "code": "HOTEL", "name": "配房", "status": "PROCESSING", "statusName": "配房中" }, + { "code": "VEHICLE", "name": "配车", "status": "PROCESSING", "statusName": "待配车" } + ] + }, + "success": true +} +``` + +### 8.2 边界 — 配房被打回 + 领队待指派 + +```json +{ + "code": 200, + "data": { + "currentSubFlows": [ + { "code": "HOTEL", "name": "配房", "status": "WAITING", "statusName": "已打回" }, + { "code": "GUIDE", "name": "领队", "status": "WAITING", "statusName": "待指派" } + ] + }, + "success": true +} +``` + +### 8.3 边界 — 订单不在资源准备节点（currentSubFlows 为 null） + +```json +{ "code": 200, "data": { "currentSubFlows": null }, "success": true } +``` + +## 9. 业务边界 + +- `currentSubFlows` 仅订单处于「资源准备」节点时有值，其余节点 null。 +- 子流程按需求标志过滤：needsHotel/needsVehicle/needsGuide/needsPhotographer 为 true 才出现对应子流程。 +- 「待审核」态仅团期订单会出现（核心订单无审核环节）。 +- 「已打回」只表达状态，具体退回原因在订单「记录」Tab 时间线（不在本接口返回）。 + +## 10. 修改前后对比 + +| 字段 | 改前 | 改后 | +|------|------|------| +| label | 存在，文案不准（配车「处理中」错显「配房中」、待提交态 null）| **删除** | +| statusName | 不存在 | **新增**，全 6 态准确中文（配房/配车分别文案）| +| status | WAITING/PROCESSING/DONE | 保留不变 | +| 配房/配车状态准确性 | 卡「待配」不动、抢单/打回不反映 | 抢单→配房中、打回→已打回，实时准确 | + +## 11. 影响评估 / 回滚 + +- **是否破坏向后兼容**：**部分**——删除了 `label` 字段。前端若读取 `currentSubFlows[].label` 需改为读 `statusName`。`status` 字段保留。 +- **前端必须同步**：是（若在用 label）。改为读 `statusName` 即可，文案后端已给全。 +- **回滚**：revert PR #3998 + #3989 并重新部署 hl-order-service-v3。 + +## 12. 注意事项 + +- 前端展示子流程状态统一读 `statusName`（中文，开箱即用），不要再依赖 `label`（已删）。 +- `status`（WAITING/PROCESSING/DONE）保留，仅用于需要机器判断分支的场景。 +- 打回原因展示：去订单「记录」Tab 时间线，不在 currentSubFlows。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#3983](https://git.1814.love:8443/wx/HL/issues/3983)（单源化）、[#3997](https://git.1814.love:8443/wx/HL/issues/3997)（字段精简） +- **PR**: [#3989](https://git.1814.love:8443/wx/HL/pulls/3989)、[#3998](https://git.1814.love:8443/wx/HL/pulls/3998) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu