hl-api-changelog/changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md

[修改接口·管理后台] 景区资源新增「是否收费」字段 (#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<ScenicSpotVO>

新增出参字段：

字段	类型	说明
isCharged	Integer	是否收费：1=是 / 0=否；历史数据默认 0
isChargedLabel	String	是否收费中文标签，取自字典 sys_yes_no；字典服务异常时为 null

5.2 景区列表（GET /admin/scenic/spots）响应结构

PageResult<ScenicSpotListVO>

新增出参字段（每条列表项）：

字段	类型	说明
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 <admin-jwt>
Content-Type: application/json

{
  "name": "呼伦贝尔大草原景区",
  "province": "内蒙古自治区",
  "city": "呼伦贝尔市",
  "isCharged": 1,
  "status": 0
}

响应（节选关键字段）：

{
  "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 <admin-jwt>

响应（节选关键字段）：

{
  "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 <admin-jwt>
Content-Type: application/json

{
  "name": "测试景区",
  "isCharged": 2
}

响应：

{
  "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
• PR: #3314
• 实现 commit: 62bd9be8b

13.2 联系人

• 后端负责人: @yaosutu