# 一袋一码生产逻辑改造 - 需求方案

> 状态：已确认并完成实施（2026-09-17）。决策点定稿见文末「6. 确认结论」。

## 1. 需求背景

一袋一码的生产逻辑调整：

- 批次生产管理**不再绑定品种**，品种下沉到「赋码管理」的数据包上。
- 生成数据包时选择**品种**并输入**托盘数**，系统按品种主计量单位的「类型」自动计算袋码数量并生成袋码。
- 按托盘数**自动生成托盘并自动绑定**袋码；托盘不再需要「可装袋数」。
- 品种为「吨」时无托盘：改为直接输入**袋码数**，袋码只绑生产批次、不绑托盘码。

## 2. 现状要点

| 对象 | 现状 |
|------|------|
| 数据包生成 | `POST /mes/pro/bag-code/generate` 仅传 `count`，生成空白袋码（无品种/批次/托盘） |
| 批次 | `mes_pro_batch.itemId` 绑定品种；批次号 = PC + 日期 + 产线编码 + 品种编码 + 流水号 |
| 托盘 | 手动创建（批量生成/预生成），创建时填 `capacity 可装袋数`；袋码手动绑托盘并校验容量 |
| 品种→单位 | `mdm_item.unitMeasureId → mdm_unit_measure.type`（类型选项：48千克/100千克/吨，本次已加） |
| 追溯 | 扫码追溯的品种信息取自批次 `batch.itemId` |

## 3. 改造方案

### 3.1 生成数据包（赋码管理，核心改动）

**换算规则**（后端计算，不信任前端传值）：

| 品种主单位类型 | 输入 | 生成结果 |
|------|------|------|
| 48千克 | 托盘数 P | 袋码 48 × P 个；自动生成 P 个托盘，每托绑定 48 个袋码 |
| 100千克 | 托盘数 P | 袋码 100 × P 个；自动生成 P 个托盘，每托绑定 100 个袋码 |
| 吨 | 袋码数 N | 袋码 N 个；不生成托盘，袋码不绑托盘 |
| 类型为空/无法解析 | - | 报错：品种主计量单位未配置类型（48千克/100千克/吨） |

**接口变更** `POST /mes/pro/bag-code/generate`：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| itemId | Long | 是 | 品种（mdm_item 编号） |
| palletCount | Integer | 条件必填 | 托盘数（类型为 N千克 时必填） |
| bagCount | Integer | 条件必填 | 袋码数（类型为 吨 时必填） |
| remark | String | 否 | 备注 |

响应新增：`uuid、type、perPallet（每托袋数）、totalCount（生成袋码数）、palletIds（自动生成的托盘）`。

**事务逻辑**：一次生成 = 同一 uuid 的袋码组 + 同批自动生成的托盘；托盘先以**临时码（PL-序号）**落库并完成袋码绑定，正式托盘码在「录入批次」时生成。

**生成数据包弹窗（前端）**：选择品种（沿用品种选择组件）→ 读取该品种主单位类型（前端查 `mdm_unit_measure`，类型为空给提示）→ 按类型切换输入「托盘数」或「袋码数」→ 实时预览"将生成 袋码 X 个 / 托盘 Y 个"。

### 3.2 录入批次（保持后录入，扩展级联）

`PUT /mes/pro/bag-code/bind-batch` 流程不变，新增级联：

1. 袋码绑定批次（现状）。
2. 该组袋码所绑定的临时托盘自动绑定同一批次，并分配正式托盘码 `批次号-P序号`，回写批次托盘数。
3. 新增校验：同一数据包（同批绑定袋码）品种必须一致（生成时天然一致，防手动混选）。

### 3.3 袋码数据模型

`mes_pro_bag_code` 新增：`item_id`、`item_code`、`item_name`（冗余）。

- 列表/查询：显示品种列（编码/名称可检索本期不做，仅展示）。
- 删除数据包（delete-by-uuid）：级联删除本组**自动生成**的托盘（前提仍是全部未绑批次；已录批次维持现状不可删）。
- 袋码不强制托盘：`pallet_id` 保持可空（吨类型）。

### 3.4 批次生产管理

- **去掉品种字段**：创建/编辑表单、列表列、查询条件、Save/Resp/Page VO 均移除 `itemId`；DO 与数据库列 `mes_pro_batch.item_id` 保留（历史数据、追溯回退用），注释标记"已废弃"。
- **批次号规则改为** `PC + yyyyMMdd + 产线编码 + 流水号`（`generateBatchCode` 不再拼品种编码；自动编码规则配置无需改）。
- 编辑批次不再因品种变化重新生成批次号。

### 3.5 托盘管理

- 批量生成/预生成接口去掉 `capacity` 入参；表单去掉「可装袋数」字段；列表去掉该列。DB 列保留兼容历史。
- 袋码手动绑托盘去掉容量校验（`capacity` 判空逻辑天然跳过，删除相关校验代码）。
- 托盘列表为自动生成托盘打标识（复用 `auto_generated` 字段 = true）。

### 3.6 追溯/扫码/看板（回归项）

- 袋码追溯（`/get-by-code`、TraceRespVO）：品种改为**优先取袋码 item_id，历史袋码回退批次 itemId**。
- 批次追溯视图（MesProBatchTraceRespVO）：保留品种返回但可能为空（历史批次有值）。
- 扫码入库、销售出库、袋码首页看板：不直接依赖批次品种的逻辑不动，涉及处回归验证。

