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

[修改接口·小程序] 景区详情/列表透传「是否收费」字段 (#3315)

PR: #3316 | 服务: hl-mp-service | 更新时间: 2026-06-01

1. 接口背景

小程序 BFF 景区详情和景区列表接口补透传「是否收费」字段，打通 #3313/#3314 管理后台新增字段的小程序链路。

字段值域与管理后台保持一致，通过系统字典 sys_yes_no 管理（1=是 / 0=否），返回时同步带字典中文标签字段 isChargedLabel。字段由 mp-service BFF 层通过 ObjectMapper.convertValue 从上游 resource-service 自动绑定透传，无需改 Service 逻辑。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	景区详情	GET	/mp/scenic/{scenicId}	修改接口	出参新增 isCharged + isChargedLabel
2	景区列表	GET	/mp/scenic/list	修改接口	出参新增 isCharged + isChargedLabel

3. 接口详情

3.1 GET /mp/scenic/{scenicId}（景区详情）

• 使用场景：小程序景区详情页，展示景区是否需要购买门票
• 认证：需要小程序用户 JWT（Bearer Token）
• 幂等性：是（GET 接口）
• 限流：接口有 BFF 缓存（TTL 300 秒，依赖 table:scenic_spot + table:scenic_season）

3.2 GET /mp/scenic/list（景区列表）

• 使用场景：小程序景区列表页，列表卡片可展示是否收费标签
• 认证：需要小程序用户 JWT（Bearer Token）
• 幂等性：是（GET 接口）
• 限流：接口有 BFF 缓存（TTL 600 秒，依赖 table:scenic_spot）

4. 接口入参

4.1 路径参数 / Query 参数

GET /mp/scenic/{scenicId}：

参数	类型	必填	说明
scenicId	Long	是	路径参数，景区 ID

GET /mp/scenic/list：

参数	类型	必填	默认值	说明
keyword	String	否	-	关键词搜索
city	String	否	-	城市筛选
page	Integer	否	1	页码
pageSize	Integer	否	20	每页条数

本次改动入参无变化，仅出参新增字段。

4.2 请求体字段

两个接口均为 GET 请求，无请求体。

5. 出参字段

5.1 景区详情（GET /mp/scenic/{scenicId}）响应结构

Result<MpScenicDetailVO>

本次新增出参字段：

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

已有出参字段（节选，保持不变）：

字段	类型	说明
scenicId	String	景区 ID（雪花字符串）
name	String	景区名称
coverUrl	String	封面图 URL
cityName	String	所在城市
longitude	BigDecimal	经度
latitude	BigDecimal	纬度
rating	BigDecimal	评分
status	Integer	状态：0=下架 1=上架
mapImageUrl	String	高德静态地图 URL（mp BFF 注入）
tags	List	标签列表
...	...	其余字段不变

5.2 景区列表（GET /mp/scenic/list）响应结构

Result<PageResult<MpScenicListItemVO>>

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

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

已有出参字段（节选，保持不变）：

字段	类型	说明
scenicId	String	景区 ID（雪花字符串）
name	String	景区名称
coverUrl	String	封面图 URL
cityName	String	所在城市
rating	BigDecimal	评分
status	Integer	状态：0=下架 1=上架
tags	List	标签列表
...	...	其余字段不变

6. 枚举 / 数据字典

6.1 isCharged（是否收费）

字典类型：sys_yes_no | 字段类型：Integer（存储值）+ String（标签，由 isChargedLabel 返回）

值（Integer）	isChargedLabel	说明
1	是	景区收取门票费
0	否	景区免费开放

字典 sys_yes_no 已在系统中配置，无需前端额外配置。

7. 错误码

code	含义	触发场景
200	成功	-
401	未授权	JWT 未携带或已过期
404	景区不存在	GET /mp/scenic/{scenicId} 时 ID 对应景区不存在

8. 示例

8.1 典型成功 — 景区详情返回收费字段

场景说明：小程序打开收费景区详情页，isCharged=1，isChargedLabel="是"。

请求：

GET /mp/scenic/1900123456789000001
Authorization: Bearer <mp-user-jwt>

响应（节选关键字段）：

{
  "code": 200,
  "data": {
    "scenicId": "1900123456789000001",
    "name": "呼伦贝尔大草原景区",
    "cityName": "呼伦贝尔",
    "coverUrl": "https://oss.example.com/scenic/cover.jpg",
    "isCharged": 1,
    "isChargedLabel": "是",
    "rating": 4.8,
    "status": 1,
    "mapImageUrl": "https://restapi.amap.com/v3/staticmap?..."
  },
  "message": "ok",
  "success": true
}

8.2 边界情况 — 历史景区未填 isCharged，列表接口返回默认值

场景说明：历史存量景区未写入 is_charged 字段，列表中 isCharged 为 0，isChargedLabel 为"否"。

请求：

GET /mp/scenic/list?page=1&pageSize=20
Authorization: Bearer <mp-user-jwt>

响应（节选一条列表项）：

{
  "code": 200,
  "data": {
    "total": 100,
    "list": [
      {
        "scenicId": "1900000000000000001",
        "name": "某历史景区",
        "isCharged": 0,
        "isChargedLabel": "否",
        "status": 1
      }
    ]
  },
  "message": "ok",
  "success": true
}

8.3 业务失败 — 景区不存在

场景说明：传入不存在的 scenicId，返回 404。

请求：

GET /mp/scenic/9999999999999999999
Authorization: Bearer <mp-user-jwt>

响应：

{
  "code": 404,
  "message": "景区不存在",
  "success": false
}

9. 业务边界

• 适用场景：小程序景区详情页和列表页需要展示「是否收费」标签时读取 isCharged 和 isChargedLabel
• 不适用场景：不涉及创建/编辑景区（管理后台接口，见 #3313 changelog）
• 特殊边界：
  • isChargedLabel 可能为 null（字典服务异常或上游未配置时），前端展示时需做空值处理，建议降级显示 isCharged === 1 ? "是" : "否"
  • 历史存量景区 isCharged 默认为 0（否），不影响现有数据使用
  • 两个接口均有 BFF 缓存，景区数据更新后缓存最多延迟 5 分钟（详情）/ 10 分钟（列表）才生效

10. 修改前后对比

出参变化

接口	字段	变更类型	原来	现在
GET /mp/scenic/{scenicId}	isCharged	✨ 新增	不存在	Integer：1=是 / 0=否
GET /mp/scenic/{scenicId}	isChargedLabel	✨ 新增	不存在	String：字典中文标签，可能为 null
GET /mp/scenic/list	isCharged	✨ 新增	不存在	Integer：1=是 / 0=否
GET /mp/scenic/list	isChargedLabel	✨ 新增	不存在	String：字典中文标签，可能为 null

入参无变化。

11. 影响评估 / 回滚

• 是否破坏向后兼容：否（纯新增字段，小程序旧代码忽略新字段不受影响）
• 前端是否必须同步上线：否，后端先上，前端按需接入新字段
• 回滚方案：仅 VO 新增字段，无 DDL 变更；回滚只需回退 hl-mp-service 即可，不影响 resource-service 数据

12. 注意事项

• isChargedLabel 可能为 null，前端展示时必须做空值判断，建议降级逻辑：isCharged === 1 ? "是" : "否"
• 本次为纯透传（mp BFF 层 ObjectMapper.convertValue 自动绑定），无额外 Service 逻辑，字段语义与管理后台 #3313 完全一致
• 两个接口均有 BFF 层 Redis 缓存，缓存未过期时不会立即反映 resource-service 的数据变更

13. 关联 / 联系人

13.1 链接

• Issue: #3315
• PR: #3316
• 实现 commit: 63539c3dd
• 上游依赖: #3313 / #3314（resource-service 新增字段）

13.2 联系人

• 后端负责人: @yaosutu