From 70a8fcdc6f6bf9dd13c8c2aeaa5f8ec74a7dfe60 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 1 Jun 2026 16:06:35 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3(admin-scenic):=20=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E3=80=8C=E6=98=AF=E5=90=A6=E6=94=B6=E8=B4=B9=E3=80=8D?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=20changelog=20(#3313/#3314)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01_3313_feat_admin_scenic_is_charged.md | 262 ++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md diff --git a/changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md b/changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md new file mode 100644 index 0000000..98fb050 --- /dev/null +++ b/changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md @@ -0,0 +1,262 @@ +# [修改接口·管理后台] 景区资源新增「是否收费」字段 (#3313) + +> **PR**: #3314 | **服务**: hl-resource-service | **更新时间**: 2026-06-01 + +## 1. 接口背景 + +景区资源（scenic_spot）新增「是否收费」属性，用于管理后台录入/编辑景区时标注该景区是否收取门票费用。 + +字段值域通过系统字典 `sys_yes_no` 管理（1=是 / 0=否），返回时同步带字典中文标签字段。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 创建景区 | POST | /admin/scenic/spot | 修改接口 | 入参新增 `isCharged`（默认 0） | +| 2 | 编辑景区 | PUT | /admin/scenic/spot/{scenicId} | 修改接口 | 入参新增 `isCharged`（可选，不传则不更新） | +| 3 | 景区详情 | GET | /admin/scenic/spot/{scenicId} | 修改接口 | 出参新增 `isCharged` + `isChargedLabel` | +| 4 | 景区列表 | GET | /admin/scenic/spots | 修改接口 | 出参新增 `isCharged` + `isChargedLabel` | + +## 3. 接口详情 + +### 3.1 POST /admin/scenic/spot（创建景区） + +- **使用场景**：管理后台录入新景区时，可选填「是否收费」，不填默认 0（否） +- **认证**：需要管理后台 JWT（Bearer Token） +- **幂等性**：否 +- **限流**：无 + +### 3.2 PUT /admin/scenic/spot/{scenicId}（编辑景区） + +- **使用场景**：管理后台编辑现有景区，补填或修改「是否收费」字段 +- **认证**：需要管理后台 JWT（Bearer Token） +- **幂等性**：否 +- **限流**：无 + +### 3.3 GET /admin/scenic/spot/{scenicId}（景区详情） + +- **使用场景**：管理后台查看/回填景区详情表单 +- **认证**：需要管理后台 JWT（Bearer Token） +- **幂等性**：是（GET 接口） +- **限流**：无 + +### 3.4 GET /admin/scenic/spots（景区列表） + +- **使用场景**：管理后台景区列表页，列表中展示是否收费标签 +- **认证**：需要管理后台 JWT（Bearer Token） +- **幂等性**：是（GET 接口） +- **限流**：无 + +## 4. 接口入参 + +### 4.1 路径参数 / Query 参数 + +**PUT /admin/scenic/spot/{scenicId}**： + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| scenicId | Long | 是 | 路径参数，景区 ID | + +其余接口入参无变化（仅 POST / PUT 请求体变化，见 4.2）。 + +### 4.2 请求体字段（仅 POST + PUT 有变化） + +新增字段： + +| 字段 | 类型 | 必填 | 默认值 | 说明 | 校验规则 | +|------|------|------|--------|------|----------| +| isCharged | Integer | 否 | POST 默认 0；PUT 不传则不更新 | 是否收费（sys_yes_no 字典）：1=是 / 0=否 | 取值只能是 0 或 1，违反返回 400 | + +## 5. 出参字段 + +### 5.1 景区详情（GET /admin/scenic/spot/{scenicId}）响应结构 + +`Result` + +新增出参字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| isCharged | Integer | 是否收费：1=是 / 0=否；历史数据默认 0 | +| isChargedLabel | String | 是否收费中文标签，取自字典 `sys_yes_no`；字典服务异常时为 null | + +### 5.2 景区列表（GET /admin/scenic/spots）响应结构 + +`PageResult` + +新增出参字段（每条列表项）： + +| 字段 | 类型 | 说明 | +|------|------|------| +| isCharged | Integer | 是否收费：1=是 / 0=否；历史数据默认 0 | +| isChargedLabel | String | 是否收费中文标签，取自字典 `sys_yes_no`；字典服务异常时为 null | + +## 6. 枚举 / 数据字典 + +### 6.1 isCharged（是否收费） + +**字典类型**：`sys_yes_no` | **字段类型**：Integer（存储值）+ String（标签，由 `isChargedLabel` 返回） + +| 值（Integer） | isChargedLabel | 说明 | +|---|---|---| +| 1 | 是 | 景区收取门票费 | +| 0 | 否 | 景区免费开放 | + +字典 `sys_yes_no` 已存在系统中，无需前端额外配置。 + +## 7. 错误码 + +| code | 含义 | 触发场景 | +|------|------|----------| +| 200 | 成功 | - | +| 400 | 参数校验失败 | isCharged 传入值不在 0～1 范围内，message 含 "是否收费取值范围为0或1" | +| 401 | 未授权 | JWT 未携带或已过期 | +| 404 | 景区不存在 | PUT 时 scenicId 对应景区不存在 | + +## 8. 示例 + +### 8.1 典型成功 — 创建收费景区 + +场景说明：创建一个收费景区，isCharged 传 1。 + +请求： + +``` +POST /admin/scenic/spot +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "name": "呼伦贝尔大草原景区", + "province": "内蒙古自治区", + "city": "呼伦贝尔市", + "isCharged": 1, + "status": 0 +} +``` + +响应（节选关键字段）： + +```json +{ + "code": 200, + "data": { + "scenicId": "1900123456789000001", + "name": "呼伦贝尔大草原景区", + "isCharged": 1, + "isChargedLabel": "是", + "status": 0 + }, + "message": "ok", + "success": true +} +``` + +### 8.2 边界情况 — 不传 isCharged（GET 详情返回历史数据默认 0） + +场景说明：历史景区数据未填 isCharged，详情接口返回默认值 0（否）。 + +请求： + +``` +GET /admin/scenic/spot/1900000000000000001 +Authorization: Bearer +``` + +响应（节选关键字段）： + +```json +{ + "code": 200, + "data": { + "scenicId": "1900000000000000001", + "name": "某历史景区", + "isCharged": 0, + "isChargedLabel": "否", + "status": 1 + }, + "message": "ok", + "success": true +} +``` + +### 8.3 业务失败 — isCharged 超出范围 + +场景说明：isCharged 传 2，触发校验失败。 + +请求： + +``` +POST /admin/scenic/spot +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "name": "测试景区", + "isCharged": 2 +} +``` + +响应： + +```json +{ + "code": 400, + "message": "是否收费取值范围为0或1", + "success": false +} +``` + +## 9. 业务边界 + +- 适用场景：管理后台创建或编辑景区，对「是否收费」属性录入/修改 +- 不适用场景：小程序端（`/mp/*` 路径）当前**不透传**此字段，小程序暂不展示是否收费信息 +- 特殊边界： + - `isChargedLabel` 依赖字典服务（hl-user-service 字典接口），字典服务异常时该字段返回 null，`isCharged` 数字值正常返回 + - 历史存量景区数据 `isCharged` 默认为 0（否），不影响现有数据使用 + - PUT 编辑接口不传 `isCharged` 时字段保持原值不变（非必填增量更新语义） + +## 10. 修改前后对比 + +### 入参变化 + +| 接口 | 字段 | 变更类型 | 原来 | 现在 | +|------|------|----------|------|------| +| POST /admin/scenic/spot | isCharged | ✨ 新增 | 不存在 | Integer，可选，默认 0 | +| PUT /admin/scenic/spot/{scenicId} | isCharged | ✨ 新增 | 不存在 | Integer，可选，不传不更新 | + +### 出参变化 + +| 接口 | 字段 | 变更类型 | 原来 | 现在 | +|------|------|----------|------|------| +| GET /admin/scenic/spot/{scenicId} | isCharged | ✨ 新增 | 不存在 | Integer：1=是 / 0=否 | +| GET /admin/scenic/spot/{scenicId} | isChargedLabel | ✨ 新增 | 不存在 | String：字典中文标签 | +| GET /admin/scenic/spots | isCharged | ✨ 新增 | 不存在 | Integer：1=是 / 0=否 | +| GET /admin/scenic/spots | isChargedLabel | ✨ 新增 | 不存在 | String：字典中文标签 | + +## 11. 影响评估 / 回滚 + +- **是否破坏向后兼容**：否（纯新增字段，旧代码忽略新字段不受影响） +- **前端是否必须同步上线**：否，后端先上，前端按需接入新字段 +- **回滚方案**：无 DDL 依赖风险；字段通过字典服务回填，字典服务异常时 isChargedLabel 为 null 但不影响接口正常返回 + +## 12. 注意事项 + +- `isChargedLabel` 可能为 null（字典服务异常场景），前端展示时需做空值处理，建议降级显示 `isCharged ? "是" : "否"` +- 小程序侧（`/internal/mp/scenic` 路径由 hl-mp-service 消费）当前 mp-service BFF 的独立 VO 未声明此字段，Jackson `convertValue` 会忽略，**小程序前端当前拿不到此字段**；若产品需要小程序展示是否收费，需由 hl-mp-service 单独跟进补字段 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#3313](https://git.1814.love:8443/wx/HL/issues/3313) +- **PR**: [#3314](https://git.1814.love:8443/wx/HL/pulls/3314) +- **实现 commit**: [62bd9be8b](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu