宁夏三级mom后端
编辑 | blame | 历史 | 原始文档

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

涉及页面

  • 库存台账（/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 汇总数量

响应示例：

{
  "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 等）。