From 9f13f63ef61d1ebae807751649150e026cfbe6cf Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 1 Jun 2026 17:41:44 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3(restaurant):=20=E9=A4=90?= =?UTF-8?q?=E5=8E=85=E6=96=B0=E5=A2=9E=E3=80=8C=E6=98=AF=E5=90=A6=E6=94=B6?= =?UTF-8?q?=E8=B4=B9=E3=80=8D=E5=AD=97=E6=AE=B5=20=E2=80=94=20=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E5=90=8E=E5=8F=B0=E6=8E=A5=E5=8F=A3=20changelog=20(#3?= =?UTF-8?q?317/#3318)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01_3317_餐厅是否收费-修改接口-管理后台.md | 291 ++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md new file mode 100644 index 0000000..699bd54 --- /dev/null +++ b/changelogs-v2/2026-06/01_3317_餐厅是否收费-修改接口-管理后台.md @@ -0,0 +1,291 @@ +# 餐厅管理新增「是否收费」字段 + +- **端类型**：管理后台 +- **变更类型**：修改接口 +- **日期**：2026-06-01 +- **Issue**：[#3317](https://git.1814.love:8443/wx/HL/issues/3317) +- **PR**：[#3318](https://git.1814.love:8443/wx/HL/pulls/3318) +- **Commit**：[3ad5860](https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804) +- **后端负责人**：腰苏图（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 +} +``` + +**响应** +```json +{ + "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） +```json +{ + "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 参数校验失败） +```json +{ + "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;` 并回退服务部署 +- 前端零改动时回滚对前端无感 + +--- + +## ⑫ 注意事项 + +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/3317](https://git.1814.love:8443/wx/HL/issues/3317) +- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3318](https://git.1814.love:8443/wx/HL/pulls/3318) +- **Commit**：[https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804](https://git.1814.love:8443/wx/HL/commit/3ad5860883819058a58ec384de0c5aac7c918804) +- **后端负责人**：腰苏图（企微 / yst@1814.love）