diff --git a/changelogs-v2/2026-06/19_4029_配房确认接入房间库存扣减-全产品硬扣+库存不足拒绝-行为变更-管理后台.md b/changelogs-v2/2026-06/19_4029_配房确认接入房间库存扣减-全产品硬扣+库存不足拒绝-行为变更-管理后台.md new file mode 100644 index 0000000..636d2a0 --- /dev/null +++ b/changelogs-v2/2026-06/19_4029_配房确认接入房间库存扣减-全产品硬扣+库存不足拒绝-行为变更-管理后台.md @@ -0,0 +1,72 @@ +# 房务管家·配房确认接入酒店房间库存扣减(全产品硬扣 + 库存不足拒绝)— 行为变更 — 管理后台 + +> 变更类型:🔧 行为变更(配房确认 submit 接入房间库存扣减;新增可能的拒绝错误码 808901) +> 端类型:管理后台(房务管家 → 提交配房方案 / 删除配房) +> 日期:2026-06-19 +> 服务:hl-order-service-v3(house 模块) +> PR:https://git.1814.love:8443/wx/HL/pulls/4036 (Closes #4029) + +--- + +## ⚠️ 关键说明(请前端先读这段) + +配房确认(submit)此前**不扣酒店房间库存**,仅团期(GROUP)走扣减,散客/私人订制「靠房务核房感知」→ 有超卖风险。本次改为**全产品(散客/私人订制/团期)配房确认即硬扣房间库存,库存不足则拒绝确认**。 + +**🟡 当前处于 dormant(休眠)态——前端现在不会看到任何变化:** + +房间库存扣减受全局开关 `hotel.stock.enabled` 控制,**当前默认关闭 = 所有酒店无限库存**。开关关闭时扣减为 no-op(不校验不扣减、直接成功)。所以: + +- **现在**:配房确认行为与之前完全一致,**不会**返 808901,前端无需任何改动即可正常工作。 +- **将来开关打开后**:配房确认会真正扣库存,库存不足时返 **808901** 拒绝。**建议前端提前把 808901 的提示文案/交互准备好**(提示房务「该房型当日库存不足,请换酒店或调整日期」),开关打开当天即可无缝生效。 + +已部署测试服双实例 health UP(boot 通过)、9443 实测我的接单 200、Flyway 加宽迁移成功。 + +--- + +## 1. 配房确认扣库存(全产品硬扣) + +**`POST /admin/house/assignments/requirements/{requirementId}/submit`**(路径/入参/正常返回**均不变**) + +提交配房方案时,后端对每个配房项(按 房型/入住日/房间数 单日)扣减酒店房间库存: + +| 产品类型 | 扣减行为(开关打开后) | +|---|---| +| 散客 / 私人订制(CORE/CUSTOM)| 🆕 现在也硬扣(之前不扣)| +| 团期(GROUP)| 维持硬扣(不变)| + +- 扣减幂等:同一需求重复提交同一晚不会重复扣(幂等键内部处理)。 +- 删除配房(delete)会自动释放(restore)已扣库存,不会泄漏。 + +## 2. 库存不足 → 拒绝确认(808901) + +开关打开后,任一配房项库存不足 → 整次提交失败、不落库,返: + +| 错误码 | 含义 | +|---|---| +| 808901 | 房型库存扣减失败:数量不足或日历记录缺失 | + +前端处理建议:捕获 808901 → 提示房务「所选房型当日库存不足,请更换酒店或调整入住日期」。 + +## 3. 「无限库存」如何设置 + +开关打开后,按房型粒度控制: + +- 某房型**不想限库存** → 该房型库存 `stock` 设为 **NULL(空)= 无限**,永不因库存不足被拒。 +- 设了具体数字 → 按数字扣减,不足则 808901 拒绝。 + +--- + +```bash +# 配房确认(开关关时与现状一致; 开关开且库存不足时返 808901) +curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/submit" \ + -H "Authorization: Bearer " -H "Content-Type: application/json" \ + -d '{"items":[{"dayNumber":1,"hotelId":123,"roomTypeId":456,"roomCount":2,"...":"..."}]}' +``` + +--- + +## 备注 + +- 本次仅散客/私人订制纳入;团期(GROUP)配房先不做(团期减配的库存回补为已知遗留项,待团期配房启用前补)。 +- resource 端扣减接口本就受 `hotel.stock.enabled` 控制(默认关),本次未改开关、未改 resource 服务,只改 order-v3 配房确认链路。 +- 网关无需改:`/admin/house/assignments/**` 路由已覆盖。