4.3 KiB
4.3 KiB
配房需求·酒店选择增强 — 候选 API 关键词地区搜索 + 默认10 + 预算强制协议价 — 修改接口 — 管理后台
变更类型：✨ 功能增强（候选 API 加 keyword/limit）+ 🔧 行为变更（需求提交预算服务端强制=协议价） 端类型：管理后台（定制师 → 调整订单 → 酒店安排） 日期：2026-06-19 服务：hl-order-service-v3 + hl-resource-service PR：wx/HL#4050 （Closes #4047）
⚠️ 关键说明（给前端）
定制师配房需求的「酒店安排」要从「城市/区域自由文本 + 预算可改」改为 搜索下拉框选酒店（带订单快照特殊标记）+ 预算显示协议价不可改 + 默认10 + 地区关键词搜 + 酒店可多选。
后端已就位（本次新增 + 现成字段），前端按下面接：
- 下拉酒店候选用现成
GET /v3/admin/hotel-candidates，本次加keyword（关键词跨地区搜）+limit（默认10）两参。 - 候选项已返
protoPrice（协议价） 和isPoolMatch（产品池内=订单快照特殊标记）+ 池内徽章，直接用。 - 预算（budget）现服务端强制=协议价：前端把预算做成只读显示
protoPrice即可；提交时传什么后端都会覆盖成协议价（防篡改）。 - 酒店可多选：每晚酒店是数组（
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（是否产品池内）、池内徽章/推荐理由。
# 默认(无 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/**路由已覆盖。