API Changelog Bot e942c1f872 docs(changelog-v2): 用房需求候选升级为方案(多房型行)+选酒店选房型(PR #4654 )前端对接

#4645 候选→方案:一个方案=1酒店+多条房型行各自房数;PUT 用房需求新增 candidates[].rooms[];
订单详情行程/房务详情 candidate/hotel 回显 rooms[](含中文label);选酒店 roomTypes[] 已就绪,前端选房型显协议价/库存。向后兼容无DB迁移。

2026-06-29 18:16:11 +08:00

5.3 KiB

原始文件 永久链接 Blame 文件历史

用房需求「候选」升级为「方案」：一个方案=1酒店+多条房型行各自房数 + 选酒店时选房型

模块：订单 · 用房需求（调整订单 → 酒店安排）/ 订单详情行程 / 房务详情（管理后台）类型：后端结构升级 + 前端对接（additive，向后兼容）日期：2026-06-29 关联：PR #4654（已合并 dev-v3 + 部署测试服 + API E2E 实测闭环）

背景（wx 手测发现）

定制师提用房需求时「海拉尔海棠·精品标间双床×2 或 海拉尔嘉世豪·标准间大床×1 + 豪华大床房×2」二选一，选不出来。根因：旧模型一个候选只能挂 1 个房型、房间数是「段级」单值，无法表达「一个方案=一家酒店的多个房型各自房数」。
「选择酒店」弹窗显示酒店级协议价/可用房 —— 协议价/库存本是房型属性，单值有误导。

模型升级（候选 → 方案）

「候选(candidate)」语义升级为「方案(option)」：一个方案 = 1 家酒店 + ≥1 条房型行，每条房型行各自房型/房数/协议价；房控仍在同段多个方案中择一回配。房数/房型/协议价从「段级 + 候选级」下沉到行级。

默认一个方案：前端每段默认建 1 个方案、方案默认 1 条房型行（与旧交互等价）。

一、提交用房需求（写）：`PUT /v3/admin/order/{id}/hotel-requirement`

请求体 days[].segments[].candidates[] 内新增 rooms[] 房型行数组：

{
  "days": [{
    "dayNumber": 1,
    "segments": [{
      "remark": "段备注（选填）",
      "candidates": [
        { "hotelId": 3001000000000000002, "hotelName": "海拉尔海棠酒店", "remark": "方案A",
          "rooms": [ {"roomTypeId": 3002000000000000002, "roomTypeName": "精品标间", "roomCategory": "STANDARD", "roomCount": 2} ] },
        { "hotelId": 2029926129876320258, "hotelName": "海拉尔嘉世豪酒店", "remark": "方案B",
          "rooms": [
            {"roomTypeId": 2029944763138936833, "roomTypeName": "标准间",   "roomCategory": "STANDARD", "roomCount": 1},
            {"roomTypeId": 2029944763138936834, "roomTypeName": "豪华大床房", "roomCategory": "DELUXE",   "roomCount": 2}
          ] }
      ]
    }]
  }]
}

rooms[] 每行字段：roomTypeId(必填,真实房型)、roomTypeName、roomCategory(房型大类字典码)、roomCount(必填,>0)、protocolPrice(选填快照,后端按协议价反查覆盖)、remark。
房间数现落在每条房型行（不再是段级单值）；一个方案可含多条房型行（=同一酒店多个房型各自房数）。
预算：segment.budget 仍是「预算/晚」，后端按协议价反查覆盖为段内各房型行协议价的最大值（前端传值不作数）。
校验：每方案至少 1 条房型行；新结构每行 roomTypeId 必填、roomCount > 0（否则 582019/582020/582016）。
兼容：旧结构（段级 roomCount/roomCategory + 候选级 roomTypeId，无 rooms[]）仍被接受，后端自动合成单行；旧前端无需立即改。

二、回显（读）：订单详情行程 + 房务详情

订单详情行程 GET /v3/admin/order/{id}/itinerary → hotelGroup.requirement.days[]：

逐家明细 hotels[] 每项、逐段候选 segments[].candidates[] 每项新增 rooms[]，每条房型行 7 字段：roomTypeId / roomTypeName / roomCategory / roomCategoryLabel(中文) / roomCount / protocolPrice / remark。
totalRoomCount / roomTypeSummary 口径：候选择一，按各段首方案的房型行汇总。
候选/段级 roomCount/roomCategory/roomTypeId 仍保留为代表值（新结构由 rooms 派生），旧前端可继续读；新前端请改用 rooms[]（权威）。

房务详情 GET /admin/house/orders/{orderId} → requirement.current.days[] 的 hotels[] 与 segments[].candidates[] 同样新增 rooms[]（同 7 字段，含中文 label）。

三、选酒店时选房型（解决背景②，纯前端）

GET /v3/admin/hotel-candidates 每家候选已返回 roomTypes[]（每个房型自带 protocolPrice 协议价 / available 可用房 / unlimited / inventoryStatus）。

【前端处理】「选择酒店」弹窗请把每家展开到房型行，让定制师选「酒店 + 房型」，协议价/可用房按所选房型显示（不要再在酒店级显示单值协议价/库存，避免误导）。
选好的房型即填入该方案的 rooms[] 一行（roomTypeId + roomTypeName + roomCategory + roomCount，可带 protocolPrice 快照）。

【前端必做】

调整订单「酒店安排」：每个方案支持多条房型行（房型 + 房间数），默认 1 方案 1 行；提交按上方 rooms[] 结构。
「选择酒店」弹窗：展开房型行，选「酒店+房型」，协议价/库存按房型显示。
订单详情/房务详情：按 candidates[].rooms[] / hotels[].rooms[] 逐房型行渲染（用 roomCategoryLabel 中文 + roomCount + protocolPrice）。

兼容性

无 DB 迁移（days 为 JSON 列）；旧订单/旧请求照常工作（后端合成单行 rooms）。
不影响金额/库存：房务配房扣库存仍走房务自填的配房项，与本需求模型解耦。

5.3 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape