# 生产线扫码入库 - 前端联调方案

## 涉及页面

- 生产线扫码入库自动工作台
- 扫码事件审计
- 生产批次和袋码详情

## 业务流程与数据带入

1. 工业相机由边缘程序完成二维码识别，上传 `eventId`、设备编码、产线编码和袋码。
2. 后端根据袋码带出生产批次和产品物料，并使用 WIP 虚拟仓配置完成库存入账。
3. 入库成功后记录服务端入库时间，增加暂存库存，并累计批次入库袋数。
4. 同一个 `eventId` 重试时返回原事件；已入库袋码不会重复增加库存。

## API

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/mes/pro/scan-in/inbound` | 袋码扫码入库，成功后增加 WIP 虚拟仓库存并写库存事务 |
| GET | `/mes/pro/scan-in/page` | 分页查询扫码事件 |
| GET | `/mes/pro/scan-in/latest` | 查询设备或全局最近扫码事件 |
| GET | `/mes/pro/scan-in/dashboard` | 查询工作台最近事件和累计事件数 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| eventId | String | 是 | 边缘设备生成的幂等事件号 |
| bagCode | String | 是 | 工业相机识别出的袋码 |
| quantity | Decimal | 是 | 入库数量，本期一袋通常为 1 |
| deviceCode | String | 是 | 设备编码，用于审计 |
| lineCode | String | 否 | 产线编码，用于审计 |
| locationId | Long | 是 | WIP 暂存库区编号 |
| areaId | Long | 是 | WIP 暂存库位编号 |
| remark | String | 否 | 备注 |

**响应字段：**

| 字段 | 类型 | 说明 |
|---|---|---|
| eventId | String | 幂等事件号 |
| bagCode | String | 袋码 |
| batchCode | String | 生产批次号 |
| quantity | Decimal | 本次入库数量 |
| deviceCode | String | 设备编码 |
| eventTime | DateTime | 服务端入库时间 |
| transactionId | Long | 库存事务编号 |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|---|---|---|
| deviceCode | 设备状态、最近扫码列表 | 显示当前设备或事件来源 |
| bagCode | 最近扫码列表 | 显示最近识别的袋码 |
| batchCode | 最近扫码列表、批次汇总 | 展示袋码归属的生产批次 |
| eventTime | 最近扫码列表 | 以服务端入库时间为准 |
| transactionId | 最近扫码列表 | 用于库存流水追溯 |
| quantity | 库存摘要 | 累计暂存数量 |

## 业务规则说明

| 场景 | 规则 |
|---|---|
| 重复事件 | 同一 `eventId` 返回第一次处理结果，不重复增加库存 |
| 已入库袋码 | 拒绝重复入库，并保留业务错误信息 |
| WIP 暂存库 | 仓库由后端使用 WIP 虚拟仓解析，前端不传仓库编号 |
| 事务一致性 | 事件、袋码状态、批次累计、库存台账和库存事务在同一事务中提交 |
| 设备时间 | 设备扫码时间用于追溯，库存入库时间使用服务端时间 |

## 失败状态与标准错误码

扫码请求无论成功或失败都会保留扫码事件记录。状态取值：

| 状态 | 说明 |
|---|---|
| SUCCESS | 已完成库存入库 |
| FAILED | 校验或库存处理失败 |

| 错误码 | 说明 |
|---|---|
| MES_SCAN_BAG_NOT_EXISTS | 袋码不存在 |
| MES_SCAN_BAG_ALREADY_INBOUND | 袋码已入库 |
| MES_SCAN_BATCH_NOT_EXISTS | 生产批次不存在 |
| MES_SCAN_WIP_WAREHOUSE_NOT_EXISTS | WIP 虚拟仓不存在 |
| MES_SCAN_TRANSACTION_FAILED | 库存事务处理失败 |
| MES_SCAN_EVENT_ID_CONFLICT | 事件号已存在但内容不一致 |

失败记录保留设备编码、袋码、接收时间、失败时间、错误码和错误原因；失败时不产生库存事务。

## 权限点

| 权限 | 用途 |
|---|---|
| mes:pro-scan-in:query | 查询事件和最近扫码 |
| mes:pro-scan-in:inbound | 执行扫码入库 |
| mes:pro-scan-in:dashboard | 查询工作台看板 |


- 边缘程序不得上传图片或视频，本接口只接收解码后的二维码结果。
- 前端工作台应在页面卸载时停止刷新任务。
- 入库失败时展示后端返回的业务错误，不自动调用通用库存调整接口重试。
- WIP 库区和库位需提前配置；接口不接受客户端指定仓库编号。