# 配比秤烹饪时长 - 设备端对接文档

> 本次变更：配比秤新增「烹饪时长」采集与计算能力。设备端只需**传烹饪开始时间**和**调料放置时间**，时长由后端自动计算落库，设备端不需要自己算。
>
> 部署依赖：数据库迁移 `V21__nut_innovation_cook_duration.sql` 需先于服务发布执行。

---

## 通用说明

- 时间格式统一为 `yyyy-MM-dd HH:mm:ss`
- 时长单位：**分钟**，由后端计算，规则：`时长 = 接口调用时间 - 烹饪开始时间`，**向上取整，正数至少 1 分钟**（如 90 秒 → 2 分钟，30 秒 → 1 分钟）
- 烹饪开始时间为空、或晚于当前时间（无效）时，后端**跳过时长计算**，接口正常成功

---

## 1. 提交采样（新增入参字段）

**POST** `/nutrition/neglect/ratio-scale/constitute/save`

### 请求参数（仅列出新增字段，其余字段不变）

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| cookStart | string | 建议 | **新增**。烹饪开始时间，用于与提交时间计算烹饪时长(分钟) |
| items[].putTime | string | - | **新增**。调料放置时间，仅调料项（`isMain=3`）传，主材/辅材不传 |

### 完整请求示例

```json
{
  "foodName": "低钠宫保鸡丁",
  "foodWeight": 1250.5,
  "cookStart": "2026-09-21 10:30:00",
  "items": [
    { "materId": 1001, "useWeight": 500, "isMain": 1 },
    { "materId": 1002, "useWeight": 200, "isMain": 2 },
    { "materId": 1003, "useWeight": 15,  "isMain": 3, "putTime": "2026-09-21 10:32:10" },
    { "materId": 1004, "useWeight": 8,   "isMain": 3, "putTime": "2026-09-21 10:35:40" }
  ]
}
```

### 后端行为

- 烹饪开始时间落库 `nut_innovation.cook_start`，时长落库 `nut_innovation.cook_duration`，调料放置时间落库 `nut_innovation_ing.put_time`
- 响应结构不变（`Result<Void>`）

---

## 2. 烹饪完成（入参字段无变化，传值要求强化）

**POST** `/nutrition/neglect/ratio-scale/cook-orders/complete`

### 相关字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| cookOrderId | long | ✓ | 烹制单 id（原有） |
| cookStart | string | **强烈建议** | 烹饪开始时间（字段原有）。**本次开始烹饪时务必回传**，否则不计算时长 |
| seasonings[].putTime | string | - | 调料放置时间（字段原有），继续按原逻辑传 |

### 后端行为（新增）

- 每次完成按 `本次 cookStart → 接口调用时间` 计算时长，**更新菜品烹饪工艺表 `nut_food_cook.cook_duration`**
- **多次烹饪时长不累计、各算各的**：同一烹制单多次提交时，每次都用本次的时长**覆盖**菜品烹饪时长
- 同时写一条餐品操作记录（后台可见）：操作标题「配比秤烹饪餐品计算」，记录时长从 X 分钟更新为 Y 分钟
- `cookStart` 为空时跳过以上更新，其余原有逻辑（流水、生熟比、累加）不受影响

---

## 3. 已提交采样列表（响应新增字段）

**POST** `/nutrition/neglect/ratio-scale/sample-list`

### 响应 `data.list[]` 新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| cookStart | string | **新增**。烹饪开始时间；提交时未传则为 null |
| cookDuration | int | **新增**。烹饪时长(分钟)；提交时未传 cookStart 则为 null |

### 响应示例

```json
{
  "code": "00000",
  "msg": "操作成功",
  "data": {
    "list": [
      {
        "innovId": 1930123456789,
        "innovNo": "INN-H-2026-041",
        "foodName": "低钠宫保鸡丁",
        "foodWeight": 1250.5,
        "cookStart": "2026-09-21 10:30:00",
        "cookDuration": 12,
        "status": 1,
        "statusName": "实验中",
        "createTime": "2026-09-21 10:42:03"
      }
    ],
    "total": 1
  }
}
```

---

## 设备端改动清单

| 接口 | 改动 |
|------|------|
| constitute/save | 请求新增 `cookStart` + 调料项 `putTime`（开始烹饪时记录时间，放调料时记录时间） |
| cook-orders/complete | 字段无变化，确保每次提交回传 `cookStart`；`seasonings[].putTime` 继续传 |
| sample-list | 响应新增 `cookDuration`，列表可展示「烹饪时长(分钟)」 |