From 98094ec861d723b3c872504446c5a252523246b2 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 5 Jul 2026 15:04:31 +0800 Subject: [PATCH] docs(api): notify resource settlement fields --- ...45_资源结算价结算方式-修改接口-管理后台.md | 176 ++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md b/changelogs-v2/2026-07/05_4745_资源结算价结算方式-修改接口-管理后台.md new file mode 100644 index 0000000..d6619e4 --- /dev/null +++ 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 +- 前端对接: 管理后台资源管理