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