# 库存袋码明细联调方案

## 业务流程

种子质检以袋码提交。质检合格时，暂存库存汇总数量减少 1，合格库存汇总数量增加 1，同时该袋码明细迁移到合格仓；质检不合格时，暂存库存汇总数量减少 1，袋码明细标记为报废。其他袋码不受影响。

库存台账继续按物料、批次、仓库、库区、库位和供应商汇总；袋码明细用于记录每个袋码的具体状态和位置。

## 袋码明细生命周期（统一服务托管）

所有带袋码的库存变动统一通过库存事务服务在同一事务内同步维护 **汇总库存 + 袋码明细 + 库存流水** 三者一致，各业务入口无需各自实现袋码逻辑。生命周期：

| 阶段 | 动作 | 袋码明细变化 |
|------|------|--------------|
| 单袋扫码入库 | 生产扫码入库（扫码类型 BAG） | 建立活动明细（暂存库） |
| 种子质检合格 | 暂存出库 + 合格入库 | 明细由暂存库迁移到合格库 |
| 种子质检不合格 | 暂存出库 | 明细报废 |
| 销售出库完成 | 出库扣减 | 明细置为已出库 |
| 整位移库 | 调拨移出 + 移入 | 明细位置迁移到目标库位 |

说明：
- 托盘（PALLET）/批次（BATCH）整批入库、采购/杂项/退货等按行按数量入库的出入口，为批量汇总，不逐袋建立明细；这些袋码在首次种子质检时通过按批次定位暂存库存补建明细。
- 事务流水 DTO 增加 `bagCodeId`/`bagCode` 字段；出库/移入按袋码自动更新袋码明细。
- 每笔带袋码的入库、出库、移库、质检都会生成对应的 `mes_wm_transaction` 流水并回填袋码，便于在库存流水页面按袋码筛选追溯。


## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/mes/wm/material-stock/page` | 库存汇总分页，响应增加袋码统计字段 |
| GET | `/mes/wm/material-stock/bag-details` | 查询指定库存汇总记录下的在库袋码明细 |
| GET | `/mes/wm/transaction/page` | 库存事务流水，支持 `bagCode` 筛选并返回袋码 |

### 袋码明细查询

请求参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| materialStockId | Long | 是 | 库存汇总记录 ID |
| bagCode | String | 否 | 袋码模糊查询 |
| pageNo | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页条数 |

响应字段包括 `bagCode`、`batchCode`、`stockState`、`status`、`quantity`、`warehouseId`、`locationId`、`areaId`、`inboundTime` 和 `outboundTime`。

库存汇总分页响应新增：

| 字段 | 类型 | 说明 |
|------|------|------|
| bagCount | Long | 当前在库袋码明细数量 |
| bagDetailSupported | Boolean | 是否存在袋码明细；历史无法还原袋码的库存为 false |

## 前端调用时序

1. 调用库存台账分页接口获取汇总记录。
2. 对 `bagDetailSupported=true` 的记录显示“查看袋码”。
3. 点击后调用 `/mes/wm/material-stock/bag-details`，传入当前行 `id` 作为 `materialStockId`。
4. 袋码明细中的 `bagCode` 可继续调用批次/袋码追溯接口查看质检和生产信息。
5. 库存流水页面使用 `bagCode` 筛选时，展示质检迁移产生的袋码级流水。

## 业务规则

- 同一袋码只能存在一条库存袋码明细。
- 质检按实际袋码定位暂存库存，不按批次随机扣减。
- 报废袋码不计入在库明细查询，但保留明细记录用于追溯。
- 无法从历史汇总库存还原袋码时，不伪造袋码明细。
- SQL 脚本不包含 `tenant_id` 字段。