做物资捐赠和分配系统这个选题，本身就是在啃一块硬骨头。业务逻辑不复杂，但牵扯的角色多、状态多、线下场景杂，稍不注意就会做成一个“能跑但没人愿意用”的演示品。我用SpringBoot从零搭了一版，把捐赠登记、库存管理、分配出库、物资追踪这几条主线全部串通，源码和设计文档都整理好了。这篇文章把我整个设计思路、核心实现和踩过的坑一次性讲清楚，给准备做类似管理系统的朋友一个可以直接参考的底子。
1. 项目整体设计与思路拆解
1.1 业务本质：这不是一个CRUD系统，而是一个协同管理平台
很多人拿到“物资捐赠和分配系统”这个需求，第一反应就是做几个表：物资表、捐赠记录表、分配记录表，然后套上SpringBoot的增删改查就完事了。这种做法做完以后大概率会被打回重做，因为真实场景下的物资管理，核心痛点根本不在“登记”上，而在供需匹配和流向透明这两个地方。
我设计的这套系统，从一开始就明确了四个核心角色：捐赠方（个人或企业）、受赠方（需求单位）、仓库管理员（物资进出）、系统管理员（全局配置与监督）。四类角色看到的界面、操作的流程、关注的数据完全不同，这就决定了不能用一个简单的权限标记打天下，而是要在业务模块划分上就拉开层次。
整个系统我拆成了六大模块：捐赠管理、物资库存、分配管理、运输跟踪、统计报表、系统管理。其中统计报表看似是附属功能，实际在真实使用中是使用频率最高的模块，各级管理者都需要通过数据来了解物资是否真的流向了最需要的地方。
1.2 设计取舍：为什么选择单系统整合而非微服务
技术选型时有不少人建议我拆成微服务，把捐赠、库存、物流分开部署。我的判断是：这个场景不需要。物资捐赠系统的并发量、数据量都远未达到需要分布式架构的程度，而微服务带来的事务一致性、服务间调用、部署复杂度，对这个体量的项目完全是负担。
我选择的是单体应用+模块化代码结构。对外是一个SpringBoot应用，对内用清晰的包结构把捐赠、库存、分配、统计等模块隔离好，未来如果某个模块真的要独立部署，代码层面已经具备了拆分的基础，但现阶段不需要额外付出运维成本。
举一个具体例子：分配物资时，需要同时扣减库存、生成分配单、记录物资流向明细。这三件事在单体应用里就是一个事务，@Transactional注解就能保证原子性。如果拆成三个微服务，就需要分布式事务方案，引入消息队列或Seata，对一个小团队来说运维成本和复杂度都是成倍上升的。
1.3 权限模型：RBAC的精细化落地
这套系统的权限设计我采用了RBAC（基于角色的访问控制）模型，但在标准RBAC基础上做了两处针对业务场景的定制。
第一处是数据范围的控制。普通的RBAC只控制“能不能访问这个接口”，但物资系统还需要控制“能看哪些数据”。比如仓管员只能看到自己仓库的库存，而不能看到其他区域的库存；受赠单位只能看到分配给自己的物资及状态，不应该看到全局的物资储备信息。我在查询层统一封装了数据权限过滤器，根据当前登录用户的角色和所属机构，自动追加查询条件，避免了在每一个Service方法里手动拼接权限逻辑的繁琐。
第二处是审批流的嵌入。物资分配不是仓库管理员一个人说了算的。我设计了“申请-审批-出库-确认”的四步流程：受赠方提交物资申请，管理员审核申请的合理性和库存余量，审批通过后生成出库任务，仓管员执行出库，受赠方最终确认收货。这个流程用一张状态机表来控制，每个节点都有对应的状态码和操作权限校验，保证了每一步操作都有据可查。
2. 核心技术实现与数据库设计
2.1 数据库设计：六张核心表如何支撑业务闭环
数据库是整个系统的地基，我前前后后改了四版设计，最终沉淀下来的核心表结构有六张。这里我把关键字段和设计意图直接列出来，你可以对照着自己建表。
第一张是物资表（material）。基础字段包括物资名称、类别、单位（件/箱/吨）、规格型号，但真正关键的是三个扩展字段：库存总量、可用库存、锁定库存。这三个字段的设计值得细说。库存总量就是实际仓库里的数量，锁定库存是已经被分配单占用但还没实际出库的数量，可用库存就是总量减去锁定。为什么要拆这么细？因为分配单生成之后到仓管员实际出库之间有一个时间差，如果不做锁定，两个审批员可能同时把最后一批物资分配给不同单位，超卖问题就出现了。
第二张是捐赠单表（donation_order）。每个捐赠单有单号、捐赠方信息、捐赠物资明细（通过子表实现一对多）、状态（待入库/已入库/已上架）。捐赠物资到达仓库后，仓管员要做入库确认，此时系统会自动为对应物资增加库存，同时生成一条入库流水。这里有一个细节：捐赠单上必须记录有效期，尤其是食品、药品类物资，我加了临期预警功能，效期不足30天的物资在分配时会被优先匹配，避免物资过期浪费。
第三张是分配单表（allocation_order）。这是业务流转的核心单据，包含申请单位、申请物资及数量、审批状态、出库状态、收货确认状态。每次分配操作会联动产生两条流水：一条是物资出库流水（减少可用库存），一条是分配明细流水（记录给了谁、给了多少）。
第四张是单位表（organization），统一维护捐赠方和受赠方的信息。这里我把企业和个人都抽象成“单位”来处理，个人捐赠者可以视为一个特殊的单位主体，字段上做兼容就行。受赠单位需要维护联系人和联系电话，方便物流环节的对接。
第五张是系统用户表（sys_user）。关联单位表和角色表，实现“用户-角色-权限”的标准RBAC链路。用户表里我预留了机构ID字段，用于数据权限的过滤。
最后是操作日志表（operation_log）。这个表容易被忽略，但实际运行中非常重要。所有关键操作（入库、出库、审批、修改库存）都写入日志，配合Spring的AOP机制实现，不侵入业务代码。审计追踪在物资管理场景里不是可选项，而是刚需。出了问题，通过日志能准确还原每一步操作的操作人、时间和内容。
2.2 库存扣减的并发安全方案
库存操作是这个系统里最需要严谨对待的地方。一开始我直接用UPDATE material SET available = available - #{num} WHERE available >= #{num}这样的条件更新语句来扣减库存，依靠数据库的行锁机制保证并发安全。后来在高并发测试中发现一个隐患：如果同一时刻大量分配单都在操作同一个物资，数据库的行锁竞争会造成部分请求等待超时。
最终我采用的方案是乐观锁+事务重试的组合策略。在物资表上增加一个version字段，每次扣减库存时先查出当前版本号，更新时带上WHERE version = #{oldVersion}，如果更新影响行数为0，说明数据被其他事务修改了，就重新查询并重试，最多重试三次。这个方案的好处是读操作完全无锁，写操作的冲突概率在物资管理场景下很低，重试三次基本不会出现失败。
还有一个容易踩坑的点：库存扣减和分配单生成必须是同一个事务。否则就会出现分配单生成了，但库存没扣减成功，实际库存和系统数据对不上的情况。我在AllocationService的createAllocation方法上加了一个事务注解，方法内部先检查库存、再生成分配单、最后扣减库存，任何一步异常都会整体回滚。
2.3 报表模块：用聚合查询替代跑批任务
统计报表如果按传统的“每天凌晨跑批生成数据表”来做，会面临一个时效性问题：管理者下午想看的报表，数据却是早上8点的，体验很差。我调研了使用场景后发现，物资系统的数据量完全撑得起实时统计，没必要定时跑批。
我直接在SQL层面写聚合查询，用GROUP BY加时间维度来统计日报、周报、月报数据。比如要统计“过去30天各类物资的入库/出库趋势”，一条SQL就能解决，查询耗时才几十毫秒。配合SpringBoot的@Cacheable缓存机制，把高频查询的结果缓存起来，设置5分钟的过期时间，既保证了时效性，又减轻了数据库压力。
报表模块我觉得最有价值的是供需匹配分析。通过对比同类别物资的入库总量和分配出库总量，计算出供需缺口，在首页仪表盘上直观展示哪些物资紧缺、哪些物资积压。这个功能在真实救灾场景里非常实用，帮助管理者动态调整物资募集方向，避免出现“帐篷堆成山，棉被却不够发”的尴尬局面。
3. 实操过程与核心环节实现
3.1 项目搭建与依赖配置
整个项目基于SpringBoot 2.7.x版本，JDK选用1.8，数据库使用MySQL 8.0，ORM框架选择了MyBatis-Plus而不是原生MyBatis。理由很简单：MyBatis-Plus提供的基础CRUD方法能省掉大量重复的XML编写工作，而业务需要的复杂动态查询，它也支持用QueryWrapper以Java代码的方式构建，配置同样灵活。前端我没有采用前后端分离架构，而是用Thymeleaf模板引擎做服务端渲染，这对于中小型管理系统来说开发效率最高，不需要额外搭建前端工程和联调接口。
核心依赖在pom.xml里就是几个关键组件，我贴一下主要配置：
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.1</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.33</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies>Spring Security的引入可能有人觉得重了，但对于管理系统来说，安全框架是标配。我用它实现了登录认证、密码加密（BCrypt）、会话管理。配置上做了一些自定义：登录接口放行，其余接口全部要求认证；静态资源放行；自定义UserDetailsService从用户表加载用户信息和角色权限。
3.2 核心业务流程的前后端衔接
我挑两个核心场景讲一下完整的数据流转过程，这部分是理解和二次开发这个系统的钥匙。
场景一：捐赠物资入库
捐赠方在前端页面填写捐赠登记表，提交后生成一张待入库状态的捐赠单。仓管员登录系统后，在待入库列表中看到这张单子，点击“入库确认”，进入入库操作页面。页面展示捐赠单的物资明细，仓管员核对实物无误后，填写实收数量（有可能捐赠100箱实际到货只有98箱），提交入库。
后端的逻辑是这样的：入库确认接口首先校验捐赠单状态必须是“待入库”，防止重复入库。然后遍历物资明细，对每项物资执行库存增加操作，同时写一条入库流水记录。全部处理成功后，把捐赠单状态置为“已入库”，并调用AOP记录操作日志。整个方法被@Transactional包裹，处理过程中任何一项物资失败了，所有操作都会回滚，不会出现“入库单状态更新了但库存没加”的情况。
场景二：物资分配与出库
受赠单位在系统里提交物资申请单，填写需要的物资种类、数量和用途说明。管理员在审批列表中看到申请，点击查看详情，系统会实时显示当前库存余量供管理员参考。审批通过后，系统自动生成分配单，并将对应数量的物资锁定。
仓管员在出库任务列表中看到待出库的分配单，执行出库操作。出库成功后，系统将锁定库存转为实际扣减，更新分配单状态为“已出库”。受赠方在系统里做“收货确认”，整个分配流程闭环，状态更新为“已完成”。每个状态变更的节点，系统都会尝试推送通知给相关方，包括站内消息和邮件通知。
3.3 代码实现要点：Service层的职责划分与事务边界
代码层面的架构我保持了经典的Controller-Service-Mapper三层结构。在Service层，严格遵守一个核心原则：事务从Service方法开始，不在Controller层做业务操作。举例来说，生成分配单的方法内部包含查库存、验权限、生成单号、插入分配单、扣库存、记录日志六个步骤。这些步骤必须在一个事务里完成，所以它们都在同一个createAllocation方法内。
在Service层内部，我还做了一个领域对象的划分。DonationDomainService负责捐赠领域逻辑，AllocationDomainService负责分配领域逻辑，InventoryDomainService负责库存的增减和冻结解冻操作。这样做的好处是，当分配逻辑里需要扣库存时，调用的是InventoryDomainService的公开方法，而不是直接操作Mapper。领域服务之间的调用边界清晰，未来调整库存规则时，不需要去改分配模块的代码。
我分享一个我觉得整套设计里比较巧妙的地方：分配单号的生成。单号格式是“AP + 年月日 + 四位随机数”，例如AP202501150032。为什么不直接用数据库自增ID？因为分配单号会出现在物流单据和对外沟通中，自增ID既容易暴露业务量，又不好记忆和核对。我在代码里写了一个单号生成器，使用Redis的INCR命令保证同一天内的序列号不重复，即使未来部署多实例也不会撞号。
3.4 前端页面的实用化设计
前端部分我没有做过多的花哨效果，主要精力花在了操作效率上。三个页面我花的时间最多。
第一个是物资入库操作页。这个页面要支持一次处理多个物资条目，每行有物资选择器、数量输入框、有效期输入框。如果用原生HTML写，表单校验和动态增删行会非常繁琐，我用了少量的JavaScript封装，实现了新增行、删除行、数量联动校验（实收数量不能大于申报数量）。
第二个是库存总览页。这个页面默认展示所有物资的库存列表，支持按类别筛选、按名称搜索、按库存余量排序。每一行都配了独立的操作按钮：入库、分配、查看流水。因为这个页面是仓管员和高频使用者每天打开次数最多的页面，我把所有常用操作的入口都聚合到了一起，尽量让用户在一个页面内完成大部分工作。
第三个是分配审批页。审批页不仅要展示申请单的基本信息和物资明细，还要并排显示库存余量参考。我特意做成双栏布局：左边是申请信息，右边是当前库存快照。审批人不需要离开当前页面就能完成库存核对，审批效率明显提升。这里我用了Thymeleaf的模板片段功能，把库存信息列表做成一个独立片段，在审批页通过th:replace引入，同时这个片段也能被其他页面复用。
4. 常见问题与排查技巧实录
4.1 环境与部署阶段的经典报错
先说你一上来就可能遇到的坑。用java -jar方式部署后，很多新手会发现上传的文件或者生成的日志不知道存到哪里了，于是习惯在代码里写绝对路径，比如/root/upload/或者D:\upload\。这个做法我强烈建议戒掉。我把上传路径和日志路径统一配置在application.yml里，用${upload.path}这样的占位符引用。部署时通过--spring.config.additional-location外部指定配置文件，这样代码和环境就完全解耦了。
环境阶段比较常见的一个问题是Spring版本与JDK版本不兼容。SpringBoot 2.7.x默认依赖的Spring Framework 5.3.x在JDK 8到JDK 17上都能跑，但如果你用了JDK 17以上还要注意一些反射相关的警告。很多人遇到“项目启动直接失败，日志一堆ClassNotFound”的情况，十有八九是明明项目指定了JDK 8，IDEA里Project SDK和Module SDK没同步改，编译用的还是高版本JDK。我的排查习惯是：先看maven-compiler-plugin的source和target配置，再核对IDEA的Project Structure，不要一上来就怀疑依赖冲突。
还有一个高发问题是MySQL连接报Public Key Retrieval is not allowed。这是MySQL 8.0以上的连接安全机制导致的，解决方案是在JDBC连接串上增加allowPublicKeyRetrieval=true&useSSL=false。这类配置小坑属于“网上答案很多但当时就是找不到”，你看到了就顺手记一下。
4.2 并发场景下库存数据不一致的实战排查
库存数据不一致是我遇到的最棘手问题之一。具体表现是：分配单明明生成了，但过了几分钟库存数量“回弹”了，好像扣减没生效。这个现象在低并发测试时不会出现，一旦用JMeter并发跑库存扣减接口，复现率就会显著提高。
排查过程我是这样走的。第一步，查看MySQL的隔离级别，确认是不是默认的REPEATABLE READ。第二步，查看事务日志，确认分配接口的事务确实提交了。第三步，给库存扣减的SQL加上FOR UPDATE行锁，重新压测，发现问题仍然偶发。第四步，我把事务日志和SQL日志联合起来看，终于发现问题所在：虽然扣库存的UPDATE语句执行了，但事务并没有立即提交，另一个事务在这个间隙读取到了旧库存，生成了超卖分配单。
最终修复方案就是我前面说的乐观锁加重试。我在扣减SQL里加上了version判断条件，执行UPDATE时返回影响行数，如果返回值是0就抛出冲突异常，由上层捕获后重新执行整个分配流程。这个方法改动量不大，但对并发安全性的提升是决定性的。实测压测1000并发分配请求，库存超卖数为0，成功率99.9%。
4.3 让系统真正稳定运行的几个习惯
这套系统正式上线运行后，我复盘了一些做得对的和本可以避免的习惯。给大家几个我认为价值最高的建议。
日志规范这件事值得从第一天就做好。很多项目上线后出了问题，排查困难是因为日志里没有任何关键业务节点的记录。我在Service层的核心方法里都加了日志输出，包括入参、关键判断、操作结果，日志级别统一，格式里带上操作人ID和单号。遇到问题，一条链路从头看到尾，定位一台服务器、一个操作、一个时间点，逻辑非常顺畅。
数据库连接池参数值得单独调一下。SpringBoot默认的HikariCP配置偏保守，默认最大连接数是10。在物资管理系统这种“用户不多但操作频繁”的场景，10个连接很可能会成为瓶颈。我调成了最大连接数20，最小空闲5，连接超时30秒。这个调整非常见效，压测时数据库连接等待的情况几乎消失。
最后一点，任何库存相关的操作一定要做库存流水的对账机制。我写了一个对账定时任务，每天凌晨检查库存表的数据是否等于初始库存加所有入库流水减所有出库流水。不一致时自动告警，定位到具体的差异物资和对应的出入库记录。这套对账机制挽救过我一次因为手动改数据库导致的数据错乱，强烈推荐你也在系统里做一个。
4.4 二次开发和扩展的三个方向
如果你拿到这套系统想继续扩展，我根据实际使用经验提供三个我认为最有价值的方向。
第一个是引入消息通知渠道。当前系统的消息通知只有站内信，实际使用中发现物资到达、审批通过这类信息如果通过短信或微信模板消息触达，效率会高得多。SpringBoot整合阿里云短信或者微信公众平台的模板消息都很成熟，建议在通知模块上做扩展。
第二个是条形码/二维码的应用。每一批物资入库后可以生成唯一的二维码标签，仓管员出库时用扫码枪直接扫描物资二维码，系统自动匹配物资和数量，替代手动录入。这能大幅降低出入库的操作时间，也能减少人为录入错误。市面上的安卓扫码枪本质上就是一个蓝牙扫码枪加一个接收程序，和后端对接的方式是暴露一个HTTP接口。
第三个是数据分析维度的深化。当前系统已经有供需匹配分析，未来可以接入地理信息，在MAP上展示各区域物资储备量和分配流向，管理人员一屏掌握全局。这个扩展需要引入地图组件，后端接口只需要提供经纬度、区域内物资汇总数据。
我个人在带这个项目的过程中最深的体会是：物资系统的技术难点不在某个单独的技术点上，而在如何把库存、单据、权限、流程这些零散的东西拼成一个严丝合缝的整体。每加一个功能，都要想清楚它会不会影响库存数据的准确性、会不会绕过审批流程。代码写得稳妥一点、日志打得完善一点、事务边界划得清晰一点，这个系统就能稳定地为一线人员提供支撑。这一版源码和文档我已经整理好了，需要的可以直接拿去作为基础，结合自己的业务场景做二次开发。
，微信公众号搜一搜云智变 ai)
