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

房需求提交+回显统一收口进「订单调整」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 兼容期内不会立即下线。