做建金粮贸项目化名实际对应某区域性粮食贸易企业这套供应链管理系统之前我翻过市面上不少进销存产品说真的没有一个能直接拿过来用。粮食这个行业太特殊了大宗、非标、质检结果直接决定价格、库存会自然减量、采购和销售还要跟合同逐笔对账。通用的ERP要么太臃肿要么压根没有质检扦样这个概念。所以最后决定基于Spring Boot从零搭一套前后端自己写从采购到入库、从仓储到出库、从质检到对账整个链条在一套系统里跑通。这篇博文就是我对这个“基于Spring Boot的粮食供应链管理系统”从设计、实现到上线踩坑的完整复盘适合正在做企业级管理系统、想了解领域模型设计或者准备用Spring Boot独立接内部系统的开发者参考。下面内容全部来自真实项目经验不写概念文章每一步都讲清楚为什么这么做。1. 项目定位与业务需求拆解1.1 粮食供应链和普通进销存到底差在哪大部分人想到供应链第一反应就是“进销存”采购入库、销售出库、库存扣减完事。但粮食行业的供应链管理难点远不止这些。我梳理了一下至少有几个特点是一般零售行业不太会遇到的第一非标品。粮食不像手机一台就是一个SKU一袋大米和另一袋大米看起来一样但产地、等级、年份、水分、杂质率完全不同。同一个供应商拉来的小麦可能这一车是二等下一车是三等价格自然也不一样。因此粮食系统的“批次”概念特别重要出库时不能只扣总数必须指定扣哪一个批次的货。第二质检前置。干粮食贸易的收粮先扦样、检验水分、容重、不完善粒这些指标决定收不收、什么价收。所以质检单据不是采购流程里的一个附加页面它本身就是核心业务节点质检未通过货物不能入库连结算单价都要跟着调整。第三库存自然损耗。粮食存放时间长了有水分蒸发、虫害损耗、搬运撒漏库存台账上的数字和实际库存永远对不上。系统里必须有一个“库存调整/报损”的功能并且操作要留痕否则财务对账的时候说不清楚。第四合同与结算绑定。粮食贸易基本都带合同采购合同、销售合同每一笔出入库要能追溯到合同结算时按合同单价、质检调整单价、过磅净重来算。很多通用系统把合同做成一个单独模块跟库存业务没有强关联实际上非常难用。我做的就是让合同贯穿采购、销售、入库、出库、对账整条线。1.2 建金粮贸的痛点清单和需求范围项目启动前我在现场跟采购、质检、仓管、财务几个岗位的人聊了两天把他们的日常操作摸了一遍问题非常集中采购员开一个到货单要跑去质检科问结果质检结果又要在Excel里手工录入数据一多就乱。仓管员入库用纸质过磅单下班后回办公室再补录电脑账实差一吨半吨都是常事。财务要做结算得同时翻合同、过磅记录、质检报告经常发现同一车货在不同单据上的净重对不上。老板要看一段时间的采购/销售/库存汇总数据得等财务手工汇总通常滞后一两天。所以这套系统的需求边界非常清晰就做六大块基础数据客户/供应商/品名/库位、采购管理合同、到货、过磅、质检管理扦样、检验项目、等级判定、仓储管理入库、库内移动、报损、出库、销售管理合同、发货、结算、统计报表与预警。不做复杂的财务总账只做跟粮食业务强相关的往来与结算。1.3 角色与权限怎么划分粮食企业的人员结构不复杂但职责边界很清晰权限设计做不好容易出现采购员改了质检结果、仓管员自己调库存这种乱象。我按岗位把用户分成六类采购员有权创建采购合同、登记到货、查看质检结果但无权修改质检数据。质检员只处理扦样、检验可以录入指标和判定等级不能动库存和价格。仓管员执行过磅、入库、出库、盘点能看到质检结果但改不了。销售员创建销售合同、开提货单。财务对账、结算、调价不直接操作仓库业务。系统管理员用户、字典、菜单权限配置。实现上用的是Spring Security JWT数据库里存用户-角色-权限三级接口层基于方法注解做细粒度控制前端菜单根据登录用户返回的路由动态渲染。这套方案在同类内部系统里非常常见开发量小也够用。2. 技术选型与架构设计思路2.1 为什么选Spring Boot 而不是其他方案技术选型这块我在项目开始前纠结过一阵。当时比较过几个方案Spring Boot全家桶、Python Django、Node.js、甚至想过用低代码平台。最后选了Spring Boot 2.7 MyBatis-Plus 3.5理由其实很现实第一生态成熟。Spring Boot在Java领域就是事实标准遇到问题搜索答案快招人也容易。建金粮贸后期想让外部公司接手维护Spring Boot的技术栈对他们来说门槛最低。第二快速开发。Spring Boot的自动配置、Starter机制能省掉大量样板代码MyBatis-Plus又解决了单表CRUD的重复劳动。像用户管理、字典管理这类基础模块我基本是半天一个模块的速度推进的。第三部署简单。打成Jar直接扔服务器上跑内置Tomcat不需要单独配外部容器。项目里还用Maven管理依赖打包命令就一条运维成本很低。但这里也要说清楚Spring Boot框架本身只解决后端工程化问题粮食系统真正复杂的是业务逻辑和状态流转。所以我在设计上把大部分精力放在领域模型上框架只是工具。2.2 前后端分离与工程结构这个项目用的还是经典的前后端分离结构。前端选了Vue 3 Element Plus Vite后端Spring Boot提供纯JSON接口。为什么不直接用服务端渲染Thymeleaf因为供应链系统的页面交互太复杂比如过磅、质检、出入库的扫码连续操作前端用组件化开发舒服太多。另外分离架构也方便后期做移动端重新调接口就能复用。工程结构按模块分包没有用微服务一个单体应用搞定。微服务在这个规模下就是给自己添麻烦——分布式事务、服务治理、链路追踪一套下来开发效率至少砍半。我采用的目录结构大致是这样的com.jianjin.supply ├── common // 通用工具、异常、常量 ├── config // 安全、跨域、MyBatisPlus配置 ├── controller // 接口层 ├── service // 业务层 ├── mapper // 数据访问层 ├── entity // 数据库实体 ├── dto // 接口传输对象 └── quartz // 计划任务预警、报表前端按模块拆页面system用户角色、base基础资料、purchase采购、quality质检、warehouse仓储、sales销售、finance结算、report报表。2.3 核心数据库设计思路数据库是这套系统的地基设计上我花的时间最多。整个库大概有三十多张表这里挑几个关键的讲一下设计思路。第一单据表用主从结构。比如采购到货单主表存到货单号、供应商、到货日期、承运车辆子表存每一车的品名、件数、预计重量。为什么要拆主从因为一单可能对应多车货每车货的质检、过磅结果还可能不同。如果一张表解决数据冗余会非常夸张。第二库存不直接存数字靠流水账算出来。这是库存系统最常见的坑我在设计阶段就定了铁律任何管理员都不能直接改库存字段库存的增删只能通过“库存流水表”来实现。流水表记录每次操作的业务单号、批次ID、变动数量、变动类型采购入库、销售出库、报损、盘盈盘亏要查当前库存就是对该批次流水的变动数量求和。这样做的好处是账实可追溯财务质疑某个数字时直接甩一张流水清单就能说清楚。第三批次表和入库单强关联。粮食入库就必须生成一个批次号这个批次绑定质检结果、库位、供应商、合同号。后续出库、盘点、结算全部按批次来。批次表设计得是否合理直接决定追溯功能能不能做。下面是核心表结构的一个简化设计资质和粮食业务相关的字段都体现出来了表名核心字段设计说明biz_purchase_contract合同号、供应商ID、品名、数量、单价、交货日期采购合同头表biz_arrival到货单号、合同号、车辆、件数、到货日期采购到货主表biz_arrival_item到货单号、品名、预计重量到货明细biz_sample扦样单号、到货单号、扦样人、取样位置一车一单biz_quality_check质检单号、样品号、水分、容量、不完善粒、等级质检结果biz_weighing过磅单号、到货单号、毛重、皮重、净重净重参与库存与结算biz_warehouse_room仓号、库位编码、最大容量、当前占用库位基础数据biz_inventory_batch批次号、品名、库位ID、供应商、质检等级、入库日期唯一库存单元biz_inventory_flowID、批次号、业务单号、变动类型、变动数量、操作人库存流水biz_outbound出库单号、销售合同号、批次号、出库数量、承运车辆销售出库2.4 用状态机管理单据流转我做过的管理系统里凡是涉及多部门协作的单据最容易出现“状态乱”的问题。所以这一版我在设计阶段就给每个核心单据定义了一套明确的流转状态用字段标识加状态校验而不是靠各个业务代码自己判断。以采购到货单为例状态依次是待质检 → 质检中 → 部分入库 → 已完成 → 已驳回。其中“部分入库”是粮食业务特有的因为一辆车可能只入库一半或者质检只合格一部分剩下部分进入退货流程。代码里我用一个状态枚举加一个状态流转校验方法从哪个状态能跳到哪个状态都写在配置里不然后期改流程特别容易改出一个“状态地狱”。3. 核心功能模块的实操实现3.1 采购入库流程的落地采购这部分是粮食系统的入口也是最容易出错的地方。业务流程是这样的采购员创建采购合同和供应商约好送粮时间粮食到厂后采购员在系统里登记到货单然后质检员在到货单上发起扦样。扦样结果出来后系统会生成质检单如果质检合格仓管员拿过磅单登记毛重、皮重算出净重确认入库如果质检不合格整批或者部分货物进入退货流程。这个流程里我特意把一个细节做重了过磅数据。实际业务中一车粮食到厂要先过一次磅称毛重卸完货再过一次磅称皮重净重 毛重 - 皮重。很多系统把毛重、皮重放在一个表单里让仓管员填写但真实操作是两次称重时间差半小时。所以我把过磅设计成两个步骤第一次保存毛重第二次保存皮重并自动计算净重。这样仓管员不用一次性填完数据也更真实。到货单和采购合同的关联也要处理好。一个合同可能分十几次交货所以合同ID是到货单的外键前端在创建到货单时可以直接带入合同的品名单价。交货数量超过合同剩余数量系统要弹提示防止超收。3.2 质检模块的领域模型细节质检模块是整个系统里最有粮食行业特色的地方也是我认为设计得最值得复盘的部分。它的核心表我拆成了三张扦样单表、质检单表、质检项目明细表。扦样是一个独立的动作质检员到现场用扦样器从不同部位取粮登记一个“扦样单”关联到货单和车辆信息。这个单可以看作一个任务单提醒质检员今天有哪些车要检。质检单是扦样单的结果里面存水分、容重、杂质、不完善粒、色泽气味等项目。这里有个业务细节不同粮食品类需要检测的项目不一样小麦主要看容重、水分、不完善粒玉米主要看容重、霉变粒、脂肪酸值。所以项目不能写死成固定字段我做了质检项目明细表支持动态配置。前端渲染时根据品名类型展示不同检测项。等级判定逻辑也写在后端按照国家标准字段阈值比如小麦二等容重要大于等于770g/L三等是750g/L这里直接用规则引擎在代码里做。质检结果确认后如果是通过就允许仓管员据此入库如果降等结算价格会跟着变这个调价逻辑我放在了结算模块质检只管出指标和等级不直接改价格避免越权。3.3 仓储管理从库位到粮情记录仓储模块不复杂但是杂。库位是基础我从仓库、廒间存粮的房间有些地方叫廒间、货位做了三级拆解每一批货入库时要指定存在哪个库位的哪个货位。这样出库的时候系统能快速找到对应批次也方便月底盘点。库内操作除了入库出库外还必须处理几个特殊场景一是转仓。粮食存放一段时间可能因为仓温问题需要倒仓或者企业把粮食从A仓挪到B仓这对应的是批次库位变更不算出入库。二是报损。存储期间水分减量、虫害损耗、运送撒漏都会让实货比账上少。仓管员需要定期报损我做成独立的“报损单”注明损耗原因审批通过后自动生成负数流水。报损数量过大时系统会强制要求必须上传现场照片附件防止管理漏洞。三是临期预警。粮食虽然不像药品有那么严格的保质期但存储超过一年品质会明显下降。我让批次在入库时记录生产年份/入库年份系统按维度统计库存账龄超过设定天数自动推送预警给销售部门。3.4 销售出库与批次追溯实现销售出库的核心是批次选择。粮食销售不是简单扣库存总数而是选择具体批次的货发给客户。业务上有一个默认原则先进先出。也就是优先扣入库日期最早的批次避免陈粮积压。但实际销售中客户可能有特殊要求比如指定要某年某产地的粮所以我也做了手动指定批次的功能。系统默认按先进先出排序允许销售员改选。出库单状态相对简单待提货 → 已出库 → 已结算。提货环节支持多次提货一单可以分几车拉走每次出库生成独立的出库流水扣减对应批次库存。这样即使一张提货单拉了五天账目也能逐车对应上。批次追溯是项目的硬性要求。我做了“库存台账”页面点开任意批次可以看到该批次的完整生命周期采购合同、到货单、扦样单、质检结果、过磅记录、入库时间、所有出库记录、当前剩余数量。这个功能对需要应付下游客户验厂审核的企业来说特别实用能直接导出PDF发给客户证明这批粮的来源和质量。3.5 库存流水与财务对账的配合财务模块在这个项目里不复杂但非常关键。我把它定位在“以结算单为核心”不做会计凭证只做业务往来。具体功能包括发票登记、结算单、应付/应收汇总、合同执行进度。结算单的数据来源很固定采购结算 采购合同单价 × 质检调整系数 × 过磅净重。这个“质检调整系数”是行业规则比如质检降等每降一个等级单价按合同约定扣减一定比例。我做成参数化配置财务在结算时选择质检单系统自动带出调整后的结算单价避免手工算错。销售结算同理出库单关联销售合同后系统自动计算结算金额。这套设计的价值在于每个数字都有单据来源财务不用再对着Excel加加减减。月底对账时打开合同执行报表已交货数量、已结算金额、未结算金额一目了然老板要的数据能直接看到。4. 关键业务流程的闭环设计4.1 采购-质检-入库怎么闭环之前我提到到货单状态有“部分入库”这在业务上是常态但代码实现时要特别小心。我处理的方法是把“入库”动作统一收敛到一个入库服务方法里这个方法做的事情是校验到货单状态和剩余可入库数量创建库存批次批次初始数量为本次入库净重生成库存流水入库正数回写到货单明细的累计入库数量根据累计入库数量和到货总数量判断是否置单已完成整个方法加Transactional任何一步失败全部回滚。这样能保证一个业务动作要么全部生效要么全部不生效不会出现单子还在“质检中”库存却已经加上了的诡异情况。类似的逻辑也用在出库流程上只是方向反过来。4.2 库存台账与流水一致性的事务方案库存系统最怕的就是台账和流水对不上。很多系统会在一张表里存“当前库存”同时记录流水但更新时容易出现两个字段不一致。我在设计时干脆不在批次表里存“当前库存”字段每次要查库存就动态计算流水的净变动数量。你可能会问这样查询性能会不会差我做了两步优化第一按批次统计流水数据量本身不大一天的流水可能几十条一个批次累计也就几百条全量求和完全来得及执行时间在几十毫秒级别。第二给流水表的批次ID和变动类型建了联合索引扫描范围非常小。每个月定时任务还会把流水按批次汇总一次月底的库存数字用汇总结果进一步降低查询压力。4.3 预警与报表模块怎么设计才实用预警模块看着简单但需求变化特别多。我实现的方式是“预警规则配置化”不是把预警逻辑写死在代码里。系统预置了几类预警库存上限预警仓储容量接近上限时提醒运营避免后续到货没有库位放库存下限预警低于安全库存提醒采购补货避免销售没货可发合同执行预警合同交货截止日期前7天还有剩余数量未交货质检临期预警质检单出具后超过15天未确认入库每种预警都有一个开关和阈值参数放在参数配置表里由管理员调整这样业务改了阈值不用改代码重新发版。报表模块相对传统我做了一张综合看板当日入库/出库量、库存周转率、合同履约率、质量合格率。具体明细报表用ECharts画折线图和柱状图可以按品名、供应商、月份组合筛选。最受老板欢迎的是“供应商质量分析”能看出哪家供应商的粮食合格率高、哪家经常水分超标这直接影响了后续采购合同的分配比例。5. 部署、安全与性能调优5.1 多环境配置与生产部署开发环境、测试环境、生产环境的配置差异我用Spring Boot的多Profile机制解决。application.yml只放公共配置application-dev.yml、application-prod.yml分别放各自数据库和日志配置。生产环境的数据库密码、Redis密码用环境变量注入不写在配置文件里否则代码仓库一泄露数据库就等于裸奔了。打包部署这块比较常规Maven打Jar包生产服务器装一个JDK 11用Systemd托管进程。服务器规格4核8G对这个体量的系统完全够用。我把定时任务单独用Spring自带的Scheduled做不引入XXL-Job这类分布式调度组件因为单实例部署用不到。Redis用于存储登录Token的临时缓存让JWT支持主动下线不然用户改了密码原Token还能用很不安全。5.2 安全设计登录、权限与操作留痕粮食系统虽然不直接涉及银行卡数据但合同价格、结算金额这些数据也是商业敏感信息。我在安全设计上做了这些事密码存储用BCrypt加密不能逆推出明文。接口鉴权用JWT但把Token有效期设短2小时配合Redis里的刷新令牌实现“记住我”功能。所有登录用户的增删改操作统一通过AOP切面写入操作日志表记录谁在什么时间改了哪个单据的哪个字段。这个功能上线后很有价值曾经帮客户查出一次质检结果被误改的问题。文件上传做了类型白名单校验强制限制只能传jpg、png、pdf等格式防止上传WebShell。项目里有一个临时附件功能上传路径设置在非Web目录下通过接口下载避免直接暴露静态路径。5.3 慢SQL与性能优化的实操记录系统上线一个月后我收到过几次“列表页打开有点慢”的反馈。排查下来发现主要集中在两个页面库存流水列表和合同执行报表。问题原因和处理方法如下库存流水列表原来分页查询时count操作会对全表COUNT(*)流水表大了以后这个统计很慢。我把分页插件改成“不执行count”用流式查询只取当前页数据前端加滚动加载。对于内部系统用户根本不需要看总共有多少条这个优化收益非常明显。合同执行报表原来是每条合同实时去查入库/出库表SUM合同多的时候就是N次查询。我改成在报表查询入口先按合同维度聚合一次用一条GROUP BY SQL搞定页面响应从三秒降到三百毫秒级别。另外给所有外键字段补了索引尤其是biz_inventory_flow的batch_id、biz_arrival的contract_id、biz_outbound的batch_id这三组都是高频查询条件。6. 开发中踩过的坑与排查实录6.1 事务注解失效同一个类里方法调用的问题这是Spring初学开发者最容易踩的坑我在项目里也中招了。Service里一个方法调另一个方法两个方法都有Transactional但内部的调用其实是绕过代理直接调用的事务根本没有生效。比如入库服务里我在addInventory方法里直接调用了自己的updateArrivalStatus方法本来希望两个操作一个事务结果updateArrivalStatus在独立事务外执行入库成功但状态没更新时数据就乱了。排查方式很简单在日志里看事务日志有没有出现“Creating new transaction”或者直接查看调用链。修复方法是把跨方法的操作拆到不同的Service类里或者通过self注入代理对象来调用。我采用的方式是把所有涉及库存变动的操作都放在一个单独的InventoryTransactionService里让这个类统一处理跨模块事务这样既能避免事务失效也方便以后做多数据源切换。6.2 库存并发超卖问题的处理粮食企业同时开多辆车进厂的情况很常见出库时也可能多个销售员同时开单。库存扣减的并发控制是必须做好的。我先用的方案是乐观锁在批次表里加version字段更新时比较版本号但实际操作中发现一个问题扣减库存时先查一遍批次然后再更新这个“查-改”之间有窗口期两个请求可能同时读到同一个剩余数量。后来改成数据库层面的原子更新用UPDATE语句直接对批次相关流水求差并发扣减UPDATE biz_inventory_batch SET version version 1 WHERE id ? AND version ?同时在扣库存的Service方法里对同一批次的操作加了synchronized锁按批次ID做粒度控制。这样既保证单实例下的并发安全也能在数据库层兜底。实测下来一百辆车同时入场的极压场景下库存账目没有出现过一次负数。6.3 Excel导入导出时的内存溢出问题Excel操作是管理系统逃不掉的功课。项目里需要导出入库台账、质检记录还要提供模板让仓管员批量导入基础库位数据。刚开始用Apache POI直接把整个工作簿读进内存数据量一大就报OutOfMemoryError。后来换成EasyExcel阿里开源的它底层用SAX模式解析一行一行处理不会把整个文件加载到内存导出用分批写盘方式。这里有个经验POI导出时默认单元格样式、字体等对象占用内存很厉害尽量复用CellStyle对象不要每个单元格都新建。还有一个小坑某次导入模板是xlsx格式但仓管员把文件后缀改成xls保存POI按老格式解析直接报错。我在导入前做了格式嗅探用文件头判断真实格式而不看后缀名这个问题就解决了。6.4 懒加载与序列化导致的报错项目里实体类之间有关联关系比如到货单关联合同对象我用的是MyBatis-Plus的关联查询手动SQL联表没有依赖JPA的懒加载所以这一块问题不大。但后来加了一个功能让批次信息关联质检单用到了MyBatis的association配置产生了懒加载代理对象。这个对象直接转JSON时Jackson序列化会报错提示无法实例化懒加载代理。解决办法是统一使用VO/DTO实体类不直接返回给前端在Service里把需要的数据装配成自定义的Response对象再交给Controller返回。这样不仅绕过了懒加载序列化问题还避免把数据库的冗余字段暴露给前端。虽然写DTO会多花一点时间但这是Java后端的一个长期受益的设计习惯。6.5 时间字段的坑LocalDateTime与前端格式项目所有时间字段统一用LocalDateTime前端组件用的是Element Plus的日期时间选择器。联调阶段发现一个问题后端返回的时间格式是“2025-06-17T09:30:00”前端直接显示很难看。需要统一配置Jackson的序列化格式spring.jackson.date-formatyyyy-MM-dd HH:mm:ss spring.jackson.time-zoneGMT8另外一个更隐蔽的坑是时区服务器部署在CentOS默认时区是UTC数据库写入时间会比北京时间早8小时。我用的是MySQL连接参数里加serverTimezoneAsia/Shanghai服务器上又把时区调整成Asia/Shanghai双保险避免了“时间突然少了8小时”的灵异事件。6.6 初始化数据与数据库版本管理开发阶段改表结构改得频繁几个人协同时经常出现“你本地数据库有这列我这边报错”的情况。我后来引入了Flyway做数据库版本管理。每改一次表结构写一个V开头的SQL脚本应用启动时自动执行增量脚本。这样所有人的库结构保持同步生产环境升级也不用手工执行SQL了部署脚本减少一多半。基础数据也要处理好。粮食企业的品名、质检项目、库位编码在系统运行初期就需要预置我写了一个DataInitializer类在启动时检查字典表是否为空为空则自动插入初始数据。注意这个类要加Profile({dev,prod})限制不要在单元测试时乱初始化。结束前说几句真心话这个系统从需求调研到正式上线前后花了三个多月。中间改过无数次需求最大的一次是采购部提出要支持“一票多车”的结算模式把整个结算模块重新设计了一遍。如果让我给后来者一个建议就是在动手写代码之前一定先花足够时间把业务流程图和数据流转图画清楚。很多项目最后返工不是因为技术难而是因为一开始就不理解业务。还有一个小技巧想分享做这类行业管理系统代码之外一定要留出时间给用户做培训和操作手册。建金粮贸的仓管员平均年龄偏大刚开始很不习惯用系统我把过磅、入库做成了大按钮、少填写的极简界面还把常用操作做成了一页纸的图文说明。系统好不好用很多时候不取决于功能多少而取决于界面是否贴近他们的操作习惯。这个项目后续还可以扩展的方向不少对接地磅硬件自动采集重量、接入RFID做批次识别、给下游客户开一个迷你查询端实时查看订单状态。如果你正在做类似的行业供应链系统希望这篇复盘能帮你少踩几个坑。
做建金粮贸项目化名实际对应某区域性粮食贸易企业这套供应链管理系统之前我翻过市面上不少进销存产品说真的没有一个能直接拿过来用。粮食这个行业太特殊了大宗、非标、质检结果直接决定价格、库存会自然减量、采购和销售还要跟合同逐笔对账。通用的ERP要么太臃肿要么压根没有质检扦样这个概念。所以最后决定基于Spring Boot从零搭一套前后端自己写从采购到入库、从仓储到出库、从质检到对账整个链条在一套系统里跑通。这篇博文就是我对这个“基于Spring Boot的粮食供应链管理系统”从设计、实现到上线踩坑的完整复盘适合正在做企业级管理系统、想了解领域模型设计或者准备用Spring Boot独立接内部系统的开发者参考。下面内容全部来自真实项目经验不写概念文章每一步都讲清楚为什么这么做。1. 项目定位与业务需求拆解1.1 粮食供应链和普通进销存到底差在哪大部分人想到供应链第一反应就是“进销存”采购入库、销售出库、库存扣减完事。但粮食行业的供应链管理难点远不止这些。我梳理了一下至少有几个特点是一般零售行业不太会遇到的第一非标品。粮食不像手机一台就是一个SKU一袋大米和另一袋大米看起来一样但产地、等级、年份、水分、杂质率完全不同。同一个供应商拉来的小麦可能这一车是二等下一车是三等价格自然也不一样。因此粮食系统的“批次”概念特别重要出库时不能只扣总数必须指定扣哪一个批次的货。第二质检前置。干粮食贸易的收粮先扦样、检验水分、容重、不完善粒这些指标决定收不收、什么价收。所以质检单据不是采购流程里的一个附加页面它本身就是核心业务节点质检未通过货物不能入库连结算单价都要跟着调整。第三库存自然损耗。粮食存放时间长了有水分蒸发、虫害损耗、搬运撒漏库存台账上的数字和实际库存永远对不上。系统里必须有一个“库存调整/报损”的功能并且操作要留痕否则财务对账的时候说不清楚。第四合同与结算绑定。粮食贸易基本都带合同采购合同、销售合同每一笔出入库要能追溯到合同结算时按合同单价、质检调整单价、过磅净重来算。很多通用系统把合同做成一个单独模块跟库存业务没有强关联实际上非常难用。我做的就是让合同贯穿采购、销售、入库、出库、对账整条线。1.2 建金粮贸的痛点清单和需求范围项目启动前我在现场跟采购、质检、仓管、财务几个岗位的人聊了两天把他们的日常操作摸了一遍问题非常集中采购员开一个到货单要跑去质检科问结果质检结果又要在Excel里手工录入数据一多就乱。仓管员入库用纸质过磅单下班后回办公室再补录电脑账实差一吨半吨都是常事。财务要做结算得同时翻合同、过磅记录、质检报告经常发现同一车货在不同单据上的净重对不上。老板要看一段时间的采购/销售/库存汇总数据得等财务手工汇总通常滞后一两天。所以这套系统的需求边界非常清晰就做六大块基础数据客户/供应商/品名/库位、采购管理合同、到货、过磅、质检管理扦样、检验项目、等级判定、仓储管理入库、库内移动、报损、出库、销售管理合同、发货、结算、统计报表与预警。不做复杂的财务总账只做跟粮食业务强相关的往来与结算。1.3 角色与权限怎么划分粮食企业的人员结构不复杂但职责边界很清晰权限设计做不好容易出现采购员改了质检结果、仓管员自己调库存这种乱象。我按岗位把用户分成六类采购员有权创建采购合同、登记到货、查看质检结果但无权修改质检数据。质检员只处理扦样、检验可以录入指标和判定等级不能动库存和价格。仓管员执行过磅、入库、出库、盘点能看到质检结果但改不了。销售员创建销售合同、开提货单。财务对账、结算、调价不直接操作仓库业务。系统管理员用户、字典、菜单权限配置。实现上用的是Spring Security JWT数据库里存用户-角色-权限三级接口层基于方法注解做细粒度控制前端菜单根据登录用户返回的路由动态渲染。这套方案在同类内部系统里非常常见开发量小也够用。2. 技术选型与架构设计思路2.1 为什么选Spring Boot 而不是其他方案技术选型这块我在项目开始前纠结过一阵。当时比较过几个方案Spring Boot全家桶、Python Django、Node.js、甚至想过用低代码平台。最后选了Spring Boot 2.7 MyBatis-Plus 3.5理由其实很现实第一生态成熟。Spring Boot在Java领域就是事实标准遇到问题搜索答案快招人也容易。建金粮贸后期想让外部公司接手维护Spring Boot的技术栈对他们来说门槛最低。第二快速开发。Spring Boot的自动配置、Starter机制能省掉大量样板代码MyBatis-Plus又解决了单表CRUD的重复劳动。像用户管理、字典管理这类基础模块我基本是半天一个模块的速度推进的。第三部署简单。打成Jar直接扔服务器上跑内置Tomcat不需要单独配外部容器。项目里还用Maven管理依赖打包命令就一条运维成本很低。但这里也要说清楚Spring Boot框架本身只解决后端工程化问题粮食系统真正复杂的是业务逻辑和状态流转。所以我在设计上把大部分精力放在领域模型上框架只是工具。2.2 前后端分离与工程结构这个项目用的还是经典的前后端分离结构。前端选了Vue 3 Element Plus Vite后端Spring Boot提供纯JSON接口。为什么不直接用服务端渲染Thymeleaf因为供应链系统的页面交互太复杂比如过磅、质检、出入库的扫码连续操作前端用组件化开发舒服太多。另外分离架构也方便后期做移动端重新调接口就能复用。工程结构按模块分包没有用微服务一个单体应用搞定。微服务在这个规模下就是给自己添麻烦——分布式事务、服务治理、链路追踪一套下来开发效率至少砍半。我采用的目录结构大致是这样的com.jianjin.supply ├── common // 通用工具、异常、常量 ├── config // 安全、跨域、MyBatisPlus配置 ├── controller // 接口层 ├── service // 业务层 ├── mapper // 数据访问层 ├── entity // 数据库实体 ├── dto // 接口传输对象 └── quartz // 计划任务预警、报表前端按模块拆页面system用户角色、base基础资料、purchase采购、quality质检、warehouse仓储、sales销售、finance结算、report报表。2.3 核心数据库设计思路数据库是这套系统的地基设计上我花的时间最多。整个库大概有三十多张表这里挑几个关键的讲一下设计思路。第一单据表用主从结构。比如采购到货单主表存到货单号、供应商、到货日期、承运车辆子表存每一车的品名、件数、预计重量。为什么要拆主从因为一单可能对应多车货每车货的质检、过磅结果还可能不同。如果一张表解决数据冗余会非常夸张。第二库存不直接存数字靠流水账算出来。这是库存系统最常见的坑我在设计阶段就定了铁律任何管理员都不能直接改库存字段库存的增删只能通过“库存流水表”来实现。流水表记录每次操作的业务单号、批次ID、变动数量、变动类型采购入库、销售出库、报损、盘盈盘亏要查当前库存就是对该批次流水的变动数量求和。这样做的好处是账实可追溯财务质疑某个数字时直接甩一张流水清单就能说清楚。第三批次表和入库单强关联。粮食入库就必须生成一个批次号这个批次绑定质检结果、库位、供应商、合同号。后续出库、盘点、结算全部按批次来。批次表设计得是否合理直接决定追溯功能能不能做。下面是核心表结构的一个简化设计资质和粮食业务相关的字段都体现出来了表名核心字段设计说明biz_purchase_contract合同号、供应商ID、品名、数量、单价、交货日期采购合同头表biz_arrival到货单号、合同号、车辆、件数、到货日期采购到货主表biz_arrival_item到货单号、品名、预计重量到货明细biz_sample扦样单号、到货单号、扦样人、取样位置一车一单biz_quality_check质检单号、样品号、水分、容量、不完善粒、等级质检结果biz_weighing过磅单号、到货单号、毛重、皮重、净重净重参与库存与结算biz_warehouse_room仓号、库位编码、最大容量、当前占用库位基础数据biz_inventory_batch批次号、品名、库位ID、供应商、质检等级、入库日期唯一库存单元biz_inventory_flowID、批次号、业务单号、变动类型、变动数量、操作人库存流水biz_outbound出库单号、销售合同号、批次号、出库数量、承运车辆销售出库2.4 用状态机管理单据流转我做过的管理系统里凡是涉及多部门协作的单据最容易出现“状态乱”的问题。所以这一版我在设计阶段就给每个核心单据定义了一套明确的流转状态用字段标识加状态校验而不是靠各个业务代码自己判断。以采购到货单为例状态依次是待质检 → 质检中 → 部分入库 → 已完成 → 已驳回。其中“部分入库”是粮食业务特有的因为一辆车可能只入库一半或者质检只合格一部分剩下部分进入退货流程。代码里我用一个状态枚举加一个状态流转校验方法从哪个状态能跳到哪个状态都写在配置里不然后期改流程特别容易改出一个“状态地狱”。3. 核心功能模块的实操实现3.1 采购入库流程的落地采购这部分是粮食系统的入口也是最容易出错的地方。业务流程是这样的采购员创建采购合同和供应商约好送粮时间粮食到厂后采购员在系统里登记到货单然后质检员在到货单上发起扦样。扦样结果出来后系统会生成质检单如果质检合格仓管员拿过磅单登记毛重、皮重算出净重确认入库如果质检不合格整批或者部分货物进入退货流程。这个流程里我特意把一个细节做重了过磅数据。实际业务中一车粮食到厂要先过一次磅称毛重卸完货再过一次磅称皮重净重 毛重 - 皮重。很多系统把毛重、皮重放在一个表单里让仓管员填写但真实操作是两次称重时间差半小时。所以我把过磅设计成两个步骤第一次保存毛重第二次保存皮重并自动计算净重。这样仓管员不用一次性填完数据也更真实。到货单和采购合同的关联也要处理好。一个合同可能分十几次交货所以合同ID是到货单的外键前端在创建到货单时可以直接带入合同的品名单价。交货数量超过合同剩余数量系统要弹提示防止超收。3.2 质检模块的领域模型细节质检模块是整个系统里最有粮食行业特色的地方也是我认为设计得最值得复盘的部分。它的核心表我拆成了三张扦样单表、质检单表、质检项目明细表。扦样是一个独立的动作质检员到现场用扦样器从不同部位取粮登记一个“扦样单”关联到货单和车辆信息。这个单可以看作一个任务单提醒质检员今天有哪些车要检。质检单是扦样单的结果里面存水分、容重、杂质、不完善粒、色泽气味等项目。这里有个业务细节不同粮食品类需要检测的项目不一样小麦主要看容重、水分、不完善粒玉米主要看容重、霉变粒、脂肪酸值。所以项目不能写死成固定字段我做了质检项目明细表支持动态配置。前端渲染时根据品名类型展示不同检测项。等级判定逻辑也写在后端按照国家标准字段阈值比如小麦二等容重要大于等于770g/L三等是750g/L这里直接用规则引擎在代码里做。质检结果确认后如果是通过就允许仓管员据此入库如果降等结算价格会跟着变这个调价逻辑我放在了结算模块质检只管出指标和等级不直接改价格避免越权。3.3 仓储管理从库位到粮情记录仓储模块不复杂但是杂。库位是基础我从仓库、廒间存粮的房间有些地方叫廒间、货位做了三级拆解每一批货入库时要指定存在哪个库位的哪个货位。这样出库的时候系统能快速找到对应批次也方便月底盘点。库内操作除了入库出库外还必须处理几个特殊场景一是转仓。粮食存放一段时间可能因为仓温问题需要倒仓或者企业把粮食从A仓挪到B仓这对应的是批次库位变更不算出入库。二是报损。存储期间水分减量、虫害损耗、运送撒漏都会让实货比账上少。仓管员需要定期报损我做成独立的“报损单”注明损耗原因审批通过后自动生成负数流水。报损数量过大时系统会强制要求必须上传现场照片附件防止管理漏洞。三是临期预警。粮食虽然不像药品有那么严格的保质期但存储超过一年品质会明显下降。我让批次在入库时记录生产年份/入库年份系统按维度统计库存账龄超过设定天数自动推送预警给销售部门。3.4 销售出库与批次追溯实现销售出库的核心是批次选择。粮食销售不是简单扣库存总数而是选择具体批次的货发给客户。业务上有一个默认原则先进先出。也就是优先扣入库日期最早的批次避免陈粮积压。但实际销售中客户可能有特殊要求比如指定要某年某产地的粮所以我也做了手动指定批次的功能。系统默认按先进先出排序允许销售员改选。出库单状态相对简单待提货 → 已出库 → 已结算。提货环节支持多次提货一单可以分几车拉走每次出库生成独立的出库流水扣减对应批次库存。这样即使一张提货单拉了五天账目也能逐车对应上。批次追溯是项目的硬性要求。我做了“库存台账”页面点开任意批次可以看到该批次的完整生命周期采购合同、到货单、扦样单、质检结果、过磅记录、入库时间、所有出库记录、当前剩余数量。这个功能对需要应付下游客户验厂审核的企业来说特别实用能直接导出PDF发给客户证明这批粮的来源和质量。3.5 库存流水与财务对账的配合财务模块在这个项目里不复杂但非常关键。我把它定位在“以结算单为核心”不做会计凭证只做业务往来。具体功能包括发票登记、结算单、应付/应收汇总、合同执行进度。结算单的数据来源很固定采购结算 采购合同单价 × 质检调整系数 × 过磅净重。这个“质检调整系数”是行业规则比如质检降等每降一个等级单价按合同约定扣减一定比例。我做成参数化配置财务在结算时选择质检单系统自动带出调整后的结算单价避免手工算错。销售结算同理出库单关联销售合同后系统自动计算结算金额。这套设计的价值在于每个数字都有单据来源财务不用再对着Excel加加减减。月底对账时打开合同执行报表已交货数量、已结算金额、未结算金额一目了然老板要的数据能直接看到。4. 关键业务流程的闭环设计4.1 采购-质检-入库怎么闭环之前我提到到货单状态有“部分入库”这在业务上是常态但代码实现时要特别小心。我处理的方法是把“入库”动作统一收敛到一个入库服务方法里这个方法做的事情是校验到货单状态和剩余可入库数量创建库存批次批次初始数量为本次入库净重生成库存流水入库正数回写到货单明细的累计入库数量根据累计入库数量和到货总数量判断是否置单已完成整个方法加Transactional任何一步失败全部回滚。这样能保证一个业务动作要么全部生效要么全部不生效不会出现单子还在“质检中”库存却已经加上了的诡异情况。类似的逻辑也用在出库流程上只是方向反过来。4.2 库存台账与流水一致性的事务方案库存系统最怕的就是台账和流水对不上。很多系统会在一张表里存“当前库存”同时记录流水但更新时容易出现两个字段不一致。我在设计时干脆不在批次表里存“当前库存”字段每次要查库存就动态计算流水的净变动数量。你可能会问这样查询性能会不会差我做了两步优化第一按批次统计流水数据量本身不大一天的流水可能几十条一个批次累计也就几百条全量求和完全来得及执行时间在几十毫秒级别。第二给流水表的批次ID和变动类型建了联合索引扫描范围非常小。每个月定时任务还会把流水按批次汇总一次月底的库存数字用汇总结果进一步降低查询压力。4.3 预警与报表模块怎么设计才实用预警模块看着简单但需求变化特别多。我实现的方式是“预警规则配置化”不是把预警逻辑写死在代码里。系统预置了几类预警库存上限预警仓储容量接近上限时提醒运营避免后续到货没有库位放库存下限预警低于安全库存提醒采购补货避免销售没货可发合同执行预警合同交货截止日期前7天还有剩余数量未交货质检临期预警质检单出具后超过15天未确认入库每种预警都有一个开关和阈值参数放在参数配置表里由管理员调整这样业务改了阈值不用改代码重新发版。报表模块相对传统我做了一张综合看板当日入库/出库量、库存周转率、合同履约率、质量合格率。具体明细报表用ECharts画折线图和柱状图可以按品名、供应商、月份组合筛选。最受老板欢迎的是“供应商质量分析”能看出哪家供应商的粮食合格率高、哪家经常水分超标这直接影响了后续采购合同的分配比例。5. 部署、安全与性能调优5.1 多环境配置与生产部署开发环境、测试环境、生产环境的配置差异我用Spring Boot的多Profile机制解决。application.yml只放公共配置application-dev.yml、application-prod.yml分别放各自数据库和日志配置。生产环境的数据库密码、Redis密码用环境变量注入不写在配置文件里否则代码仓库一泄露数据库就等于裸奔了。打包部署这块比较常规Maven打Jar包生产服务器装一个JDK 11用Systemd托管进程。服务器规格4核8G对这个体量的系统完全够用。我把定时任务单独用Spring自带的Scheduled做不引入XXL-Job这类分布式调度组件因为单实例部署用不到。Redis用于存储登录Token的临时缓存让JWT支持主动下线不然用户改了密码原Token还能用很不安全。5.2 安全设计登录、权限与操作留痕粮食系统虽然不直接涉及银行卡数据但合同价格、结算金额这些数据也是商业敏感信息。我在安全设计上做了这些事密码存储用BCrypt加密不能逆推出明文。接口鉴权用JWT但把Token有效期设短2小时配合Redis里的刷新令牌实现“记住我”功能。所有登录用户的增删改操作统一通过AOP切面写入操作日志表记录谁在什么时间改了哪个单据的哪个字段。这个功能上线后很有价值曾经帮客户查出一次质检结果被误改的问题。文件上传做了类型白名单校验强制限制只能传jpg、png、pdf等格式防止上传WebShell。项目里有一个临时附件功能上传路径设置在非Web目录下通过接口下载避免直接暴露静态路径。5.3 慢SQL与性能优化的实操记录系统上线一个月后我收到过几次“列表页打开有点慢”的反馈。排查下来发现主要集中在两个页面库存流水列表和合同执行报表。问题原因和处理方法如下库存流水列表原来分页查询时count操作会对全表COUNT(*)流水表大了以后这个统计很慢。我把分页插件改成“不执行count”用流式查询只取当前页数据前端加滚动加载。对于内部系统用户根本不需要看总共有多少条这个优化收益非常明显。合同执行报表原来是每条合同实时去查入库/出库表SUM合同多的时候就是N次查询。我改成在报表查询入口先按合同维度聚合一次用一条GROUP BY SQL搞定页面响应从三秒降到三百毫秒级别。另外给所有外键字段补了索引尤其是biz_inventory_flow的batch_id、biz_arrival的contract_id、biz_outbound的batch_id这三组都是高频查询条件。6. 开发中踩过的坑与排查实录6.1 事务注解失效同一个类里方法调用的问题这是Spring初学开发者最容易踩的坑我在项目里也中招了。Service里一个方法调另一个方法两个方法都有Transactional但内部的调用其实是绕过代理直接调用的事务根本没有生效。比如入库服务里我在addInventory方法里直接调用了自己的updateArrivalStatus方法本来希望两个操作一个事务结果updateArrivalStatus在独立事务外执行入库成功但状态没更新时数据就乱了。排查方式很简单在日志里看事务日志有没有出现“Creating new transaction”或者直接查看调用链。修复方法是把跨方法的操作拆到不同的Service类里或者通过self注入代理对象来调用。我采用的方式是把所有涉及库存变动的操作都放在一个单独的InventoryTransactionService里让这个类统一处理跨模块事务这样既能避免事务失效也方便以后做多数据源切换。6.2 库存并发超卖问题的处理粮食企业同时开多辆车进厂的情况很常见出库时也可能多个销售员同时开单。库存扣减的并发控制是必须做好的。我先用的方案是乐观锁在批次表里加version字段更新时比较版本号但实际操作中发现一个问题扣减库存时先查一遍批次然后再更新这个“查-改”之间有窗口期两个请求可能同时读到同一个剩余数量。后来改成数据库层面的原子更新用UPDATE语句直接对批次相关流水求差并发扣减UPDATE biz_inventory_batch SET version version 1 WHERE id ? AND version ?同时在扣库存的Service方法里对同一批次的操作加了synchronized锁按批次ID做粒度控制。这样既保证单实例下的并发安全也能在数据库层兜底。实测下来一百辆车同时入场的极压场景下库存账目没有出现过一次负数。6.3 Excel导入导出时的内存溢出问题Excel操作是管理系统逃不掉的功课。项目里需要导出入库台账、质检记录还要提供模板让仓管员批量导入基础库位数据。刚开始用Apache POI直接把整个工作簿读进内存数据量一大就报OutOfMemoryError。后来换成EasyExcel阿里开源的它底层用SAX模式解析一行一行处理不会把整个文件加载到内存导出用分批写盘方式。这里有个经验POI导出时默认单元格样式、字体等对象占用内存很厉害尽量复用CellStyle对象不要每个单元格都新建。还有一个小坑某次导入模板是xlsx格式但仓管员把文件后缀改成xls保存POI按老格式解析直接报错。我在导入前做了格式嗅探用文件头判断真实格式而不看后缀名这个问题就解决了。6.4 懒加载与序列化导致的报错项目里实体类之间有关联关系比如到货单关联合同对象我用的是MyBatis-Plus的关联查询手动SQL联表没有依赖JPA的懒加载所以这一块问题不大。但后来加了一个功能让批次信息关联质检单用到了MyBatis的association配置产生了懒加载代理对象。这个对象直接转JSON时Jackson序列化会报错提示无法实例化懒加载代理。解决办法是统一使用VO/DTO实体类不直接返回给前端在Service里把需要的数据装配成自定义的Response对象再交给Controller返回。这样不仅绕过了懒加载序列化问题还避免把数据库的冗余字段暴露给前端。虽然写DTO会多花一点时间但这是Java后端的一个长期受益的设计习惯。6.5 时间字段的坑LocalDateTime与前端格式项目所有时间字段统一用LocalDateTime前端组件用的是Element Plus的日期时间选择器。联调阶段发现一个问题后端返回的时间格式是“2025-06-17T09:30:00”前端直接显示很难看。需要统一配置Jackson的序列化格式spring.jackson.date-formatyyyy-MM-dd HH:mm:ss spring.jackson.time-zoneGMT8另外一个更隐蔽的坑是时区服务器部署在CentOS默认时区是UTC数据库写入时间会比北京时间早8小时。我用的是MySQL连接参数里加serverTimezoneAsia/Shanghai服务器上又把时区调整成Asia/Shanghai双保险避免了“时间突然少了8小时”的灵异事件。6.6 初始化数据与数据库版本管理开发阶段改表结构改得频繁几个人协同时经常出现“你本地数据库有这列我这边报错”的情况。我后来引入了Flyway做数据库版本管理。每改一次表结构写一个V开头的SQL脚本应用启动时自动执行增量脚本。这样所有人的库结构保持同步生产环境升级也不用手工执行SQL了部署脚本减少一多半。基础数据也要处理好。粮食企业的品名、质检项目、库位编码在系统运行初期就需要预置我写了一个DataInitializer类在启动时检查字典表是否为空为空则自动插入初始数据。注意这个类要加Profile({dev,prod})限制不要在单元测试时乱初始化。结束前说几句真心话这个系统从需求调研到正式上线前后花了三个多月。中间改过无数次需求最大的一次是采购部提出要支持“一票多车”的结算模式把整个结算模块重新设计了一遍。如果让我给后来者一个建议就是在动手写代码之前一定先花足够时间把业务流程图和数据流转图画清楚。很多项目最后返工不是因为技术难而是因为一开始就不理解业务。还有一个小技巧想分享做这类行业管理系统代码之外一定要留出时间给用户做培训和操作手册。建金粮贸的仓管员平均年龄偏大刚开始很不习惯用系统我把过磅、入库做成了大按钮、少填写的极简界面还把常用操作做成了一页纸的图文说明。系统好不好用很多时候不取决于功能多少而取决于界面是否贴近他们的操作习惯。这个项目后续还可以扩展的方向不少对接地磅硬件自动采集重量、接入RFID做批次识别、给下游客户开一个迷你查询端实时查看订单状态。如果你正在做类似的行业供应链系统希望这篇复盘能帮你少踩几个坑。
