5472817dc3
- 删除误放文件：changelogs/2026-06/01_3313_feat_admin_scenic_is_charged.md - 删除误放文件：changelogs/2026-06/01_3315_feat_mp_scenic_is_charged.md - 新建管理后台：changelogs-v2/2026-06/01_3313_景区是否收费-修改接口-管理后台.md - 新建小程序端：changelogs-v2-mp/2026-06/01_3315_景区是否收费-修改接口-小程序端.md 接口路径 /admin/scenic/* 和 /mp/scenic/* 均属二期 v3，应路由至 v2/v2-mp 目录，对齐餐厅 #3317 的推送方式。
245 行
7.6 KiB
Markdown
245 行
7.6 KiB
Markdown
# 景区新增「是否收费」字段（小程序端）
|
||
|
||
- **端类型**：小程序端
|
||
- **变更类型**：修改接口
|
||
- **日期**：2026-06-01
|
||
- **Issue**：[#3315](https://git.1814.love:8443/wx/HL/issues/3315)
|
||
- **PR**：[#3316](https://git.1814.love:8443/wx/HL/pulls/3316)
|
||
- **Commit**：[63539c3](https://git.1814.love:8443/wx/HL/commit/63539c3dd2435c0e3d499302e53877944311e27b)
|
||
- **后端负责人**：腰苏图（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}
|
||
```
|
||
|
||
**响应**
|
||
```json
|
||
{
|
||
"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）
|
||
```json
|
||
{
|
||
"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，景区不存在）
|
||
```json
|
||
{
|
||
"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](https://git.1814.love:8443/wx/HL/issues/3315)
|
||
- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3316](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/commit/63539c3dd2435c0e3d499302e53877944311e27b)
|
||
- **上游依赖**：[https://git.1814.love:8443/wx/HL/issues/3313](https://git.1814.love:8443/wx/HL/issues/3313) / [https://git.1814.love:8443/wx/HL/pulls/3314](https://git.1814.love:8443/wx/HL/pulls/3314)
|
||
- **后端负责人**：腰苏图（企微 / yst@1814.love）
|