From ec0ec9ede1cf6542d5ed5fa1afac263226144173 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Sat, 25 Jul 2026 11:00:58 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E9=85=92=E5=BA=97=E5=80=99?=
 =?UTF-8?q?=E9=80=89=E6=88=BF=E5=9E=8B=E7=BB=93=E7=AE=97=E4=BB=B7=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...…’店候选补é½�房型结算价-修改接å�£-管ç�†å�Žå�°.md | 421 ++++++++++++++++++
 1 file changed, 421 insertions(+)
 create mode 100644 changelogs-v2/2026-07/25_5237_酒店候选补�房型结算价-修改接�-管���.md

diff --git a/changelogs-v2/2026-07/25_5237_酒店候选补�房型结算价-修改接�-管���.md b/changelogs-v2/2026-07/25_5237_酒店候选补�房型结算价-修改接�-管���.md
new file mode 100644
index 0000000..5ce520f
--- /dev/null
+++ b/changelogs-v2/2026-07/25_5237_酒店候选补�房型结算价-修改接�-管���.md
@@ -0,0 +1,421 @@
+# �修改接�·管���】酒店候选补�房型结算价 (#5237)
+
+> **PR**: #5240 | **�务**: hl-order-service-v3 | **更新时间**: 2026-07-25 10:58
+
+## 1. 接�背景
+
+管���酒店候选列表原��在候选酒店顶层返回 `protoPrice`，�端无法确认这个价格�自哪个真实房型，也拿�到�一房型�一天的结算价。�房时如果�看房型列表或自行匹�最低价，容易把�议价和结算价�径拆到��房型。
+
+本次在候选酒店顶层补�：
+
+- `protoPriceRoomTypeId`：产生顶层 `protoPrice` 的真实房型 ID。
+- `settlementPrice`：与 `protoPriceRoomTypeId` �一房型��一天的结算价。
+
+顶层 `protoPrice`�`protoPriceRoomTypeId`�`settlementPrice` 是�一代表房型�径。未维护结算价时 `settlementPrice = null`，�会用�议价兜底。
+
+## 2. �更清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询酒店候选（4 场景统一入�） | GET | `/v3/admin/hotel-candidates` | 修改接� | 候选酒店项新增 `protoPriceRoomTypeId`�`settlementPrice` 两个出�字段；入���。 |
+
+## 3. 接�详情
+
+### 3.1 查询酒店候选（4 场景统一入�）
+
+- **使用场景**：管���在订�维度查询�一晚的候选酒店，用于�房选酒店�回显当�已�酒店�按产�池/定制师点�/资�库候选排�。
+- **认�**：需�管��� JWT。
+- **幂等性**：�读查询，幂等。
+- **��**：无接�级特殊��；�网关与�务通用��策略约�。
+
+## 4. 接�入�
+
+### 4.1 路径�数 / Query �数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `orderId` | String | 是 | 订� ID。�端 Long，JSON/Query 建议按字符串传，��长 ID 精度问题。 |
+| `dayNumber` | Integer | � | 第几天，从 1 开始；用于推算 `stayDate = departDate + dayNumber - 1`。最�值 1。 |
+| `stayDate` | String | � | 入�日期，格� `yyyy-MM-dd`；直接指定时优先于 `dayNumber` 推算。 |
+| `city` | String | � | 城市代�或城市�；未传且�关键�模�时默认�按城市�制。 |
+| `keyword` | String | � | 关键�；�空时跨城/�匹�酒店��城市��份�地�，此时 `city` ��传。 |
+| `limit` | Integer | � | 返回候选�数上�，默认 30，最� 1，最大 50。 |
+| `roomCategory` | String | � | 房型字典 code。 |
+| `roomCount` | Integer | � | 需�的房间数；最� 1。 |
+| `preferredHotelId` | String | � | 定制师指定的优先酒店 ID。�端 Long，建议字符串传。 |
+| `requirementId` | String | � | 用房需求 ID；传入�将该需求 days JSON 中当�天的酒店候选作为定制师指定候选。�端 Long，建议字符串传。 |
+
+### 4.2 请求体字段
+
+GET 接�无请求体。
+
+## 5. 出�字段
+
+统一�应结构：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | Integer | 业务状��，�功为 `200`。 |
+| `message` | String | �应消�，�功为 `�功`。 |
+| `data` | Object | 酒店候选查询出�。 |
+| `traceId` | String | 链路追踪 ID，�能为空。 |
+| `success` | Boolean | `code == 200` 时为 `true`。 |
+
+`data` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `stayDate` | String | 入�日期，格� `yyyy-MM-dd`。 |
+| `city` | String / null | 本次查询使用的城市；关键�模�或默认��城市时�为 `null`。 |
+| `productType` | String | 产�类型：`CORE` / `GROUP` / `CUSTOM`。 |
+| `candidates` | Array | 候选酒店列表，已按产�类型分�排�。 |
+
+`data.candidates[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `hotelId` | String | 酒店 ID。 |
+| `hotelName` | String | 酒店�称。 |
+| `level` | String / null | 酒店等级。 |
+| `form` | String / null | �宿形�。 |
+| `address` | String / null | 地�。 |
+| `tags` | Array<String> | ��标签；无标签时为空数组或 `null`。 |
+| `contactPerson` | String / null | �系人。 |
+| `contactWechat` | String / null | �系微信。 |
+| `settleType` | String / null | 结算类型，�值� §6.1。 |
+| `city` | String / null | 酒店所在城市。 |
+| `district` | String / null | 酒店所在区/县。 |
+| `roomTypes` | Array | 该酒店当日真实房型列表；无房型数�时为空数组。 |
+| `protoPrice` | String / null | 代表房型�议价。与 `protoPriceRoomTypeId`�顶层 `settlementPrice` �一房型�一天。 |
+| `protoPriceRoomTypeId` | String / null | 产生顶层 `protoPrice` 的真实房型 ID。无有效�售�议价时为 `null`。 |
+| `settlementPrice` | String / null | 与 `protoPriceRoomTypeId` �一房型��一天的结算价。未维护时为 `null`，�会用 `protoPrice` 兜底。 |
+| `todayAvailable` | Integer / null | 今日全房型�用房数�计。 |
+| `availFreshness` | String / null | �用数数�时效：`fresh` / `stale` / `never_checked`。 |
+| `lastCheckedAt` | String / null | 最近一次核房时间，格� `yyyy-MM-dd'T'HH:mm:ss`。 |
+| `matchedRoomTypeAvailable` | Integer / null | 匹�房型今日�用数。 |
+| `matchedRoomTypeId` | String / null | 匹�的房型 ID。 |
+| `matchedRoomTypeLabel` | String / null | 匹�的房型中文。 |
+| `quickPickEnabled` | Boolean / null | 是�支�快速�房。 |
+| `quickPickDisabledReason` | String / null | 置�原因。 |
+| `isPoolMatch` | Boolean / null | 是�产�池内。 |
+| `poolMatchBadge` | Object / null | 产�池内徽章。 |
+| `isConsultantRecommended` | Boolean / null | 是�被定制师点�。 |
+| `consultantRecommendBadge` | Object / null | 定制师点�徽章。 |
+| `historyMatchScore` | Number / null | 历�匹�度，范围 0-1。 |
+| `score` | Number / null | 排�分数。 |
+| `recommendation` | String / null | 推��由。 |
+| `recommended` | Boolean / null | 是�为推�候选。 |
+| `recommendSource` | String / null | 推���，� §6.4。 |
+| `historyScoreStub` | Boolean / null | 历�命中分数是�为 stub。 |
+| `isCurrentlyAssigned` | Boolean / null | 是�为本天当�已�酒店。 |
+| `assignedRoomTypeId` | String / null | 本天当�已�的房型 ID；`isCurrentlyAssigned=true` 时�用于预填原房型。 |
+
+`data.candidates[].roomTypes[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `roomTypeId` | String | 房型 ID。 |
+| `name` | String / null | 房型�称。 |
+| `roomCategory` | String / null | 房型分类字典值。 |
+| `bedType` | String / null | 床型，已按字典尽�翻译；字典缺失时�回退为 code。 |
+| `maxOccupancy` | Integer / null | 最大入�人数。 |
+| `available` | Integer / null | 今日�用房数；`unlimited=true` 时为 `null`，语义为��。 |
+| `unlimited` | Boolean | 是���库存。 |
+| `stock` | Integer / null | 当��用房；`unlimited=true` 时为 `null`。 |
+| `protocolPrice` | String / null | 该房型当日�议价。 |
+| `settlementPrice` | String / null | 该房型当日结算价。 |
+| `basePrice` | String / null | 标价/挂牌价。 |
+| `inventoryStatus` | String | 库存状�，� §6.2。 |
+
+徽章对象字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `label` | String | 中文徽章文字。 |
+| `color` | String | 徽章色，� §6.5。 |
+| `tooltip` | String | 悬浮�示。 |
+
+## 6. 枚举 / 数�字典
+
+### 6.1 `settleType`
+
+**所属字段**：`data.candidates[].settleType` | **类型**：String | **必填**：�
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `cash` | 现付 | 到店或线下现金类结算。 |
+| `sign` | 签� | 供应商签�结算。 |
+| `company` | 公�付 | 公�统一付款结算。 |
+
+### 6.2 `inventoryStatus`
+
+**所属字段**：`data.candidates[].roomTypes[].inventoryStatus` | **类型**：String | **必填**：是
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `AVAILABLE` | �售 | 有余�，或 `unlimited=true` ��库存。 |
+| `FULL` | 满房 | 有日历记录，但库存为 0。 |
+| `CLOSED` | 未开放 | 无该日价格日历记录。 |
+
+### 6.3 `availFreshness`
+
+**所属字段**：`data.candidates[].availFreshness` | **类型**：String | **必填**：�
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `fresh` | 最新 | �用于快速�房判断。 |
+| `stale` | 过期 | 核房数�过期。 |
+| `never_checked` | 从未核房 | 无�用核房数�。 |
+
+### 6.4 `recommendSource`
+
+**所属字段**：`data.candidates[].recommendSource` | **类型**：String | **必填**：�
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `PRODUCT_POOL` | 产�池 | �自产�池候选。 |
+| `CONSULTANT` | 定制师点� | �自定制师指定候选。 |
+| `RESOURCE_LIB` | 资�库 | �自资�库候选。 |
+
+### 6.5 `Badge.color`
+
+**所属字段**：`poolMatchBadge.color` / `consultantRecommendBadge.color` | **类型**：String | **必填**：�
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `blue` | �色 | 普通推�或池内标识。 |
+| `gold` | 金色 | 高优先级推�标识。 |
+| `gray` | �色 | 弱�示标识。 |
+
+## 7. 错误�
+
+| code | �义 | 触�场景 |
+|------|------|----------|
+| `200` | �功 | 查询�功。 |
+| `400` | �数错误 | `orderId` 为空�`dayNumber < 1`�`limit` 超出 1-50�`roomCount < 1`�日期格��是 `yyyy-MM-dd` 等�数绑定或校验失败。 |
+| `401` | 未认� | JWT 缺失或无效。 |
+| `403` | 无�� | 当�账�无�访问该管���接�或订�数�。 |
+| `581007` | 订��存在 | `orderId` 对应订��存在。 |
+| `500` | �务内部错误 | �预期异常。 |
+
+## 8. 示例（3 组：典型 / 边界 / 异常）
+
+### 8.1 典型�功
+
+**请求**：
+
+```http
+GET /v3/admin/hotel-candidates?orderId=100001&dayNumber=1&stayDate=2026-07-25&limit=30&roomCount=2 HTTP/1.1
+Authorization: Bearer <admin-jwt>
+```
+
+无请求体。
+
+**�应**：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "stayDate": "2026-07-25",
+    "city": null,
+    "productType": "CORE",
+    "candidates": [
+      {
+        "hotelId": "2023714929877450753",
+        "hotelName": "测试酒店",
+        "level": "舒适型",
+        "form": "HOTEL",
+        "address": "呼伦�尔市海拉尔区测试路 1 �",
+        "tags": ["�议酒店"],
+        "contactPerson": "张��",
+        "contactWechat": "hotel_mgr",
+        "settleType": "sign",
+        "city": "呼伦�尔市",
+        "district": "海拉尔区",
+        "protoPrice": "280.00",
+        "protoPriceRoomTypeId": "2023727403196502017",
+        "settlementPrice": "279.00",
+        "todayAvailable": 7,
+        "availFreshness": "fresh",
+        "lastCheckedAt": null,
+        "matchedRoomTypeAvailable": 7,
+        "matchedRoomTypeId": "2023727403196502017",
+        "matchedRoomTypeLabel": "豪�大床房",
+        "quickPickEnabled": true,
+        "quickPickDisabledReason": null,
+        "isPoolMatch": true,
+        "poolMatchBadge": {
+          "label": "产�池内",
+          "color": "blue",
+          "tooltip": "本酒店在产�池内，优先推�"
+        },
+        "isConsultantRecommended": false,
+        "consultantRecommendBadge": null,
+        "historyMatchScore": 0.85,
+        "score": 1185.0,
+        "recommendation": "池内 · 历��作 8 ��功率 95%",
+        "recommended": true,
+        "recommendSource": "PRODUCT_POOL",
+        "historyScoreStub": true,
+        "isCurrentlyAssigned": false,
+        "assignedRoomTypeId": null,
+        "roomTypes": [
+          {
+            "roomTypeId": "2023727403196502017",
+            "name": "豪�大床房",
+            "roomCategory": "KING",
+            "bedType": "大床",
+            "maxOccupancy": 2,
+            "available": 7,
+            "unlimited": false,
+            "stock": 7,
+            "protocolPrice": "280.00",
+            "settlementPrice": "279.00",
+            "basePrice": "568.00",
+            "inventoryStatus": "AVAILABLE"
+          }
+        ]
+      }
+    ]
+  },
+  "traceId": "trace-20260725-0001",
+  "success": true
+}
+```
+
+### 8.2 边界情况
+
+**场景说明**：代表房型有�议价但未维护结算价，顶层 `settlementPrice` 返回 `null`，�使用 `protoPrice` 兜底。
+
+**请求**：
+
+```http
+GET /v3/admin/hotel-candidates?orderId=100001&stayDate=2026-07-25&keyword=%E6%B5%B7%E6%8B%89%E5%B0%94&limit=1 HTTP/1.1
+Authorization: Bearer <admin-jwt>
+```
+
+无请求体。
+
+**�应**：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "stayDate": "2026-07-25",
+    "city": null,
+    "productType": "CUSTOM",
+    "candidates": [
+      {
+        "hotelId": "2023714929877450753",
+        "hotelName": "测试酒店",
+        "settleType": "cash",
+        "protoPrice": "280.00",
+        "protoPriceRoomTypeId": "2023727403196502017",
+        "settlementPrice": null,
+        "roomTypes": [
+          {
+            "roomTypeId": "2023727403196502017",
+            "name": "豪�大床房",
+            "available": 7,
+            "unlimited": false,
+            "protocolPrice": "280.00",
+            "settlementPrice": null,
+            "basePrice": "568.00",
+            "inventoryStatus": "AVAILABLE"
+          }
+        ],
+        "quickPickEnabled": true,
+        "recommended": true,
+        "recommendSource": "RESOURCE_LIB"
+      }
+    ]
+  },
+  "traceId": "trace-20260725-0002",
+  "success": true
+}
+```
+
+### 8.3 业务失败（异常）
+
+**场景说明**：`orderId` 未传，触��数校验失败。
+
+**请求**：
+
+```http
+GET /v3/admin/hotel-candidates?stayDate=2026-07-25 HTTP/1.1
+Authorization: Bearer <admin-jwt>
+```
+
+无请求体。
+
+**�应**：
+
+```json
+{
+  "code": 400,
+  "message": "orderId �能为空",
+  "data": null,
+  "traceId": "trace-20260725-0003",
+  "success": false
+}
+```
+
+## 9. 业务边界
+
+- **适用场景**：管���按订�和入�日查询酒店候选；`stayDate` �直接传，也�通过 `dayNumber` 和订�出�日推算。
+- **�适用场景**：�用于�端直接查询内部资��务；本文��述管��� `/v3/admin/hotel-candidates`。
+- **特殊边界**：顶层 `protoPrice`�`protoPriceRoomTypeId`�`settlementPrice` 必须按�一代表房型�解；`settlementPrice = null` 表示该代表房型当天未维护结算价。
+- **特殊边界**：`roomTypes[].settlementPrice` 是�个房型自己的当日结算价；顶层 `settlementPrice` �对应 `protoPriceRoomTypeId` 指�的代表房型。
+
+## 10. 修改��对比
+
+### 10.1 字段级对比
+
+| 字段 | 改� | 改� |
+|------|------|------|
+| `data.candidates[].protoPriceRoomTypeId` | �返回 | 返回产生顶层 `protoPrice` 的真实房型 ID；无有效�售�议价为 `null`。 |
+| `data.candidates[].settlementPrice` | �返回 | 返回与 `protoPriceRoomTypeId` �一房型��一天的结算价；未维护为 `null`。 |
+| `data.candidates[].protoPrice` | 已返回，但无法判断�自哪个房型 | �返回原字段，并与新增的 `protoPriceRoomTypeId`�顶层 `settlementPrice` 组��一代表房型�径。 |
+
+### 10.2 行为级对比
+
+| 行为 | 改� | 改� |
+|------|------|------|
+| 候选酒店顶层价格展示 | �能拿到代表�议价 `protoPrice`。 | ��时拿到代表�议价�代表房型 ID�该代表房型结算价。 |
+| 结算价为空 | 顶层没有结算价字段。 | 顶层 `settlementPrice` 返回 `null`；�使用 `protoPrice` 兜底。 |
+
+## 11. 影�评估 / 回滚
+
+### 11.1 影�评估
+
+- **是�破���兼容**：�。�新增出�字段，已有字段��类型�入���。
+- **�端是�必须�步上线**：�。��端�忽略新增字段；需�展示或回填结算价的页��读�新增字段。
+- **影�已有数�**：无数��移�求；历�未维护结算价的房型按 `settlementPrice = null` 返回。
+
+### 11.2 回滚方案
+
+- **回滚方�**：回滚 PR #5240 �，顶层新增字段��返回。
+- **回滚�清�**：无�端数�清��求。
+- **回滚耗时**：按常规�务回滚�程处�。
+
+## 12. 注�事项
+
+- �端读�顶层 `settlementPrice` 时，��把 `null` 当作 `protoPrice`；`null` 表示未维护结算价。
+- 如需定�价格�自哪个房型，使用顶层 `protoPriceRoomTypeId` 去匹� `roomTypes[].roomTypeId`。
+- 金�和长 ID 在�应 JSON 中按字符串处�，例如 `"280.00"`�`"2023727403196502017"`。
+
+## 13. 关� / �系人
+
+### 13.1 链接
+
+- **Issue**: [#5237](https://git.1814.love:8443/wx/HL/issues/5237)
+- **PR**: [#5240](https://git.1814.love:8443/wx/HL/pulls/5240)
+- **Merge commit**: [dc6e2ef](https://git.1814.love:8443/wx/HL/commit/dc6e2ef6c2b49bd503353814f85723566d4413c6)
+
+### 13.2 �系人
+
+- **�端负责人**: @yst