# 仓储优化 - 三库存状态流转 + 预警/汇总/盘点 前端联调方案

## 涉及页面

- 库存台账（`/mes/wm/material-stock/page`）
- 生产线扫码入库（`/mes/pro/scan-in`）
- 种子质检（种子质检提交界面）
- 销售出库（销售扫码拣货）
- 库存预警（新增页面）
- 库存多维汇总（新增页面/面板）
- PDA 扫码盘点（盘点任务扫码界面）

## 业务规则：三库存状态流转

| 操作 | 库存状态变化 | 说明 |
|------|-------------|------|
| 生产线扫码入库 | → 暂存库（TEMP=10） | 扫码袋码入库成功后，库存进入暂存库（待质检），不再直接进入合格库 |
| 种子质检提交「合格」 | 暂存库 → 合格库（QUALIFIED=20） | 质检结果=合格时，按批次将暂存库库存整批转为合格库（正式库存） |
| 销售扫码出库 | 合格库 → 已出库（OUT=30） | 扣减合格库库存，数量≤0 时状态自动变为已出库 |
| 不合格（质检结果=不合格） | 留在暂存库 | 本期不做退货/报废流，由后续人工处理 |

> **核心变化**：生产线扫码入库从「直接进合格库」改为「先进暂存库待质检」，质检合格后才进入合格库。前端需在库存台账页按状态维度区分展示三个库。

### 生产线扫码入库（关键修复，前端无参变化）

- 接口：`POST /mes/pro/scan-in/inbound`，请求参数**保持不变**。
- 后端内部变化：打通生产批次体系与仓库批次体系，入库时自动桥接仓库批次并写入 `batchId`，库存进入**暂存库**。
- 前端影响：入库成功后，库存不体现在「合格库」筛选下，而是体现在「暂存库」筛选下；需等待种子质检提交合格后才会出现在合格库。

## API

### 一、库存台账（已有接口，建议增强查询条件展示）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/wm/material-stock/page | 库存台账分页，新增按 `stockState` 过滤 |

**请求参数（新增/强调）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| stockState | Integer | 否 | 库存状态：10-暂存库，20-合格库，30-已出库 |
| itemId | Long | 否 | 品种（物料）ID |
| batchCode | String | 否 | 批次号 |
| warehouseId | Long | 否 | 仓库 ID |

**响应字段（已有，无需新增）：** 含 itemCode、itemName、batchCode、warehouseName、quantity、stockState 等。

### 二、库存多维汇总（新增）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/wm/material-stock/summary-by-item | 按品种汇总数量 |
| GET | /mes/wm/material-stock/summary-by-batch | 按批次汇总数量 |
| GET | /mes/wm/material-stock/summary-by-warehouse | 按仓库汇总数量 |

**请求参数（均可选，复用库存查询条件）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| stockState | Integer | 否 | 库存状态过滤，不传则按状态分开展示 |
| itemId | Long | 否 | 品种过滤 |
| batchCode | String | 否 | 批次号过滤 |
| warehouseId | Long | 否 | 仓库过滤 |
| areaId / locationId | Long | 否 | 库位/库区过滤 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| itemId / itemCode / itemName | Long/String/String | 品种维度（按品种汇总时返回） |
| batchId / batchCode | Long/String | 批次维度（按批次汇总时返回） |
| warehouseId / warehouseName | Long/String | 仓库维度（按仓库汇总时返回） |
| stockState / stockStateName | Integer/String | 库存状态及名称 |
| totalQuantity | BigDecimal | 汇总数量 |

**响应示例：**

```json
{
  "code": 0,
  "data": [
    { "itemId": 1, "itemCode": "ITEM001", "itemName": "早稻种子", "stockState": 10, "stockStateName": "暂存库", "totalQuantity": 500.00 },
    { "itemId": 1, "itemCode": "ITEM001", "itemName": "早稻种子", "stockState": 20, "stockStateName": "合格库", "totalQuantity": 400.00 }
  ]
}
```

### 三、库存预警（新增）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/wm/stock-warning/page | 预警分页（落库记录，含已处理历史） |
| GET | /mes/wm/stock-warning/current | 实时计算当前预警（不落库，秒级） |
| POST | /mes/wm/stock-warning/refresh | 重新计算并落库当前预警 |
| PUT | /mes/wm/stock-warning/handle | 处理预警（标记已处理） |

**GET /page 请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| itemCode | String | 否 | 品种编码模糊查询 |
| batchCode | String | 否 | 批次号模糊查询 |
| warningType | Integer | 否 | 预警类型：10-低库存，20-临期，30-库龄 |
| status | Integer | 否 | 处理状态：10-未处理，20-已处理 |
| pageNo / pageSize | Integer | 是 | 分页 |

**GET /page 响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 预警记录编号 |
| itemCode / itemName | String | 品种编码/名称 |
| batchCode | String | 批次号 |
| warehouseName | String | 仓库名称 |
| warningType / warningTypeName | Integer/String | 预警类型及名称 |
| thresholdValue / currentValue | BigDecimal | 阈值（低库存=最低库存、临期=剩余天数阈值、库龄=超龄天数）/ 当前值 |
| expireDate | String(datetime) | 过期日期（临期预警才有） |
| receiptTime | String(datetime) | 入库时间（库龄预警才有） |
| status / statusName | Integer/String | 处理状态及名称 |
| handleTime / handleRemark | String/String | 处理时间/备注 |

