docs(changelog-v2): 配房填结算价加同步到协议价开关(#4378 后端就绪,前端加开关)

changelogs-v2/2026-06/25_4377_配房填结算价加同步到协议价开关_管理后台.md

@@ -0,0 +1,37 @@
+# 配房填结算价加「同步到资源协议价」开关（写回价格日历；后端已部署，前端加开关 UI）
+
+> 变更类型：✅ 新增接口字段（additive，已部署测试服 boot + 单测充分 verify 写回逻辑）
+> 端类型：管理后台（房务管家·配房填写「结算价」处）
+> 日期：2026-06-25 ｜ 工单/PR：#4377 / #4378 ｜ 服务：hl-order-service-v3（写回经 Feign → hl-resource-service）
+> 关联：复用 #4072「房务改协议价写回 resource」现成设施；承接配房填结算价（#4367 选房型房间数）。
+
+---
+
+## ⚠️ 关键说明
+- 房务配房填「结算价」(sellPrice)时，可勾选开关「同步到资源协议价（改价格日历）」。
+- 勾选 → 后端在提交成功后（afterCommit）**用该项结算价写回 resource 价格日历的协议价**（`room_price_calendar.protocol_price`，resource 是协议价单源）。
+- 不勾（默认）→ 行为不变，只落配房、不动 resource 协议价。
+
+## 1. 提交配房 — 单项加字段
+`POST /v3/admin/order/hotel-requirements/{requirementId}/assignments` → `items[]`（`AssignmentItemReqVO`）**新增**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `syncProtocolPrice` | Boolean | 否（默认 false） | true=把本项 `sellPrice` 同步写回 resource 该(roomTypeId, stayDate)协议价；false/不传=不同步 |
+
+（`dayNumber`/`hotelId`/`roomTypeId`/`roomCategory`/`roomCount`/`sellPrice`/`remark` 字段不变。）
+
+## 2. 修改单条配房 — 同步加字段
+`PUT /v3/admin/order/assignments/{id}`（`AssignmentUpdateReqVO`）**新增** `syncProtocolPrice`（Boolean，同上语义）。
+- 勾选 `syncProtocolPrice=true` 且传了 `sellPrice` → 用 **sellPrice** 写回协议价（**优先**于 #4072 的「改 protoPrice 字段触发写回」）。
+- 不勾 → 保留 #4072 原逻辑：改了 `protoPrice` 字段才写回 protoPrice 值。
+
+## 3. 前端动作
+- 配房填「结算价」处加一个开关/勾选框「同步到资源协议价（改价格日历）」，默认**不勾**。
+- 提交时把开关值放进对应 item 的 `syncProtocolPrice`（提交配房）或 body 的 `syncProtocolPrice`（修改配房）。
+- 写回是后端行为（afterCommit 经 Feign 写 resource），前端无需关心写回细节；写回失败不阻断配房（后端只记日志）。
+
+## 4. 验证状态（诚实标注）
+- 后端已部署测试服：order-v3 双实例 boot 成功（`Started OrderServiceV3Application` 12.3s）、网关 health code=200，接口已接受 `syncProtocolPrice` 字段。
+- 写回逻辑由单测充分覆盖：`HouseAssignmentServiceTest` 56 绿（2 新用例 verify 写回 Feign 被调 + 写回值=该项 sellPrice、且 update 场景 sellPrice 优先于 protoPrice）+ 门禁全绿。
+- 端到端「真提交配房 → resource 协议价被改」因需 CLAIMING 抢单状态数据 + 真扣库存/改单源价格副作用，未单独造数据跑；逻辑正确性由单测保证。