修正路由：景区是否收费 changelog 从一期 changelogs/ 迁移到 v2 系列目录
- 删除误放文件：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 的推送方式。
这个提交包含在：
yaosutu
父节点
66f94cadcd
当前提交
5472817dc3
@ -0,0 +1,244 @@
|
|||||||
|
# 景区新增「是否收费」字段（小程序端）
|
||||||
|
|
||||||
|
- **端类型**：小程序端
|
||||||
|
- **变更类型**：修改接口
|
||||||
|
- **日期**：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）
|
||||||
@ -0,0 +1,280 @@
|
|||||||
|
# 景区管理新增「是否收费」字段
|
||||||
|
|
||||||
|
- **端类型**：管理后台
|
||||||
|
- **变更类型**：修改接口
|
||||||
|
- **日期**：2026-06-01
|
||||||
|
- **Issue**：[#3313](https://git.1814.love:8443/wx/HL/issues/3313)
|
||||||
|
- **PR**：[#3314](https://git.1814.love:8443/wx/HL/pulls/3314)
|
||||||
|
- **Commit**：[62bd9be](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b)
|
||||||
|
- **后端负责人**：腰苏图（yst@1814.love）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ① 接口背景
|
||||||
|
|
||||||
|
景区资源新增「是否收费」属性，用于在管理后台创建/编辑景区时标记该景区是否需要游客付费（如收取门票费）。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费景区。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ② 变更清单
|
||||||
|
|
||||||
|
| 接口 | 方法 | 路径 | 变更内容 |
|
||||||
|
|------|------|------|----------|
|
||||||
|
| 创建景区 | POST | `/admin/scenic/spot` | 入参新增 `isCharged`（Integer，默认 0） |
|
||||||
|
| 编辑景区 | PUT | `/admin/scenic/spot/{scenicId}` | 入参新增 `isCharged`（Integer，可选） |
|
||||||
|
| 景区详情 | GET | `/admin/scenic/spot/{scenicId}` | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
| 景区列表 | GET | `/admin/scenic/spots` | 出参新增 `isCharged` + `isChargedLabel` |
|
||||||
|
|
||||||
|
所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ③ 接口详情
|
||||||
|
|
||||||
|
| 项目 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` |
|
||||||
|
| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 scenicId 可重复调用） |
|
||||||
|
| **限流** | 无单独限流配置，走网关全局限流 |
|
||||||
|
| **权限** | 管理员角色，普通前端用户无访问权限 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ④ 接口入参
|
||||||
|
|
||||||
|
### 4.1 路径参数 / Query 参数
|
||||||
|
|
||||||
|
**PUT `/admin/scenic/spot/{scenicId}`**
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| scenicId | Long | 是 | 景区 ID（路径参数） |
|
||||||
|
|
||||||
|
**GET `/admin/scenic/spots`**（列表，原有参数不变，无新增查询参数）
|
||||||
|
|
||||||
|
### 4.2 请求体字段（新增字段，含于已有请求体中）
|
||||||
|
|
||||||
|
**POST `/admin/scenic/spot`**（`ScenicSpotCreateReqVO`，新增字段）
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 |
|
||||||
|
|--------|------|------|----------|--------|------|
|
||||||
|
| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 |
|
||||||
|
|
||||||
|
**PUT `/admin/scenic/spot/{scenicId}`**（`ScenicSpotUpdateReqVO`，新增字段）
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 |
|
||||||
|
|--------|------|------|----------|--------|------|
|
||||||
|
| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑤ 出参字段
|
||||||
|
|
||||||
|
### GET `/admin/scenic/spot/{scenicId}` 详情（`ScenicSpotVO`，新增字段）
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 说明 | 可能为 null |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
|
||||||
|
| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
|
||||||
|
|
||||||
|
### GET `/admin/scenic/spots` 列表（`ScenicSpotListVO`，新增字段）
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 说明 | 可能为 null |
|
||||||
|
|--------|------|------|-------------|
|
||||||
|
| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
|
||||||
|
| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑥ 枚举 / 数据字典
|
||||||
|
|
||||||
|
### sys_yes_no 字典（后端已配置，前端无需维护）
|
||||||
|
|
||||||
|
| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 |
|
||||||
|
|--------------------|-----------------------------|------|
|
||||||
|
| 1 | 是 | 该景区收费 |
|
||||||
|
| 0 | 否 | 该景区免费 |
|
||||||
|
|
||||||
|
> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑦ 错误码
|
||||||
|
|
||||||
|
| 错误码 | HTTP 状态 | 场景 |
|
||||||
|
|--------|-----------|------|
|
||||||
|
| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败 |
|
||||||
|
| 401 | 401 | 未登录或 Token 失效 |
|
||||||
|
| 403 | 403 | 无管理员权限 |
|
||||||
|
| 404 | 404 | 景区 ID 不存在或已删除 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑧ 示例
|
||||||
|
|
||||||
|
### 8.1 典型成功 — 创建收费景区
|
||||||
|
|
||||||
|
**请求**
|
||||||
|
```
|
||||||
|
POST /admin/scenic/spot
|
||||||
|
Authorization: Bearer {admin_token}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "呼伦贝尔大草原景区",
|
||||||
|
"province": "内蒙古自治区",
|
||||||
|
"city": "呼伦贝尔市",
|
||||||
|
"cityName": "呼伦贝尔",
|
||||||
|
"longitude": 119.758,
|
||||||
|
"latitude": 49.215,
|
||||||
|
"isCharged": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**响应**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"msg": "成功",
|
||||||
|
"data": {
|
||||||
|
"scenicId": "1900123456789000001",
|
||||||
|
"name": "呼伦贝尔大草原景区",
|
||||||
|
"isCharged": 1,
|
||||||
|
"isChargedLabel": "是",
|
||||||
|
"status": 0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 边界情况 — 不传 isCharged（使用默认值 0）
|
||||||
|
|
||||||
|
**请求**
|
||||||
|
```
|
||||||
|
POST /admin/scenic/spot
|
||||||
|
Authorization: Bearer {admin_token}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "某免费公园",
|
||||||
|
"province": "内蒙古自治区",
|
||||||
|
"city": "呼伦贝尔市",
|
||||||
|
"cityName": "呼伦贝尔",
|
||||||
|
"longitude": 119.700,
|
||||||
|
"latitude": 49.200
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**响应**（isCharged 默认为 0）
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"msg": "成功",
|
||||||
|
"data": {
|
||||||
|
"scenicId": "1900123456789000002",
|
||||||
|
"name": "某免费公园",
|
||||||
|
"isCharged": 0,
|
||||||
|
"isChargedLabel": "否",
|
||||||
|
"status": 0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.3 业务失败 — isCharged 传入越界值
|
||||||
|
|
||||||
|
**请求**
|
||||||
|
```
|
||||||
|
POST /admin/scenic/spot
|
||||||
|
Authorization: Bearer {admin_token}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "测试景区",
|
||||||
|
"isCharged": 2
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**响应**（400 参数校验失败）
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 400,
|
||||||
|
"msg": "是否收费取值范围为0或1",
|
||||||
|
"data": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑨ 业务边界
|
||||||
|
|
||||||
|
**适用场景**：
|
||||||
|
- 创建新景区时，可设置是否收费标记（不传默认不收费）
|
||||||
|
- 编辑已有景区时，可随时修改是否收费状态（传 null 或不传则保持原值不变）
|
||||||
|
- 列表和详情页均可展示该字段，用于运营人员快速判断景区性质
|
||||||
|
|
||||||
|
**不适用场景**：
|
||||||
|
- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理）
|
||||||
|
- 不用于权限控制，仅作展示属性
|
||||||
|
|
||||||
|
**特殊边界**：
|
||||||
|
- 历史存量景区（PR #3314 上线前创建的）`isCharged` 默认为 0（否），`isChargedLabel` 返回 "否"
|
||||||
|
- PUT 编辑时若不传 `isCharged` 字段，该字段值保持不变（不会被清零）
|
||||||
|
- `isChargedLabel` 为 null 时属于字典配置异常，前端可用 `isCharged` 值自行映射（1→"是"，0→"否"）兜底
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑩ 修改前后对比
|
||||||
|
|
||||||
|
### 字段级对比
|
||||||
|
|
||||||
|
**入参（POST 创建 / PUT 编辑）**
|
||||||
|
|
||||||
|
| 字段名 | 变更前 | 变更后 |
|
||||||
|
|--------|--------|--------|
|
||||||
|
| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），可 null（Update） |
|
||||||
|
|
||||||
|
**出参（详情 + 列表）**
|
||||||
|
|
||||||
|
| 字段名 | 变更前 | 变更后 |
|
||||||
|
|--------|--------|--------|
|
||||||
|
| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 |
|
||||||
|
| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null |
|
||||||
|
|
||||||
|
### 行为级对比
|
||||||
|
|
||||||
|
| 行为 | 变更前 | 变更后 |
|
||||||
|
|------|--------|--------|
|
||||||
|
| 创建景区 | 无收费标记 | 可设置 isCharged，默认 0 |
|
||||||
|
| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel |
|
||||||
|
| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑪ 影响评估 / 回滚
|
||||||
|
|
||||||
|
**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。
|
||||||
|
|
||||||
|
**前端同步上线**：
|
||||||
|
- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认 0
|
||||||
|
- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能
|
||||||
|
|
||||||
|
**回滚方案**：
|
||||||
|
- 若需回滚，执行 `ALTER TABLE scenic_spot DROP COLUMN is_charged;` 并回退服务部署
|
||||||
|
- 前端零改动时回滚对前端无感
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑫ 注意事项
|
||||||
|
|
||||||
|
1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表
|
||||||
|
2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"）
|
||||||
|
3. PUT 编辑时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否）
|
||||||
|
4. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⑬ 关联 / 联系人
|
||||||
|
|
||||||
|
- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3313](https://git.1814.love:8443/wx/HL/issues/3313)
|
||||||
|
- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3314](https://git.1814.love:8443/wx/HL/pulls/3314)
|
||||||
|
- **Commit**：[https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b)
|
||||||
|
- **后端负责人**：腰苏图（企微 / yst@1814.love）
|
||||||
@ -1,262 +0,0 @@
|
|||||||
# [修改接口·管理后台] 景区资源新增「是否收费」字段 (#3313)
|
|
||||||
|
|
||||||
> **PR**: #3314 | **服务**: hl-resource-service | **更新时间**: 2026-06-01
|
|
||||||
|
|
||||||
## 1. 接口背景
|
|
||||||
|
|
||||||
景区资源（scenic_spot）新增「是否收费」属性，用于管理后台录入/编辑景区时标注该景区是否收取门票费用。
|
|
||||||
|
|
||||||
字段值域通过系统字典 `sys_yes_no` 管理（1=是 / 0=否），返回时同步带字典中文标签字段。
|
|
||||||
|
|
||||||
## 2. 变更清单
|
|
||||||
|
|
||||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
|
||||||
|---|------|------|------|----------|------|
|
|
||||||
| 1 | 创建景区 | POST | /admin/scenic/spot | 修改接口 | 入参新增 `isCharged`（默认 0） |
|
|
||||||
| 2 | 编辑景区 | PUT | /admin/scenic/spot/{scenicId} | 修改接口 | 入参新增 `isCharged`（可选，不传则不更新） |
|
|
||||||
| 3 | 景区详情 | GET | /admin/scenic/spot/{scenicId} | 修改接口 | 出参新增 `isCharged` + `isChargedLabel` |
|
|
||||||
| 4 | 景区列表 | GET | /admin/scenic/spots | 修改接口 | 出参新增 `isCharged` + `isChargedLabel` |
|
|
||||||
|
|
||||||
## 3. 接口详情
|
|
||||||
|
|
||||||
### 3.1 POST /admin/scenic/spot（创建景区）
|
|
||||||
|
|
||||||
- **使用场景**：管理后台录入新景区时，可选填「是否收费」，不填默认 0（否）
|
|
||||||
- **认证**：需要管理后台 JWT（Bearer Token）
|
|
||||||
- **幂等性**：否
|
|
||||||
- **限流**：无
|
|
||||||
|
|
||||||
### 3.2 PUT /admin/scenic/spot/{scenicId}（编辑景区）
|
|
||||||
|
|
||||||
- **使用场景**：管理后台编辑现有景区，补填或修改「是否收费」字段
|
|
||||||
- **认证**：需要管理后台 JWT（Bearer Token）
|
|
||||||
- **幂等性**：否
|
|
||||||
- **限流**：无
|
|
||||||
|
|
||||||
### 3.3 GET /admin/scenic/spot/{scenicId}（景区详情）
|
|
||||||
|
|
||||||
- **使用场景**：管理后台查看/回填景区详情表单
|
|
||||||
- **认证**：需要管理后台 JWT（Bearer Token）
|
|
||||||
- **幂等性**：是（GET 接口）
|
|
||||||
- **限流**：无
|
|
||||||
|
|
||||||
### 3.4 GET /admin/scenic/spots（景区列表）
|
|
||||||
|
|
||||||
- **使用场景**：管理后台景区列表页，列表中展示是否收费标签
|
|
||||||
- **认证**：需要管理后台 JWT（Bearer Token）
|
|
||||||
- **幂等性**：是（GET 接口）
|
|
||||||
- **限流**：无
|
|
||||||
|
|
||||||
## 4. 接口入参
|
|
||||||
|
|
||||||
### 4.1 路径参数 / Query 参数
|
|
||||||
|
|
||||||
**PUT /admin/scenic/spot/{scenicId}**：
|
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| scenicId | Long | 是 | 路径参数，景区 ID |
|
|
||||||
|
|
||||||
其余接口入参无变化（仅 POST / PUT 请求体变化，见 4.2）。
|
|
||||||
|
|
||||||
### 4.2 请求体字段（仅 POST + PUT 有变化）
|
|
||||||
|
|
||||||
新增字段：
|
|
||||||
|
|
||||||
| 字段 | 类型 | 必填 | 默认值 | 说明 | 校验规则 |
|
|
||||||
|------|------|------|--------|------|----------|
|
|
||||||
| isCharged | Integer | 否 | POST 默认 0；PUT 不传则不更新 | 是否收费（sys_yes_no 字典）：1=是 / 0=否 | 取值只能是 0 或 1，违反返回 400 |
|
|
||||||
|
|
||||||
## 5. 出参字段
|
|
||||||
|
|
||||||
### 5.1 景区详情（GET /admin/scenic/spot/{scenicId}）响应结构
|
|
||||||
|
|
||||||
`Result<ScenicSpotVO>`
|
|
||||||
|
|
||||||
新增出参字段：
|
|
||||||
|
|
||||||
| 字段 | 类型 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| isCharged | Integer | 是否收费：1=是 / 0=否；历史数据默认 0 |
|
|
||||||
| isChargedLabel | String | 是否收费中文标签，取自字典 `sys_yes_no`；字典服务异常时为 null |
|
|
||||||
|
|
||||||
### 5.2 景区列表（GET /admin/scenic/spots）响应结构
|
|
||||||
|
|
||||||
`PageResult<ScenicSpotListVO>`
|
|
||||||
|
|
||||||
新增出参字段（每条列表项）：
|
|
||||||
|
|
||||||
| 字段 | 类型 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| isCharged | Integer | 是否收费：1=是 / 0=否；历史数据默认 0 |
|
|
||||||
| isChargedLabel | String | 是否收费中文标签，取自字典 `sys_yes_no`；字典服务异常时为 null |
|
|
||||||
|
|
||||||
## 6. 枚举 / 数据字典
|
|
||||||
|
|
||||||
### 6.1 isCharged（是否收费）
|
|
||||||
|
|
||||||
**字典类型**：`sys_yes_no` | **字段类型**：Integer（存储值）+ String（标签，由 `isChargedLabel` 返回）
|
|
||||||
|
|
||||||
| 值（Integer） | isChargedLabel | 说明 |
|
|
||||||
|---|---|---|
|
|
||||||
| 1 | 是 | 景区收取门票费 |
|
|
||||||
| 0 | 否 | 景区免费开放 |
|
|
||||||
|
|
||||||
字典 `sys_yes_no` 已存在系统中，无需前端额外配置。
|
|
||||||
|
|
||||||
## 7. 错误码
|
|
||||||
|
|
||||||
| code | 含义 | 触发场景 |
|
|
||||||
|------|------|----------|
|
|
||||||
| 200 | 成功 | - |
|
|
||||||
| 400 | 参数校验失败 | isCharged 传入值不在 0～1 范围内，message 含 "是否收费取值范围为0或1" |
|
|
||||||
| 401 | 未授权 | JWT 未携带或已过期 |
|
|
||||||
| 404 | 景区不存在 | PUT 时 scenicId 对应景区不存在 |
|
|
||||||
|
|
||||||
## 8. 示例
|
|
||||||
|
|
||||||
### 8.1 典型成功 — 创建收费景区
|
|
||||||
|
|
||||||
场景说明：创建一个收费景区，isCharged 传 1。
|
|
||||||
|
|
||||||
请求：
|
|
||||||
|
|
||||||
```
|
|
||||||
POST /admin/scenic/spot
|
|
||||||
Authorization: Bearer <admin-jwt>
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "呼伦贝尔大草原景区",
|
|
||||||
"province": "内蒙古自治区",
|
|
||||||
"city": "呼伦贝尔市",
|
|
||||||
"isCharged": 1,
|
|
||||||
"status": 0
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
响应（节选关键字段）：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"code": 200,
|
|
||||||
"data": {
|
|
||||||
"scenicId": "1900123456789000001",
|
|
||||||
"name": "呼伦贝尔大草原景区",
|
|
||||||
"isCharged": 1,
|
|
||||||
"isChargedLabel": "是",
|
|
||||||
"status": 0
|
|
||||||
},
|
|
||||||
"message": "ok",
|
|
||||||
"success": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 8.2 边界情况 — 不传 isCharged（GET 详情返回历史数据默认 0）
|
|
||||||
|
|
||||||
场景说明：历史景区数据未填 isCharged，详情接口返回默认值 0（否）。
|
|
||||||
|
|
||||||
请求：
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /admin/scenic/spot/1900000000000000001
|
|
||||||
Authorization: Bearer <admin-jwt>
|
|
||||||
```
|
|
||||||
|
|
||||||
响应（节选关键字段）：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"code": 200,
|
|
||||||
"data": {
|
|
||||||
"scenicId": "1900000000000000001",
|
|
||||||
"name": "某历史景区",
|
|
||||||
"isCharged": 0,
|
|
||||||
"isChargedLabel": "否",
|
|
||||||
"status": 1
|
|
||||||
},
|
|
||||||
"message": "ok",
|
|
||||||
"success": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 8.3 业务失败 — isCharged 超出范围
|
|
||||||
|
|
||||||
场景说明：isCharged 传 2，触发校验失败。
|
|
||||||
|
|
||||||
请求：
|
|
||||||
|
|
||||||
```
|
|
||||||
POST /admin/scenic/spot
|
|
||||||
Authorization: Bearer <admin-jwt>
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "测试景区",
|
|
||||||
"isCharged": 2
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
响应：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"code": 400,
|
|
||||||
"message": "是否收费取值范围为0或1",
|
|
||||||
"success": false
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 9. 业务边界
|
|
||||||
|
|
||||||
- 适用场景：管理后台创建或编辑景区，对「是否收费」属性录入/修改
|
|
||||||
- 不适用场景：小程序端（`/mp/*` 路径）当前**不透传**此字段，小程序暂不展示是否收费信息
|
|
||||||
- 特殊边界：
|
|
||||||
- `isChargedLabel` 依赖字典服务（hl-user-service 字典接口），字典服务异常时该字段返回 null，`isCharged` 数字值正常返回
|
|
||||||
- 历史存量景区数据 `isCharged` 默认为 0（否），不影响现有数据使用
|
|
||||||
- PUT 编辑接口不传 `isCharged` 时字段保持原值不变（非必填增量更新语义）
|
|
||||||
|
|
||||||
## 10. 修改前后对比
|
|
||||||
|
|
||||||
### 入参变化
|
|
||||||
|
|
||||||
| 接口 | 字段 | 变更类型 | 原来 | 现在 |
|
|
||||||
|------|------|----------|------|------|
|
|
||||||
| POST /admin/scenic/spot | isCharged | ✨ 新增 | 不存在 | Integer，可选，默认 0 |
|
|
||||||
| PUT /admin/scenic/spot/{scenicId} | isCharged | ✨ 新增 | 不存在 | Integer，可选，不传不更新 |
|
|
||||||
|
|
||||||
### 出参变化
|
|
||||||
|
|
||||||
| 接口 | 字段 | 变更类型 | 原来 | 现在 |
|
|
||||||
|------|------|----------|------|------|
|
|
||||||
| GET /admin/scenic/spot/{scenicId} | isCharged | ✨ 新增 | 不存在 | Integer：1=是 / 0=否 |
|
|
||||||
| GET /admin/scenic/spot/{scenicId} | isChargedLabel | ✨ 新增 | 不存在 | String：字典中文标签 |
|
|
||||||
| GET /admin/scenic/spots | isCharged | ✨ 新增 | 不存在 | Integer：1=是 / 0=否 |
|
|
||||||
| GET /admin/scenic/spots | isChargedLabel | ✨ 新增 | 不存在 | String：字典中文标签 |
|
|
||||||
|
|
||||||
## 11. 影响评估 / 回滚
|
|
||||||
|
|
||||||
- **是否破坏向后兼容**：否（纯新增字段，旧代码忽略新字段不受影响）
|
|
||||||
- **前端是否必须同步上线**：否，后端先上，前端按需接入新字段
|
|
||||||
- **回滚方案**：无 DDL 依赖风险；字段通过字典服务回填，字典服务异常时 isChargedLabel 为 null 但不影响接口正常返回
|
|
||||||
|
|
||||||
## 12. 注意事项
|
|
||||||
|
|
||||||
- `isChargedLabel` 可能为 null（字典服务异常场景），前端展示时需做空值处理，建议降级显示 `isCharged ? "是" : "否"`
|
|
||||||
- 小程序侧（`/internal/mp/scenic` 路径由 hl-mp-service 消费）当前 mp-service BFF 的独立 VO 未声明此字段，Jackson `convertValue` 会忽略，**小程序前端当前拿不到此字段**；若产品需要小程序展示是否收费，需由 hl-mp-service 单独跟进补字段
|
|
||||||
|
|
||||||
## 13. 关联 / 联系人
|
|
||||||
|
|
||||||
### 13.1 链接
|
|
||||||
|
|
||||||
- **Issue**: [#3313](https://git.1814.love:8443/wx/HL/issues/3313)
|
|
||||||
- **PR**: [#3314](https://git.1814.love:8443/wx/HL/pulls/3314)
|
|
||||||
- **实现 commit**: [62bd9be8b](https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b)
|
|
||||||
|
|
||||||
### 13.2 联系人
|
|
||||||
|
|
||||||
- **后端负责人**: @yaosutu
|
|
||||||
@ -1,266 +0,0 @@
|
|||||||
# [修改接口·小程序] 景区详情/列表透传「是否收费」字段 (#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
|
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户