设备端向菜谱添加菜品接口

用于把指定菜品增量添加到指定档口、指定日期、指定餐次的菜谱中。

基本信息

接口名称设备端向菜谱添加菜品

请求方式POST/api/device/recipe/addDishes

终端分类设备端

控制器application/api/controller/Device.php::recipeAddDishes

服务application/api/service/DeviceRestaurant.php::addDishesToRecipe

请求参数

Content-Type 支持表单 application/x-www-form-urlencoded 或 JSON application/json。

参数	类型	必填	说明
`equipment_code`	string	是	设备编号。兼容别名 `code`。
`dishes_uuid`	string	是	要添加到菜谱中的菜品 uuid。兼容别名 `uuid`。
`restaurant_id`	int	是	档口 ID。
`menu_date`	string	是	菜谱日期，格式 `YYYY-MM-DD`。兼容别名 `date`。
`meal_times`	int	是	餐次：`1` 早餐，`2` 午餐，`3` 晚餐，`4` 加餐。

请求示例

POST /api/device/recipe/addDishes
Content-Type: application/json

{
  "equipment_code": "WEIGH-001",
  "dishes_uuid": "dish-uuid-001",
  "restaurant_id": 12,
  "menu_date": "2026-06-25",
  "meal_times": 2
}

成功响应

接口按幂等方式处理：如果目标菜品已经在该日期、餐次、档口的菜谱中，也返回成功，added_count 为 0。

{
  "code": 0,
  "message": "添加成功",
  "data": {
    "equipment_code": "WEIGH-001",
    "restaurant_id": 12,
    "dishes_uuid": "dish-uuid-001",
    "menu_date": "2026-06-25",
    "meal_times": 2,
    "recipe_uuid": "recipe-uuid-001",
    "added_count": 1
  }
}

失败响应

{
  "code": 1,
  "message": "设备编号不能为空",
  "data": []
}

场景	message
未传设备编号	`设备编号不能为空`
设备不存在	`设备不存在`
未传菜品 uuid	`添加菜品uuid不能为空`
菜品不存在	`菜品不存在`
菜品停用	`菜品已停用`
未传档口 ID	`档口ID不能为空`
档口不存在	`档口不存在`
菜谱日期为空或格式错误	`时间格式错误`
餐次不在 1-4 范围	`餐次参数错误`
添加过程异常	`菜谱菜品添加失败`

处理逻辑

校验设备编号存在于 ydy_equipment 且未删除。
校验菜品 uuid 存在于 ydy_dishes、未删除且启用。
校验档口 ID 存在于 ydy_restaurants 且未删除。
按 dishes_uuid + restaurant_id + menu_date + meal_times 精确匹配 ydy_recipes。
已存在时直接返回成功，added_count=0。
不存在时开启事务插入 ydy_recipes，同步递增 ydy_dishes.menu_quantity，并将菜品标记为食堂常用菜。

测试覆盖

已补充控制器契约测试：tests/apifox/openapi/OpenApiControllerContractValidationTest.php::testDeviceRecipeAddDishesRejectsMissingEquipmentCode

用例	输入	预期
正常添加	合法设备编号、菜品 uuid、档口 ID、日期、餐次	`code=0`，`added_count=1`
幂等添加	目标菜品已在该菜谱	`code=0`，`added_count=0`
缺设备编号	不传 `equipment_code`	`code=1`，`message=设备编号不能为空`
缺菜品 uuid	不传 `dishes_uuid`	`code=1`，`message=添加菜品uuid不能为空`
菜品停用	菜品 `status!=1`	`code=1`，`message=菜品已停用`
日期格式错误	`menu_date=2026/06/25`	`code=1`，`message=时间格式错误`
餐次越界	`meal_times=9`	`code=1`，`message=餐次参数错误`