# 仓储物流模块(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 事务服务核心流程 ```java // 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 通用状态常量 ```java MesOrderStatusConstants: PREPARE = 0 // 草稿 APPROVING = 10 // 待审批/待上架/待拣货 CONFIRMED = 5 // 待确认/待检测 APPROVED = 20 // 已审批/待执行 FINISHED = 30 // 已完成 CANCELLED = 40 // 已取消 ``` ### 11.2 业务类型常量 ```java 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 // 生产入库 ... ```