docs(changelog/order-v3): 配房询房候选流程接线说明(#4427/#4433) — 详情逐日询房中态+候选清单, 第一次选房走发询房, 单日确认改结算价/同步协议价

changelogs-v2/2026-06/27_4427_配房询房候选流程-询房中天级态+候选清单+单日确认同步协议价-管理后台.md

@@ -0,0 +1,76 @@
+# 配房「先询房选候选 → 单日确认定一家」流程 — 详情逐日补询房中态/候选清单 + 单日确认同步协议价
+
+> 变更类型：✨ 新增字段 + 接口接线说明（后端已就绪，**房务管家前端需按此接线**）
+> 端类型：管理后台（房务管家·配房工作台）
+> 日期：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）。