# 种子质检按袋码粒度流转库存 - 前端联调方案

## 背景

种子质检原逻辑：质检合格后**整批**将仓库批次库存从暂存库(10)转为合格库(20)，一袋合格即整批放行，颗粒度过粗。

本次改造为**按袋码粒度**：质检只针对被扫的那一袋，合格仅将该袋对应库存从暂存库转入合格库，同批次其他袋保持暂存库待检；同时给每袋打上质检标记（`qc_status`），销售出库扫袋码/托盘时校验已质检合格才允许出库。

## 涉及页面

- 质量管理-种子质检（提交质检表单）
- 销售出库-扫码拣货（扫袋码/托盘）
- 库存台账（`mes_wm_material_stock` 分页：同批次可能同时出现暂存库与合格库两条记录，状态列已按字典展示文字）

## API

本次**无新增/修改接口**，均为既有接口的校验语义与数据流转变化。

### 1. 提交种子质检

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mes/qc/seed-quality/submit` | 提交种子质检（按袋码） |

**请求参数（不变）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 袋码（扫码内容），**必须为有效袋码** |
| batchCode | String | 否 | 生产批次号（兼容预留） |
| indicators | Array | 是 | 四项指标（purity/cleanliness/germination_rate/moisture） |
| reason | String | 否 | 备注 |

**响应（不变）：** `{ "code": 0, "data": 质检记录ID }`

### 2. 扫码拣货

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mes/wm/product-sales/scan` | 扫码拣货（袋码/托盘） |

**请求参数（不变）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| salesId | Long | 是 | 销售出库单ID |
| scanContent | String | 是 | 袋码或托盘码 |
| quantity | BigDecimal | 否 | 出库数量（缺省用行数量） |

**响应（不变）：** 沿用 `MesWmProductSalesScanRespVO`，`availableQuantity`/`outboundQuantity` 均基于**合格库**库存计算。

## 业务规则变化

| 场景 | 原行为 | 新行为 |
|------|--------|--------|
| 种子质检提交非袋码 | 兼容批次码提交 | 报错「未解析到有效袋码，种子质检必须以袋码提交」 |
| 质检合格 | 整批暂存库→合格库 | 仅该袋：暂存库 -1、合格库 +1（同批次其他袋仍为暂存库）；袋码 qc_status=20 |
| 质检不合格 | 无库存变化 | 该袋从暂存库存清除（报废）；袋码 qc_status=30 |
| 销售出库扫袋码 | 不校验质检 | qc_status 必须为 20，否则报「该袋码未质检合格，禁止出库」 |
| 销售出库扫托盘 | 不校验质检 | 托盘下所有袋码 qc_status 必须为 20，否则报「托盘下存在未质检袋码，禁止整托出库」 |
| 销售出库选库存 | 可能选中暂存库记录 | 仅从合格库(20)记录中选数量足够的 |

## 库存语义说明

同一次（入库仍按批次聚合）质检合格后，同批次 `mes_wm_material_stock` 会同时存在两条记录：

| 记录 | stock_state | 含义 | 是否可出库 |
|------|-------------|------|-----------|
| 暂存库 | 10 | 该批次未质检的剩余袋数 | 否 |
| 合格库 | 20 | 已质检合格、可销售的袋数 | 是 |

示例：批次入库 3 袋（quantity=3、暂存库）。质检合格 1 袋后 → 暂存库 quantity=2 + 合格库 quantity=1。

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 质检状态（qc_status） | 种子质检提交结果反馈 | 前端无需展示，后端在第二次提交同一袋码时报「该袋码已质检，禁止重复提交」 |
| 库存状态 | 库存台账列表 | 同一物料/批次可能出现两条不同状态记录，均为正常现象 |
| 可出库数量 | 扫码拣货结果 | 以 `availableQuantity` 为准，只反映合格库库存 |

## 注意事项

1. **种子质检提交必须传袋码**：`code` 字段现在必须是系统中存在的有效袋码；仅传批次号不再被接受。
2. **质检成功后库存总数不变**：暂存库 -1 与合格库 +1 同步发生，物料在库总数守恒，只是从"待检"变为"可售"。
3. **同批次双状态并存**：暂存库与合格库记录同时存在是预期行为，前端在库存台账、出库选库存时应能接受同一物料/批次出现多行。
4. **出库数量提示**：若某批次仅部分袋质检合格，扫码拣货可出库数量只包含合格袋，前端提示应以接口返回的 `availableQuantity` 为准。
5. **不合格袋报废**：质检不合格的袋会从暂存库存中扣除，且该袋码 qc_status=30，禁止出库。