# [修改接口·小程序] 景区详情/列表透传「是否收费」字段 (#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