docs(changelog): 配房需求酒店选择增强 #4047(候选API keyword/limit + 预算强制协议价 + 多选)

changelogs-v2/2026-06/19_4047_配房需求酒店选择增强-候选API关键词地区搜索+默认10+预算强制协议价-修改接口-管理后台.md

@@ -0,0 +1,79 @@
+# 配房需求·酒店选择增强 — 候选 API 关键词地区搜索 + 默认10 + 预算强制协议价 — 修改接口 — 管理后台
+
+> 变更类型：✨ 功能增强（候选 API 加 keyword/limit）+ 🔧 行为变更（需求提交预算服务端强制=协议价）
+> 端类型：管理后台（定制师 → 调整订单 → 酒店安排）
+> 日期：2026-06-19
+> 服务：hl-order-service-v3 + hl-resource-service
+> PR：https://git.1814.love:8443/wx/HL/pulls/4050 （Closes #4047）
+
+---
+
+## ⚠️ 关键说明（给前端）
+
+定制师配房需求的「酒店安排」要从「城市/区域自由文本 + 预算可改」改为 **搜索下拉框选酒店（带订单快照特殊标记）+ 预算显示协议价不可改 + 默认10 + 地区关键词搜 + 酒店可多选**。
+
+后端已就位（本次新增 + 现成字段），前端按下面接：
+
+1. 下拉酒店候选用现成 **`GET /v3/admin/hotel-candidates`**，本次加 `keyword`（关键词跨地区搜）+ `limit`（默认10）两参。
+2. 候选项已返 **`protoPrice`（协议价）** 和 **`isPoolMatch`（产品池内=订单快照特殊标记）+ 池内徽章**，直接用。
+3. **预算（budget）现服务端强制=协议价**：前端把预算做成**只读显示** `protoPrice` 即可；提交时传什么后端都会覆盖成协议价（防篡改）。
+4. **酒店可多选**：每晚酒店是数组（`days[].hotels[]`），多选直接放多个；后端按每个酒店各取协议价。
+
+测试服双服务已部署 health UP，9443 实测：默认返10个带协议价+池内标记、keyword=海拉尔跨地区返海拉尔酒店、limit=3 截断，均通过。
+
+---
+
+## 1. 候选 API 加 keyword + limit（修改接口）
+
+**`GET /v3/admin/hotel-candidates`**（路径不变，新增 2 个可选入参）
+
+| 入参 | 说明 |
+|---|---|
+| keyword（新增，可选）| 关键词跨地区搜酒店（匹配酒店名/城市/省份/地址）。**非空时突破单城限定**，跨城/省搜。下拉是酒店级、选不了城市，地区搜就用它 |
+| limit（新增，可选）| 返回条数上限，**默认 10**，范围 1-50。排序后取前 N（产品池内优先） |
+
+- keyword 为空 → 维持现行为（按订单快照当晚城市搜全城）。
+- 出参结构不变；每项已含 `protoPrice`（协议价，resource 价格日历）、`isPoolMatch`（是否产品池内）、池内徽章/推荐理由。
+
+```bash
+# 默认(无 keyword)：返当晚城市候选, 默认10个
+curl -k "https://api.test.1814.love:9443/v3/admin/hotel-candidates?orderId={id}&dayNumber=1" -H "Authorization: Bearer <token>"
+# 关键词跨地区搜
+curl -k "https://api.test.1814.love:9443/v3/admin/hotel-candidates?orderId={id}&dayNumber=1&keyword=海拉尔&limit=10" -H "Authorization: Bearer <token>"
+```
+
+响应候选项关键字段：
+
+| 字段 | 说明 |
+|---|---|
+| hotelId / hotelName | 酒店 ID / 名称（下拉选项）|
+| protoPrice | 协议价（预算只读显示用）|
+| isPoolMatch | 是否产品池内（订单快照特殊标记，true 显「产品池内」徽章）|
+| matchedRoomTypeId / matchedRoomTypeLabel | 匹配房型 |
+| todayAvailable / quickPickEnabled | 可用房 / 是否支持快速配房 |
+
+---
+
+## 2. 需求提交预算强制=协议价（行为变更）
+
+**`PUT /v3/admin/order/{id}/hotel-requirement`**（路径/入参结构不变）
+
+提交配房需求时，后端对每个 `days[].hotels[]` **按 (hotelId, roomCategory, 当晚 stayDate) 反查协议价并覆盖 `budget`**，前端传的 budget 不作数（真正「不能改」防篡改）。
+
+- 前端把预算字段做成只读，展示候选项的 `protoPrice` 即可。
+- 取不到协议价（无在售价格日历）时该酒店 budget 落 null，不阻断提交。
+- 跟团（GROUP）budget 传 null；自由行/私人订制按上面强制。
+
+---
+
+## 3. 酒店多选
+
+每晚酒店本就是数组（`days[].hotels[]`，≥1 项，对应「同一晚分住」），多选直接放多个酒店项，后端逐个处理（各取协议价 / roomCount 各自）。前端把单选下拉改多选即可，无需后端配合。
+
+---
+
+## 备注
+
+- 本次仅后端支撑；下拉/只读/多选/关键词框是前端 UI。
+- 团期(GROUP)配房先不做；预算强制主要面向自由行/私人订制。
+- 网关无需改：`/v3/admin/hotel-candidates` 与 `/v3/admin/order/**` 路由已覆盖。