# 生产批次与赋码管理（一袋一码） - 前端联调方案

> ⚠️ **本文档已过时**：三个页面已提取为独立顶级模块「一袋一码管理」，并移除品种、设备、工单关联，
> 最新接口以 `mes_bag_code_module_decouple.md` 为准。

## 功能概述

1. **批次生产管理**：录入生产批次（人—机—种全环节数字化对接），配置生产人员（责任落实到人），批次号自动生成（编码规则：前缀 PC + 日期 + 产线 + 品种 + 流水号）。
2. **赋码管理（一袋一码）**：根据批次信息自动生成唯一二维码数据包（袋码），支持批量导出交付印刷；二维码内容为袋码字符串，扫码后可反查批次、品种、产线、生产日期、责任人。
3. **托盘码管理**：按批次批量生成托盘码（批次号-P+序号），袋码可绑定/解绑到托盘。

## 涉及页面

- 生产管控 → 生产管理 → **批次生产管理**（新增页面：列表 + 新增/编辑表单 + 详情）
- 生产管控 → 生产管理 → **赋码管理**（新增页面：袋码列表 + 生成数据包弹窗 + 扫码追溯）
- 生产管控 → 生产管理 → **托盘码管理**（新增页面：托盘列表 + 批量生成弹窗）

## 业务流程与数据带入

1. **新增批次**：选择品种（物料）→ 手填产线编码/名称 → 可选设备、工单 → 选生产日期、责任人 → 配置生产人员（至少 1 人）。保存后**批次号自动生成**，无需填写。
2. **批次 → 袋码生成**：生成袋码时只需传入 `batchId` 和袋数，批次号、品种等信息由后端自动带入袋码记录。
3. **批次 → 托盘码生成**：生成托盘码时只需传入 `batchId`、数量、可装袋数，批次号自动带入。
4. **袋码 → 托盘绑定**：先选批次再选托盘（托盘下拉用 `GET /mes/pro/pallet/simple-list?batchId=` 获取，只展示该批次的托盘），勾选袋码后绑定。
5. **扫码追溯**：扫出的二维码内容即袋码字符串，直接作为 `code` 参数调 `GET /mes/pro/bag-code/get-by-code` 反查全部信息。

## 批次状态流转

| 当前状态 | 可流转到 | 说明 |
|----------|----------|------|
| 10 草稿 | 20 生产中、40 已作废 | 创建后初始为草稿 |
| 20 生产中 | 30 已完成、40 已作废 | 只有生产中才能生成袋码/托盘码 |
| 30 已完成 | — | 终态 |
| 40 已作废 | — | 终态 |

字典类型：`mes_pro_batch_status`。

## API 一：生产批次（权限前缀 `mes:pro-batch`）

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | /mes/pro/batch/create | 创建批次（自动生成批次号） | mes:pro-batch:create |
| PUT | /mes/pro/batch/update | 更新批次（含人员配置重建） | mes:pro-batch:update |
| DELETE | /mes/pro/batch/delete | 删除批次 | mes:pro-batch:delete |
| PUT | /mes/pro/batch/update-status | 更新批次状态 | mes:pro-batch:update |
| GET | /mes/pro/batch/get | 批次详情（含人员配置） | mes:pro-batch:query |
| GET | /mes/pro/batch/page | 批次分页 | mes:pro-batch:query |
| GET | /mes/pro/batch/simple-list | 批次精简列表（供下拉选择） | mes:pro-batch:query |
| GET | /mes/pro/batch/export-excel | 导出批次 Excel | mes:pro-batch:export |

