# 房务管家·配房确认接入酒店房间库存扣减（全产品硬扣 + 库存不足拒绝）— 行为变更 — 管理后台

> 变更类型：🔧 行为变更（配房确认 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 <token>" -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/**` 路由已覆盖。