# [修改接口·管理后台] 景区资源新增「是否收费」字段 (#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