mazengfei
6d3c5490a4
- 新增手动录入食材信息的UI布局，包含食材名称搜索、主辅材选择及用量输入 - 整合采样模式下的食材搜索弹窗，支持食材模糊查询与净材种类选择 - 新增相关网络接口调用，实现食材搜索、菜品搜索、菜品构成查询及采样历史等功能 - 优化食材列表展示，支持采样历史审核状态和熟重显示，增加颜色区分 - 修改PrepareFoodActivity，采样模式启用手动新增食材功能，包含添加、重置操作 - 调整Adapter和ViewModel，兼容新接口数据模型，支持分页加载和状态回调 - 修正接口路径和网络请求地址，统一使用nutrition/neglect路径前缀 - 删除冗余代码和未使用的旧接口代码，简化搜索逻辑及界面响应机制
424 lines
16 KiB
Markdown
424 lines
16 KiB
Markdown
# 配比秤（新设备）— 制作菜品 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 | 待烹制 | 初始状态，可进行"烹饪完成"操作 |
|
||
| 2 | 已完成 | 烹制结束，不可再操作 |
|
||
| 3 | 异常 | 异常状态 |
|
||
|
||
### 食材分类枚举
|
||
|
||
| 分类 | 名称 | 说明 |
|
||
|:----:|------|------|
|
||
| 1 | 主材 | 菜品主要食材 |
|
||
| 2 | 辅材 | 菜品辅助食材 |
|
||
| 3 | 调料 | 油盐酱醋等，烹饪完成时提交 |
|
||
|
||
---
|
||
|
||
## 接口清单
|
||
|
||
| 序号 | 接口 | 路径 | 用途 |
|
||
|:----:|------|------|------|
|
||
| 一 | 当日烹饪任务列表（按餐次分组） | `POST /neglect/ratio-scale/cook-orders/list` | 按餐次分组返回今日需烹制的菜品列表 |
|
||
| 二 | 菜品食材构成 | `GET /neglect/ratio-scale/cook-orders/{cookOrderId}/composition` | 查看菜品的主材和辅材清单（含标准用量） |
|
||
| 三 | 烹饪完成 | `POST /neglect/ratio-scale/cook-orders/complete` | 提交主辅材用量+熟重+调料，一次完成烹制 |
|
||
| 四 | 调料模糊搜索 | `POST /neglect/ratio-scale/seasoning-search` | 模糊搜索调料（糖蜜饯+油脂+调味品三大类） |
|
||
|
||
---
|
||
|
||
## 一、当日烹饪任务列表（按餐次分组）
|
||
|
||
```
|
||
POST /neglect/ratio-scale/cook-orders/list
|
||
Content-Type: application/json
|
||
X-DEVICE-CODE: <设备编码>
|
||
X-DEVICE-TOKEN: <设备登录Token>
|
||
```
|
||
|
||
查询当前食堂当日的烹饪任务，后端按餐次分组返回，每个餐次为一个独立对象，内含该餐次下的烹制单列表。
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"date": "2026-07-29", // 选填 — 计划日期 yyyy-MM-dd，默认当天
|
||
"mealType": 2, // 选填 — 餐次筛选: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐
|
||
"keyword": "红烧肉" // 选填 — 菜品名称模糊搜索
|
||
}
|
||
```
|
||
|
||
> 注：`mealType` 不传则返回全部餐次；传了只返回对应餐次的单个分组。
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"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 |
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"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/complete
|
||
Content-Type: application/json
|
||
X-DEVICE-CODE: <设备编码>
|
||
X-DEVICE-TOKEN: <设备登录Token>
|
||
```
|
||
|
||
厨师在秤上完成称重后一次性提交全部数据，后端自动完成：组配任务完善 → 组配完成 → 计算生重生熟比 → 保存调料 → 烹制单置为已完成。
|
||
|
||
**该接口为事务性操作（`@Transactional`），所有步骤在同一事务中执行，任意步骤失败则全部回滚。**
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"cookOrderId": 10001, // 必填 — 烹制单id
|
||
"items": [ // 必填 — 主辅材实际用量列表，至少1条
|
||
{
|
||
"materId": 20001, // 必填 — 食材id
|
||
"actualQty": 520.5 // 必填 — 实际用量(g)
|
||
},
|
||
{
|
||
"materId": 20002,
|
||
"actualQty": 310.0
|
||
}
|
||
],
|
||
"cookedWeight": 3.200, // 必填 — 熟重(kg)
|
||
"seasonings": [ // 选填 — 调料用量列表
|
||
{
|
||
"materId": 30001, // 必填 — 调料食材id
|
||
"actualQty": 15.0 // 必填 — 实际用量(g)
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"msg": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 处理流程
|
||
|
||
```
|
||
1. 校验烹制单状态 = 0（待烹制），否则报错
|
||
2. 通过内供申领单关联餐品净菜包：
|
||
链路: nut_prod_cook_order(food_id + canteen_id + meal_type) → nut_prod_clean_order(food_id + canteen_id + meal_type + clean_type=2)
|
||
→ clean_order_id → nut_sup_internal_supply(clean_order_id + clean_type=2)
|
||
→ batch_no → nut_sup_meal_package → nut_sup_meal_pkg_ingredient → trace_code
|
||
餐次匹配：通过 nut_prod_clean_order.meal_type 过滤，确保同菜不同餐次不会串单
|
||
3. 解析各食材的溯源码（materId → traceCode 映射）
|
||
4. 完善组配任务明细（按 materCode 匹配 comboTaskItem，更新 actualQty + traceCode）
|
||
5. 完成组配任务（comboStatus=2，记录完成时间）
|
||
6. 计算生重（Σ actualQty / 1000，g→kg，保留3位小数）
|
||
7. 从设备Token获取厨师信息（chef + chefId）
|
||
8. 更新烹制食材明细（主辅材 actualQty + traceCode，无已有明细时兜底创建）
|
||
9. 保存调料用量（ingredientClass=3）
|
||
10. 计算生熟比 = 熟重 / 生重（保留3位小数，HALF_UP，生重>0且熟重≠null时才计算）
|
||
11. 更新烹制单：
|
||
- cookStatus → 2（已完成）
|
||
- cookStart / cookEnd → 当前时间
|
||
- rawWeight → 生重(kg)
|
||
- cookedWeight → 熟重(kg)
|
||
- rawCookedRatio → 生熟比
|
||
- chef / chefId → 登录厨师
|
||
- needPortions / cookedPortions → 份数
|
||
```
|
||
|
||
### 份数计算优先级
|
||
|
||
```
|
||
内供申领单 quantity > 烹制单 needPortions > 兜底值 1
|
||
```
|
||
|
||
### 异常场景
|
||
|
||
| 场景 | 错误信息 |
|
||
|------|---------|
|
||
| 烹制单不存在 | `烹制单不存在` |
|
||
| 当前状态不是"待烹制" | `当前状态不允许此操作，仅待烹制状态可提交` |
|
||
| 烹制单未关联组配任务（comboNo 为空） | `烹制单未关联组配任务，无法开始烹制` |
|
||
| 组配任务不存在 | `组配任务不存在，comboNo=xxx` |
|
||
|
||
### 涉及数据表
|
||
|
||
| 表名 | 操作 | 说明 |
|
||
|------|:--:|------|
|
||
| `nut_prod_cook_order` | 查询 + 更新 | 校验状态，更新为已完成 |
|
||
| `nut_prod_clean_order` | 查询 | 通过 foodId + canteenId + mealType + cleanType=2 匹配净菜订单，获取 clean_order_id 用于内供申领单的餐次过滤 |
|
||
| `nut_sup_internal_supply` | 查询 | 通过 clean_order_id + 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/seasoning-search
|
||
Content-Type: application/json
|
||
X-DEVICE-CODE: <设备编码>
|
||
```
|
||
|
||
搜索调料食材库，数据源 `nut_mater_base` 一级分类为 18(糖蜜饯)、19(油脂)、20(调味品) 的食材。
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"keyword": "酱油", // 选填 — 模糊匹配食材名称和别名
|
||
"pageNum": 1, // 必填 — 页码
|
||
"pageSize": 20 // 必填 — 每页条数
|
||
}
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"msg": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": "30001",
|
||
"materName": "酱油",
|
||
"materCode": "19192004",
|
||
"alias": "生抽",
|
||
"canteenId": "2"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Long → String | 食材id |
|
||
| materName | String | 食材名称 |
|
||
| materCode | String | 食材编码 |
|
||
| alias | String | 别名 |
|
||
| canteenId | Long → String | 归属食堂id |
|
||
|
||
---
|
||
|
||
## 总体数据链路图
|
||
|
||
```
|
||
nut_prod_cook_order (烹制单)
|
||
│
|
||
├── food_id ──→ nut_food_composition (菜品食材构成: 主材/辅材/调料)
|
||
│ │
|
||
│ └── mater_id ──→ nut_mater_base (食材库: 编码、名称、分类)
|
||
│
|
||
├── food_id + canteen_id + meal_type ──→ nut_prod_clean_order (净菜订单, clean_type=2)
|
||
│ │
|
||
│ └── id = clean_order_id
|
||
│
|
||
├── clean_order_id ──→ nut_sup_internal_supply (内供申领单, 按 clean_order_id + clean_type=2 匹配)
|
||
│ │
|
||
│ ├── 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/complete │
|
||
│─────────────────────→│ │
|
||
│ │──→ 校验状态=待烹制 │
|
||
│ │──→ 匹配净菜订单(餐次过滤) │
|
||
│ │──→ 关联internal_supply │
|
||
│ │──→ 解析溯源码 │
|
||
│ │──→ 完善+完成组配任务 │
|
||
│ │──→ 计算生重 │
|
||
│ │──→ 更新食材明细 │
|
||
│ │──→ 保存调料用量 │
|
||
│ │──→ 计算生熟比 │
|
||
│ │──→ 更新烹制单=已完成 │
|
||
│ ← 操作成功 │←──── 事务提交 ──────│
|
||
│ │ │
|
||
```
|