## 4. 数据库变更（mom-thzy）

```sql
ALTER TABLE mes_pro_bag_code ADD COLUMN item_id BIGINT NULL COMMENT '品种（物料）编号' AFTER pallet_code;
ALTER TABLE mes_pro_bag_code ADD COLUMN item_code VARCHAR(64) NULL COMMENT '品种编码（冗余）' AFTER item_id;
ALTER TABLE mes_pro_bag_code ADD COLUMN item_name VARCHAR(255) NULL COMMENT '品种名称（冗余）' AFTER item_code;
-- mes_pro_batch.item_id 保留不删，Java 注释标记废弃
```

## 5. 前后端改动清单

| 层 | 文件 | 改动 |
|----|------|------|
| DB | mes_pro_bag_code | +item_id/item_code/item_name |
| 后端 | MesProBagCodeGenerateReqVO/RespVO、ServiceImpl | 新参数、类型换算、自动建托盘、事务 |
| 后端 | MesProBagCodeDO/RespVO/Mapper | +品种字段 |
| 后端 | bind-batch 流程 | 级联托盘绑批次、品种一致性校验 |
| 后端 | MesProBatchServiceImpl/VO | 去品种、批次号规则、编辑逻辑 |
| 后端 | MesProPalletServiceImpl/VO | 去 capacity 入参与校验 |
| 后端 | delete-by-uuid | 级联删自动托盘 |
| 后端 | 追溯 VO | 品种优先袋码、回退批次 |
| 前端 | pro/bagCode generate-form | 品种+托盘数/袋码数表单 |
| 前端 | pro/bagCode 列表 | +品种列 |
| 前端 | pro/batch form/list/search | 移除品种 |
| 前端 | pro/pallet form/list | 移除可装袋数 |

## 6. 确认结论（定稿）

1. **混品种**：要。一次 bind-batch 勾选的袋码品种必须一致，否则报错「录入批次的袋码必须属于同一品种」（历史空白袋码不参与校验）。
2. **自动托盘可否再手动增绑**：无容量上限，装满后仍可继续手动绑入袋码。
3. **批次列表历史数据**：老批次 itemId 直接不展示即可，无数据迁移；追溯视图保留批次品种做历史回退。
4. **流程与批次号**：保持「先生成数据包、后录入批次」；批次号规则改为 `PC + yyyyMMdd + 产线编码 + 流水号`。

## 7. 实施记录（2026-09-17）

- DB（mom-thzy）：`mes_pro_bag_code` 新增 `item_id/item_code/item_name`；`mdm_unit_measure.type`（48千克/100千克/吨）；`mes_pro_batch.item_id` 保留标废弃。
- 后端：`generate` 重写（类型换算+自动临时托盘）、`bind-batch` 级联托盘正式码+品种一致校验、`delete-by-uuid` 级联删自动托盘、`replace` 继承品种、托盘创建去 `capacity` 入参、袋码绑托盘去容量校验、批次 VO/Service 去品种、批次号单产线要素、袋码/公共追溯与二维码标签品种「袋码优先、批次回退」。
- 前端：袋码生成弹窗（品种+托盘数/袋码数动态+预览）、列表品种列；批次表单/列表/搜索去品种；托盘表单/列表去可装袋数、列表加「自动生成」标识、绑托盘下拉去容量提示。
- 编译：`mvn compile -pl yudao-module-mes -am -q` 通过。

## 8. 补充需求：批次操作绑定托盘（2026-09-17）

- 批次新增/补录/编辑均可选「绑定托盘」（多选、非必填）：勾选后批次状态直接置**生产中**，同事务复用托盘绑定批次逻辑（正式托盘码、托盘下袋码级联录入、品种一致校验），任一步失败整体回滚。
- 编辑时仅传本次新增勾选的托盘；已绑定托盘不在下拉中（unbound-list 已过滤），不支持解绑，未勾选不改状态、不截断回退。
- 新接口 `GET /mes/pro/pallet/unbound-list`：batch_id 为空、无正式托盘码且未作废的临时托盘。
- 前端联调细则见 `docs/mes_bag_code_package_refactor_integration.md`。

## 9. 补充需求：原始袋码与列表排序（2026-09-17）

- 新增 `POST /mes/pro/bag-code/raw-generate`：仅选品种+袋码数量即生成对应数量袋码（带品种冗余、uuid 成组），**不校验计量单位类型、不生成托盘**；后续录入批次/绑托盘/印刷/删除与数据包袋码一致。赋码管理页工具栏加「生成原始袋码」弹窗入口。
- 袋码分页查询改为按**创建时间倒序**（同秒按编号倒序），原「袋序号升序」废弃。
- 编译 `mvn compile -pl yudao-module-mes -am -q` 通过、前端类型检查改动文件零错误。

## 10. 补充需求：袋码列表品种查询（2026-09-17）

- 赋码管理列表搜索区新增「品种」条件（复用 `MdmItemSelect` 选择组件），按 `mes_pro_bag_code.item_id` 等值过滤；分页与导出 Excel 同口径生效。
- 历史空白袋码 `item_id` 为空，选择品种后不会命中（属正常）。§3.3 原「编码/名称可检索本期不做，仅展示」就此升级为按品种编号检索。