### 创建/更新请求参数（POST /create、PUT /update）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 更新时必填 | 批次编号 |
| itemId | Long | 是 | 品种（产品物料）编号，下拉选物料 |
| lineCode | String | 是 | 产线编码（手填，参与批次号生成，建议限制长度 ≤ 4） |
| lineName | String | 否 | 产线名称（手填） |
| machineryId | Long | 否 | 生产设备编号 |
| workOrderId | Long | 否 | 关联生产工单编号 |
| produceDate | String | 是 | 生产日期，格式 yyyy-MM-dd HH:mm:ss |
| planQuantity | Number | 否 | 计划数量 |
| ownerUserId | Long | 是 | 责任人用户编号（责任落实到人） |
| remark | String | 否 | 备注 |
| workers | Array | 是 | 生产人员配置，至少 1 条 |
| workers[].userId | Long | 是 | 生产人员用户编号 |
| workers[].workerType | Integer | 是 | 岗位类型（字典 mes_pro_batch_worker_type：10 组长/20 操作工/30 包装工/40 质检员/50 其他） |
| workers[].remark | String | 否 | 备注 |

### 分页查询参数（GET /page）

| 参数 | 类型 | 说明 |
|------|------|------|
| code | String | 批次号（模糊） |
| itemId | Long | 品种编号 |
| lineCode / lineName | String | 产线编码/名称（模糊） |
| machineryId | Long | 设备编号 |
| workOrderId | Long | 工单编号 |
| ownerUserId | Long | 责任人编号 |
| status | Integer | 批次状态（字典 mes_pro_batch_status） |
| produceDate | Array | 生产日期范围 [开始, 结束] |
| createTime | Array | 创建时间范围 |
| pageNo / pageSize | Integer | 分页参数 |

### 更新状态参数（PUT /update-status）

Query 参数：`id`（批次编号）、`status`（目标状态）。

### 响应字段（列表/详情）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 编号 |
| code | String | 批次号（自动生成，如 PC20260818L01NY001） |
| itemId / itemCode / itemName / itemSpecification | — | 品种编号/编码/名称/规格（后端拼接） |
| lineCode / lineName | String | 产线编码/名称 |
| machineryId / machineryCode / machineryName | — | 设备编号/编码/名称（后端拼接） |
| workOrderId / workOrderCode | — | 工单编号/编码（后端拼接） |
| produceDate | String | 生产日期 |
| planQuantity | Number | 计划数量 |
| ownerUserId / ownerUserName | — | 责任人编号/昵称（后端拼接） |
| bagQuantity | Integer | 已生成袋码数量 |
| palletQuantity | Integer | 已生成托盘码数量 |
| status | Integer | 批次状态（字典 mes_pro_batch_status） |
| remark | String | 备注 |
| createTime | String | 创建时间 |
| workers | Array | 人员配置列表（仅 GET /get 详情返回） |
| workers[].id / batchId / userId / userName / workerType / remark | — | 人员配置明细（userName 后端拼接） |

## API 二：袋码赋码（权限前缀 `mes:pro-bag-code`）

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | /mes/pro/bag-code/generate | 生成袋码数据包 | mes:pro-bag-code:create |
| DELETE | /mes/pro/bag-code/delete-by-uuid | 删除生成组（整组删除） | mes:pro-bag-code:delete |
| PUT | /mes/pro/bag-code/bind-pallet | 袋码绑定托盘 | mes:pro-bag-code:update |
| PUT | /mes/pro/bag-code/unbind-pallet | 袋码解绑托盘 | mes:pro-bag-code:update |
| GET | /mes/pro/bag-code/get | 袋码详情 | mes:pro-bag-code:query |
| GET | /mes/pro/bag-code/get-by-code | 扫码追溯（按袋码反查） | mes:pro-bag-code:query |
| GET | /mes/pro/bag-code/page | 袋码分页 | mes:pro-bag-code:query |
| GET | /mes/pro/bag-code/list-by-uuid | 生成组的袋码列表 | mes:pro-bag-code:query |
| GET | /mes/pro/bag-code/export-excel | 批量导出（交付印刷） | mes:pro-bag-code:export |

### 生成数据包（POST /generate）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| batchId | Long | 是 | 生产批次编号（批次须为"生产中"状态） |
| count | Integer | 是 | 本次生成袋数（手动输入，必须大于 0） |
| remark | String | 否 | 备注 |

