WMS 仓储管理系统 · 阿龙的编程日记

项目介绍

本项目是一个以若依 RuoYi-Vue 3.9.0（前后端分离版）为底座、面向乐高积木零件贸易场景二次开发的 WMS 仓储管理系统。业务背景是一家经营乐高兼容积木零件（高砖）的商家：零件按「零件编码 + 颜色编号」两个维度定义唯一商品，例如 GDS-1227-030 即零件 GDS-1227 的 030 号颜色；代理商批量下单采购零件，仓库需要把”订单 → 出库 → 扣减库存 → 留痕”整条链路管理起来，同时支持采购入库补充库存。项目在若依框架之上新增了完整的 wms_* 业务域，共 8 张业务表（订单、订单详情、库存、库存日志、入库单、入库单详情、出库单、出库单详情），从 sql/wms.sql 的表设计、sql/wms_menu.sql 的菜单权限 SQL 到 sql/wms_dict.sql 的数据字典，均是一套独立的、可落地的业务扩展。

订单管理是整个系统的业务入口：代理商在「订单管理」页下载 Excel 模板，填好零件编码、颜色编号、数量后上传，后端逐行校验并自动生成订单号，订单名称默认取上传文件名（去掉扩展名），订单状态默认”待处理”；管理员看到订单后执行”确认出库”，系统校验每一条明细的库存充足性，通过后自动生成出库单并扣减库存，同时把订单置为”已处理”并记录出库时间。对应地，采购入库通过「入库管理」维护入库单与明细（支持 Excel 批量导入），确认入库即调用统一的库存增加服务。

项目架构

项目采用若依前后端分离的标准双端结构：后端为 Spring Boot 多模块 Maven 工程（ruoyi-admin / ruoyi-framework / ruoyi-system / ruoyi-common / ruoyi-quartz / ruoyi-generator），前端为独立的 web-admin-wms（Vue 2.6.12 + Element UI 2.15.14 + Vuex + Vue Router + axios 0.28.1）。数据库为 MySQL（251105-wms 库），连接池使用 Druid，缓存与登录态沿用若依的 Redis + JWT 方案。

端	技术栈	WMS 业务实现
`ruoyi-admin`	Spring Boot 2.5.15、Spring Security、JWT	`controller/wms/` 下 5 个控制器：`WmsOrderController`（订单 CRUD、`/importData` 导入、`/importTemplate` 模板、`/stockout/{orderId}` 确认出库、`/exportDetail` 详情导出）、`WmsStockInController`、`WmsStockOutController`、`WmsInventoryController`、`WmsInventoryLogController`
`ruoyi-system`	MyBatis、PageHelper、Druid	`com.ruoyi.system` 下新增 8 个 `Wms` 领域对象 + 5 个 Mapper（XML 位于 `resources/mapper/system/Wms.xml`）+ 5 个 Service，业务核心在 `WmsOrderServiceImpl`（导入/确认出库）与 `WmsInventoryServiceImpl`（增减库存与日志）
`web-admin-wms`	Vue 2、Element UI、ECharts	`src/views/wms/` 下 5 个页面：`order/index.vue`（导入对话框 + 明细表格 + 下载模板）、`inventory/index.vue`（图片上传预览 + 库存 CRUD）、`stockIn/index.vue`（明细批量导入）、`stockOut/index.vue`、`inventoryLog/index.vue`
`sql/`	MySQL	`wms.sql`（8 张业务表建表 + 测试数据）、`wms_menu.sql`（1 个一级菜单 + 5 个二级菜单 + 26 个按钮权限）、`wms_dict.sql`（订单/入库/出库状态字典）、`251105-wms.sql`（全库导出）

后端分层严格遵循若依规范：控制器用 @PreAuthorize("@ss.hasPermi('system:order:import')") 做接口级权限控制，前端按钮用 v-hasPermi 指令按权限标识显隐，操作记录通过 @Log(title = "订单导入", businessType = BusinessType.IMPORT) 落操作日志；Excel 读写统一复用若依 ExcelUtil（基于 Apache POI）；分页由 PageHelper startPage() 自动完成。

核心功能

订单 Excel 导入与代理商数据隔离。 代理商在订单页点击”导入订单”，前端把文件 POST 到 /system/wms/order/importData，后端用 ExcelUtil<WmsOrderDetail>.importExcel() 解析后交给 importOrder()：先生成订单号 "ORD" + DateUtils.dateTimeNow()、订单名称取文件名去扩展名，再逐行校验零件编码非空、颜色编号非空、数量大于 0（不合法直接抛出 ServiceException 并提示具体行号），随后自动拼接商品编码 partCode + "-" + colorCode、累加总数量、批量落库，最终返回”导入成功！订单号：xxx，共导入 N 条明细，总数量：M”。订单列表接口在非管理员登录时强制 wmsOrder.setUserId(SecurityUtils.getUserId()) 只返回自己导入的订单，导出接口同样复刻该过滤，实现代理商与管理员的数据隔离。

