docs(changelog-v2): 询房弹窗改造前端对接(候选list/真实房型/联系人只读/正文预览/回填改价)

工单 #4404(PR #4408) + #4405(PR #4409),hl-order-service-v3 + hl-resource-service,测试服已部署 + API/DB 实测通过。

changelogs-v2/2026-06/25_4408-4409_询房弹窗改造_候选list+真实房型+联系人只读+正文预览+回填改价_管理后台.md

@@ -0,0 +1,51 @@
+# 询房弹窗改造 — 酒店候选 list + 真实房型联动 + 联系人资源带出只读 + 正文预览 + 回填可改协议价/库存
+
+> 变更类型：✨ 功能增强（后端，**房务管家前端需配合改「发起询房」+「回填」弹窗**）
+> 端类型：管理后台（房务管家·发起询房 / 回填询房）
+> 日期：2026-06-25 ｜ 工单：#4404 + #4405 ｜ PR：#4408 + #4409 ｜ 服务：hl-order-service-v3 + hl-resource-service（双实例已部署 health UP）
+
+---
+
+## 背景
+房务「发起询房」弹窗 + 「回填」共 5 处改造：酒店从下拉改候选 list（全部在售可选）、房型按所选酒店真实房型联动、联系人/微信从酒店资源自动带出且只读、询房正文支持发起前预览、回填时可直接改该房型当日协议价/库存并写回 resource 价格日历。
+
+---
+
+## 前端必改（房务管家，mmg）
+
+### 1. 发起询房弹窗：酒店栏「下拉」改「候选 list」
+- 数据源改调 `GET /v3/admin/hotel-candidates`（传 orderId/requirementId/dayNumber/stayDate，CUSTOM 不传 city）→ 列**全部在售酒店**（池内/定制师点名带徽章排前），替换原「候选池摘要（2 家）」。
+- 候选项 `candidates[]` **本次新增 5 字段**：`contactPerson`（联系人）、`contactWechat`（联系人微信）、`settleType`（结算类型）、`paymentMode`（结算模式）、`hotelType`（住宿形态）。
+
+### 2. 房型下拉：用候选项 roomTypes 联动
+- 选定酒店后，房型下拉用该候选项的 `roomTypes[]`（`roomTypeId`/`name`/协议价/可用数）生成 = 该酒店**真实房型**，替换原 `room_category` 字典固定枚举。
+
+### 3. 联系人/微信：只读展示（资源带出）
+- 弹窗「联系人」「联系人微信」两栏改**只读**，值从选中候选项的 `contactPerson`/`contactWechat` 回显（resource 单源）。
+- 发起询房 `POST /v3/admin/order/inquiry/send` 的 `contactName`/`contactWechat` 入参**已废弃**（后端按 hotelId 从 resource 取，前端传了也忽略），无需再传。
+
+### 4. 询房正文：发起前预览（新端点）
+- 新增 `POST /v3/admin/order/inquiry/preview`，body `{hotelId, stayDate, nights, roomCount, roomCategory, messageBody(选填)}`。
+- 返回 `{messageBody(渲染后最终文案), contactName, contactWechat}`——发起前预览将发出去的文案（messageBody 留空走系统模板），所见即所发；联系人同样 resource 带出只读。
+
+### 5. 回填弹窗：可改协议价/库存写回酒店日历
+- `POST /v3/admin/order/inquiry/{inquiryId}/reply` **新增 4 个可选字段**：
+  - `roomTypeId`：改哪个房型（从候选 roomTypes 带入）
+  - `newProtocolPrice`：新协议价（选填）
+  - `newStock`：新库存（选填，当日基准库存 stock）
+  - `syncToCalendar`：是否写回酒店价格日历（默认 false）
+- 房务勾选「写回」（`syncToCalendar=true`）+ 填新协议价/新库存 → 后端写回 resource 价格日历（单源）；**不勾或不填则只记本次回填、不碰酒店主数据**。
+
+---
+
+## 后端行为（前端知悉即可）
+- 联系人/微信单一真相是 resource 酒店主数据：候选 list、send、preview 都从这里取。测试库当前 wechat 列暂无数据 → contactWechat 多为空，**酒店资料维护了微信后即自动带出**。
+- 回填写回幂等（绝对值覆盖）；写回失败只记日志、不阻断回填主流程；写回操作有审计日志（改动人/内容）。
+- preview / send 共用同一套渲染逻辑（所见即所发）。
+
+---
+
+## 测试服实测
+- 发起侧（#4404，已通过）：候选 `contactPerson` 真值带出（嘉世豪前台/王经理/成悦前台等）；preview 留空走系统模板+联系人插入、传入原样回显，核 DB 一致。
+- 回填侧（#4405，已通过）：正例 `syncToCalendar=true` + newProtocolPrice=333/newStock=9 → resource 价格日历 protocol_price 320→**333**、stock 20→**9**（stock_used/status 不变）；反例 `syncToCalendar=false`（即使带新值）→ 价/库存不变（开关生效）。核 DB 一致。
+- 提示：回填 `roomTypeId` 请务必从所选酒店候选的 `roomTypes` 取（须为该酒店真实房型），后端将校验房型归属该酒店。