# 【前端对接·管理后台】资源价格日历支持 unlimitedStock 显式清空库存

> Issue: [wx/HL#4842](https://git.1814.love:8443/wx/HL/issues/4842)  
> PR: [#4843](https://git.1814.love:8443/wx/HL/pulls/4843)  
> 服务: `hl-resource-service`  
> 日期: 2026-07-08  
> 影响范围: 景区、游玩项目、服务、服务人员价格日历弹窗的库存清空

## 1. 结论

- 景区、游玩项目、服务、服务人员价格日历请求体新增 `unlimitedStock`，规则对齐酒店房型。
- 前端要把“清空库存/不限库存”作为显式动作提交：`unlimitedStock=true`。
- 仅把 `stock` 置空、不传 `unlimitedStock`，后端会保留已有库存，避免误清历史库存。
- 新建日期时 `stock=null` 仍表示不限库存；本字段主要解决“已有库存日期改回不限库存”。

## 2. 变更接口清单

| # | 模块 | 方法 | 路径 | 变更类型 |
|---|------|------|------|----------|
| 1 | 景区价格日历 | PUT | `/admin/scenic/spot/{scenicId}/prices` | 请求体新增字段 |
| 2 | 游玩项目价格日历 | PUT | `/admin/activity/item/{activityId}/prices` | 请求体新增字段 |
| 3 | 服务价格日历 | PUT | `/admin/service/item/{serviceId}/prices` | 请求体新增字段 |
| 4 | 服务人员价格日历 | PUT | `/admin/staff/type/{staffType}/prices` | 请求体新增字段 |

## 3. 新增入参

| 字段 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| `unlimitedStock` | Body | Boolean | 否 | `true` 表示显式清空该日期库存为不限；`false/不传` 表示 `stock=null` 时不覆盖已有库存 |

## 4. 正确 payload

| 场景 | payload | 结果 |
|------|---------|------|
| 设置有限库存 | `{ "stock": 50, "unlimitedStock": false }` | 库存更新为 50 |
| 已有库存改回不限库存 | `{ "stock": null, "unlimitedStock": true }` | 数据库 `stock=NULL` |
| 编辑价格但不改库存 | `{ "stock": null }` | 保留原库存 |

示例：

```json
{
  "startDate": "2026-09-18",
  "endDate": "2026-09-18",
  "protocolPrice": 60.00,
  "settlementPrice": 59.00,
  "stock": null,
  "unlimitedStock": true,
  "status": "AVAILABLE",
  "remark": "改为不限库存"
}
```

## 5. 数据库行为

| 前端提交 | 已有 `stock` | 保存后 `stock` |
|----------|--------------|----------------|
| `stock=50, unlimitedStock=false/不传` | 任意 | `50` |
| `stock=null, unlimitedStock=true` | `50` | `NULL` |
| `stock=null, unlimitedStock=false/不传` | `50` | `50` |

`stock=NULL` 表示不限库存；可售判断和扣减逻辑已按这个口径处理。

## 6. 不影响范围

- 不改报价、订单固化口径，现有报价和订单仍按协议价等既有字段使用。
- 不改价格日历返回结构。
- 不影响备品管理；备品没有价格日历。

## 7. 后端验证

聚焦单测已覆盖 4 类资源：

```text
ScenicPriceCalendarUnlimitedStockTest
ActivityPriceCalendarUnlimitedStockTest
ServicePriceCalendarUnlimitedStockTest
StaffPriceCalendarUnlimitedStockTest
```

测试环境已部署 `hl-resource-service`，Deploy Panel task `71561a2f` 返回 success。网关 API 验证结果：

| 模块 | 验证方式 | 结果 |
|------|----------|------|
| 景区 | `2026-12-31` 设 `stock=50` → `unlimitedStock=true` 清空 → 回滚原值 | 通过 |
| 游玩项目 | 同上 | 通过 |
| 服务 | 同上 | 通过 |
| 服务人员 | `OTHER/2026-12-31` 新建 `unlimitedStock=true` → 回读 `stock=null` → 删除恢复空 | 通过 |

说明：测试环境服务人员价格日历当前 `stockEnabled=false`，所以“已有有限库存清空”分支不在测试库做 SQL 写入验证，避免污染 `GUIDE` 现有库存数据；该分支由 `StaffPriceCalendarUnlimitedStockTest` 覆盖。