# 配房「先询房选候选 → 单日确认定一家」流程 — 详情逐日补询房中态/候选清单 + 单日确认同步协议价

> 变更类型：✨ 新增字段 + 接口接线说明（后端已就绪，**房务管家前端需按此接线**）
> 端类型：管理后台（房务管家·配房工作台）
> 日期：2026-06-26 ｜ 工单：#4427 ｜ PR：#4433 ｜ 服务：hl-order-service-v3（双实例已部署 health UP，**测试服 API+DB 实测通过**）

---

## 背景：房务配房两阶段流程
1. **第一次选酒店/房型 = 选「询房候选」（可多家）** → 当天进入「询房中」 → 复制话术问酒店。
2. **「单日确认」= 从候选挑一家定下来** → 当天配房完成（一天一家）。

后端能力本就齐：候选落 `house_inquiry_message`（一家一行）；确认走询房回填转配房。本次补齐**详情把「询房中」显示出来 + 当天候选清单**，并让单日确认支持改结算价/同步协议价。

---

## 一、配房详情新增字段（`GET /admin/house/orders/{orderId}` → `itinerary[]`）

### 1. 逐日状态 `arrange` 新增「询房中」
`itinerary[].arrange` 取值由原 `pending`/`confirmed` 扩为三态，`arrangeLabel` 为中文：
- `pending` / **待配房**：当天无询房、无配房。
- `waiting` / **询房中**（新）：当天有进行中的询房（PENDING 待回复 / REPLIED 已回复）且尚未定稿配房。
- `confirmed` / **已确认**：当天已有配房行（**优先级最高**——即便还有遗留询房，也显已确认）。

### 2. 逐日新增 `inquiries[]` 当天询房候选清单
`itinerary[].inquiries`（数组，无询房则空数组）——供「单日确认」弹窗列候选选保留哪家。每项字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `inquiryId` | String(雪花) | 询房记录 ID（回填/确认时用） |
| `hotelId` | String(雪花) | 酒店 ID |
| `hotelName` | String | 酒店名 |
| `roomCategory` | String | 房型类别字典 code（询房只到类别粒度；**具体房型 ID 由前端单日确认时从该酒店房型列表现选**，故候选不带 roomTypeId） |
| `roomCount` | Integer | 询问间数 |
| `status` | String | 询房状态：PENDING/REPLIED/CONFIRMED/REJECTED/TIMEOUT |
| `statusLabel` | String | 中文：待回复/已回复/已确认/已拒单/已超时 |
| `replyPrice` | String(金额) | 酒店回复报价（未回则空） |
| `replyAvailable` | Integer | 酒店回复可用房数（未回则空） |
| `priority` | String | NORMAL/URGENT |
| `timeoutAt` | DateTime | 询房超时刻（create + 4h） |

> 已取消（CANCELLED）的询房不进清单。

---

## 二、前端接线（房务管家，mmg 需改）

### 1. 第一次选房 → 走「发询房」（多候选），不要走「配房」
- **第一次给某天选候选酒店/房型 → 逐个调 `POST /v3/admin/order/inquiry/send`**（一家一调，body 见下），不要调配房保存 `…/assignments`。
  - 原因：配房保存是「一天一家**定稿**」模型（按天归集，多家只留一家）——这就是「选多个酒店只存一个」的根因。多候选必须落询房表。
  - `send` body：`{requirementId, hotelId, dayNumber, stayDate, nights, roomCount, roomCategory, messageBody?}`；返回 `wechatTemplate`（话术，供复制）。
- 复制话术：`POST /v3/admin/order/inquiry/preview`（所见即所发，不落库），或直接用 send 返回的 `wechatTemplate`。
- 发起后该天 `arrange` 自动变 `waiting`/**询房中**，前端据此显示徽章。

### 2. 「单日确认」→ 弹窗列候选选一家 → 回填转配房
- 弹窗数据源：详情 `itinerary[].inquiries`（或 `GET /v3/admin/order/inquiry?requirementId=&...` 历史）。
- 选定一家 → `POST /v3/admin/order/inquiry/{inquiryId}/reply`，`convertToAssignment=true` → 落配房，该天变「已确认」。
- **可在确认时改价**：
  - 改结算价：传 `replyPrice`（→ 落配房成交售价 sellPrice）。
  - **同步到协议价（新）**：传 `syncProtocolPrice=true` —— 把本次结算价(replyPrice)同步写回 resource 协议价（**与配房 `syncProtocolPrice` 同口径**，无需另填值）。需同时传 `roomTypeId`（前端从该酒店房型列表带入，写回价格日历定位用）。
  - 也可走原显式路径：`syncToCalendar=true` + `newProtocolPrice`/`newStock`（显式另填协议价/库存）。

---

## 接口速查
| 操作 | 接口 |
|------|------|
| 发起询房（一家一调，多候选） | `POST /v3/admin/order/inquiry/send` |
| 话术预览 | `POST /v3/admin/order/inquiry/preview` |
| 询房历史/候选 | `GET /v3/admin/order/inquiry?requirementId=` |
| 单日确认（选一家定稿，可改结算价/同步协议价） | `POST /v3/admin/order/inquiry/{inquiryId}/reply`（convertToAssignment=true，可带 replyPrice / syncProtocolPrice / roomTypeId） |
| 详情逐日态+候选清单 | `GET /admin/house/orders/{orderId}` → `itinerary[].arrange`(+waiting/询房中) / `itinerary[].inquiries[]` |

## 测试服实测（已通过）
- 详情逐日 `inquiries[]` 正确归集当天候选：发一条询房 → DAY 候选清单回 `status=PENDING/待回复`、中文 statusLabel、报价/可用房/优先级齐全；该天有配房时 `arrange` 保持 `confirmed`（已确认优先）。
- 全量单测 4668 通过（含三态 + 候选归集 + 同步协议价写回 replyPrice 当协议价 UT）。