确认出库：校验 → 生成出库单 → 扣库存。 confirmStockOut(orderId) 是一段完整的事务链路（@Transactional）：先校验订单存在且状态为”0 待处理”、明细非空；再逐条通过 selectWmsInventoryByPartCodeOrProductCode（零件编码或商品编码任一匹配）查库存，库存不存在或 库存数量 < 需求量 时分别给出明确报错；全部通过后生成出库单（单号 "OUT" + 时间戳，状态直接置为”1 已出库”，记录出库时间），循环调用 inventoryService.decreaseInventory(...) 扣减库存（以”订单出库：单号”作为变动原因），批量写入出库单详情，最后把订单状态更新为”1 已处理”并记录 out_time。任何一步失败都会整体回滚，保证不会出现”扣了库存但订单没处理”的中间态。

库存增减统一服务与变动日志。 WmsInventoryServiceImpl 对外暴露 increaseInventory / decreaseInventory 两个核心方法，入库确认与订单出库都只通过它们触碰库存：按零件编码或商品编码匹配到库存记录则增减数量，匹配不到时入库场景自动新建库存行（商品编码为空时自动拼接）、出库场景直接报”库存不存在”；每次变动都先记录变动前数量、算好变动后数量，再向 wms_inventory_log 写入一条日志（change_type 1 入库 / 2 出库、change_quantity 正数增加负数减少、order_no 关联单号、reason 变动原因），实现库存每一步变动都可追溯。库存列表还支持图片上传（el-image 预览）与单价维护，商品编码在新增时同样自动由零件编码与颜色编号拼接而成。

入库单管理与明细批量导入。 入库单号自动生成（"IN" + 时间戳），明细支持手工添加或”批量导入”：上传 Excel 后前端解析把数据追加进明细表格，confirmStockIn(stockInId) 校验单据状态为”0 待入库”后循环调用 increaseInventory 增加库存并更新状态为”1 已入库”、记录入库时间。出库单则由订单确认出库自动生成并关联订单号，出库页可按订单编号检索、查看关联详情。三个状态字典（wms_order_status / wms_stock_in_status / wms_stock_out_status，待处理→已处理→已取消）通过若依字典模块驱动前端 DictTag 标签着色（warning/success/danger），单据状态一目了然。订单详情导出接口还专门处理了图片路径：兼容 http URL、/profile 前缀与裸路径三种存储形式，统一转换为可访问的 /profile/... 路径后随 Excel 一起导出，方便仓库打印”拿货单”。

功能截图

暂无运行截图。

快速上手

准备数据库：在 MySQL 中先执行 sql/251105-wms.sql（若依框架库 + 8 张 wms 业务表 + 菜单数据），再按需执行 sql/wms_menu.sql（若菜单缺失）与 sql/wms_dict.sql（状态字典），sql/wms.sql 中预置了 3 条库存测试数据（如 GDS-1227-030 数量 6）。
启动后端：修改 ruoyi-admin/src/main/resources/application-druid.yml 与 application.yml 中的数据源、Redis 配置后执行：

mvn clean package -DskipTests
java -jar ruoyi-admin/target/ruoyi-admin.jar

启动前端：进入 web-admin-wms 目录，配置 vue.config.js 中的代理地址后执行 npm install && npm run dev，浏览器访问开发服务器地址。
体验流程：以管理员登录进入”WMS 仓库管理 → 订单管理”，下载模板并导入一份订单明细 → 在”库存管理”确认对应商品库存 → 回到订单列表点击”确认出库”（库存充足则自动生成出库单并扣减库存）→ 在”库存日志”查看变动前后数量记录 → 在”入库管理”新建入库单并确认入库补充库存。

总结

这个项目是一个”若依脚手架 + 真实仓储业务”的完整实践样本，业务模型值得借鉴：以「零件编码 + 颜色编号」二元维度定义唯一商品编码，把”订单（需求侧）→ 出库（履约侧）→ 库存（账实侧）→ 日志（追溯侧）“四条线用明确的单号体系（ORD / IN / OUT）串起来，且所有库存变更收敛到 increaseInventory / decreaseInventory 两个服务方法，配合变动前后数量日志，实现了仓库账目的完整可审计性。技术上同样有不少亮点：确认出库的”先校验后扣减”事务设计避免了负库存；selectWmsInventoryByPartCodeOrProductCode 双通道匹配兼容了订单只知零件编码、库存按商品编码维护的两种口径；代理商与管理员按 SecurityUtils.isAdmin 做数据隔离；订单详情导出对图片路径三种存储形态的归一化处理，都是真实业务里会反复踩坑的细节。对于想基于若依快速搭建进销存、订单履约或仓库管理系统，并希望库存变动可追溯的开发者，这套表结构设计与服务层划分很有参考价值。