docs(changelog-v2): 房需求提交+回显统一收口进 adjustment snapshot/submit + 旧 PUT deprecated (#4515 PR#4520)

changelogs-v2/2026-06/32_4520_房需求提交回显统一收口adjustment快照提交-修改接口-管理后台.md

@@ -0,0 +1,59 @@
+# 房需求提交+回显统一收口进「订单调整」snapshot/submit（弃用旧 PUT /hotel-requirement）
+
+> 变更类型：🔁 接口迁移 + 出参新增字段 + 入参字段清理 + 旧端点 Deprecated
+> 端类型：管理后台（定制师·房需求）
+> 日期：2026-06-27 ｜ 工单：#4515 ｜ PR：#4520 ｜ 服务：hl-order-service-v3（已部署测试服 + 双实例 health UP + API round-trip 实测通过）
+
+---
+
+## 背景
+
+房需求（逐晚 `days[].segments[].candidates[]` 段×候选结构）的**提交**与**回显**统一收口到「订单调整」的两个接口，前端不再使用独立的旧 PUT 端点：
+
+- 提交：`POST /v3/admin/order/{id}/adjustment/submit`（`updates.hotelRequirement`）
+- 回显：`GET /v3/admin/order/{id}/adjustment/snapshot?scope=HOTEL_REQ`（`hotelRequirement.days`）
+
+---
+
+## 一、回显（GET snapshot）：`hotelRequirement` 新增 `days` 嵌套结构
+
+`GET /v3/admin/order/{id}/adjustment/snapshot?scope=HOTEL_REQ` 出参 `data.hotelRequirement` **新增 `days[].segments[].candidates[]`**，是当前 active 房需求的**无损回显**，结构与提交入参完全一致，可直接回填编辑表单、改完原样重交：
+
+```
+hotelRequirement: {
+  id, version, status, remark, specialTags,         // specialTags 现已回填（此前恒 null）
+  claimerId, claimerName, claimedAt,
+  days: [                                            // ✅ 新增
+    { dayNumber, segments: [
+        { roomCount, roomCategory, budget, remark,
+          candidates: [ { hotelId, hotelName, roomTypeId, roomTypeName, protocolPrice, remark } ] }
+    ] }
+  ]
+}
+```
+
+- **前端收益**：有 active 房需求时直接读 `hotelRequirement.days` 做回显，**不必再为房需求回显单独拉「行程安排 Tab」`GET /v3/admin/order/{id}/itinerary`**。
+- **删字段**：`hotelRequirement.totalRoomCount` / `roomTypeSummary` 已移除（此前恒为 null，无值）。
+- `hotelDayDefaults` 仍保留，定位调整为「仅某晚**无** active 房需求时的三级兜底预填建议（行程酒店节点/城市占位）」；有 active 需求时以 `hotelRequirement.days` 为准回显。
+
+## 二、提交（POST submit）：`updates.hotelRequirement` 入参清理 + 校验收紧
+
+`POST /v3/admin/order/{id}/adjustment/submit` 的 `updates.hotelRequirement` 提交体：
+
+- **结构不变**：仍是 `{ specialTags?, remark?, days[].segments[].candidates[] }`（与旧 PUT body 同源）。
+- **删字段**：不要再传 `totalRoomCount` / `roomTypeSummary`（后端从不读取，已从入参移除）。
+- **校验收紧（恢复与旧 PUT 等价的级联校验）**：`days` 必传且非空；逐项 `dayNumber` 必填、`segments` 非空、`roomCount` 必填、`candidates` 非空。违反返回 `code 400`（实测：空 days / `dayNumber=null` / 空 candidates 均被 400 拒）。此前经调整接口提交这些非法值会被静默落库，现已堵住。
+
+## 三、旧端点 `PUT /v3/admin/order/{id}/hotel-requirement` 标记 Deprecated
+
+- 该端点**仍可用**（保留兼容期），但已标记 `@Deprecated`，请前端迁移到 `POST .../adjustment/submit` 的 `updates.hotelRequirement`。迁移完成后端将下线该端点（届时另行通知）。
+- 同 Controller 的 dispatch / reject / assign / room / urgent 等端点**不受影响**。
+
+## 四、错误码说明
+
+- 房需求提交的历史错误码 `582011`～`582018`（days 长度 / dayNumber / roomCount / roomCategory 等）**当前不返回**（历史死码）。实际生效的校验为：`@Valid` 字段校验 `400` + `587xxx`（终态 587002 / 已过天 587030）+ 团期阶段闸。
+- `candidates[].hotelId` 自 #4204 起为**选填**（支持「只提房数、酒店留房控统筹」的无酒店候选）；前端旧约定若视为必填，以后端选填为准。
+
+---
+
+> 后端已部署测试服 + 双实例 health UP；API round-trip 实测：snapshot 回显 `hotelRequirement.days` 段×候选 + 候选 protocolPrice + specialTags 与 DB 逐字段一致；非法提交（空 days / dayNumber=null / 空 candidates）均 400 拒绝、无副作用。前端按上述迁移到 snapshot/submit 即可，旧 PUT 兼容期内不会立即下线。