---
schema: "hl-changelog/v2"
ticket: "8087"
title: "餐食下拉按餐厅联动：未选餐厅只给「全部」餐食"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "233de7be087d164a5033ebaa61d85bf1fad378cd"
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`；没选餐厅时不传该参数。切换餐厅后重新调用本接口即可拿到联动后的候选。前端已交付(mmg 2026-09-21, hl-admin 233de7be):订单详情「用餐」页签 MealTab 餐食下拉按行内选中餐厅传 restaurantId(未选不带,即「全部」口径);候选为共享单列表,scopeKey 记录本批候选的餐厅口径,聚焦时与行内餐厅不一致即按该行重查,搜索关键词随行餐厅一并上送;已选中行靠选中标签回显兜底,不受共享列表换口径影响。MealTab 13 例(新增联动 2 例)+dish api 8 例全过,checkpoint 全项通过。交付后修复(mmg 2026-09-21, hl-admin 07dfe636,用户实测反馈):①餐厅清除/更换时清空该行已选餐食(单价保留),回到新口径重选,避免存出「餐厅A餐食+餐厅B/无餐厅」的不一致行;②餐食/餐厅下拉取候选的 loading 圈改为只显当前操作行(候选是共享单状态,此前所有行下拉一起转圈)。MealTab 15 例全过。二次修复(mmg 2026-09-21, hl-admin f9b4ef7c):取候选触发页面级全局遮罩(request.js 普通请求默认 showLoading),getDishList/getRestaurantResourceOptions 默认 showLoading:false,加载反馈回到下拉框自身 loading;全部调用方(MealTab/餐食编辑弹窗/结算餐厅选项)同类一并清零。dish 8 例+resource-options 5 例+MealTab 15 例全过。

---

## 一、背景

订单详情「用餐」页签的餐厅、餐食都是下拉选择，餐食下拉取本接口。此前接口不按餐厅过滤，不论有没有选餐厅，下拉都列出全部上架餐食，与「餐食按餐厅维护、餐厅为空表示全部」（#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