# 配房需求·酒店选择增强 — 候选 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/**` 路由已覆盖。