响应 `data` 为生成组 UUID（字符串），同一次生成的袋码共享该 UUID。

### 删除生成组（DELETE /delete-by-uuid）

Query 参数：`uuid`。仅当组内袋码全部为"已生成"状态且未绑定托盘时允许。

### 绑定/解绑托盘（PUT /bind-pallet、PUT /unbind-pallet）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| palletId | Long | 是 | 托盘编号 |
| ids | Array<Long> | 是 | 袋码编号列表 |

### 分页查询参数（GET /page）

| 参数 | 类型 | 说明 |
|------|------|------|
| code | String | 袋码（模糊） |
| batchId | Long | 批次编号 |
| batchCode | String | 批次号（模糊） |
| uuid | String | 生成组 UUID |
| palletId | Long | 托盘编号 |
| status | Integer | 袋码状态（字典 mes_pro_bag_code_status） |
| createTime | Array | 创建时间范围 |

### 袋码响应字段（列表/详情）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 编号 |
| uuid | String | 生成组 UUID |
| code | String | 袋码（二维码内容，如 PC20260818L01NY001-0001） |
| bagNo | Integer | 批次内袋序号 |
| batchId / batchCode | — | 批次编号/批次号 |
| itemId / itemCode / itemName / itemSpecification | — | 品种编号/编码/名称/规格（后端拼接） |
| lineCode / lineName | String | 产线编码/名称（后端拼接） |
| palletId / palletCode | — | 绑定托盘编号/托盘码（未绑定为 null） |
| status | Integer | 状态（字典 mes_pro_bag_code_status：10 已生成/20 已导出印刷/30 已作废） |
| printTime | String | 导出（交付印刷）时间 |
| createTime | String | 创建时间 |

### 扫码追溯响应字段（GET /get-by-code）

Query 参数：`code`（袋码字符串，即二维码扫出的内容）。不存在时返回错误码 1040752000。

| 字段 | 类型 | 说明 |
|------|------|------|
| id / code / bagNo / status / printTime | — | 袋码信息 |
| batchId / batchCode / batchStatus / produceDate | — | 批次信息 |
| lineCode / lineName | String | 产线 |
| ownerUserId / ownerUserName | — | 责任人 |
| itemId / itemCode / itemName / itemSpecification | — | 品种信息 |
| palletId / palletCode | — | 绑定托盘信息 |

### 批量导出（GET /export-excel）

参数同分页查询（建议按 `batchId` 或 `uuid` 过滤导出指定数据包）。**导出后，后端自动将导出的"已生成"状态袋码标记为"已导出印刷"并记录导出时间**，前端导出成功后应刷新列表状态。

## API 三：托盘码（权限前缀 `mes:pro-pallet`）

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | /mes/pro/pallet/batch-create | 批量生成托盘码 | mes:pro-pallet:create |
| DELETE | /mes/pro/pallet/delete | 删除托盘码 | mes:pro-pallet:delete |
| GET | /mes/pro/pallet/get | 托盘码详情 | mes:pro-pallet:query |
| GET | /mes/pro/pallet/page | 托盘码分页 | mes:pro-pallet:query |
| GET | /mes/pro/pallet/simple-list | 批次的托盘列表（供下拉选择） | mes:pro-pallet:query |
| GET | /mes/pro/pallet/export-excel | 导出托盘码 Excel | mes:pro-pallet:export |

### 批量生成（POST /batch-create）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| batchId | Long | 是 | 生产批次编号（批次须为"生产中"状态） |
| count | Integer | 是 | 生成数量（必须大于 0） |
| capacity | Integer | 否 | 可装袋数（袋/托盘），用于绑定时容量校验 |
| remark | String | 否 | 备注 |

响应 `data` 为生成的托盘编号列表。

### 分页查询参数（GET /page）

code（模糊）、batchId、batchCode（模糊）、status（字典 mes_pro_pallet_status）、createTime[]。

