From 9e8f405d6257b799067b9b6d53b885bc2562e0c4 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sat, 20 Jun 2026 18:36:49 +0800
Subject: [PATCH] =?UTF-8?q?docs(v2):=20=E9=85=8D=E6=88=BF/=E9=80=89?=
 =?UTF-8?q?=E9=85=92=E5=BA=97=E6=B5=81=E7=A8=8B=E8=AF=84=E5=AE=A111?=
 =?UTF-8?q?=E7=82=B9=E6=94=B6=E5=8F=A3(=E5=80=99=E9=80=89=E6=88=BF?=
 =?UTF-8?q?=E5=9E=8B=E5=AF=8C=E5=8C=96+=E6=AE=B5=C3=97=E5=80=99=E9=80=89+?=
 =?UTF-8?q?=E6=B1=A0=E5=86=85=E5=BF=AB=E7=85=A7+=E7=89=B9=E6=AE=8A?=
 =?UTF-8?q?=E8=AF=89=E6=B1=82=E5=AD=97=E5=85=B8)=E5=89=8D=E7=AB=AF?=
 =?UTF-8?q?=E5=AF=B9=E6=8E=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...ž‹å¯ŒåŒ–+段候选+池内快照+特殊诉求字典-修改接å�£-管ç�†å�Žå�°.md | 142 ++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 changelogs-v2/2026-06/20_�房选酒店�程评审11点_候选房型富化+段候选+池内快照+特殊诉求字典-修改接�-管���.md

