DishMatch/配比秤-制作菜品-API文档.md

配比秤（新设备）— 制作菜品 API 文档

Controller: NutRatioScaleController 路径前缀: /neglect/ratio-scale（Nacos 白名单 /nutrition/neglect/**，无需 Sa-Token） 设备上下文通过请求头 X-DEVICE-CODE 解析（TerminalContextHelper） 用户上下文通过请求头 X-DEVICE-TOKEN 解析（DeviceAuthContextHelper，获取登录厨师信息） 日期: 2026-07-29

序列化规则：Long 类型字段响应中均为字符串（Jackson ToStringSerializer），BigDecimal 为普通数字 单位约定：

• 食材用量（actualQty、useWeight）统一为 克 (g)
• 烹制单生重（rawWeight）、熟重（cookedWeight）为 千克 (kg)

---

业务背景

配比秤是一款独立于现有组配秤（/neglect 路径）的新硬件设备，部署在食堂后厨。第一期实现"按单烹制"功能：厨师在配比秤终端上查看当日烹饪任务 → 查看菜品食材构成 → 提交食材实际用量并触发组配完成 → 开始烹制 → 烹饪完成后提交熟重和调料用量。

核心流程

当日烹饪任务列表 → 查看菜品食材构成 → 去制作（提交主辅材实际用量） → 烹饪完成（提交熟重 + 调料用量）

烹制状态枚举

状态码	状态名	说明
0	待烹制	初始状态，可进行"去制作"操作
1	烹制中	已提交制作，可进行"烹饪完成"操作
2	已完成	烹制结束，不可再操作
3	异常	异常状态

食材分类枚举

分类	名称	说明
1	主材	菜品主要食材
2	辅材	菜品辅助食材
3	调料	油盐酱醋等，烹饪完成时提交

---

接口清单

序号	接口	路径	用途
一	当日烹饪任务列表（按餐次分组）	POST /neglect/ratio-scale/cook-orders/page	按餐次分组返回今日需烹制的菜品列表
二	菜品食材构成	GET /neglect/ratio-scale/cook-orders/{cookOrderId}/composition	查看菜品的主材和辅材清单（含标准用量）
三	去制作	POST /neglect/ratio-scale/cook-orders/submit	提交主辅材实际用量，完善组配并开始烹制
四	烹饪完成	POST /neglect/ratio-scale/cook-orders/finish	提交熟重和调料用量，计算生熟比

---

一、当日烹饪任务列表（按餐次分组）

POST /neglect/ratio-scale/cook-orders/page
Content-Type: application/json
X-DEVICE-CODE: <设备编码>
X-DEVICE-TOKEN: <设备登录Token>

查询当前食堂当日的烹饪任务，后端按餐次分组返回，每个餐次为一个独立对象，内含该餐次下的烹制单列表。

请求体

{
  "date": "2026-07-29",           // 选填 — 计划日期 yyyy-MM-dd，默认当天
  "mealType": 2,                  // 选填 — 餐次筛选: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐
  "keyword": "红烧肉",             // 选填 — 菜品名称模糊搜索
  "pageNum": 1,                   // 选填 — 保留字段，当前不使用
  "pageSize": 20                  // 选填 — 保留字段，当前不使用
}

注：mealType 不传则返回全部餐次；传了只返回对应餐次的单个分组。

响应

{
  "code": "200",
  "msg": "操作成功",
  "data": [
    {
      "mealType": 2,                    // 餐次: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐
      "mealTypeName": "午餐",           // 餐次中文名称
      "cookOrders": [
        {
          "cookOrderId": "10001",       // 烹制单id
          "cookNo": "CK20260729001",    // 烹制单号
          "dishName": "红烧肉",          // 菜品名称
          "foodId": "5001",             // 菜品id（关联 nut_food）
          "mealType": 2,                // 餐次
          "mealTypeName": "午餐",       // 餐次中文
          "cookStatus": 0,              // 烹制状态: 0=待烹制 / 1=烹制中 / 2=已完成 / 3=异常
          "cookStatusName": "待烹制",    // 烹制状态中文
          "rawWeight": null,            // 生重(kg) — 烹制完成后才有值
          "needPortions": 5,            // 需求份数
          "cookedPortions": null        // 烹制份数 — 烹制完成后才有值
        },
        {
          "cookOrderId": "10002",
          "cookNo": "CK20260729002",
          "dishName": "清炒时蔬",
          "foodId": "5002",
          "mealType": 2,
          "mealTypeName": "午餐",
          "cookStatus": 1,
          "cookStatusName": "烹制中",
          "rawWeight": 3.500,
          "needPortions": 3,
          "cookedPortions": 3
        }
      ]
    },
    {
      "mealType": 3,
      "mealTypeName": "晚餐",
      "cookOrders": [
        {
          "cookOrderId": "10003",
          "cookNo": "CK20260729003",
          "dishName": "清蒸鲈鱼",
          "foodId": "5003",
          "mealType": 3,
          "mealTypeName": "晚餐",
          "cookStatus": 0,
          "cookStatusName": "待烹制",
          "rawWeight": null,
          "needPortions": 2,
          "cookedPortions": null
        }
      ]
    }
  ]
}

逻辑说明

• 数据源：nut_prod_cook_order 表
• 查询条件：canteen_id = 终端食堂ID（由 X-DEVICE-CODE 解析） + plan_date = 指定日期（默认当天）
• 排序规则：meal_type ASC, create_time DESC
• 后端按 mealType 分组，每组为一个 NutRatioCookMealGroupVO 对象，内含 mealType + mealTypeName + cookOrders 列表
• keyword 字段对 dish_name 做 LIKE 模糊匹配
• rawWeight 在烹制完成后为累计主辅材实际用量之和（kg），烹制中为 null

---

二、菜品食材构成（主材+辅材）

GET /neglect/ratio-scale/cook-orders/{cookOrderId}/composition
X-DEVICE-CODE: <设备编码>
X-DEVICE-TOKEN: <设备登录Token>

查询烹制单对应菜品的主材和辅材清单（不包含调料，调料在烹饪完成时单独提交）。

路径参数

参数	类型	必填	说明
cookOrderId	Long	是	烹制单id

响应

{
  "code": "200",
  "msg": "操作成功",
  "data": [
    {
      "materId": "20001",               // 食材id
      "ingredientName": "五花肉",        // 食材名称
      "ingredientClass": 1,             // 食材分类: 1=主材 / 2=辅材
      "ingredientClassName": "主材",     // 食材分类中文
      "useWeight": 500.0,               // 标准用量(g)
      "vegTypeId": "10"                 // 净菜类型id
    },
    {
      "materId": "20002",
      "ingredientName": "土豆",
      "ingredientClass": 2,
      "ingredientClassName": "辅材",
      "useWeight": 300.0,
      "vegTypeId": "10"
    }
  ]
}

逻辑说明

• 先通过烹制单查询 food_id（菜品id），再查 nut_food_composition 表
• 仅返回 is_main IN (1, 2) 的食材（主材和辅材），调料（is_main=3）不在此接口返回
• 食材名称通过 nut_mater_base 批量查询后回填
• vegTypeId 为净菜类型id，用于前端展示毛菜/净菜标识

---

三、去制作：提交食材实际用量并开始烹制

POST /neglect/ratio-scale/cook-orders/submit
Content-Type: application/json
X-DEVICE-CODE: <设备编码>
X-DEVICE-TOKEN: <设备登录Token>

厨师在秤上完成主辅材称重后，提交各食材的实际用量。后端自动完成：组配任务完善 → 组配完成 → 烹制单状态切换为"烹制中" → 烹制食材明细更新。

该接口为事务性操作（@Transactional），所有步骤在同一事务中执行，任意步骤失败则全部回滚。

请求体

{
  "cookOrderId": 10001,                 // 必填 — 烹制单id
  "items": [                            // 必填 — 食材实际用量列表，至少1条
    {
      "materId": 20001,                 // 必填 — 食材id
      "actualQty": 520.5                // 必填 — 实际用量(g)
    },
    {
      "materId": 20002,
      "actualQty": 310.0
    }
  ]
}

响应

{
  "code": "200",
  "msg": "操作成功",
  "data": null
}

处理流程

1. 校验烹制单状态 = 0（待烹制），否则报错
2. 通过内供申领单关联餐品净菜包：
   链路: nut_prod_cook_order.food_id → nut_sup_internal_supply(food_id + canteen_id + clean_type=2)
        → batch_no → nut_sup_meal_package → nut_sup_meal_pkg_ingredient → trace_code
3. 解析各食材的溯源码（materId → traceCode 映射）
4. 完善组配任务明细（按 materCode 匹配 comboTaskItem，更新 actualQty + traceCode）
5. 完成组配任务（comboStatus=2，记录完成时间）
6. 计算生重（Σ actualQty / 1000，g→kg，保留3位小数）
7. 从设备Token获取厨师信息（chef + chefId）
8. 更新烹制单：
   - cookStatus → 1（烹制中）
   - cookStart → 当前时间
   - rawWeight → 生重(kg)
   - chef / chefId → 登录厨师
   - needPortions / cookedPortions → 份数
9. 更新烹制食材明细（cook_ingredient）：
   - 已有明细 → 更新 actualQty + traceCode
   - 无已有明细 → 按 foodComposition 自动创建兜底记录

份数计算优先级

内供申领单 quantity > 烹制单 needPortions > 兜底值 1

异常场景

场景	错误信息
烹制单不存在	烹制单不存在
当前状态不是"待烹制"	当前状态不允许此操作，仅待烹制状态可提交制作
烹制单未关联组配任务（comboNo 为空）	烹制单未关联组配任务，无法开始烹制
组配任务不存在	组配任务不存在，comboNo=xxx

涉及数据表

表名	操作	说明
nut_prod_cook_order	查询 + 更新	校验状态，更新为烹制中
nut_sup_internal_supply	查询	通过 foodId + canteenId + cleanType=2 关联，获取 batchNo 和 quantity
nut_sup_meal_package	查询	通过 batchNo 查餐品净菜包
nut_sup_meal_pkg_ingredient	查询	获取各食材的溯源码
nut_prod_combo_task	查询 + 更新	完善组配状态为已完成
nut_prod_combo_task_item	查询 + 更新	更新 actualQty + traceCode
nut_prod_cook_ingredient	查询 + 新增/更新	更新实际用量，不存在时兜底创建
nut_mater_base	查询	获取食材编码和名称
nut_food_composition	查询	兜底创建 cook_ingredient 时获取食材分类等信息

---

四、烹饪完成：提交熟重和调料用量

POST /neglect/ratio-scale/cook-orders/finish
Content-Type: application/json
X-DEVICE-CODE: <设备编码>
X-DEVICE-TOKEN: <设备登录Token>

烹饪结束后，厨师在秤上称量熟重，并提交调料用量。后端自动计算生熟比。

该接口为事务性操作（@Transactional）。

请求体

{
  "cookOrderId": 10001,                 // 必填 — 烹制单id
  "cookedWeight": 3.200,                // 必填 — 熟重(kg)
  "seasonings": [                       // 选填 — 调料用量列表
    {
      "materId": 30001,                 // 必填 — 调料食材id
      "actualQty": 15.0                 // 必填 — 实际用量(g)
    },
    {
      "materId": 30002,
      "actualQty": 8.5
    }
  ]
}

响应

{
  "code": "200",
  "msg": "操作成功",
  "data": null
}

处理流程

1. 校验烹制单状态 = 1（烹制中），否则报错
2. 如有调料：保存到 nut_prod_cook_ingredient
   - 已在 cook_ingredient 中的调料（ingredientClass=3） → 更新 actualQty
   - 新调料 → 新增记录（ingredientClass=3 调料）
3. 计算生熟比 = cookedWeight / rawWeight（保留3位小数，HALF_UP）
4. 更新烹制单：
   - cookStatus → 2（已完成）
   - cookedWeight → 熟重(kg)
   - rawCookedRatio → 生熟比
   - cookEnd → 当前时间

生熟比计算

生熟比 = 熟重(kg) / 生重(kg)
精度: 3位小数, HALF_UP
条件: 生重 > 0 且熟重 != null 时才计算，否则生熟比为 null

异常场景

场景	错误信息
烹制单不存在	烹制单不存在
当前状态不是"烹制中"	当前状态不允许此操作，仅烹制中状态可完成烹制

涉及数据表

表名	操作	说明
nut_prod_cook_order	查询 + 更新	校验状态，更新为已完成，记录熟重和生熟比
nut_prod_cook_ingredient	查询 + 新增/更新	保存调料用量（ingredientClass=3）
nut_mater_base	查询	获取调料食材编码和名称

---

总体数据链路图

nut_prod_cook_order (烹制单)
    │
    ├── food_id ──→ nut_food_composition (菜品食材构成: 主材/辅材/调料)
    │                    │
    │                    └── mater_id ──→ nut_mater_base (食材库: 编码、名称、分类)
    │
    ├── canteen_id + food_id ──→ nut_sup_internal_supply (内供申领单)
    │                                   │
    │                                   ├── batch_no ──→ nut_sup_meal_package (餐品净菜包)
    │                                   │                      │
    │                                   │                      └── nut_sup_meal_pkg_ingredient (溯源码)
    │                                   │
    │                                   └── quantity ──→ 份数
    │
    ├── combo_no ──→ nut_prod_combo_task (组配任务)
    │                      │
    │                      └── nut_prod_combo_task_item (组配明细: ingredientCode)
    │
    └── cook_ingredient: nut_prod_cook_ingredient (烹制食材明细)

---

接口调用时序

┌─────────┐          ┌─────────────┐          ┌──────────┐
│ 配比秤终端 │          │ Controller   │          │ Database  │
└────┬────┘          └──────┬──────┘          └────┬─────┘
     │                      │                      │
     │ 1. POST /cook-orders/page                   │
     │─────────────────────→│                      │
     │                      │──→ nut_prod_cook_order (当日+食堂)
     │  ← 任务列表(按餐次)    │←────────────────────│
     │                      │                      │
     │ 2. GET /cook-orders/{id}/composition        │
     │─────────────────────→│                      │
     │                      │──→ nut_food_composition (主材+辅材)
     │                      │──→ nut_mater_base (食材名称)
     │  ← 食材清单(含标准用量)  │←────────────────────│
     │                      │                      │
     │ 3. POST /cook-orders/submit                 │
     │─────────────────────→│                      │
     │                      │──→ 校验状态=待烹制     │
     │                      │──→ 关联internal_supply │
     │                      │──→ 解析溯源码          │
     │                      │──→ 完善+完成组配任务    │
     │                      │──→ 计算生重            │
     │                      │──→ 更新烹制单=烹制中    │
     │                      │──→ 更新食材明细        │
     │  ← 操作成功            │←──── 事务提交 ──────│
     │                      │                      │
     │ 4. POST /cook-orders/finish                 │
     │─────────────────────→│                      │
     │                      │──→ 校验状态=烹制中     │
     │                      │──→ 保存调料用量        │
     │                      │──→ 计算生熟比          │
     │                      │──→ 更新烹制单=已完成    │
     │  ← 操作成功            │←──── 事务提交 ──────│
     │                      │                      │