一袋一码破损袋码替换 - 前端联调方案

涉及页面

• 赋码管理：袋码列表、袋码详情、扫码追溯
• 批次生产管理：批次详情及有效袋码数量展示
• 托盘码管理：托盘详情及绑定袋码列表

本次只新增后端接口和字段约定，不修改前端项目代码。

业务流程与数据带入

1. 生产人员在袋码列表中选择同一批次下包装破损的袋码，记录其数据库编号。
2. 前端调用破损替换接口，传入批次编号、旧袋码编号列表和破损原因。
3. 后端在一个事务内将旧袋码改为“已作废”，生成等量新袋码，并返回旧码与新码一对一映射。
4. 如果旧袋码已绑定启用托盘，新袋码自动继承原托盘；旧码从托盘当前有效袋码中移除，托盘已绑定数量保持不变。
5. 前端根据响应中的 replaceUuid 或新袋码列表刷新袋码列表，并调用现有袋码导出接口完成新标签打印。
6. 新袋码导出后状态由“已生成”变为“已导出印刷”；旧袋码不参与打印。
7. 扫描旧码仍可查询原批次和作废信息；扫描新码可查询当前批次、托盘和替换来源。

API

1. 破损袋码替换

权限：mes:pro-bag-code:replace

请求参数：

请求示例：

{
  "batchId": 1001,
  "oldIds": [5001, 5002],
  "reason": "包装破损"
}

响应字段：

响应示例：

{
  "code": 0,
  "data": {
    "replaceUuid": "9f6e4c4b2b2c4d5b8a8a8c0a0b0c0d0e",
    "batchId": 1001,
    "batchCode": "PC20260821L01ITEM001",
    "count": 2,
    "items": [
      {
        "oldBagCodeId": 5001,
        "oldCode": "PC20260821L01ITEM001-0001",
        "oldBagNo": 1,
        "oldStatus": 20,
        "oldPalletId": 3001,
        "oldPalletCode": "PC20260821L01ITEM001-P01",
        "newBagCodeId": 6001,
        "newCode": "PC20260821L01ITEM001-1201",
        "newBagNo": 1201,
        "newPalletId": 3001,
        "newPalletCode": "PC20260821L01ITEM001-P01",
        "reason": "包装破损",
        "replaceTime": "2026-08-21 15:30:00"
      }
    ]
  }
}

字段展示规则

业务规则说明

接口调用时序

1. 获取袋码分页，按批次和状态筛选有效袋码。
2. 用户勾选破损袋码并填写原因。
3. 调用 /mes/pro/bag-code/replace。
4. 成功后刷新袋码列表和批次数量。
5. 依据响应的新袋码集合，按 replaceUuid 查询或导出新码进行打印。
6. 打印成功后刷新状态；如需扫码确认，分别扫描旧码和新码核对替换关系。

注意事项

• oldIds 不要混入不同批次的袋码；服务端会再次校验。
• 不要调用普通 /generate 实现破损补码，普通生成会增加袋码数量且不保存替换关系。
• 新袋码不复用旧袋码的 code 或袋序号，1200 袋替换 2 袋时新码通常从 1201、1202 继续生成。
• 已作废旧码仍可追溯，但不可绑定托盘、不可再次替换、不可打印。
• 原托盘已作废或不存在时，已绑定袋码的替换会失败，需要先处理托盘状态。
• 批次追溯中的袋码对象包含状态字段；展示作废标识时不要只显示 code 字符串。
• 替换接口返回的新码初始未打印，导出成功后才变为“已导出印刷”。