diff --git a/changelogs/2026-06/01_3315_feat_mp_scenic_is_charged.md b/changelogs/2026-06/01_3315_feat_mp_scenic_is_charged.md new file mode 100644 index 0000000..cd45370 --- /dev/null +++ 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` + +本次新增出参字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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>` + +本次新增出参字段（每条列表项）： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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 +``` + +响应（节选关键字段）： + +```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 +``` + +响应（节选一条列表项）： + +```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 +``` + +响应： + +```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