wx/hl-api-changelog

派生 0

yaosutu 9f13f63ef6 文档(restaurant): 餐厅新增「是否收费」字段 — 管理后台接口 changelog (#3317/#3318)

2026-06-01 17:41:44 +08:00

9.0 KiB

原始文件 Blame 文件历史

餐厅管理新增「是否收费」字段

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

① 接口背景

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

② 变更清单

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

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

③ 接口详情

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

④ 接口入参

4.1 路径参数 / Query 参数

PUT /admin/restaurant/item/{restaurantId}

参数名	类型	必填	说明
restaurantId	Long	是	餐厅 ID（路径参数）

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

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

POST /admin/restaurant/item（RestaurantCreateRequest，新增字段）

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

PUT /admin/restaurant/item/{restaurantId}（RestaurantUpdateRequest，新增字段）

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

⑤ 出参字段

GET `/admin/restaurant/item/{restaurantId}` 详情（`RestaurantVO`，新增字段）

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

GET `/admin/restaurant/items` 列表（`RestaurantListVO`，新增字段）

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

{
  "name": "云端藏餐",
  "categoryCode": "TIBETAN",
  "province": "西藏自治区",
  "city": "拉萨市",
  "cityName": "拉萨",
  "longitude": 91.132,
  "latitude": 29.660,
  "isCharged": 1
}

响应

{
  "code": 200,
  "msg": "成功",
  "data": {
    "restaurantId": "1927000000000001",
    "name": "云端藏餐",
    "isCharged": 1,
    "isChargedLabel": "是",
    "status": 0,
    ...
  }
}

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

请求

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

{
  "name": "免费体验餐厅",
  "categoryCode": "CHINESE",
  "province": "西藏自治区",
  "city": "拉萨市",
  "cityName": "拉萨",
  "longitude": 91.100,
  "latitude": 29.650
  // isCharged 字段不传
}

响应（isCharged 默认为 0）

{
  "code": 200,
  "msg": "成功",
  "data": {
    "restaurantId": "1927000000000002",
    "name": "免费体验餐厅",
    "isCharged": 0,
    "isChargedLabel": "否",
    "status": 0,
    ...
  }
}

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

请求

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

{
  "name": "测试餐厅",
  "categoryCode": "CHINESE",
  "province": "西藏自治区",
  "city": "拉萨市",
  "cityName": "拉萨",
  "longitude": 91.100,
  "latitude": 29.650,
  "isCharged": 2
}

响应（400 参数校验失败）

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

⑨ 业务边界

适用场景：

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

不适用场景：

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

特殊边界：

历史存量餐厅（PR #3318 上线前创建的）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 restaurant 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/3317
PR：https://git.1814.love:8443/wx/HL/pulls/3318
Commit：https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804
后端负责人：腰苏图（企微 / yst@1814.love）

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