docs(api): notify resource settlement fields

2026-07-05 15:04:31 +08:00 · 2026-07-05 15:04:31 +08:00 · 98094ec861
--- a/changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md
@ -0,0 +1,176 @@
+# 【修改接口·管理后台】资源管理新增结算价 settlementPrice 与结算方式 settleType
+
+> **PR**: [wx/HL#4746](https://git.1814.love:8443/wx/HL/pulls/4746)
+> **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`。
+- 备品的协议价字段名仍是 `basePrice`，但页面文案统一叫“协议价”，不要再叫“基础单价”。
+
+兼容规则：`settlementPrice` 不传时后端默认等于协议价。现有报价和订单固化逻辑仍继续使用 `protocolPrice`，本次不改报价/订单金额来源。
+
+---
+
+## 2. 前端必须处理
+
+| 场景 | 前端处理 |
+|------|----------|
+| 价格日历设置页 | 在“协议价”旁新增“结算价”输入框，字段 `settlementPrice`；不填可省略，后端默认取 `protocolPrice`。 |
+| 价格日历查询页 | 每日项响应新增 `settlementPrice`，用于回显结算价。 |
+| 备品新建/编辑/详情/列表 | 新增 `settlementPrice`；`basePrice` 字段保留，但 UI 文案改为“协议价”。 |
+| 六类资源基础信息 | 新增/回显 `settleType`，使用字典 `resource_settle_type`。 |
+| 酒店管理 | 原已有 `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`。 |
+
+### 4.2 备品新增 `settlementPrice`
+
+备品的新建、编辑、详情、列表接口新增 `settlementPrice`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `basePrice` | BigDecimal | 否 | 协议价。字段名兼容保留，页面文案叫“协议价”。 |
+| `settlementPrice` | BigDecimal/String | 否 | 结算价；新建不传时默认等于 `basePrice`。响应按 String 处理。 |
+| `settleType` | String | 否 | 结算方式，字典 `resource_settle_type`。 |
+
+备品请求示例：
+
+```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` 回填。
+- 前端不传 `settlementPrice`：后端默认等于协议价。
+- 前端传负数 `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)
+- 后端负责人: @wx
+- 前端对接: 管理后台资源管理