hl-api-changelog/changelogs-v2/2026-06/01_3313_景区是否收费-修改接口-管理后台.md

景区管理新增「是否收费」字段

• 端类型：管理后台
• 变更类型：修改接口
• 日期：2026-06-01
• Issue：#3313
• PR：#3314
• Commit：62bd9be
• 后端负责人：腰苏图（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
}

响应

{
  "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）

{
  "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 参数校验失败）

{
  "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
• PR：https://git.1814.love:8443/wx/HL/pulls/3314
• Commit：https://git.1814.love:8443/wx/HL/commit/62bd9be8b9ac67bbb2493d0dcb6f2be41172684b
• 后端负责人：腰苏图（企微 / yst@1814.love）