feat(mp): 小程序景区详情/列表透传「是否收费」字段 (Closes #3315) (#3316)

2026-06-01 16:21:56 +08:00 · 2026-06-01 16:21:56 +08:00 · 78ff66b36d
--- a/changelogs/2026-06/01_3315_feat_mp_scenic_is_charged.md
+++ b/changelogs/2026-06/01_3315_feat_mp_scenic_is_charged.md
@ -0,0 +1,266 @@
+# [修改接口·小程序] 景区详情/列表透传「是否收费」字段 (#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>
+```
+
+响应（节选关键字段）：
+
+```json
+{
+  "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>
+```
+
+响应（节选一条列表项）：
+
+```json
+{
+  "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>
+```
+
+响应：
+
+```json
+{
+  "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](https://git.1814.love:8443/wx/HL/issues/3315)
+- **PR**: [#3316](https://git.1814.love:8443/wx/HL/pulls/3316)
+- **实现 commit**: [63539c3dd](https://git.1814.love:8443/wx/HL/commit/63539c3dd2435c0e3d499302e53877944311e27b)
+- **上游依赖**: [#3313](https://git.1814.love:8443/wx/HL/issues/3313) / [#3314](https://git.1814.love:8443/wx/HL/pulls/3314)（resource-service 新增字段）
+
+### 13.2 联系人
+
+- **后端负责人**: @yaosutu