From 2c0f1c3ee3bf52727a2fe5cb6205da9d786c79ff Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 18 Jun 2026 16:34:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E6=88=BF=E5=8A=A1=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E5=88=97=E8=A1=A8=E6=8E=A5=E5=8F=A3(=E6=8A=A2?= =?UTF-8?q?=E5=8D=95=E6=B1=A0+=E6=88=91=E7=9A=84=E6=8E=A5=E5=8D=95)?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=E7=A1=AE=E8=AE=A4=EF=BC=8C=E6=A0=B8=E9=AA=8C?= =?UTF-8?q?=E8=AE=A2=E5=8D=95=E6=94=B9=E5=8A=A8=E6=9C=AA=E5=BD=B1=E5=93=8D?= =?UTF-8?q?+=E5=9B=A2=E6=9C=9F=E9=85=8D=E6=88=BF=E5=85=88=E4=B8=8D?= =?UTF-8?q?=E5=81=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...务订单列表接口契约确认-接口说明-管理后台.md | 184 ++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md diff --git a/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md b/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md new file mode 100644 index 0000000..56e720c --- /dev/null +++ b/changelogs-v2/2026-06/18_房务订单列表接口契约确认-接口说明-管理后台.md @@ -0,0 +1,184 @@ +# 房务管家·订单列表接口（抢单池 + 我的接单）契约确认 — 接口说明 — 管理后台 + +> 变更类型：📋 接口契约梳理与确认（**无后端代码变更**；核验订单模块近期改动后房务订单列表接口仍稳定） +> 端类型：管理后台（房务管家 → 订单列表页：「抢单池」/「我的订单」两个 Tab） +> 日期：2026-06-18 +> 服务：hl-order-service-v3（house 抢单池模块，API §1.1 / §1.5） +> 关联订单模块近期改动：#3967（flowDisplayText→flowStepName 改名）、#3981/#3976（出行人类型按生日派生）、#3972（需求历史 ALL 默认）、#3983（配房 control_status 主表单源化） + +--- + +## ⚠️ 关键说明 + +订单服务同事近期改了一批订单模块（出参字段改名、出行人类型派生、状态归类、control_status 单源化等）。本次**核验房务管家「订单列表」页所依赖的两个列表接口在这些改动后是否仍然稳定**。 + +**结论：两个接口的请求/响应契约均未受订单改动影响，已在测试服网关 9443 + 真实 admin token 实测返回 200、结构与设计一致。前端可继续按本契约对接。** + +两件事请前端留意（**非订单改动导致，是当前实现基线**，提前讲清避免拿真接口替换 mock 时踩空）： + +1. **团期（GROUP）产品配房先不做**（详见 §5）——房务抢单/配房当前只面向私人订制（CUSTOM）/散客。 +2. **部分字段本期为占位/简化值**（详见 §4）——房务跟单状态目前后端只产出「配房中 / 已确认」两态，尚未细分到「待配房 / 驳回 / 待最终确认 / 回配成功」全流程；`stats` 的部分计数、异常/待办/未读数本期固定 0。若前端 UI 已按全流程状态展示，请知悉这些值暂由后端简化提供。 + +--- + +## 1. 接口总览（房务抢单池模块，订单列表页用到前 2 个） + +| # | 方法 | 路径 | 用途 | 本页 | +|---|---|---|---|---| +| §1.1 | GET | `/v3/admin/order/grab-pool/hotel-requirements` | 抢单池列表（分页 + 多维筛选） | ✅「抢单池」Tab | +| §1.5 | GET | `/v3/admin/order/grab-pool/my-claims/hotel` | 我的接单（分页 + stats 聚合） | ✅「我的订单」Tab | +| §1.2 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/claim` | 抢单（乐观锁先抢先得） | 抢单按钮 | +| §1.3 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/transfer` | 转单 / 超管指派 | — | +| §1.4 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/release` | 释放回池 | — | + +> 网关路由：已被 `hl-gateway` 的 `/v3/admin/order/**` 路由块覆盖，实测经 9443 可达。 +> 身份：抢单/我的接单从 JWT 取房务 adminId；「我的接单」按 `claimer_id = 当前登录房务` 过滤（admin 超管无接单时返回空 list，属正常）。 + +--- + +## 2. §1.1 抢单池列表 + +**`GET /v3/admin/order/grab-pool/hotel-requirements`** + +请求参数（query，均可选）： + +| 参数 | 类型 | 说明 | +|---|---|---| +| keyword | String | 通用模糊搜（订单号/客人姓名/客人电话/产品名，≤32 字） | +| productType | String | 产品类型 CORE/GROUP/CUSTOM（当页内存精筛，见 §4 注） | +| productName | String | 产品名模糊搜 | +| consultantId | Long | 定制师 ID 精确过滤 | +| guestName | String | 客人姓名/联系人模糊搜 | +| departDateFrom / departDateTo | LocalDate | 出行日期区间 | +| page / pageSize | Integer | 默认 1 / 20，pageSize 最大 100 | +| sortBy | String | 默认 `createTime,desc`；可切 `departDate,asc` | + +响应 `data`（PageResult）：`{ records[], total, page, pageSize }`，`records[]` 子项字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String(雪花) | 房型需求 ID（requirement_id） | +| orderId | String(雪花) | 订单 ID | +| orderNo | String | 订单号（如 26-0501） | +| guestName | String | 客人姓名 | +| personsDesc | String | 人数描述（后端拼，如「2大1小」，按大/小/幼/婴四段） | +| productType | String | 产品类型（经 product-v2 Feign 富化，降级 null） | +| productName | String | 产品名 | +| productNo | String | 产品编号（C/G/D 前缀，Feign 富化，降级 null） | +| route | String | 档位·夜数（如「舒适型 · 5晚」） | +| departDate | LocalDate | 出行日期 | +| nights | Integer | 夜数 | +| cities | String[] | 行程城市（中文，按行程去重） | +| **totalAmount** | **String** | **订单总额（金额=带引号字符串，防精度，如 "6840.00"）** | +| consultantName | String | 定制师姓名 | +| consultantRemark | String | 定制师订单级备注 | +| requirementNote | String | 定制师在需求里填的备注（>50 字截断） | +| special | String[] | 特殊诉求标签 | +| requirementVersion | Integer | 需求版本号（>1 时 UI 标「已修订」） | +| createTime | LocalDateTime | 创建时间 | + +```bash +curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/hotel-requirements?page=1&pageSize=2" \ + -H "Authorization: Bearer " +# 实测返回 200，结构：{ "code":200, "data":{ "records":[...], "total":N, "page":1, "pageSize":2 }, "success":true } +``` + +--- + +## 3. §1.5 我的接单 + +**`GET /v3/admin/order/grab-pool/my-claims/hotel`** + +请求参数（query，均可选）： + +| 参数 | 类型 | 说明 | +|---|---|---| +| keyword | String | 通用模糊搜（订单号/客人姓名/客人电话/产品名，≤32 字） | +| status | String | 房务跟单状态过滤：`inProgress`/`pendingConfirm`/`confirmed`/`exception`（**当前实际只有「进行中 vs 已确认」两档真实区分，见 §4**） | +| productType / productName / consultantId / guestName | — | 同 §1.1 | +| departDateFrom / departDateTo | LocalDate | 出行日期区间 | +| claimedAtFrom / claimedAtTo | LocalDateTime | 抢单时间区间 | +| city / hasException / hasTodo / hasUnreadMessage | — | **接口预留，本期未生效** | +| page / pageSize | Integer | 默认 1 / 20，最大 100 | +| sortBy | String | 默认 `claimedAt,desc` | + +响应 `data`：`{ list[], total, stats }` + +`list[]` 子项字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| id / orderId | String(雪花) | 需求 ID / 订单 ID | +| orderNo / guestName / personsDesc / productType / productName / route / departDate / nights / cities / consultantName | 同 §1.1 | — | +| claimedAt | LocalDateTime | 抢单时间 | +| houseStatus | String | 房务跟单状态（**当前仅「配房中」/「已确认」**） | +| progressDesc | String | 进度文字（如「已配 3 / 共 5 晚」） | +| hotelSummary | String | 已配酒店摘要（按 day 拼，如「伯爵+叶卡捷琳娜」） | +| waitingDesc | String | 等待提示（如「等酒店回复 4h」，无则 null） | +| lastAction | String | 最近一次动作（操作日志） | +| exceptionCount / todoCount / unreadMessageCount | Integer | **本期固定 0** | +| primaryAction | Object | `{ code, label, url }` 主操作按钮意图（见 §4 注） | + +`stats`：`{ inProgress, pendingConfirm, confirmed, exception }`（按房务跟单状态聚合的徽章数） + +```bash +curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/my-claims/hotel?page=1&pageSize=2" \ + -H "Authorization: Bearer " +# 实测返回 200，结构：{ "code":200, "data":{ "list":[...], "total":N, +# "stats":{"inProgress":0,"pendingConfirm":0,"confirmed":0,"exception":0} }, "success":true } +``` + +--- + +## 4. 📌 字段对接须知（已接通 vs 本期占位/简化） + +**✅ 已接通真实值**：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。 + +**⏳ 本期占位 / 简化（前端对接请知悉）**： + +| 字段 / 行为 | 当前实现 | 说明 | +|---|---|---| +| `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 | 同上 | +| `city` / `hasException` / `hasTodo` / `hasUnreadMessage` 入参 | 预留未生效 | — | +| `productType` 入参筛选（§1.1） | 仅对当前页生效；total 仍为未含 productType 的 DB 总数 | productType 跨服务无法下推 SQL，当页内存精筛 | + +> 提示：若房务管家前端当前展示的「待配房 / 待最终确认」状态与「配房」按钮来自前端自身 mock/派生，替换为真实接口时请按上表对齐——后端目前不产出这些细分态。完整 5 态流转的后端支持待产品拍板后另行补充。 + +--- + +## 5. ⚠️ 团期（GROUP）产品配房先不做 + +房务抢单池 / 我的接单 / 配房**当前只面向私人订制（CUSTOM）/散客类订单**，**团期（GROUP，跟团/批量出团产品）的房务配房先不做、暂不纳入**（wx 2026-06-18 明确）。 + +前端请勿按团期建房务配房 UI。说明：后端当前**未按 productType 硬过滤把 GROUP 需求挡在抢单池外**（productType 仅作展示/当页筛选），"先不做"是产品范围约定；如需硬过滤为后续增强。 + +--- + +## 6. 核验与实测 + +逐条核对订单模块近期改动对本两接口的影响： + +| 订单改动 | 是否波及房务 list | 依据 | +|---|---|---| +| #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）不变 | +| 合同/保险 NONE→null、待支付流程归类、order_tag.tagType 删除 | ❌ 否 | 均不在房务 list 出参/查询字段内 | + +实测（测试服网关 9443 + 真实 admin token）： + +- §1.1 抢单池：`200`，`data = { records, total, page, pageSize }` ✓ +- §1.5 我的接单：`200`，`data = { list, total, stats:{inProgress,pendingConfirm,confirmed,exception} }` ✓ + +--- + +## 备注 + +- 本文为接口契约梳理与确认，无后端代码变更、零 DDL。 +- 金额字段（totalAmount）已按平台「金额=String」约定带引号序列化（关联 18_3978 金额 String 化批次）。 +- 完整配房 5 步状态流（待配房→配房中→驳回→配房中→回配成功）与实时聊天的后端支持仍在设计/待拍板，落地后再行同步。