hl-api-changelog/changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md

# 【修改接口·管理后台】资源管理新增结算价 settlementPrice 与结算方式 settleType

> **PR**: [wx/HL#4746](https://git.1814.love:8443/wx/HL/pulls/4746)，补充 [wx/HL#4774](https://git.1814.love:8443/wx/HL/pulls/4774)，迁移修正 [wx/HL#4785](https://git.1814.love:8443/wx/HL/pulls/4785)
> **Issue**: [wx/HL#4745](https://git.1814.love:8443/wx/HL/issues/4745)
> **服务**: hl-resource-service + hl-user-service
> **日期**: 2026-07-05
> **影响范围**: 管理后台资源管理：景区、游玩项目、备品、酒店、服务、服务人员

---

## 1. 关键变化

- 价格日历新增 `settlementPrice`（结算价）：景区、游玩项目、酒店房型、服务、服务人员。
- 备品没有价格日历，备品主表新增 `settlementPrice`（结算价）。
- 六类资源主数据新增/统一 `settleType`（结算方式）。
- 结算方式字典统一为 `resource_settle_type`，不要再使用旧的 `hotel_settle_type`。
- `settleType` 不传时后端默认写入 `cash`（现付）；历史资源主表空值也会回填为 `cash`。
- 备品的协议价字段名仍是 `basePrice`，但页面文案统一叫“协议价”，不要再叫“基础单价”。

兼容规则：`settlementPrice` 不传时后端默认等于协议价。现有报价和订单固化逻辑仍继续使用 `protocolPrice`，本次不改报价/订单金额来源。

---

## 2. 前端必须处理

| 场景 | 前端处理 |
|------|----------|
| 价格日历设置页 | 在“协议价”旁新增“结算价”输入框，字段 `settlementPrice`；不填可省略，后端默认取 `protocolPrice`。 |
| 价格日历查询页 | 每日项响应新增 `settlementPrice`，用于回显结算价。 |
| 备品新建/编辑/详情/列表 | 新增 `settlementPrice`；`basePrice` 字段保留，但 UI 文案改为“协议价”。 |
| 六类资源基础信息 | 新增/回显 `settleType`，使用字典 `resource_settle_type`；新建不传默认 `cash`（现付）。 |
| 酒店管理 | 原已有 `settleType`，字典来源需从 `hotel_settle_type` 改为 `resource_settle_type`。 |

字典值：

| dictType | dictValue | label |
|----------|-----------|-------|
| `resource_settle_type` | `cash` | 现付 |
| `resource_settle_type` | `sign` | 签单 |
| `resource_settle_type` | `company` | 公司付款 |

---

## 3. 价格日历接口变更

以下接口请求体新增可选字段 `settlementPrice`，响应每日项也新增 `settlementPrice`。

| 资源 | 查询 | 设置 |
|------|------|------|
| 景区 | `GET /admin/scenic/spot/{scenicId}/prices` | `PUT /admin/scenic/spot/{scenicId}/prices` |
| 游玩项目 | `GET /admin/activity/item/{activityId}/prices` | `PUT /admin/activity/item/{activityId}/prices` |
| 酒店房型 | `GET /admin/hotel/room-type/{roomTypeId}/prices` | `PUT /admin/hotel/room-type/{roomTypeId}/prices` |
| 服务 | `GET /admin/service/item/{serviceId}/prices` | `PUT /admin/service/item/{serviceId}/prices` |
| 服务人员 | `GET /admin/staff/type/{staffType}/prices` | `PUT /admin/staff/type/{staffType}/prices` |

请求体新增字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `settlementPrice` | BigDecimal | 否 | 结算价；不传默认等于 `protocolPrice`。不能小于 0。 |

响应每日项新增字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `settlementPrice` | String | 结算价；历史数据已按协议价回填。 |

示例：

```json
{
  "startDate": "2026-07-01",
  "endDate": "2026-07-31",
  "protocolPrice": 580.00,
  "settlementPrice": 520.00,
  "status": "AVAILABLE",
  "stock": 10
}
```

查询每日项示例：

```json
{
  "date": "2026-07-01",
  "protocolPrice": "580.00",
  "settlementPrice": "520.00",
  "status": "AVAILABLE",
  "stock": 10,
  "stockUsed": 0,
  "remark": null
}
```

---

## 4. 资源主数据接口变更

### 4.1 新增 `settleType`

以下资源的新建、编辑、详情、列表接口新增/透出 `settleType`：

| 资源 | 新建 | 编辑 | 详情 | 列表 |
|------|------|------|------|------|
| 景区 | `POST /admin/scenic/spot` | `PUT /admin/scenic/spot/{scenicId}` | `GET /admin/scenic/spot/{scenicId}` | `GET /admin/scenic/spots` |
| 游玩项目 | `POST /admin/activity/item` | `PUT /admin/activity/item/{activityId}` | `GET /admin/activity/item/{activityId}` | `GET /admin/activity/items` |
| 备品 | `POST /admin/supplies/item` | `PUT /admin/supplies/item/{suppliesId}` | `GET /admin/supplies/item/{suppliesId}` | `GET /admin/supplies/items` |
| 酒店 | `POST /admin/hotel/item` | `PUT /admin/hotel/item/{hotelId}` | `GET /admin/hotel/item/{hotelId}` | `GET /admin/hotel/items` |
| 服务 | `POST /admin/service/item` | `PUT /admin/service/item/{serviceId}` | `GET /admin/service/item/{serviceId}` | `GET /admin/service/items` |
| 服务人员 | `POST /admin/staff` | `PUT /admin/staff/{staffId}` | `GET /admin/staff/{staffId}` | `GET /admin/staff/list` |

字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `settleType` | String | 否 | 结算方式，字典 `resource_settle_type`：`cash` / `sign` / `company`；不传默认 `cash`。 |

### 4.2 备品新增 `settlementPrice`

备品的新建、编辑、详情、列表接口新增 `settlementPrice`。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `basePrice` | BigDecimal | 否 | 协议价。字段名兼容保留，页面文案叫“协议价”。 |
| `settlementPrice` | BigDecimal/String | 否 | 结算价；新建不传时默认等于 `basePrice`。响应按 String 处理。 |
| `settleType` | String | 否 | 结算方式，字典 `resource_settle_type`；不传默认 `cash`。 |

备品请求示例：

```json
{
  "name": "露营椅",
  "basePrice": 80.00,
  "settlementPrice": 65.00,
  "settleType": "sign"
}
```

备品响应片段：

```json
{
  "suppliesId": "2079000000000000001",
  "name": "露营椅",
  "basePrice": 80.00,
  "settlementPrice": "65.00",
  "settleType": "sign"
}
```

---

## 5. 兼容与边界

- 存量价格日历：`settlementPrice` 已按 `protocolPrice` 回填。
- 存量备品：`settlementPrice` 已按 `basePrice` 回填。
- 存量六类资源主表：`settleType` 为空或空白字符串时已按 `cash`（现付）回填。
- 前端不传 `settlementPrice`：后端默认等于协议价。
- 前端不传 `settleType`：后端默认 `cash`（现付）。
- 前端传负数 `settlementPrice`：后端返回参数错误。
- 修改价格日历状态、删除价格日历、批量启停接口路径不变。
- 报价、订单、签单等订单侧固化金额仍使用协议价 `protocolPrice`，不读取本次新增的 `settlementPrice`。

---

## 6. 验证状态

- 后端 PR 已创建，base `dev-v3`，当前 `mergeable=true`。
- 已通过资源服务编译、用户服务编译、资源服务定向单测。
- 尚未部署测试服；测试服部署后再用 Knife4j/API 做运行时契约确认。

---

## 7. 关联

- Issue: [wx/HL#4745](https://git.1814.love:8443/wx/HL/issues/4745)
- PR: [wx/HL#4746](https://git.1814.love:8443/wx/HL/pulls/4746)
- 补充 PR: [wx/HL#4774](https://git.1814.love:8443/wx/HL/pulls/4774)
- 迁移修正 PR: [wx/HL#4785](https://git.1814.love:8443/wx/HL/pulls/4785)
- 后端负责人: @wx
- 前端对接: 管理后台资源管理