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

> 变更类型：📋 接口契约梳理与确认（**无后端代码变更**；核验订单模块近期改动后房务订单列表接口仍稳定）
> 端类型：管理后台（房务管家 → 订单列表页：「抢单池」/「我的订单」两个 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. **配房完整状态请从订单的 `currentSubFlows[].statusName` 读取**（详见 §4）——配房全流程状态（待提交需求 / 待审核 / 待配房 / 配房中 / 已打回 / 已完成，**全 6 态中文直显**）**已在订单列表/详情接口实现**（Issue #3983/#3368），由 `order_main.room_control_status` 单源化、与需求状态 `RequirementStatus` 同值集。房务「我的接单」列表自带的 `houseStatus` 是房务侧**粗粒度标签**（配房中/已确认），**不是**配房完整状态源。另：`stats` 的部分计数、异常/待办/未读数本期仍为占位 0。

---

## 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 <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 }`（按房务跟单状态聚合的徽章数）

```bash
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。

**✅ 配房完整状态：已实现（权威来源 = 订单 `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` 可关联订单）。

**🆕 `requirement_status` 数据字典已配置**（2026-06-18，测试服已生效，镜像 `RequirementStatus` 枚举的散客/私人订制态）——需求状态 value→中文 label 已入字典，前端可经 `GET /admin/dict/data/requirement_status`（或后台初始化 `GET /admin/dict/all`）取下列 **4 态**做筛选下拉 / value 翻译：

| value | label | 样式 |
|---|---|---|
| PENDING | 待房务配 | warning |
| PROCESSING | 配房中 | primary |
| DONE | 配房完成 | success |
| REJECTED_TO_CONSULTANT | 已打回定制师 | danger |

> 团期专用状态（`PENDING_REVIEW` 待审核 / `REJECTED_TO_ADMIN` 已打回团期管理员）因「团期配房先不做」（见 §5）**不纳入字典**。

**⏳ 仅以下房务「我的接单」列表自带字段为占位/简化（与上面的"配房状态"无关，主要是计数器与房务侧粗标签）**：

| 字段 / 行为 | 当前实现 | 说明 |
|---|---|---|
| `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，当页内存精筛 |

---

## 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 单源化 + currentSubFlows 全态展示 | ❌ 否（且正向增强） | 不破坏房务 list 契约；**正是它把配房全 6 态单源化到 order_main 并经订单 `currentSubFlows[].statusName` 直显**（见 §4） |
| 合同/保险 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 步状态流（待配房→配房中→驳回→配房中→回配成功）**后端已实现**，经订单 `currentSubFlows[].statusName` 全 6 态中文直显（见 §4）；仅「实时聊天」集成仍在设计/待拍板，落地后再行同步。