房务管家·订单列表接口（抢单池 + 我的接单）契约确认 — 接口说明 — 管理后台

变更类型：📋 接口契约梳理与确认（无后端代码变更；核验订单模块近期改动后房务订单列表接口仍稳定）端类型：管理后台（房务管家 → 订单列表页：「抢单池」/「我的订单」两个 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 时踩空）：

团期（GROUP）产品配房先不做（详见 §5）——房务抢单/配房当前只面向私人订制（CUSTOM）/散客。
部分字段本期为占位/简化值（详见 §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	创建时间

curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/hotel-requirements?page=1&pageSize=2" \
  -H "Authorization: Bearer <adminToken>"
# 实测返回 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 }（按房务跟单状态聚合的徽章数）

curl -k "https://api.test.1814.love:9443/v3/admin/order/grab-pool/my-claims/hotel?page=1&pageSize=2" \
  -H "Authorization: Bearer <adminToken>"
# 实测返回 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 步状态流（待配房→配房中→驳回→配房中→回配成功）与实时聊天的后端支持仍在设计/待拍板，落地后再行同步。

11 KiB 原始文件 Blame 文件历史 Unescape Escape