文档(admin-scenic): 新增「是否收费」字段 changelog (#3313/#3314)
这个提交包含在：
yaosutu
父节点
6b611e1711
当前提交
70a8fcdc6f
@ -0,0 +1,262 @@
|
|||||||
|
# [修改接口·管理后台] 景区资源新增「是否收费」字段 (#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
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户