hl-api-changelog/changelogs-v2-mp/2026-06/01_3315_景区是否收费-修改接口-小程序端.md

景区新增「是否收费」字段（小程序端）

• 端类型：小程序端
• 变更类型：修改接口
• 日期：2026-06-01
• Issue：#3315
• PR：#3316
• Commit：63539c3
• 后端负责人：腰苏图（yst@1814.love）

---

① 接口背景

景区资源新增「是否收费」属性。小程序端的景区详情接口和列表接口均已同步透传该字段，供小程序展示景区是否需要付费（如收取门票费）。字典来源 sys_yes_no，后端已配置并完成翻译，小程序无需任何字典配置。上游依赖 #3313/#3314（resource-service 新增字段）。

---

② 变更清单

接口	方法	路径	变更内容
景区详情	GET	/mp/scenic/{scenicId}	出参新增 isCharged + isChargedLabel
景区列表	GET	/mp/scenic/list	出参新增 isCharged + isChargedLabel

所有变更均为向后兼容新增字段，小程序现有调用代码无需修改。

---

③ 接口详情

项目	说明
认证方式	小程序 JWT Token，请求头 Authorization: Bearer {mp_token}
幂等性	GET 查询，天然幂等
限流	无单独限流配置，走网关全局限流
缓存	详情接口缓存 300 秒（scenic:detail:{id}），列表接口缓存 600 秒（scenic:list:{keyword}:{city}:{page}:{pageSize}）。新字段随正常缓存刷新即可，无需额外处理
权限	小程序用户，已登录状态

---

④ 接口入参

GET /mp/scenic/{scenicId} 详情

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

GET /mp/scenic/list 列表

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

入参无变化，以上为完整入参文档。

---

⑤ 出参字段

GET /mp/scenic/{scenicId} 详情（MpScenicDetailVO，新增字段）

字段名	类型	说明	可能为 null
isCharged	Integer	是否收费，1=是 0=否	否（DB 默认 0）
isChargedLabel	String	是否收费中文文本，取自字典 sys_yes_no（"是"/"否"）	是（字典缺失时为 null）

GET /mp/scenic/list 列表（MpScenicListItemVO，新增字段）

字段名	类型	说明	可能为 null
isCharged	Integer	是否收费，1=是 0=否	否（DB 默认 0）
isChargedLabel	String	是否收费中文文本，取自字典 sys_yes_no（"是"/"否"）	是（字典缺失时为 null）

---

⑥ 枚举 / 数据字典

sys_yes_no 字典（后端已配置，小程序无需维护）

字典值（isCharged）	中文标签（isChargedLabel）	说明
1	是	该景区收费
0	否	该景区免费

isChargedLabel 由后端查字典自动翻译并返回，小程序可直接展示。若字典配置异常（不正常情况），该字段返回 null。

---

⑦ 错误码

错误码	HTTP 状态	场景
401	401	未登录或 Token 失效
404	404	景区 ID 不存在、已删除或已下架

---

⑧ 示例

8.1 典型成功 — 获取收费景区详情

请求

GET /mp/scenic/1900123456789000001
Authorization: Bearer {mp_token}

响应

{
  "code": 200,
  "msg": "成功",
  "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?..."
  }
}

8.2 边界情况 — 历史景区（isCharged 默认 0，列表返回"否"）

请求

GET /mp/scenic/list?page=1&pageSize=20
Authorization: Bearer {mp_token}

响应（列表含收费和免费景区，均有 isCharged/isChargedLabel）

{
  "code": 200,
  "msg": "成功",
  "data": {
    "total": 2,
    "list": [
      {
        "scenicId": "1900123456789000001",
        "name": "呼伦贝尔大草原景区",
        "isCharged": 1,
        "isChargedLabel": "是"
      },
      {
        "scenicId": "1900000000000000001",
        "name": "某历史免费景区",
        "isCharged": 0,
        "isChargedLabel": "否"
      }
    ]
  }
}

8.3 业务失败 — 访问不存在的景区

请求

GET /mp/scenic/9999999999999999999
Authorization: Bearer {mp_token}

响应（404，景区不存在）

{
  "code": 404,
  "msg": "景区不存在",
  "data": null
}

---

⑨ 业务边界

适用场景：

• 小程序景区详情页展示"是否收费"标签（如"免费"/"付费"徽标）
• 小程序景区列表卡片可展示收费状态，帮助用户快速识别

不适用场景：

• isCharged 仅为展示属性，不影响小程序下单流程或费用计算
• 不可作为用户端过滤条件（列表接口不支持按 isCharged 筛选）

特殊边界：

• 历史存量景区（PR #3314 上线前创建）isCharged 默认为 0（否），isChargedLabel 返回 "否"
• 两个接口均有 BFF 缓存，景区数据更新后缓存最多延迟 5 分钟（详情）/ 10 分钟（列表）才生效

---

⑩ 修改前后对比

字段级对比

出参（详情 + 列表）

字段名	变更前	变更后
isCharged	不存在	✨ 新增，Integer，1=是/0=否
isChargedLabel	不存在	✨ 新增，String，字典翻译文本，可能为 null

行为级对比

行为	变更前	变更后
景区详情接口	无收费信息	新增 isCharged + isChargedLabel
景区列表接口	无收费信息	新增 isCharged + isChargedLabel

---

⑪ 影响评估 / 回滚

破坏兼容性：无，新增字段，现有小程序代码可忽略不用。

前端同步上线：无强制要求，可选接入展示。

回滚方案：仅 VO 新增字段，无 DDL 变更；回滚只需回退 hl-mp-service 即可，isCharged 和 isChargedLabel 字段从响应中消失，小程序侧字段不存在时不展示即可。

---

⑫ 注意事项

1. 小程序无需配置 sys_yes_no 字典，后端已完成翻译并在 isChargedLabel 中直接返回中文
2. 若不需要展示该字段，忽略即可，不影响任何现有功能
3. 受缓存影响，运营后台修改后小程序侧缓存最多 5-10 分钟后自动刷新，属正常现象

---

⑬ 关联 / 联系人

• Issue：https://git.1814.love:8443/wx/HL/issues/3315
• PR：https://git.1814.love:8443/wx/HL/pulls/3316
• Commit：https://git.1814.love:8443/wx/HL/commit/63539c3dd2435c0e3d499302e53877944311e27b
• 上游依赖：https://git.1814.love:8443/wx/HL/issues/3313 / https://git.1814.love:8443/wx/HL/pulls/3314
• 后端负责人：腰苏图（企微 / yst@1814.love）