docs: notify house assignment price snapshot contract

changelogs-v2/2026-07/30_4782_房务配房价格快照与询房酒店名-修改接口-管理后台.md

@@ -0,0 +1,110 @@
+# 30_4782_房务配房价格快照与询房酒店名-修改接口-管理后台
+
+- 状态：frontend-todo
+- 后端工单：wx/HL#4782
+- 影响端：管理后台 `hl-ui-v2.1` 房务/订单详情
+- 关联文档：`docs/order-v3/api/API-SPEC-HOUSE-V1.1.html` v1.1.9
+
+## 背景
+
+房务配房时，协议价、结算价、成交价都需要按“配房当时”冻结到订单配房表。后续资源价格日历变化不能反向改历史订单。
+
+同时，房务在配房弹窗里改协议价/结算价时，不能默认同步到资源价格日历，必须由房务显式选择是否同步。
+
+## 前端改动点
+
+### 1. 配房提交/替换要传价格快照
+
+接口：`POST /v3/admin/order/hotel-requirements/{requirementId}/assignments`
+
+`items[]` 新增/明确字段：
+
+```json
+{
+  "protoPrice": "320.00",
+  "settlementPrice": "300.00",
+  "sellPrice": "340.00",
+  "syncProtocolPrice": false,
+  "syncSettlementPrice": false
+}
+```
+
+- `protoPrice`：协议价快照。
+- `settlementPrice`：结算价快照。
+- `sellPrice`：售价/成交价快照。
+- `syncProtocolPrice`：是否把本次 `protoPrice` 写回资源价格日历。
+- `syncSettlementPrice`：是否把本次 `settlementPrice` 写回资源价格日历。
+
+### 2. 修改单条配房也要支持同步选择
+
+接口：`PUT /v3/admin/order/assignments/{assignmentId}`
+
+请求体同样支持：
+
+```json
+{
+  "protoPrice": "330.00",
+  "settlementPrice": "310.00",
+  "sellPrice": "350.00",
+  "syncProtocolPrice": false,
+  "syncSettlementPrice": true,
+  "remark": "酒店周末加价 20"
+}
+```
+
+前端交互要求：
+
+- 房务改了协议价时，弹出是否同步到资源价格日历，结果写入 `syncProtocolPrice`。
+- 房务改了结算价时，弹出是否同步到资源价格日历，结果写入 `syncSettlementPrice`。
+- 默认不同步，不能静默写回资源。
+- `sellPrice` 不参与资源价格日历写回。
+
+### 3. 选酒店列表需要展示并携带结算价
+
+resource 候选/库存返回里会带 `settlementPrice`。前端选中房型加入已选列表时，需要保留：
+
+- 协议价：`protocolPrice`/`protoPrice`
+- 结算价：`settlementPrice`
+- 成交价：`sellPrice`
+
+提交配房时把这些快照一起传给 order-v3。
+
+### 4. 清空配房必须二次确认
+
+接口：`DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments`
+
+前端清空前必须连续两次确认：
+
+1. 第一次说明：将清空当前需求下全部已配房信息，不释放抢单人。
+2. 第二次说明：清空后需要重新配房/重新最终确认，已扣库存会释放。
+
+任一确认取消都不能调用接口。接口成功后刷新订单详情，状态会回退到配房中/待配房，不应继续显示最终确认。
+
+### 5. 询房复制话术必须带酒店名
+
+前端自拼 `messageBody` 时必须带酒店名，推荐格式：
+
+```text
+@张经理 伯爵大酒店 2026-07-24 入住 1 晚, 需要 1 间标间, 请问还有房吗? 方便报个价
+```
+
+没有联系人时不要生成孤立 `@`。
+
+后端 preview 兜底模板也会自动带酒店名，并兼容旧文案补酒店名；但前端仍应按新格式拼，避免复制框首屏缺酒店名。
+
+### 6. Internal 配房快照响应新增价格字段
+
+接口：`GET /v3/internal/house/orders/{orderId}/assignments`
+
+`items[]` 新增：
+
+```json
+{
+  "protoPrice": "320.00",
+  "settlementPrice": "300.00",
+  "sellPrice": "340.00",
+  "confirmStatus": "CONFIRMED"
+}
+```
+
+下游读取订单配房酒店信息时，以这些字段作为订单当时快照，不要重新按当前资源价格日历推断历史价格。