仓储物流模块(WM)架构文档
一、模块概述
仓储物流模块(WM)是MES系统中的核心模块，负责管理物料库存、出入库业务、仓库设置等功能。
1.1 核心设计理念
- 六维库存模型：物料 + 批次 + 仓库 + 库区 + 库位 + 供应商
- 事务驱动：所有库存变动通过事务流水记录，保证数据可追溯
- 状态机管理：单据状态流转严格控制，保证业务完整性
二、核心数据模型
2.1 库存台账（mes_wm_material_stock）
库存现有量表，记录每个物料在每个库位的实时库存。
┌─────────────────────────────────────────────────────────────┐
│ mes_wm_material_stock │
├─────────────────────────────────────────────────────────────┤
│ 物料维度：itemId(物料) + batchId(批次) + batchCode(批次号) │
│ 位置维度：warehouseId(仓库) + locationId(库区) + areaId(库位)│
│ 业务维度：vendorId(供应商) + receiptTime(入库时间) │
│ 数量状态：quantity(数量) + frozen(是否冻结) │
└─────────────────────────────────────────────────────────────┘
唯一键：(itemId, warehouseId, locationId, areaId, batchId)
2.2 库存事务流水（mes_wm_transaction）
记录每一笔库存增减事件，系统自动生成，只读查询。
┌─────────────────────────────────────────────────────────────┐
│ mes_wm_transaction │
├─────────────────────────────────────────────────────────────┤
│ 业务归属：type(事务类型) + bizType(业务类型) │
│ bizId(业务单ID) + bizCode(业务单号) + bizLineId(行ID)│
│ 物料信息：itemId + quantity(变动数量，正负) + batchId │
│ 位置信息：warehouseId + locationId + areaId │
│ 时间信息：transactionTime + receiptTime │
│ 关联信息：materialStockId + relatedTransactionId │
└─────────────────────────────────────────────────────────────┘
quantity 规则：
- 正数 = 入库（库存增加）
- 负数 = 出库（库存减少）
2.3 仓库层级结构
仓库(Warehouse)
└── 库区(Location)
└── 库位(Area)
三、业务单据分类
3.1 入库类单据
| 单据 |
说明 |
状态流转 |
库存影响 |
| 采购入库单 |
采购物料入库 |
草稿→待上架→待入库→已完成 |
+库存 |
| 到货通知单 |
采购到货登记 |
草稿→待入库→已完成 |
无（生成采购入库单） |
| 生产入库单 |
生产产品入库 |
草稿→待审批→待执行→已完成 |
+库存 |
| 杂项入库单 |
其他原因入库 |
草稿→待审批→已完成 |
+库存 |
| 外协入库单 |
外协加工入库 |
草稿→待审批→待执行→已完成 |
+库存 |
| 销售退货单 |
客户退货入库 |
草稿→待审批→待执行→已完成 |
+库存 |
| 生产退料单 |
生产退回物料 |
草稿→待审批→待执行→已完成 |
+库存 |
3.2 出库类单据
| 单据 |
说明 |
状态流转 |
库存影响 |
| 销售出库单 |
销售产品出库 |
草稿→待检测/待拣货→待填写运单→待出库→已完成 |
-库存 |
| 生产领料单 |
生产领用物料 |
草稿→待审批→待执行→已完成 |
-库存 |
| 杂项出库单 |
其他原因出库 |
草稿→待审批→已完成 |
-库存 |
| 外协发料单 |
外协加工发料 |
草稿→待审批→待执行→已完成 |
-库存 |
| 采购退货单 |
退回供应商 |
草稿→待审批→待执行→已完成 |
-库存 |
3.3 调拨类单据
| 单据 |
说明 |
状态流转 |
库存影响 |
| 转移调拨单 |
库位间移库 |
草稿→待确认→待上架→待执行→已完成 |
原库位-库存，目标库位+库存 |
3.4 盘点类单据
| 单据 |
说明 |
状态流转 |
库存影响 |
| 盘点计划 |
制定盘点任务 |
草稿→已发布→已完成 |
无 |
| 盘点任务 |
执行盘点 |
待执行→盘点中→已完成 |
无 |
| 盘点结果 |
盘点差异处理 |
草稿→待审批→已完成 |
盘盈+库存，盘亏-库存 |
四、单据状态流转图
4.1 采购入库单（采购入库）
┌────────┐ submit ┌────────┐ stock ┌─────────┐ finish ┌────────┐
│ 草稿 │ ─────────→ │ 待上架 │ ─────────→ │ 待入库 │ ─────────→ │ 已完成 │
│(PREPARE)│ │(APPROVING)│ │(APPROVED)│ │(FINISHED)│
└────────┘ └────────┘ └─────────┘ └────────┘
│ │ │ │
│ │ │ │
└──────────────────────┴──────────────────────┴──────────────────────┘
│
cancel│
↓
┌────────┐
│ 已取消 │
│(CANCELED)│
└────────┘
4.2 销售出库单（销售出库）
┌─────────────┐
│ 草稿 │
│ (PREPARE) │
└──────┬──────┘
│ submit
┌────────────────┼────────────────┐
│ │ │
↓ (需要OQC) │ ↓ (不需要OQC)
┌───────────┐ │ ┌───────────┐
│ 待检测 │ │ │ 待拣货 │
│(CONFIRMED)│ │ │(APPROVING)│
└─────┬─────┘ │ └─────┬─────┘
│ OQC完成 │ │
└───────────────┘ │
│ │ stock
↓ ↓
┌───────────┐ ┌───────────┐
│ 待拣货 │───→│待填写运单 │
│(APPROVING)│ │ (SHIPPING)│
└───────────┘ └─────┬─────┘
│ shipping
↓
┌───────────┐
│ 待执行出库│
│(APPROVED) │
└─────┬─────┘
│ finish
↓
┌───────────┐
│ 已完成 │
│(FINISHED) │
└───────────┘
4.3 转移调拨单
┌────────┐ submit ┌──────────┐ ┌────────┐ stock ┌────────┐ finish ┌────────┐
│ 草稿 │ ────────→ │ 待确认/ │ ────────→ │ 待上架 │ ──────→ │ 待执行 │ ──────→ │ 已完成 │
│(PREPARE)│ │ 待上架 │ │(APPROVING)│ │(APPROVED)│ │(FINISHED)│
└────────┘ │(UNCONFIRMED/│ └────────┘ └────────┘ └────────┘
│ APPROVING) │
└────────────┘
↑
(配送模式先待确认)
五、核心服务架构
5.1 服务分层
┌─────────────────────────────────────────────────────────────┐
│ Controller 层 │
│ (MesWmItemReceiptController, MesWmProductSalesController) │
└─────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Service 层 │
│ 主单Service：业务逻辑、状态流转 │
│ 行Service：单据行管理 │
│ 明细Service：单据明细管理 │
└─────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ 核心库存服务 │
│ MesWmTransactionService：事务服务（入库/出库的核心） │
│ MesWmMaterialStockService：库存台账服务 │
│ MesWmBatchService：批次服务 │
└─────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Mapper 层 │
│ (MesWmTransactionMapper, MesWmMaterialStockMapper) │
└─────────────────────────────────────────────────────────────┘
5.2 事务服务核心流程
// MesWmTransactionService#createTransaction
public Long createTransaction(MesWmTransactionSaveReqDTO reqDTO) {
// 1. 获取或创建库存台账记录
MesWmMaterialStockDO stock = materialStockService.getOrCreateMaterialStock(...);
// 2. 校验库存数量（出库时）
if (quantity < 0 && checkFlag) {
validateStockQuantity(stock, quantity);
}
// 3. 更新库存台账数量
materialStockService.updateMaterialStockQuantity(stock.getId(), quantity);
// 4. 插入事务流水记录
MesWmTransactionDO transaction = convertToTransaction(reqDTO, stock);
transactionMapper.insert(transaction);
return transaction.getId();
}
六、单据结构设计
每种业务单据采用**三表结构**：
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 主单表 │ 1:n │ 行表 │ 1:n │ 明细表 │
│ (xxxDO) │────→│ (xxxLineDO) │────→│(xxxDetailDO) │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
│ │ │
↓ ↓ ↓
单据头信息 按物料分组 具体库位明细
- 单号 - 物料ID - 库位ID
- 状态 - 计划数量 - 实际数量
- 供应商/客户 - 批次信息 - 批次信息
示例：采购入库单
mes_wm_item_receipt（主单）
├── mes_wm_item_receipt_line（行）
│ ├── 物料A - 计划入库100个
│ └── 物料B - 计划入库50个
└── mes_wm_item_receipt_detail（明细）
├── 物料A - 库位01 - 60个
├── 物料A - 库位02 - 40个
└── 物料B - 库位01 - 50个
七、与外部模块集成
7.1 ERP集成（采购入库/销售出库）
ERP采购入库单 ──审核──→ WmsStockApi.purchaseInbound()
│
↓
查找仓库映射(ERP仓库→MES仓库)
│
↓
查找物料映射(ERP产品barCode→MDM物料barCode)
│
↓
创建MES库存事务
│
↓
MES库存增加
7.2 生产模块集成
生产工单 ──完工汇报──→ 创建生产入库单
│
↓
生产入库单审核通过
│
↓
MES库存增加（产品入库）
7.3 质检模块集成
销售出库单 ──提交──→ 检查是否需要OQC检验
│ │
│ ↓ (需要)
│ 创建OQC检验单
│ │
│ ↓ OQC通过
│ 销售出库单状态流转
│ │
↓ (不需要) ↓
直接待拣货 ←───────────┘
八、关键业务规则
8.1 库存校验规则
- 出库时必须校验库存是否充足
- 支持冻结库存（调拨配送模式下冻结源库存）
- 库位混放规则校验（可配置是否允许物料/批次混放）
8.2 批次管理
- 入库时自动生成或指定批次号
- 批次信息跟随库存流转
- 支持批次追溯
8.3 条码/SN码管理
- 入库时自动生成条码记录
- SN码支持批量生成（按批次UUID管理）
- 条码与库存记录关联
九、数据库表清单
9.1 基础设置
| 表名 |
说明 |
| mes_wm_warehouse |
仓库 |
| mes_wm_warehouse_location |
库区 |
| mes_wm_warehouse_area |
库位 |
| mes_wm_batch |
批次 |
| mes_wm_barcode |
条码 |
| mes_wm_barcode_config |
条码配置 |
| mes_wm_sn |
SN码 |
9.2 库存核心
| 表名 |
说明 |
| mes_wm_material_stock |
库存台账（现有量） |
| mes_wm_transaction |
库存事务流水 |
9.3 入库单据
| 表名 |
说明 |
| mes_wm_arrival_notice |
到货通知单 |
| mes_wm_arrival_notice_line |
到货通知单行 |
| mes_wm_item_receipt |
采购入库单 |
| mes_wm_item_receipt_line |
采购入库单行 |
| mes_wm_item_receipt_detail |
采购入库单明细 |
| mes_wm_product_receipt |
生产入库单 |
| mes_wm_misc_receipt |
杂项入库单 |
| mes_wm_outsource_receipt |
外协入库单 |
| mes_wm_return_sales |
销售退货单 |
| mes_wm_return_issue |
生产退料单 |
9.4 出库单据
| 表名 |
说明 |
| mes_wm_sales_notice |
发货通知单 |
| mes_wm_product_sales |
销售出库单 |
| mes_wm_product_issue |
生产领料单 |
| mes_wm_misc_issue |
杂项出库单 |
| mes_wm_outsource_issue |
外协发料单 |
| mes_wm_return_vendor |
采购退货单 |
9.5 调拨盘点
| 表名 |
说明 |
| mes_wm_transfer |
转移调拨单 |
| mes_wm_stock_taking_plan |
盘点计划 |
| mes_wm_stock_taking_task |
盘点任务 |
| mes_wm_stock_taking_task_line |
盘点任务行 |
| mes_wm_stock_taking_task_result |
盘点结果 |
十、接口权限前缀
| 模块 |
权限前缀 |
| 仓库设置 |
mes:wm-warehouse |
| 采购入库 |
mes:wm-item-receipt |
| 销售出库 |
mes:wm-product-sales |
| 生产领料 |
mes:wm-product-issue |
| 生产入库 |
mes:wm-product-receipt |
| 转移调拨 |
mes:wm-transfer |
| 库存现有量 |
mes:wm-material-stock |
| 盘点 |
mes:wm-stock-taking |
十一、关键枚举说明
11.1 通用状态常量
MesOrderStatusConstants:
PREPARE = 0 // 草稿
APPROVING = 10 // 待审批/待上架/待拣货
CONFIRMED = 5 // 待确认/待检测
APPROVED = 20 // 已审批/待执行
FINISHED = 30 // 已完成
CANCELLED = 40 // 已取消
11.2 业务类型常量
MesBizTypeConstants:
WM_ITEM_RECEIPT_IN = 110 // 采购入库
WM_TRANSFER_OUT = 111 // 调拨出库
WM_TRANSFER_IN = 112 // 调拨入库
WM_PRODUCT_SALES = 118 // 销售出库
WM_ISSUE = 115 // 生产领料
WM_PRODUCT_RECPT = 117 // 生产入库
...
