wx/hl-api-changelog

派生 0

yaosutu 52f35eacc8 feat: 酒店是否收费字段 changelog（管理后台 + 小程序端）#3325 #3326

2026-06-01 22:11:56 +08:00

8.6 KiB

原始文件 Blame 文件历史

酒店管理新增「是否收费」字段

端类型：管理后台
变更类型：修改接口
日期：2026-06-01
Issue：#3325
PR：#3326
Commit：58afda7
后端负责人：腰苏图（yst@1814.love）

① 接口背景

酒店资源新增「是否收费」属性，用于在管理后台创建/编辑酒店时标记该酒店是否需要游客付费。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费酒店。字典来源 sys_yes_no，后端已配置，前端无需额外配置。

② 变更清单

接口	方法	路径	变更内容
创建酒店	POST	`/admin/hotel/item`	入参新增 `isCharged`（Integer，默认 0）
更新酒店	PUT	`/admin/hotel/item/{hotelId}`	入参新增 `isCharged`（Integer，可选）
酒店详情	GET	`/admin/hotel/item/{hotelId}`	出参新增 `isCharged` + `isChargedLabel`
酒店列表	GET	`/admin/hotel/items`	出参新增 `isCharged` + `isChargedLabel`

所有变更均为向后兼容新增字段，不涉及字段改名或删除。

③ 接口详情

项目	说明
认证方式	管理后台 JWT Token，请求头 `Authorization: Bearer {token}`
幂等性	POST 创建非幂等；PUT 更新幂等（相同 hotelId 可重复调用）
限流	无单独限流配置，走网关全局限流
权限	管理员角色，普通前端用户无访问权限

④ 接口入参

4.1 路径参数 / Query 参数

PUT /admin/hotel/item/{hotelId}

参数名	类型	必填	说明
hotelId	Long	是	酒店 ID（路径参数）

GET /admin/hotel/items（列表，原有参数不变，无新增查询参数）

4.2 请求体字段（新增字段，含于已有请求体中）

POST /admin/hotel/item（HotelCreateRequest，新增字段）

字段名	类型	必填	校验规则	默认值	说明
isCharged	Integer	否	Min=0, Max=1	0	是否收费，1=是 0=否

PUT /admin/hotel/item/{hotelId}（HotelUpdateRequest，新增字段）

字段名	类型	必填	校验规则	默认值	说明
isCharged	Integer	否	Min=0, Max=1	null（不传则不修改）	是否收费，1=是 0=否

⑤ 出参字段

GET `/admin/hotel/item/{hotelId}` 详情（`HotelVO`，新增字段）

字段名	类型	说明	可能为 null
isCharged	Integer	是否收费，1=是 0=否	否（DB 默认 0）
isChargedLabel	String	是否收费中文文本，取自字典 sys_yes_no（"是"/"否"）	是（字典缺失时为 null）

GET `/admin/hotel/items` 列表（`HotelListVO`，新增字段）

字段名	类型	说明	可能为 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/hotel/item
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "丽江悦榕庄",
  "hotelType": "HOTEL",
  "address": "束河古镇悦榕路1号",
  "longitude": 100.2134,
  "latitude": 26.8721,
  "isCharged": 1
}

响应

{
  "code": 200,
  "msg": "成功",
  "data": {
    "hotelId": "1928000000000001",
    "name": "丽江悦榕庄",
    "isCharged": 1,
    "isChargedLabel": "是",
    "status": 0
  }
}

8.2 边界情况 — 不传 isCharged（使用默认值 0）

请求

POST /admin/hotel/item
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "团队免费住宿点",
  "hotelType": "HOSTEL",
  "address": "丽江古城区某路1号",
  "longitude": 100.2200,
  "latitude": 26.8800
}

响应（isCharged 默认为 0）

{
  "code": 200,
  "msg": "成功",
  "data": {
    "hotelId": "1928000000000002",
    "name": "团队免费住宿点",
    "isCharged": 0,
    "isChargedLabel": "否",
    "status": 0
  }
}

8.3 业务失败 — isCharged 传入越界值

请求

POST /admin/hotel/item
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "测试酒店",
  "hotelType": "HOTEL",
  "address": "测试地址",
  "longitude": 100.0,
  "latitude": 26.0,
  "isCharged": 2
}

响应（400 参数校验失败）

{
  "code": 400,
  "msg": "是否收费取值范围为0或1",
  "data": null
}

⑨ 业务边界

适用场景：

创建新酒店时，可设置是否收费标记（不传默认不收费）
编辑已有酒店时，可随时修改是否收费状态（传 null 或不传则保持原值不变）
列表和详情页均可展示该字段，用于运营人员快速判断酒店性质

不适用场景：

该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理）
不用于权限控制，仅作展示属性

特殊边界：

历史存量酒店（PR #3326 上线前创建的）isCharged 默认为 0（否），isChargedLabel 返回 "否"
PUT 更新时若不传 isCharged 字段，该字段值保持不变（不会被清零）
isChargedLabel 为 null 时属于字典配置异常，非正常情况

⑩ 修改前后对比

字段级对比

入参（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 hotel DROP COLUMN is_charged; 并回退服务部署
前端零改动时回滚对前端无感

⑫ 注意事项

isChargedLabel 依赖字典 sys_yes_no 配置，后端已配置好，前端不需要维护字典表
列表接口返回 isChargedLabel 纯粹为展示便利，前端也可用 isCharged 值自行映射（1→"是"，0→"否"）
PUT 更新时 isCharged 不传（null）表示不修改，区别于传 0（明确设置为否）
历史数据库存量记录 is_charged 列已通过 DDL 添加默认值 0，无历史数据问题

⑬ 关联 / 联系人

Issue：https://git.1814.love:8443/wx/HL/issues/3325
PR：https://git.1814.love:8443/wx/HL/pulls/3326
Commit：https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c
后端负责人：腰苏图（企微 / yst@1814.love）

8.6 KiB 原始文件 Blame 文件历史 Unescape Escape