**PUT /handle 请求体：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 预警记录编号 |
| handleRemark | String | 否 | 处理备注 |

**业务规则：**
- 预警针对**合格库**（正式库存）计算：低库存=在库数量 ≤ 品种最低库存；临期=批次剩余天数 ≤ 品种有效期天数；库龄=入库天数 ≥ 365 天。
- 预警双通道：`/current` 实时计算（适合看板刷新）；`/page` 为定时落库记录（适合列表，含处理历史）。
- 定时任务 `MesWmStockWarningJob`（Quartz，JobHandler）每日重算：删除旧未处理预警、写入当前预警，已处理记录保留为历史。

### 四、PDA 扫码盘点（新增）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /mes/wm/stock-taking-task/scan | PDA 扫码盘点（解析追溯码定位批次，写入盘点结果） |
| POST | /mes/wm/stock-taking-task/process-difference | 处理盘点差异（盘盈入库/盘亏出库，调整库存） |
| POST | /mes/wm/stock-taking-task/finish | 完成盘点任务（已有） |

**POST /scan 请求体：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId | Long | 是 | 盘点任务编号 |
| scanCode | String | 是 | 追溯码/袋码/托盘码/批次号 |
| takingQuantity | BigDecimal | 是 | 盘点数量 |
| remark | String | 否 | 备注 |

**响应：** 返回盘点结果编号（Long）。

**业务规则：**
- 仅**盘点中**状态的任务允许扫码（提交盘点任务后）。
- 扫码解析顺序：批次号 → 袋码 → 托盘码，最终定位到仓库批次。
- 同一任务行**只允许盘点一次**，重复扫码报错「该盘点清单行已有盘点记录，不能重复盘点」；如需修改先删除对应盘点结果再重新扫码。
- 扫码批次不在任务范围内时报「扫码批次不在盘点任务范围内」。
- 盘点流程：创建任务 → 提交（进入盘点中）→ PDA 扫码逐个批次盘点 → 完成（任务→已完成，解冻库存）→ 处理差异（写盘盈/盘亏库存流水）。

## 数据带入说明

| 上一步 | 下一步 | 带入字段 |
|--------|--------|----------|
| 生产线扫码入库 | 库存台账（暂存库） | 袋码→生产批次→仓库批次（batchId/batchCode/itemId/warehouseId 自动桥接） |
| 种子质检提交合格 | 库存台账（合格库） | 按批次号（batchCode）将暂存库整批转合格库，无需前端传库存 ID |
| 销售扫码出库 | 库存台账（已出库） | 销售扫码解析批次 → 定位合格库库存 → 扣减 |
| PDA 扫码盘点 | 盘点结果/任务行 | 追溯码 → 批次 → 任务行（taskId+batchId 定位） |

## 前端修改点

### 1. 库存台账页
- 顶部筛选增加「库存状态」下拉（暂存库/合格库/已出库），对应 `stockState` 参数。
- 列表增加「库存状态」列展示，状态名称可用接口返回的 `stockStateName`（台账）或前端字典。

### 2. 生产线扫码入库页
- 提示文案：入库成功进入「暂存库（待质检）」；原「直接为合格库存」的展示逻辑需调整。

### 3. 种子质检提交
- 提交「合格」后，可刷新库存台账「合格库」看到该批次库存；若提交「不合格」，库存仍停留在「暂存库」。

### 4. 销售扫码拣货
- 出库成功后可刷新库存台账，「合格库」扣减、数量≤0 的批次出现在「已出库」。

### 5. 库存预警页（新增）
- 列表展示 `/page` 数据；提供「实时计算」按钮调 `/current`；「处理」按钮弹窗填备注调 `/handle`；「重新计算」按钮调 `/refresh`。
- 预警类型/处理状态列展示 `warningTypeName` / `statusName`。

### 6. 库存汇总面板（新增）
- 三个汇总接口分别出品种/批次/仓库维度的数量面板，支持按 `stockState` 筛选，展示 `totalQuantity`。

### 7. PDA 盘点扫码
- 盘点任务详情进入「盘点中」后，提供扫码输入框（`taskId` 固定为当前任务，`scanCode` 扫码、`takingQuantity` 手输）。
- 扫码成功提示返回的盘点结果编号；重复盘点需先删结果。

## 注意事项

- 所有接口均为管理后台接口，需带登录 token 访问，权限点：`mes:wm-stock-warning:query/update`、`mes:wm-stock-taking-task:update`、`mes:wm-material-stock:query`。
- 预警仅对**合格库**计算；暂存库与已出库不计入预警。
- 生产线扫码入库修复后，历史数据中已存在但未桥接的批次，会在下次扫码/质检/销售时按生产批次号自动桥接创建仓库批次，老数据无需迁移。
- 预警定时任务需在管理后台「系统管理-定时任务」注册 JobHandler：`MesWmStockWarningJob`（每日执行一次）。
- 汇总接口为内存聚合，数据量大时建议前端按需过滤（传 stockState/warehouseId 等）。