docs(changelog): #8087 餐食下拉按餐厅联动，未选餐厅只给「全部」餐食（修改接口·管理后台）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-09/21_8087_餐食下拉按餐厅联动未选餐厅只给全部-修改接口-管理后台.md

@@ -0,0 +1,244 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8087"
+title: "餐食下拉按餐厅联动：未选餐厅只给「全部」餐食"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-21"
+status_note: "餐食下拉 GET /admin/dish/items/list 新增可选入参 restaurantId，并改变默认口径：不传只返回餐厅为「全部」（restaurantId 为 null）的上架餐食，传了只返回该餐厅的上架餐食。前端在订单详情「用餐」页签的餐食下拉需按该行选中的餐厅传 restaurantId；没选餐厅时不传。出参字段、排序与条数上限不变。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# resource: 餐食下拉按餐厅联动，未选餐厅只给「全部」餐食
+
+> **服务**: hl-resource-service
+> **PR**: #8089
+> **Issue**: #8087
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台餐食下拉接口 `GET /admin/dish/items/list`
+
+---
+
+## ⚠️ 关键变化
+
+📝 **默认返回口径变了**：不传 `restaurantId` 时，`GET /admin/dish/items/list` 只返回餐厅为「全部」（`restaurantId` 为 `null`）的上架餐食，不再返回所有上架餐食。
+
+🆕 **新增可选入参 `restaurantId`**：传了只返回该餐厅的上架餐食。
+
+**前端需要改**：订单详情「用餐」页签的餐食下拉，按该行当前选中的餐厅传 `restaurantId`；没选餐厅时不传该参数。切换餐厅后重新调用本接口即可拿到联动后的候选。
+
+---
+
+## 一、背景
+
+订单详情「用餐」页签的餐厅、餐食都是下拉选择，餐食下拉取本接口。此前接口不按餐厅过滤，不论有没有选餐厅，下拉都列出全部上架餐食，与「餐食按餐厅维护、餐厅为空表示全部」（#7947）的数据口径对不上。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询餐食列表 | GET | `/admin/dish/items/list` | 入参新增 + 行为变化 | 新增可选 `restaurantId`；不传只返回餐厅为「全部」的上架餐食 |
+
+---
+
+## 三、接口详情
+
+### 1. 查询餐食列表 `GET /admin/dish/items/list`
+
+**VO**: `DishListReqVO` → `List<DishListItemRespVO>`
+
+#### 使用场景
+
+餐食下拉数据源。订单详情「用餐」页签按行选餐厅、选餐食，餐食候选跟着该行选中的餐厅走。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| restaurantId | Query | Long | 否 | 正整数 | **新增**。不传只返回餐厅为「全部」的餐食；传了只返回该餐厅的餐食。0 与负数返回 400「餐厅ID必须为正数」 |
+| keyword | Query | String | 否 | 去首尾空格后 ≤64 | 模糊匹配名称（不变） |
+| settleType | Query | String | 否 | cash / sign / company | 结算方式（不变） |
+| limit | Query | Integer | 否 | 1–200，默认 50 | 最大返回条数（不变） |
+
+四个条件之间是「并且」，并且固定只返回上架（`status=1`）、未删除的餐食。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].dishId | String | 餐食 ID（不变） |
+| [].restaurantId | String | 餐厅 ID，「全部」为 `null`（不变） |
+| [].restaurantName | String | 餐厅名称，「全部」返回「全部」（不变） |
+| [].dishName | String | 餐食名称（不变） |
+| [].unitPrice | Number | 单价（元），两位小数（不变） |
+| [].priceUnit | String | 桌/人：`person` 按人 / `table` 按桌（不变） |
+| [] 其余字段 | — | `imageUrl`、`settleType`、`status`、`remark`、`createdBy`、`createdByName`、`createdAt` 均不变 |
+
+出参字段、排序（创建时间升序、餐食 ID 升序）与条数上限都没有变化，只是返回哪些行变了。
+
+#### 请求示例
+
+```http
+GET /admin/dish/items/list?restaurantId=2023382108491247617&limit=50
+Authorization: Bearer <admin token>
+```
+
+没选餐厅时：
+
+```http
+GET /admin/dish/items/list?limit=50
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [
+    {
+      "dishId": "2100978380923863042",
+      "restaurantId": "2023382108491247617",
+      "restaurantName": "七间房全羊馆",
+      "dishName": "团队标准餐（八菜一汤）",
+      "unitPrice": 35.00,
+      "priceUnit": "person",
+      "imageUrl": null,
+      "settleType": "cash",
+      "status": 1,
+      "remark": null,
+      "createdBy": "1900000000000000001",
+      "createdByName": "张三",
+      "createdAt": "2026-09-19 14:20:03"
+    }
+  ]
+}
+```
+
+#### 空数据 / 降级响应
+
+`data` 为 `[]`：没选餐厅且没有「全部」类上架餐食，或所选餐厅下没有上架餐食（例如该餐厅的餐食都被下架）。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "餐厅ID必须为正数", "success": false, "data": null }
+```
+
+```json
+{ "code": 400, "message": "limit最大为200", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 「全部」的餐食只在不传 `restaurantId` 时出现；传了某餐厅就只有该餐厅自己的餐食。
+- 下架、已删除的餐食任何情况下都不返回。
+- 本接口只决定下拉候选，不影响订单用餐的保存：订单仍按页面传的餐厅、餐食原样存。
+
+---
+
+## 四、契约约束与正确调用方式
+
+| 场景 | 调用 |
+|------|------|
+| ✅ 该行没选餐厅 | `GET /admin/dish/items/list?limit=50`（不带 `restaurantId`） |
+| ✅ 该行选了餐厅 | `GET /admin/dish/items/list?restaurantId=<餐厅ID>&limit=50` |
+| ✅ 换了餐厅 | 用新餐厅 ID 重新调用本接口取候选 |
+| ❌ 用 `restaurantId=0` 表示「全部」 | 400「餐厅ID必须为正数」；表示「全部」要省略该参数 |
+| ❌ 用 `restaurantId=-1` | 400「餐厅ID必须为正数」 |
+
+---
+
+## 五、数据库行为
+
+只读查询，不写库。过滤条件对应 `dish.restaurant_id`：不传时按 `restaurant_id IS NULL` 查，传了按等值查。餐食数据本身没有任何改动。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截），不变。
+- 所选餐厅不存在或已删除：不报错，返回 `[]`（接口不回查餐厅表）。
+- `restaurantId` 与 `keyword`、`settleType`、`limit` 是「并且」关系。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 入参 `restaurantId` | 无 | 新增，可选，正整数 |
+| 入参 `keyword` / `settleType` / `limit` | — | 不变 |
+| 出参全部字段 | — | 不变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 不传 `restaurantId` | 返回所有上架餐食 | 只返回餐厅为「全部」的上架餐食 |
+| 传 `restaurantId` | 参数被忽略，返回所有上架餐食 | 只返回该餐厅的上架餐食 |
+| 排序、条数上限、只查上架 | — | 不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。老调用方不传 `restaurantId` 时，拿到的候选会收窄为「全部」类餐食。
+- **前端是否必须同步上线**: 是。餐食下拉需按选中的餐厅传 `restaurantId`，否则选了餐厅也只能看到「全部」类餐食。
+- **前端 workaround 清理点**: 无。
+
+## 七、不影响范围
+
+- **仅影响**: 餐食下拉 `GET /admin/dish/items/list` 返回哪些行
+- **零影响**:
+  - 餐食分页 `GET /admin/dish/items/page`、详情 `GET /admin/dish/items/{dishId}/view`
+  - 餐食新建 `POST /admin/dish/items/add`、修改 `PUT /admin/dish/items/{dishId}/update`、上下架 `PUT /admin/dish/items/{dishId}/status/update`、删除 `DELETE /admin/dish/items/{dishId}/del`
+  - 餐厅接口与订单用餐信息、用餐模版接口
+  - 已有餐食数据
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `79722aef1`，部署前后各抓一次本接口返回做比对：
+
+```
+不传 restaurantId                        → 12 条收窄为 9 条，全部是 restaurantId 为 null 的上架餐食 ✓
+不传 restaurantId 的行出参                → 与部署前逐字段一致 ✓
+restaurantId=2023382108491247617（七间房全羊馆） → 只返回该餐厅上架的 2 条，出参逐字段一致 ✓
+restaurantId=2023382111074938881（九牧羊鲜羊火锅） → 只返回该餐厅上架的 1 条 ✓
+restaurantId=2023382100664676353（菌香园火锅，餐食全下架） → 返回 [] ✓
+restaurantId=0 / -1                       → 400「餐厅ID必须为正数」 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8087](https://git.1814.love:8443/wx/HL/issues/8087)
+- 关联 PR: [wx/HL#8089](https://git.1814.love:8443/wx/HL/pulls/8089)
+- 餐食按餐厅维护的由来: [#7947 Changelog](19_7947_餐食删除编码关联餐厅增加桌人-修改接口-管理后台.md)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8087](https://git.1814.love:8443/wx/HL/issues/8087)
+- **PR**: [#8089](https://git.1814.love:8443/wx/HL/pulls/8089)
+- **Merge commit**: [79722aef1](https://git.1814.love:8443/wx/HL/commit/79722aef18000ec004f85262bbfc64c1b33b8201)
+
+### 联系人
+
+- **后端负责人**: @lc