From 979ecdf8f12d942f8fb58ae09b84506cb9b1595a Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 18 Jun 2026 16:57:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E6=9B=B4=E6=AD=A3=E6=88=BF?= =?UTF-8?q?=E5=8A=A1=E7=8A=B6=E6=80=81=E8=AF=B4=E6=98=8E=E2=80=94=E2=80=94?= =?UTF-8?q?=E9=85=8D=E6=88=BF=E5=85=A86=E6=80=81=E5=B7=B2=E7=94=B1?= =?UTF-8?q?=E8=AE=A2=E5=8D=95=20currentSubFlows.statusName=20=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0(=E5=90=8C=E4=BA=8B=E7=A1=AE=E8=AE=A4=E7=8A=B6?= =?UTF-8?q?=E6=80=81=E9=83=BD=E6=9C=89)=EF=BC=8C=E9=9D=9E=E5=BE=85?= =?UTF-8?q?=E8=A1=A5/=E5=BE=85=E6=8B=8D=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...务订单列表接口契约确认-接口说明-管理后台.md | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md b/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md index 56e720c..f19d21b 100644 --- a/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md +++ b/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md @@ -17,7 +17,7 @@ 两件事请前端留意（**非订单改动导致，是当前实现基线**，提前讲清避免拿真接口替换 mock 时踩空）： 1. **团期（GROUP）产品配房先不做**（详见 §5）——房务抢单/配房当前只面向私人订制（CUSTOM）/散客。 -2. **部分字段本期为占位/简化值**（详见 §4）——房务跟单状态目前后端只产出「配房中 / 已确认」两态，尚未细分到「待配房 / 驳回 / 待最终确认 / 回配成功」全流程；`stats` 的部分计数、异常/待办/未读数本期固定 0。若前端 UI 已按全流程状态展示，请知悉这些值暂由后端简化提供。 +2. **配房完整状态请从订单的 `currentSubFlows[].statusName` 读取**（详见 §4）——配房全流程状态（待提交需求 / 待审核 / 待配房 / 配房中 / 已打回 / 已完成，**全 6 态中文直显**）**已在订单列表/详情接口实现**（Issue #3983/#3368），由 `order_main.room_control_status` 单源化、与需求状态 `RequirementStatus` 同值集。房务「我的接单」列表自带的 `houseStatus` 是房务侧**粗粒度标签**（配房中/已确认），**不是**配房完整状态源。另：`stats` 的部分计数、异常/待办/未读数本期仍为占位 0。 --- @@ -134,20 +134,38 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/my-claims/hote **✅ 已接通真实值**：id / orderId / orderNo / guestName / personsDesc / productName / route / departDate / nights / cities / totalAmount / consultantName / consultantRemark / requirementNote / special / requirementVersion / createTime / claimedAt / progressDesc / hotelSummary / waitingDesc / lastAction / productType·productNo（Feign 富化，降级 null） / stats.inProgress / stats.confirmed。 -**⏳ 本期占位 / 简化（前端对接请知悉）**： +**✅ 配房完整状态：已实现（权威来源 = 订单 `currentSubFlows[].statusName`）** + +配房 5 步流（待配房→配房中→驳回→配房中→回配成功）的状态**后端已全部实现**，存于需求状态列并单源镜像到主表，通过**订单列表 / 详情接口**的 `currentSubFlows` 暴露（当订单当前流程步为「资源准备 RESOURCE」时非 null）： + +| 来源 | 字段 | 取值（中文直显） | +|---|---|---| +| `RequirementStatus`（需求状态，权威生命周期） | requirement.status | PENDING 待房务配 / PROCESSING 配房中 / REJECTED_TO_CONSULTANT 已打回定制师 / DONE 配房完成（+团期 PENDING_REVIEW 待审核 / REJECTED_TO_ADMIN 已打回团期管理员） | +| `order_main.room_control_status`（#3983 单源镜像，同值集） | `currentSubFlows[].statusName` | 待提交需求 / 待审核 / 待配房 / 配房中 / 已打回 / 已完成（全 6 态，零 null） | +| 同上（仅订单详情链路 REJECTED_* 时） | `currentSubFlows[].statusRemark` | 打回原因（如「房源紧张，请调整日期」） | + +实测（订单列表 `GET /v3/admin/order`）： + +```json +{ "orderNo": "HL20260618095826571", "flowStepName": "资源准备", + "currentSubFlows": [ { "code": "HOTEL", "name": "配房", + "status": "WAITING", "statusName": "待提交需求", "statusRemark": null } ] } +``` + +> 5 步流 ↔ 状态映射：待配房=PENDING / 配房中=PROCESSING / 驳回=REJECTED_TO_CONSULTANT / 重提=PROCESSING / 回配成功=DONE。前端展示配房进度/状态请优先读订单的 `currentSubFlows[].statusName`（房务列表项带 `orderId` 可关联订单）。 + +**⏳ 仅以下房务「我的接单」列表自带字段为占位/简化（与上面的"配房状态"无关，主要是计数器与房务侧粗标签）**： | 字段 / 行为 | 当前实现 | 说明 | |---|---|---| -| `houseStatus` | 仅「配房中」(PROCESSING) / 「已确认」(DONE) | 设计的「待配房 / 驳回 / 待最终确认 / 回配成功」全流程暂未在列表细分（后端待补，关联配房 5 步流设计） | -| `status` 入参筛选 | inProgress/pendingConfirm/exception 实际都映射 PROCESSING，仅 confirmed→DONE | 即当前只有「进行中 vs 已确认」两档真实生效 | -| `primaryAction.code` | 仅 `CONTINUE_ARRANGE`(继续配房)/`FINALIZE`(最终确认)/`VIEW`(查看) | 暂不产出 `ARRANGE`(配房)；按 PROCESSING/DONE 简化推导 | -| `stats.pendingConfirm` / `stats.exception` | 固定 0 | 待对应工单接入后真实化 | -| `exceptionCount` / `todoCount` / `unreadMessageCount` | 固定 0 | 同上 | +| `houseStatus`（房务列表项） | 房务侧粗粒度标签：配房中(PROCESSING)/已确认(DONE) | **非配房完整状态**；完整状态读订单 `currentSubFlows[].statusName`（见上） | +| `status` 入参筛选（§1.5） | inProgress/pendingConfirm/exception 都映射 PROCESSING，仅 confirmed→DONE | 房务列表的筛选粒度，当前两档真实生效 | +| `primaryAction.code` | `CONTINUE_ARRANGE`/`FINALIZE`/`VIEW` | 房务列表按钮意图，按 PROCESSING/DONE 推导 | +| `stats.pendingConfirm` / `stats.exception` | 固定 0 | 计数器待对应工单接入 | +| `exceptionCount` / `todoCount` / `unreadMessageCount` | 固定 0 | 计数器待对应工单接入 | | `city` / `hasException` / `hasTodo` / `hasUnreadMessage` 入参 | 预留未生效 | — | | `productType` 入参筛选（§1.1） | 仅对当前页生效；total 仍为未含 productType 的 DB 总数 | productType 跨服务无法下推 SQL，当页内存精筛 | -> 提示：若房务管家前端当前展示的「待配房 / 待最终确认」状态与「配房」按钮来自前端自身 mock/派生，替换为真实接口时请按上表对齐——后端目前不产出这些细分态。完整 5 态流转的后端支持待产品拍板后另行补充。 - --- ## 5. ⚠️ 团期（GROUP）产品配房先不做 @@ -167,7 +185,7 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/my-claims/hote | #3967 flowDisplayText→flowStepName 改名 | ❌ 否 | 只改订单出参 VO；房务列表直读 order_main 列，不复用该 VO | | #3981/#3976 出行人类型按生日派生 | ❌ 否 | personsDesc 取 **order_main 存量计数列**（adult/child/youngChild/baby），与 traveler 记录解耦，且已按四段渲染 | | #3972 需求历史 ALL 默认 | ❌ 否 | 只改 `getRequirementHistory`（版本历史端点），未碰两个分页 JOIN | -| #3983 配房 control_status 单源化 | ❌ 否 | 只在 claim() 写端补镜像；list 读契约与 houseStatus（取 requirement.status）不变 | +| #3983 配房 control_status 单源化 + currentSubFlows 全态展示 | ❌ 否（且正向增强） | 不破坏房务 list 契约；**正是它把配房全 6 态单源化到 order_main 并经订单 `currentSubFlows[].statusName` 直显**（见 §4） | | 合同/保险 NONE→null、待支付流程归类、order_tag.tagType 删除 | ❌ 否 | 均不在房务 list 出参/查询字段内 | 实测（测试服网关 9443 + 真实 admin token）： @@ -181,4 +199,4 @@ curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/my-claims/hote - 本文为接口契约梳理与确认，无后端代码变更、零 DDL。 - 金额字段（totalAmount）已按平台「金额=String」约定带引号序列化（关联 18_3978 金额 String 化批次）。 -- 完整配房 5 步状态流（待配房→配房中→驳回→配房中→回配成功）与实时聊天的后端支持仍在设计/待拍板，落地后再行同步。 +- 完整配房 5 步状态流（待配房→配房中→驳回→配房中→回配成功）**后端已实现**，经订单 `currentSubFlows[].statusName` 全 6 态中文直显（见 §4）；仅「实时聊天」集成仍在设计/待拍板，落地后再行同步。