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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8087	餐食下拉按餐厅联动：未选餐厅只给「全部」餐食	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	233de7be087d164a5033ebaa61d85bf1fad378cd		2026-09-21	餐食下拉 GET /admin/dish/items/list 新增可选入参 restaurantId，并改变默认口径：不传只返回餐厅为「全部」（restaurantId 为 null）的上架餐食，传了只返回该餐厅的上架餐食。前端在订单详情「用餐」页签的餐食下拉需按该行选中的餐厅传 restaurantId；没选餐厅时不传。出参字段、排序与条数上限不变。	2026-09-21	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 升序）与条数上限都没有变化，只是返回哪些行变了。

请求示例

GET /admin/dish/items/list?restaurantId=2023382108491247617&limit=50
Authorization: Bearer <admin token>

没选餐厅时：

GET /admin/dish/items/list?limit=50
Authorization: Bearer <admin token>

响应示例

{
  "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 为 []：没选餐厅且没有「全部」类上架餐食，或所选餐厅下没有上架餐食（例如该餐厅的餐食都被下架）。

错误响应

{ "code": 400, "message": "餐厅ID必须为正数", "success": false, "data": null }

{ "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
• 关联 PR: wx/HL#8089
• 餐食按餐厅维护的由来: #7947 Changelog

关联 / 联系人

链接

• Issue: #8087
• PR: #8089
• Merge commit: 79722aef1

联系人

• 后端负责人: @lc