From a4f4889e0906e2a6662b0806269dd602fde93a6b Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 27 Jun 2026 17:57:44 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E6=88=BF=E9=9C=80?= =?UTF-8?q?=E6=B1=82=E6=8F=90=E4=BA=A4+=E5=9B=9E=E6=98=BE=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E6=94=B6=E5=8F=A3=E8=BF=9B=20adjustment=20snapshot/su?= =?UTF-8?q?bmit=20+=20=E6=97=A7=20PUT=20deprecated=20(#4515=20PR#4520)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...统一收口adjustment快照提交-修改接口-管理后台.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 changelogs-v2/2026-06/32_4520_房需求提交回显统一收口adjustment快照提交-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/32_4520_房需求提交回显统一收口adjustment快照提交-修改接口-管理后台.md b/changelogs-v2/2026-06/32_4520_房需求提交回显统一收口adjustment快照提交-修改接口-管理后台.md new file mode 100644 index 0000000..9bb75d3 --- /dev/null +++ b/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 兼容期内不会立即下线。