### 托盘响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 编号 |
| code | String | 托盘码（如 PC20260818L01NY001-P01） |
| batchId / batchCode | — | 批次编号/批次号 |
| palletNo | Integer | 批次内托盘序号 |
| capacity | Integer | 可装袋数 |
| bagCount | Integer | 已绑定袋码数量 |
| status | Integer | 状态（字典 mes_pro_pallet_status：10 启用/20 作废） |
| remark / createTime | — | 备注/创建时间 |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 批次号 code | 批次列表、详情、袋码列表、托盘列表 | 自动生成，不可编辑 |
| 品种（编码+名称+规格） | 批次列表、批次详情、袋码列表 | 下拉选择物料，展示用后端拼接字段 |
| 产线编码/名称 | 批次表单（手填）、批次列表、袋码列表 | 产线编码参与批次号生成 |
| 责任人 | 批次列表、详情、扫码追溯 | 用户选择器 |
| 生产人员 workers | 批次新增/编辑表单（子表）、批次详情 | 岗位类型用字典 mes_pro_batch_worker_type 下拉 |
| 袋码数量 bagQuantity / 托盘码数量 palletQuantity | 批次列表 | 只读，生成/删除码后后端自动维护 |
| 二维码内容 code | 袋码列表、导出 Excel | 袋码字符串即二维码内容 |
| 托盘码 palletCode | 袋码列表（绑定时展示）、托盘列表 | 绑定后自动带出 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 批次号生成规则 | 前缀 PC + 日期(yyyyMMdd) + 产线编码+品种编码(截取8位) + 流水号(3位，按日循环)，全自动生成 |
| 袋码生成规则 | 袋码 = 批次号 + "-" + 4位袋序号（如 -0001），序号只增不减，全局唯一 |
| 托盘码生成规则 | 托盘码 = 批次号 + "-P" + 2位托盘序号，序号只增不减，全局唯一 |
| 生成码前置条件 | 批次必须为"生产中(20)"状态 |
| 批次修改 | 仅草稿/生产中可修改；修改品种或产线编码会自动重新生成批次号 |
| 批次删除 | 仅草稿/已作废可删除；已生成袋码或托盘码的批次不允许删除 |
| 生成组删除 | 仅组内袋码全部为"已生成"且未绑定托盘时允许；删除后批次袋码数量自动回减 |
| 袋码绑定托盘 | 袋码与托盘必须属于同一批次；袋码未绑定过托盘；绑定后总数不超过托盘可装袋数 |
| 导出即印刷 | 导出 Excel 后，导出的"已生成"袋码自动变为"已导出印刷"并记录时间 |
| 二维码内容 | 二维码内容 = 袋码字符串（如 PC20260818L01NY001-0001），扫码后调 get-by-code 反查 |

## 菜单与权限

菜单已初始化：批次生产管理、赋码管理、托盘码管理（挂在生产管控 → 生产管理下），按钮权限分别为 `mes:pro-batch:*`、`mes:pro-bag-code:*`、`mes:pro-pallet:*`。

## 注意事项

- 批次号、袋码、托盘码均由后端自动生成，**前端表单不提供任何编码输入框**。
- 生成袋码/托盘码前，先用 `GET /mes/pro/batch/simple-list` 让用户选择批次（只允许选择"生产中"状态的批次，前端可按 status=20 过滤）。
- 绑定托盘时，托盘下拉应调用 `GET /mes/pro/pallet/simple-list?batchId=`，确保托盘与袋码同批次。
- 生成袋码的 `count` 为手动输入的本次袋数，可能分多次生成，序号自动接续，不会重复。
- 扫码追溯接口对不存在的袋码返回错误（错误码 1040752000），前端需提示"袋码不存在"。
- 导出袋码 Excel 会改变袋码状态（已生成 → 已导出印刷），导出后请刷新列表；重复导出同一数据包不会重复变更状态。
- 岗位类型、批次状态、袋码状态、托盘状态均为字典项，字典类型分别为 `mes_pro_batch_worker_type`、`mes_pro_batch_status`、`mes_pro_bag_code_status`、`mes_pro_pallet_status`。