diff --git a/changelogs-v2/2026-06/20_�房选酒店�程评审11点_候选房型富化+段候选+池内快照+特殊诉求字典-修改接�-管���.md b/changelogs-v2/2026-06/20_�房选酒店�程评审11点_候选房型富化+段候选+池内快照+特殊诉求字典-修改接�-管���.md
new file mode 100644
index 0000000..50876ec
--- /dev/null
+++ b/changelogs-v2/2026-06/20_�房选酒店�程评审11点_候选房型富化+段候选+池内快照+特殊诉求字典-修改接�-管���.md
@@ -0,0 +1,142 @@
+# �修改·管���】�房/选酒店�程评审 11 点收�（候选房型富化 + 段×候选 + 池内快照 + 特殊诉求字典）
+
+> 涉� PR：#4126 / #4127 / #4135 / #4136 / #4148 / #4149（hl-order-service-v3，区县�涉 hl-resource-service）
+> 影�页�：**订�详情 → 调整订� → 酒店安排**（�房需求表�）+ 其中的**「选择酒店�弹窗**
+> 状�：已�并 dev-v3�已部署测试��实例�候选接�已网关 API 实测通过
+
+---
+
+## ⚠� 关键说明（先读）
+
+1. 这是定制师「�交�房需求�表� +「选择酒店�弹窗的一轮产�评审收�，共 11 个点，��端都�改。
+2. 两处契约�化，�端必改：
+   - **�房需求�交体** `HotelRequirementReqVO.days` 结构�级为「**段 × 候选**�（� §三-2）。
+   - **选酒店候选接�** `GET /v3/admin/hotel-candidates` 出�**富化**（真实房型/城市/区县/池内，� §三-1）。
+3. **房型下拉��用通用字典**，改由「所选酒店的真实房型�驱动；**�选酒店�能选房型**。
+4. 金�字段（�议价/标价/预算）�为 **String**（�端 @JsonSerialize），�端按字符串收。
+
+---
+
+## 一��房需求表�改动
+
+### 点1 删「当晚备注�
+- �晚的「当晚备注（当晚整体安排说明）�**整�去掉**（输入框删除）。
+- �端 `DayHotelReq.remark` 字段已移除；行程 Tab 的 `requirementDays[].remark` 也�之废弃（新��空，�端别�展示当晚备注）。
+- **�留**「该酒店备注�（�为�个候选酒店的备注，�点8 `CandidateHotel.remark`）。
+
+### 点2 删「城市/区域�输入（纯�端）
+- �晚那个「城市/区域（如 拉�市区）�输入框**删掉**——它本就没进�端，且与「选择酒店�弹窗自带的�索框��。
+
+### 点3 特殊诉求改字典（多选 + �许自定义）
+- 「特殊诉求�从自由文本标签改为**绑定字典** `house_special_demand`，�端�**多选**，**��许回车加自定义**。
+- 字典加载：`GET /admin/dict/data/house_special_demand` → `[{dictValue, dictLabel}]`（当�值：安�楼层/高楼层/景观房/无烟房/�早�/��早/�加床/�拆分�床/相邻房间/远离电梯，���在字典管�增删）。
+- �交字段��，�是 `specialTags: List<String>`（存字典 value，自定义则存原文）。
+
+### 点8 酒店支�「段 × 候选�（�交体结构�级，�点）
+两个**独立**维度（产�确认都�）：
+- **分�**：�一晚�两家（房数相加）—— 一晚有多个 **段(segment)**。
+- **候选**：定制师对�段�多家心仪酒店，**房控��择一**回� —— 一段有多个 **候选(candidate)**。
+
+UI：
+- �晚�「+ 加一段��酒店（�一晚分�）�= 加 segment（�段独立填 房数/房型/预算/段备注）。
+- �段的「酒店�框支�**多选**候选酒店（房控择一）；�个候选�填该酒店备注。
+- 候选酒店会自动进候选接�的「定制师点��高亮（`isConsultantRecommended`）。
+
+---
+
+## 二�选择酒店弹窗 + 房型
+
+### 点4 �议价按真实房型 / 点6 �用房按真实房型 / 点7 房型按真实酒店
+- 候选接�现返回�家酒店的**真实房型列表** `roomTypes[]`（�自 resource 价格日历/库存）。
+- �端：
+  - **房型下拉**改由所选酒店的 `roomTypes[]` 驱动（`name`/`bedType`/`maxOccupancy`），**�选酒店则房型��选**；��用通用 `room_category` 字典。
+  - **�议价**显示所选房型的 `roomTypes[].protocolPrice`（�是酒店级起步价 `protoPrice`）。
+  - **�用房**显示所选房型的 `roomTypes[].available`（+ `inventoryStatus` AVAILABLE/FULL/CLOSED）。
+- 注：测试酒店需 resource 侧�了价格日历+库存�有 `roomTypes` 数�（无则该酒店 roomTypes 为空/价 null）。
+
+### 点5 城市 / 点10 区县
+- 候选项新增 `city`（城市，如 呼伦�尔市）+ `district`（区/县，如 满洲里市）。
+- 选酒店列表/候选展示加「城市�「区/县�两列。
+
+### 点9+11 池内徽章：按行程天数 + 从订�产�快照�
+- 「池内�徽章 `isPoolMatch` 语义修正为：**该酒店在「订�产�快照�里当天当档（order.tierSeq）的产�酒店池中**。
+  - 按**行程天数**：第1天�标第1天产�行程的酒店，第2天标第2天的。
+  - 从**订�产�快照冻结值**�（� live 产��置）——产�下��被改�影�已下�订�的池内判定。
+- �端无需改调用方�，照常按 `dayNumber` 查候选，`isPoolMatch`/`poolMatchBadge` 直接用。
+
+---
+
+## 三�接�契约
+
+### 1. 候选接�出�（新增字段）
+`GET /v3/admin/hotel-candidates?orderId=&dayNumber=&roomCategory=&roomCount=&keyword=&limit=`
+出� `data.candidates[]`（`HotelCandidateRespVO.Candidate`）**新增**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `city` | String | 酒店所在城市（如 呼伦�尔市） |
+| `district` | String | 酒店所在区/县（如 满洲里市） |
+| `roomTypes` | List | 该酒店当日真实房型列表（�下） |
+
+`roomTypes[]`（`RoomTypeOption`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `roomTypeId` | String | 房型 ID |
+| `name` | String | 房型�称（如 普通标间） |
+| `bedType` | String | 床型（如 TWIN_BED） |
+| `maxOccupancy` | Integer | 最大入�人数 |
+| `available` | Integer | 今日�用房数 |
+| `stock` | Integer | 总库存 |
+| `protocolPrice` | String | �议价（金�字符串） |
+| `basePrice` | String | 标价 |
+| `inventoryStatus` | String | AVAILABLE / FULL / CLOSED |
+
+`isPoolMatch`（既有字段，语义改为按天+快照）�`protoPrice`/`matchedRoomType*`（既有，��兼容�留）��。
+
+### 2. �房需求�交体（结构�级）
+`HotelRequirementReqVO`（�交�房需求 / 调整订� hotelRequirement.days �构）：
+```
+{
+  "days": [
+    {
+      "dayNumber": 1,
+      "segments": [                      // � 原 hotels[] 改为 segments[]（分�段）
+        {
+          "roomCount": 2,
+          "roomCategory": "TWIN",
+          "budget": "600.00",            // �空(�端�查�议价覆盖)
+          "remark": "段备注",
+          "candidates": [                // � 候选酒店列表(房控择一)
+            { "hotelId": 80001, "hotelName": "拉�西�宾馆", "remark": "�湖一侧" },
+            { "hotelId": 80002, "hotelName": "山景酒店", "remark": "��早" }
+          ]
+        }
+      ]
+    }
+  ],
+  "specialTags": ["安�楼层", "�早�"],   // 字典 house_special_demand 的 value(�许自定义)
+  "remark": "整�备注"
+}
+```
+- **去掉**：`days[].remark`（当晚备注）�`days[].hotels[].source`（死字段）。
+- �端兼容旧 `hotels[]` 结构读�（存�订��报错），但**新�交请用 `segments[].candidates[]`**。
+
+### 3. 特殊诉求字典
+`GET /admin/dict/data/house_special_demand` → `data: [{dictValue, dictLabel, ...}]`。
+
+---
+
+## 四�curl 实测（候选接�，2026-06-20 测试�）
+```
+GET /v3/admin/hotel-candidates?orderId=2068235380959682562&dayNumber=1&limit=3
+→ 200
+data.candidates[0]:
+  hotelName=呼伦�尔香格里拉大酒店  city=呼伦�尔市  district=满洲里市  isPoolMatch=true
+  roomTypes=[{name:普通标间, bedType:TWIN_BED, available:20, protocolPrice:"280.00", inventoryStatus:AVAILABLE}, ...]
+data.candidates[1]: 海拉尔嘉世豪酒店  district=海拉尔区  isPoolMatch=false
+```
+
+---
+
+如对契约/字段有疑问�时找�端（王�）。