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

PR: wx/HL#4746，补充 wx/HL#4774，迁移修正 wx/HL#4785 Issue: wx/HL#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	结算价；历史数据已按协议价回填。

示例：

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

查询每日项示例：

{
  "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`。

备品请求示例：

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

备品响应片段：

{
  "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
PR: wx/HL#4746
补充 PR: wx/HL#4774
迁移修正 PR: wx/HL#4785
后端负责人: @wx
前端对接: 管理后台资源管理

7.1 KiB 原始文件 Blame 文件历史 Unescape Escape