# 一袋一码生产逻辑改造 - 前端联调方案

> 配套需求方案：`docs/mes_bag_code_package_refactor_requirements.md`。本方案覆盖接口变更与页面数据带入，前端主体改动已随本次改造同步完成，供联调回归使用。

## 涉及页面

- 赋码管理（袋码）：生成数据包弹窗、生成原始袋码弹窗、袋码列表、录入批次、绑定托盘、追溯弹窗
- 生产批次：新增/编辑/补录表单（新增「绑定托盘」多选）、列表、搜索区
- 托盘管理：预生成弹窗、列表、绑定批次弹窗
- 公共 H5 溯源页、扫码追溯弹窗（回归）

## 业务流程与数据带入

1. 生成数据包：选品种 → 前端按品种主计量单位类型联动（查 `/mdm/item/get` 取 `unitMeasureId`，再查 `/mdm/unit/get?id=` 取 `type`）：
   - `48千克`/`100千克` → 输入**托盘数**，预览「每托 N 袋 × 托盘数 = 袋码数」
   - `吨` → 输入**袋码数**（无托盘）
   - 类型未配置 → 提示前往「计量单位」维护，提交时后端也会兜底报错
2. 生成结果：同一 uuid 袋码组 + 自动生成的临时托盘（PL-序号），袋码已带品种、已绑托盘。
3. 录入批次：勾选袋码 → 选生产批次。后端级联：临时托盘升正式码（批次号-P序号）并绑批次、回写袋码冗余托盘码。混品种会被拦截。
4. 批次不再录入/展示品种；品种信息全部由袋码数据包携带。
5. 新增/补录/编辑批次时均可选「绑定托盘」（多选、非必填，数据源 `GET /mes/pro/pallet/unbound-list`，展示临时托盘码+已装袋数）：勾选后批次状态直接为**生产中**，后端同事务复用托盘绑定批次逻辑（托盘升正式码、托盘下袋码级联录入），任一校验失败整体回滚；编辑时仅需勾选本次新增的托盘（已绑定托盘不在下拉中、不可解绑）。

## API

| 方法 | 路径 | 变更 |
|------|------|------|
| POST | /mes/pro/bag-code/generate | 请求/响应结构变更（见下） |
| POST | /mes/pro/bag-code/raw-generate | **新增**：生成原始袋码，请求 `{ itemId, count, remark? }`；仅按数量生成、不换算计量单位类型、不生成托盘；响应结构同 generate（`type/perPallet` 为空、`palletIds` 空数组） |
| PUT | /mes/pro/bag-code/bind-batch | 路径不变；新增品种一致校验、托盘级联绑定；已导出印刷（PRINTED）袋码也允许录入批次 |
| PUT | /mes/pro/pallet/bind-batch | 路径不变；托盘绑定批次时，托盘下未绑批次的袋码自动级联录入同一批次（品种一致校验、回写批次袋数） |
| DELETE | /mes/pro/bag-code/delete-by-uuid | 路径不变；级联删除本组自动生成托盘 |
| POST | /mes/pro/bag-code/replace | 不变；新袋码自动继承原品种 |
| GET | /mes/pro/bag-code/page、list-by-uuid、get-by-code | 响应新增品种字段；page 新增可选查询参数 `itemId`（品种，等值匹配；导出 Excel 同口径） |
| POST | /mes/pro/pallet/batch-create、pre-generate | 请求去掉 capacity |
| GET | /mes/pro/pallet/page | 响应去掉 capacity，保留 autoGenerated |
| POST/PUT | /mes/pro/batch/create、update、fill-info | 请求去掉 itemId；三者均新增可选 `palletIds`（绑定时批次进入生产中） |
| GET | /mes/pro/pallet/unbound-list | **新增**：未绑定批次的临时托盘列表（权限 mes:pro-pallet:query），供批次新增/补录绑定托盘下拉 |
| GET | /mes/pro/batch/page、get、simple-list | 响应去掉 itemId/itemCode/itemName/itemSpecification |

**生成数据包请求参数：**

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

**生成数据包响应示例：**

```json
{
  "code": 0,
  "data": {
    "uuid": "生成组UUID",
    "type": "48千克",
    "perPallet": 48,
    "totalCount": 96,
    "palletIds": [101, 102]
  }
}
```

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 品种编码/名称（itemCode/itemName） | 袋码列表、追溯、导出 Excel | 生成时绑定在袋码上 |
| autoGenerated | 托盘列表「自动生成」Tag | 数据包自动创建的托盘标识 |
| 品种（批次页） | 不再展示 | 表单/列表/搜索均已移除 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 类型=N千克 生成 | 袋码数 = N × 托盘数，自动建 N 个托盘并均分绑定 |
| 类型=吨 生成 | 无托盘，袋码仅绑批次 |
| 生成原始袋码 | 仅需品种+数量；袋码带品种、不绑批次/托盘，后续录入批次、绑托盘、导出印刷、删除组与数据包袋码完全一致；不校验品种计量单位类型 |
| 录入批次混品种 | 报错「录入批次的袋码必须属于同一品种」（与批次已有袋码一并校验） |
| 托盘绑定批次 | 托盘下未绑批次的袋码（已生成/已导出印刷）自动随托盘录入同一批次，袋码冗余托盘码同步更新为正式码 |
| 批次新增/补录/编辑绑定托盘 | palletIds 非空时批次状态直接置「生产中」，同事务复用托盘绑定批次逻辑（正式码+袋码级联+品种一致校验），失败整体回滚；新增/补录未勾选则维持草稿；编辑取消勾选不回退状态、已绑定托盘不可解绑 |
| 绑托盘容量 | 无上限，自动托盘可继续手动绑入 |
| 删除数据包 | 组内托盘已绑批次或有正式码则不可删，否则级联删自动托盘 |
| 追溯品种 | 优先袋码品种；历史袋码回退批次品种（公共 H5 同步支持） |
| 批次号 | PC + yyyyMMdd + 产线编码 + 流水号（不再含品种编码） |

## 注意事项

- `generate` 旧参数 `count` 已废弃，只传 `palletCount` 或 `bagCount`（按品种类型二选一）。
- 批次 `itemId` 相关字段已从接口移除，勿再引用（批次追溯视图 `get-by-code` 的品种字段保留，可能为空=新批次）。
- 托盘追溯视图（PalletTrace/qr-trace-modal）仍返回 `capacity` 供历史数据展示，新托盘为空。
- 老数据（历史空白袋码）品种为空属正常，追溯走批次回退。
- `palletIds` 在 create/update/fill-info 均生效；下拉每次打开弹窗重新拉取 `unbound-list`，若提交时所选托盘已被他人绑定，后端整体报错回滚（本次批次操作不生效），提示用户刷新重试。
- 袋码分页（`/page`）后端已改为**创建时间倒序**（同秒内按编号倒序），前端无需再传排序参数；导出 Excel 同口径。
- 原始袋码与数据包袋码同表同规则（uuid 成组、可整组删除），列表页通过生成组 UUID 区分来源。
- 列表搜索区新增「品种」条件（复用 `MdmItemSelect`，可清空），传 `itemId` 等值过滤；导出 Excel 携带同一查询条件同口径生效。历史空白袋码品种为空，按品种筛选不会命中。