# MES 一袋一码（批次 / 托盘 / 袋码）前端联调方案

## 涉及页面

- 生产批次管理（`mes/pro/batch`）
- 托盘码管理（`mes/pro/pallet`）
- 袋码赋码管理（`mes/pro/bagCode`）
- 扫码追溯弹窗（`mes/pro/components/qr-trace-modal`）

## 总体流程

三类码统一采用“先生成唯一二维码，再录入业务信息”：

1. 生产批次：预生成临时批次码（`PB-YYYYYYYY`）→ 补录品种、袋型、产线、日期、责任人、生产人员（生成正式批次号 `PC...`）。
2. 托盘：预生成临时托盘码（`PL-YYYYYYYY`，不绑定批次）→ 绑定已正式补录且生产中的生产批次（生成正式托盘码 `批次号-PXX`）。
3. 袋码：先生成唯一袋码（`BAG-YYYYYYYY`，不绑定批次）→ 录入已正式补录且生产中的生产批次 → 绑定同批次托盘。

二维码一经打印不会因“转正式”而失效：扫码追溯同时兼容正式码与临时码，临时码扫码回持久保留并映射到原记录。

## API

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/mes/pro/batch/pre-generate` | 预生成批次临时二维码（不录入业务信息） |
| PUT | `/mes/pro/batch/fill-info` | 批次补录正式信息（生成正式批次号） |
| GET | `/mes/pro/batch/get-by-code?code=` | 批次扫码追溯（兼容正式码与临时码） |
| GET | `/mes/pro/batch/export-qr?batchId=` | 按批次导出整套二维码 ZIP |
| POST | `/mes/pro/pallet/pre-generate` | 预生成托盘临时二维码（不绑定批次） |
| PUT | `/mes/pro/pallet/bind-batch` | 托盘绑定生产批次（生成正式托盘码） |
| POST | `/mes/pro/pallet/export-qr-by-ids` | 按编号列表导出托盘二维码 ZIP（支持临时托盘） |
| GET | `/mes/pro/pallet/export-qr?batchId=` | 按批次导出托盘二维码 ZIP |
| GET | `/mes/pro/pallet/get-by-code?code=` | 托盘扫码追溯（兼容正式码与临时码） |
| POST | `/mes/pro/bag-code/generate` | 只生成唯一袋码，不绑定生产批次 |
| PUT | `/mes/pro/bag-code/bind-batch` | 袋码录入生产批次 |
| GET | `/mes/pro/bag-code/get-by-code?code=` | 袋码扫码追溯 |

### 批次接口

**预生成请求（`/mes/pro/batch/pre-generate`）：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `count` | Integer | 是 | 生成批次个数，必须大于 0 |
| `remark` | String | 否 | 备注 |

响应 `data`：`[{ id, tempCode }]`，`tempCode` 为临时批次码（二维码内容）。

**补录信息请求（`/mes/pro/batch/fill-info`）：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | Long | 是 | 临时批次编号 |
| `itemId` | Long | 是 | 品种（产品物料）编号 |
| `lineId` | Long | 是 | 产线编号 |
| `produceDate` | Datetime | 是 | 生产日期 |
| `ownerUserId` | Long | 是 | 责任人 |
| `workers` | List | 是 | 生产人员配置（user_id / worker_type） |
| `remark` | String | 否 | 备注 |

服务端校验通过后生成正式批次号并将批次状态保持为草稿；`code` 为正式批次号，`tempCode` 仍保留供历史扫码。

### 托盘接口

**预生成请求（`/mes/pro/pallet/pre-generate`）：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `count` | Integer | 是 | 生成数量，必须大于 0 |
| `capacity` | Integer | 否 | 可装袋数（袋/托盘） |
| `remark` | String | 否 | 备注 |

响应 `data`：`[{ id, tempCode }]`，`tempCode` 为临时托盘码（二维码内容）。

**绑定批次请求（`/mes/pro/pallet/bind-batch`）：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | Long[] | 是 | 待绑定的临时托盘编号列表 |
| `batchId` | Long | 是 | 生产批次编号 |

仅允许未绑定批次的临时托盘绑定；目标批次必须已完成正式信息补录且处于生产中。绑定后按批次内序号生成正式托盘码。

**按编号导出二维码（`/mes/pro/pallet/export-qr-by-ids`）：** 请求 `{ ids: Long[] }`，返回 ZIP；未绑定批次的临时托盘会显示“未绑定批次”状态而非虚构批次信息。

### 袋码录入批次请求（`/mes/pro/bag-code/bind-batch`）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `ids` | Long[] | 是 | 待录入的袋码 ID 列表 |
| `batchId` | Long | 是 | 生产批次 ID |

目标批次必须已完成正式信息补录（`code` 非空）且处于生产中；录入后批次的袋码数量同步重算。托盘一律通过手工“预生成 → 绑定批次 → 绑定袋码”流程维护。

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|---|---|---|
| `code` | 列表、详情、二维码 | 正式批次号 / 正式托盘码 |
| `tempCode` | 列表、详情、扫码追溯（新增） | 临时批次码（`PB-`）/ 临时托盘码（`PL-`）；未补录/未绑定时作为二维码展示值 |
| `status`（批次） | 列表、追踪 | 未补录临时批次为“草稿”，列表显示“待补录”标签 |
| `batchId` / `batchCode`（托盘） | 列表、详情 | 未绑定为空，列表显示“未绑定批次”标签 |
| 批次业务字段 | 追溯 | 未补录/未绑定时不展示虚构的品种、产线、日期、责任人 |

## 业务规则说明

| 场景 | 规则 |
|---|---|
| 预生成批次 | 不要求品种/袋型/产线/日期/责任人；生成全局唯一临时批次码，状态为草稿 |
| 批次补录 | 仅允许尚未生成正式批次号的临时批次；重复补录提示“已补录” |
| 批次开始生产 | 未补录正式信息的临时批次不允许进入生产（后端校验 + 前端按钮隐藏） |
| 预生成托盘 | 不要求生产批次；生成全局唯一临时托盘码，`batchId` 为空 |
| 托盘绑定批次 | 临时托盘仅能绑定已正式补录且生产中的批次；跨批次、重复绑定被拒绝 |
| 临时托盘出库 | 未绑定批次的托盘禁止参与销售出库等业务操作 |
| 袋码录入批次 | 仅允许生产中的正式批次；临时批次不可作为录入目标 |
| 袋码绑定托盘 | 双方必须为同一正式批次；未绑定批次的临时托盘不可参与绑定 |
| 二维码导出 | 临时批次/临时托盘按临时码导出；业务信息为空时不显示虚构内容 |
| 扫码识别 | `PB-YYYYYYYY`→批次、`PL-YYYYYYYY`→托盘、`批次号-PXX`→托盘、`BAG-YYYYYYYY`→袋码；正式批次号/托盘码照常识别 |

## 注意事项

- 前端调用顺序：批次“预生成 → 补录信息 → 开始生产”；托盘“预生成 → 绑定批次 → 绑定袋码”；袋码“生成 → 录入批次 → 绑定托盘”。
- 批次正式化后 `tempCode` 不删除，历史打印的临时二维码扫码仍能追溯，勿用正式码覆盖临时码。
- 临时托盘在绑定批次前不可被袋码绑定、不可销售出库；批量绑定需先勾选多条临时托盘记录。
- 补录/绑定失败时保留当前选择，避免误以为已完成业务关联。