文档(restaurant): 餐厅新增「是否收费」字段 — 小程序端接口 changelog (#3317/#3318)

2026-06-01 17:41:58 +08:00 · 2026-06-01 17:41:58 +08:00 · 66f94cadcd
--- a/changelogs-v2-mp/2026-06/01_3317_餐厅是否收费-修改接口-小程序端.md
+++ b/changelogs-v2-mp/2026-06/01_3317_餐厅是否收费-修改接口-小程序端.md
@ -0,0 +1,249 @@
+# 餐厅新增「是否收费」字段（小程序端）
+
+- **端类型**：小程序端
+- **变更类型**：修改接口
+- **日期**：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`，后端已配置并完成翻译，小程序无需任何字典配置。
+
+---
+
+## ② 变更清单
+
+| 接口 | 方法 | 路径 | 变更内容 |
+|------|------|------|----------|
+| 餐厅详情 | GET | `/mp/restaurant/{restaurantId}` | 出参新增 `isCharged` + `isChargedLabel` |
+| 餐厅列表 | GET | `/mp/restaurant/list` | 出参新增 `isCharged` + `isChargedLabel` |
+
+所有变更均为**向后兼容新增字段**，小程序现有调用代码无需修改。
+
+---
+
+## ③ 接口详情
+
+| 项目 | 说明 |
+|------|------|
+| **认证方式** | 小程序 JWT Token，请求头 `Authorization: Bearer {mp_token}` |
+| **幂等性** | GET 查询，天然幂等 |
+| **限流** | 无单独限流配置，走网关全局限流 |
+| **缓存** | 详情接口缓存 300 秒（`restaurant:detail:{id}`），列表接口缓存 600 秒（`restaurant:list:{keyword}:{city}:{page}:{pageSize}`）。新字段随正常缓存刷新即可，无需额外处理 |
+| **权限** | 小程序用户，已登录状态 |
+
+---
+
+## ④ 接口入参
+
+### GET `/mp/restaurant/{restaurantId}` 详情
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| restaurantId | Long | 是 | 餐厅 ID（路径参数） |
+
+### GET `/mp/restaurant/list` 列表
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | String | 否 | - | 关键词搜索 |
+| city | String | 否 | - | 城市筛选 |
+| page | Integer | 否 | 1 | 页码 |
+| pageSize | Integer | 否 | 20 | 每页条数 |
+
+> 入参无变化，以上为完整入参文档。
+
+---
+
+## ⑤ 出参字段
+
+### GET `/mp/restaurant/{restaurantId}` 详情（`MpRestaurantDetailVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+### GET `/mp/restaurant/list` 列表（`MpRestaurantListItemVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+### sys_yes_no 字典（后端已配置，小程序无需维护）
+
+| 字典值（isCharged） | 中文标签（isChargedLabel） | 建议小程序展示 |
+|--------------------|-----------------------------|----------------|
+| 1 | 是 | 收费 / 付费 |
+| 0 | 否 | 免费 |
+
+> `isChargedLabel` 由后端查字典自动翻译并返回，小程序可直接展示。若字典配置异常（不正常情况），该字段返回 null，建议展示"-"或不显示该标签。
+
+---
+
+## ⑦ 错误码
+
+| 错误码 | HTTP 状态 | 场景 |
+|--------|-----------|------|
+| 401 | 401 | 未登录或 Token 失效 |
+| 404 | 404 | 餐厅 ID 不存在、已删除或已下架 |
+
+---
+
+## ⑧ 示例
+
+### 8.1 典型成功 — 获取收费餐厅详情
+
+**请求**
+```
+GET /mp/restaurant/1927000000000001
+Authorization: Bearer {mp_token}
+```
+
+**响应**
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "restaurantId": "1927000000000001",
+    "name": "云端藏餐",
+    "subtitle": "正宗藏式风味体验",
+    "categoryCode": "TIBETAN",
+    "categoryName": "藏式",
+    "isCharged": 1,
+    "isChargedLabel": "是",
+    "status": 1,
+    "cityName": "拉萨",
+    "pricePerPerson": 88.00,
+    ...
+  }
+}
+```
+
+### 8.2 边界情况 — 免费餐厅列表（isChargedLabel 返回"否"）
+
+**请求**
+```
+GET /mp/restaurant/list?city=拉萨&page=1&pageSize=20
+Authorization: Bearer {mp_token}
+```
+
+**响应**（列表中包含收费和免费餐厅，均有 isCharged/isChargedLabel）
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "total": 2,
+    "list": [
+      {
+        "restaurantId": "1927000000000001",
+        "name": "云端藏餐",
+        "isCharged": 1,
+        "isChargedLabel": "是",
+        ...
+      },
+      {
+        "restaurantId": "1927000000000002",
+        "name": "团队免费体验餐",
+        "isCharged": 0,
+        "isChargedLabel": "否",
+        ...
+      }
+    ]
+  }
+}
+```
+
+### 8.3 业务失败 — 访问已下架餐厅
+
+**请求**
+```
+GET /mp/restaurant/1927000000000099
+Authorization: Bearer {mp_token}
+```
+
+**响应**（404，餐厅不存在或下架）
+```json
+{
+  "code": 404,
+  "msg": "餐厅不存在",
+  "data": null
+}
+```
+
+---
+
+## ⑨ 业务边界
+
+**适用场景**：
+- 小程序餐厅详情页展示"是否收费"标签（如"免费"/"付费"徽标）
+- 小程序餐厅列表卡片可展示收费状态，帮助用户快速识别
+
+**不适用场景**：
+- `isCharged` 仅为展示属性，不影响小程序下单流程或费用计算
+- 不可作为用户端过滤条件（列表接口不支持按 `isCharged` 筛选）
+
+**特殊边界**：
+- 历史存量餐厅（PR #3318 上线前创建）`isCharged` 默认为 0，`isChargedLabel` 返回 "否"
+- `isChargedLabel` 为 null 属于后台字典配置异常，小程序侧可用 isCharged 自行映射（1→"是"，0→"否"）
+- 该字段受缓存影响：管理后台修改 isCharged 后，小程序侧缓存最多 5-10 分钟后自动刷新（详情 300s / 列表 600s）
+
+---
+
+## ⑩ 修改前后对比
+
+### 字段级对比
+
+**出参（详情 + 列表）**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 |
+| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null |
+
+### 行为级对比
+
+| 行为 | 变更前 | 变更后 |
+|------|--------|--------|
+| 餐厅详情接口 | 无收费信息 | 新增 isCharged + isChargedLabel |
+| 餐厅列表接口 | 无收费信息 | 新增 isCharged + isChargedLabel |
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+**破坏兼容性**：无，新增字段，现有小程序代码可忽略不用。
+
+**前端同步上线**：无强制要求，可选接入展示。建议在餐厅卡片/详情增加"免费"/"收费"标签。
+
+**回滚方案**：若后端回滚，`isCharged` 和 `isChargedLabel` 字段会从响应中消失，小程序需做防御性处理（字段不存在时不展示）。
+
+---
+
+## ⑫ 注意事项
+
+1. 小程序**无需**配置 `sys_yes_no` 字典，后端已完成翻译并在 `isChargedLabel` 中直接返回中文
+2. 若不需要展示该字段，忽略即可，不影响任何现有功能
+3. 建议小程序对 `isChargedLabel` 做 null 防御（`isChargedLabel ?? isCharged === 1 ? '是' : '否'`）
+4. 受缓存影响，运营后台修改后小程序最长延迟 10 分钟可见，属正常现象
+
+---
+
+## ⑬ 关联 / 联系人
+
+- **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）