去年接到一个疫情物资捐赠和分配管理系统的开发需求，技术栈明确要求是SpringBoot+Vue，Java后端，MySQL存数据，MyBatis做持久层。第一反应就是这套组合太经典了，搞过课程设计或者中小型业务系统的朋友应该都懂：SpringBoot把后端配置降到最低，Vue把页面拆成组件，MySQL管事务，MyBatis写动态SQL又灵活。但等我把需求梳理完才发现，这个系统表面看就是“捐赠登记、物资入库、分配出库、数据统计”四件事，真要做实务，远比想象中要复杂。这篇文章就把我的设计思路、数据库建模、核心实现逻辑和踩坑记录一次性讲清楚，适合正在做类似管理系统设计、准备毕业设计或者刚接触前后端分离项目的朋友直接参考。
1. 项目整体设计与思路拆解
1.1 业务需求：这不是简单的出入库系统
物资捐赠和分配系统，和普通的进销存最大区别在于：整个流程极强调“透明”和“可追溯”。捐赠方把一批物资捐过来，系统要记录是哪个捐赠方、什么品名、什么规格、多少数量、什么批次、有效期到什么时候；入库之后要能形成库存；分配侧要根据受助对象的需求生成分配单，审批通过后出库；出库后还要能看到这批物资被分配到了哪里、有没有签收、还剩多少。
所以系统核心角色至少要有三类：管理员、仓库操作员、普通用户（捐赠方/受助方都可以算进去）。管理员负责分配审批、账号管理和整体数据查看；仓库操作员负责入库、出库、盘点；普通用户能提交捐赠登记、查看自己的捐赠记录和分配情况。这样一个流程下来，才能做到每一件物资从哪儿来、到哪儿去都有据可查。
还需要考虑一个很重要的使用场景：突发公共卫生事件期间，物资种类杂、有效期敏感、捐赠方多、分配需求变动快。如果系统只支持简单的“库存总数量增减”，很快就会出现过期没人管、超发库存变负数、物资去向说不清的问题。因此设计上必须引入“批次”概念，库存一定要按批次管理，分配时优先分配临期物资，这是整个系统最关键的点。
1.2 技术选型：为什么是这套组合
技术栈上，SpringBoot + Vue + MySQL + MyBatis 放到今天依然是中小型管理系统的主力方案。SpringBoot 的好处不用多讲，内嵌Tomcat，java -jar 就能跑，省去了以前SSM那套繁琐的XML配置；MyBatis 比 JPA 更透明，复杂查询和动态条件筛选写SQL自己控制，尤其适合这类多表关联、统计报表特别多的系统；MySQL 的 InnoDB 引擎支持事务，库存模块最怕数据错乱，事务保证写入安全；Vue 的优势在于表单多、状态多，响应式数据绑定能省掉大量DOM操作，Element UI / Element Plus 这类组件库又能快速搭出后台管理界面。
有人可能会问，为什么不用 Spring Cloud 微服务？这个系统的体量根本没有到需要拆服务的程度，拆了反而要处理服务通信、分布式事务、部署复杂度，纯属给自己挖坑。为什么不用 JSP 老方案？前后端不分离，前端逻辑写起来很痛苦，而且后来要扩展小程序端、对接第三方系统都不方便。核心判断标准就是一句话：够用、稳定、可控。
2. 核心功能拆解与数据库设计
2.1 用户角色与权限设计
权限这一块我推荐用“用户表 + 角色表 + 用户角色关联表”的方式，而不是简单地在用户表里加一个 type 字段。虽然加 type 字段实现更快，但后续如果要加“审核员”“调配专员”之类的角色，改表结构就麻烦了。
基础用户表字段大致是 id、username、password、real_name、phone、status、create_time。密码必须用 BCrypt 加密存储，千万不能明文。角色表里预置 admin、operator、user 三种角色，管理员账号在初始化SQL里插入。关联表负责把用户和角色绑定，支持一个用户多角色。
控制上要做两层：第一层是前端路由守卫，根据当前用户的角色，控制能进入哪些菜单；第二层是后端拦截器，在访问敏感接口时校验角色。前端控制是为了体验，后端控制才是真正保证安全的。这部分在实现里通过自定义注解 @RequireRole 配合拦截器实现，比在每个 Controller 里写角色判断干净得多。
2.2 物资流转模型：一切围绕批次
我设计这个系统的数据库时，最核心的思路是“所有库存变动都围绕批次展开”。一个批次对应一次捐赠入库，有自己的批次号、生产日期、有效期、来源方。库存表里存的是批次级库存，而不是物资大类库存。
流程大概是：捐赠方提交捐赠单，仓库操作员核对后入库，生成或更新一个库存批次；管理员创建分配单，选择接收单位、选择物资和数量；系统自动按照“先到期先出”的规则从库存批次中扣减数量，同时记录分配明细和批次出库记录；接收方确认签收后，分配单状态改为已完成。
对应的核心表我最终确定为这些：物资表 material，捐赠单主表 donation_order、捐赠明细表 donation_item，库存批次表 stock_batch，分配单主表 allocation_order、分配明细表 allocation_item，批次出库明细表 allocation_batch_detail，物资流水日志表 stock_log。额外还有通知表、操作日志表，就不展开细讲了。
这样设计最大的好处是追溯能力强。比如某个接收单位反馈收到的方便面有质量问题，我们可以从分配明细反查是哪个批次、哪笔捐赠单、哪个捐赠方捐赠的，也能判断是否在保质期内。没有批次设计的话，这类问题根本查不清楚。
2.3 核心表结构细节说明
库存批次表是整个系统的核心，我贴一下关键字段设计：
CREATE TABLE stock_batch ( id BIGINT PRIMARY KEY AUTO_INCREMENT, batch_no VARCHAR(64) NOT NULL COMMENT '批次号', material_id BIGINT NOT NULL COMMENT '物资ID', total_quantity INT NOT NULL COMMENT '入库总数量', available_quantity INT NOT NULL COMMENT '当前可用数量', production_date DATE COMMENT '生产日期', expire_date DATE NOT NULL COMMENT '有效期', supplier VARCHAR(128) COMMENT '来源捐赠方', create_time DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_material_expire (material_id, expire_date) ) COMMENT '库存批次表';注意我特意建了 (material_id, expire_date) 联合索引，因为库存列表最常用的两个操作就是按物资查和按到期日期排序。索引加上之后，前端筛选“即将过期”的物资会快很多。
分配明细表也很关键：
CREATE TABLE allocation_item ( id BIGINT PRIMARY KEY AUTO_INCREMENT, allocation_id BIGINT NOT NULL COMMENT '分配单ID', material_id BIGINT NOT NULL COMMENT '物资ID', apply_quantity INT NOT NULL COMMENT '申请数量', actual_quantity INT NOT NULL COMMENT '实际分配数量', stock_batch_id BIGINT COMMENT '来源批次ID', create_time DATETIME DEFAULT CURRENT_TIMESTAMP ) COMMENT '分配明细表';这里把 stock_batch_id 直接放到分配明细里，简化了查询。虽然批次出库明细单独存一张表也不是不行，但考虑到系统规模不大，把来源批次和数量合在一张表里，查询分配单详情时一次 join 就能拿到所有数据，效率更高。我实际测试下来，这样设计在报表统计时确实省心。
3. 后端核心实现：SpringBoot + MyBatis
3.1 项目分层与工程结构
后端工程结构我按这样的方式组织：
src/main/java ├── com.example.donation │ ├── controller 接口层 │ ├── service 业务层 │ │ └── impl │ ├── mapper MyBatis Mapper接口 │ ├── entity 实体类 │ ├── dto 前端交互参数对象 │ ├── common 统一返回结果、异常、常量 │ ├── config 拦截器、跨域等配置 │ └── task 定时任务（库存预警）Controller 只负责参数接收和返回，业务逻辑全部放在 Service 层，Mapper 只做数据库操作。很多初学者喜欢把业务写在 Controller 里面，图省事，但后面一旦要复用或者排查问题，就会特别难受。我坚持一个原则：Controller 里绝不写 if 判断业务逻辑，一个方法只做一件事。
3.2 捐赠入库：多表写入必须同时成功
捐赠入库这个动作，后端涉及的不只是一张表：保存捐赠单主表、保存捐赠明细表、更新库存批次表、写入流水日志。这四件事，要么全部成功，要么全部失败，绝对不能出现“单子保存了但库存没加上”的情况。
实现上就是在 Service 方法上加 @Transactional：
@Transactional(rollbackFor = Exception.class) public void receiveDonation(DonationOrderDTO dto) { // 1. 保存捐赠单主表 // 2. 保存捐赠明细列表 // 3. 逐个更新或新增库存批次 // 4. 写流水日志 }这里有个细节很多人不注意：@Transactional 默认只在 RuntimeException 时回滚，如果方法抛的是 checked Exception，事务不会回滚。所以我一般都会显式写成 rollbackFor = Exception.class，宁可把所有异常都纳入回滚范围，也不要因为漏了 checked exception 导致库存数据不一致。
3.3 分配出库：如何彻底根治库存超发
库存超发是这个系统遇到的最典型并发问题。场景是这样的：两个分配单同时操作同一个批次库存，A 单要扣 100，B 单也要扣 100，库存只有 150。如果都先查库存再更新，就都会认为够扣，最后扣成负数。
正确的做法是直接在 SQL 层面做“条件更新”，把这句更新作为原子操作：
UPDATE stock_batch SET available_quantity = available_quantity - #{quantity} WHERE id = #{batchId} AND available_quantity >= #{quantity}MyBatis 中执行这条 update，通过返回的影响行数判断是否成功。如果影响行数为 0，说明库存不够，此时直接抛出业务异常，让整个分配单事务回滚。这样做最核心的好处是：数据库层面的行锁和条件判断保证了并发安全，避免了“先查后改”很容易出现的竞态问题。
我还做过一个额外的保障：分配单主表加一个 status 字段，所有更新操作都带条件 WHERE status = '待确认'，防止用户重复点击提交导致同一个分配单被处理多次。前端按钮防抖是一回事，后端状态判断才是真正的防线。
3.4 MyBatis 动态 SQL 与报表查询技巧
这个系统有大量的组合条件查询，比如库存列表要支持按物资名称模糊查、按分类筛选、按是否临期筛选，MyBatis 的<where>+<if>组合写起来非常舒服：
<select id="selectStockList" resultType="map"> SELECT m.name AS materialName, m.specification, s.batch_no, s.available_quantity, s.expire_date FROM stock_batch s JOIN material m ON s.material_id = m.id <where> <if test="keyword != null and keyword != ''"> AND m.name LIKE CONCAT('%', #{keyword}, '%') </if> <if test="expireWarning"> AND s.expire_date > NOW() AND s.expire_date < DATE_ADD(NOW(), INTERVAL 30 DAY) </if> </where> ORDER BY s.expire_date ASC </select>注意 XML 里写大于小于号一定要用转义字符><，不然 XML 解析直接报错。这个坑我见过太多人踩了。
统计报表方面，建议直接用 SQL 做聚合，不要在前端遍历 JS 数组累加。比如月度捐赠量统计，一条 GROUP BY 就能完成，前端直接拿数据渲染 ECharts 图标。SQL 聚合数据更少、传输更快，代码也更简单。
4. 前端Vue实现与交互设计
4.1 项目初始化和工具链踩坑
前端我用的 Vue CLI 创建项目，配合 Element UI 组件库（如果 Vue3 就用 Element Plus）。axios 封装一个 request.js，统一设置 baseURL、请求头、超时时间、响应拦截器，遇到 code != 200 时自动弹出错误提示。
最容易被卡住的是跨域问题。开发环境里前端跑在 localhost:8081，后端跑在 localhost:8080，ajax 直接请求后端会跨域。我推荐用开发代理去解决，而不是在后端粗暴地加 @CrossOrigin。比如 vue.config.js 里这样配：
module.exports = { devServer: { port: 8081, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } } }以后前端所有请求都走 /api 前缀，浏览器看着是同源请求，代理在中间转发到后端，本地开发完全感觉不到跨域的存在。后端的 @CrossOrigin 适合临时测试，生产环境还是用 Nginx 反向代理更稳妥。
4.2 核心页面拆解和流程状态
整个系统前端页面不多，但每个页面都有互动性。捐赠登记页用动态表格，允许用户点击“添加一行”来填写多个物资项，每一行包含物资名称、规格、数量、生产日期、有效期。动态表单实现时要注意 v-model 绑定数组里的对象字段，删除行时下标会变化，最好用唯一的行 id 而不是索引。
分配单创建页稍微复杂一点。选择接收方之后，添加物资明细时，系统要根据物资 ID 请求后端查询可用批次和可分配数量。前端拿到批次列表后展示一个批次选择下拉框，默认按有效期从早到晚排序，用户也可以手动选择具体批次。这里的前端校验一定要做：分配数量不能大于该批次的可用数量，不然请求后端也会被拒，白白浪费一次接口调用。
库存管理页面就是典型的数据表格，我加了三类状态标签：正常、临期（30天内到期）、过期。过期物资不允许再分配，列表里直接禁用分配按钮。统计页用 ECharts 展示柱状图和饼图，柱状图看每月捐赠入库量和分配出库量的对比，饼图看物资类别占比。数据全部来自后端聚合接口，前端只负责渲染。
4.3 路由守卫和权限控制的实现
路由守卫这块，我在 router/index.js 里给每个页面加了 meta.roles 配置，然后在全局前置守卫里判断：
router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (!token) { next('/login') return } const roles = JSON.parse(localStorage.getItem('roles') || '[]') if (to.meta.roles && !to.meta.roles.some(r => roles.includes(r))) { next('/403') return } next() })后端接口同样有权限拦截器，所以前端守卫应付体验，真正防止越权不能全靠它。因为 localStorage 里的 token 和 roles 本来就可以被修改，如果需求严格的话，后端接口要每次从 token 解析用户真实角色。
5. 环境搭建与部署验证
5.1 从零开始跑通这个系统
如果你拿到项目源码想先在本地跑起来，顺序很重要，我建议按下面的步骤来。
第一步装环境：JDK 1.8 或 JDK 17（看 SpringBoot 版本）、Maven 3.x、Node.js 14+、MySQL 5.7 或 8.0。这里要特别提醒一句：SpringBoot 版本和 JDK 版本必须匹配。SpringBoot 2.7.x 用 JDK8 没问题，SpringBoot 3.x 就必须 JDK17 以上，如果你本地只装了 JDK8，不建议硬上 SpringBoot 3，版本太高会遇到一堆编译问题，这就是很多人常说的“SpringBoot版本太高跑不起来”。
第二步建数据库：在 MySQL 里执行 init.sql，脚本里包含库表创建和初始管理员账号，然后修改后端 application.yml 里的数据源配置：
spring: datasource: url: jdbc:mysql://localhost:3306/donation_db?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai username: root password: your_password第三步启动后端：IDEA 里直接运行主类，或者 mvn spring-boot:run，看到 Tomcat initialized 和端口 8080 就说明启动成功。
第四步启动前端：在 frontend 目录下执行 npm install，然后 npm run serve。如果 node_modules 安装时报错，多半是 Node 版本太高导致 node-sass 不兼容，换成 sass 或者降 Node 版本能解决。前端起来后访问 localhost:8081，用管理员账号登录，系统就能用了。
5.2 MySQL 初始化脚本的几个细节
初始化脚本里要包含：建库语句（指定 utf8mb4）、建表语句、初始管理员账号插入语句。我踩过的一个坑是 MySQL 5.7 里如果表字段不指定字符集，默认可能是 latin1，中文乱码。解决方法是建库时执行：
CREATE DATABASE donation_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;另外一个常见怪问题：数据库明明写对了，启动后查询中文条件却查不到结果。检查一下 MySQL 连接 URL 后面有没有加 characterEncoding=utf8mb4，没加的话即使库表是 utf8mb4，连接层也会用错编码。另外 MySQL 8.0 的驱动类名是 com.mysql.cj.jdbc.Driver，5.7 用 com.mysql.jdbc.Driver，别搞混。
5.3 前端打包进后端，还是 Nginx 单独部署
部署方式有两种，我都试过。
第一种最简单：前端执行 npm run build，生成 dist 目录，把里面的文件拷到后端的 src/main/resources/static 下，然后后端打成 jar 包，一个 java -jar 就把前后端都带起来了。这种模式适合内部测试、课程设计演示，优点是省事。但有一个必须注意的点：前端路由要用 hash 模式（URL 带 #），不能用 history 模式，否则用户手动刷新某个子页面时，后端没有对应的路由映射，直接 404。
第二种方式更正规：Nginx 托管前端静态文件，后端单独部署。Nginx 配置里做个反向代理，把 /api 请求转发到后端服务：
server { listen 80; server_name your-domain; location / { root /opt/frontend/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; } }try_files 那行是为了解决 history 模式刷新 404 的问题。生产环境用 Nginx 的好处是不用把前端文件塞进 jar，前端可以单独更新，后端重启也不影响静态资源访问。
6. 常见问题与排查技巧实录
6.1 @Transactional 失效的几种情况
我见过太多人写事务方法发现不生效，其实原因就那么几个。第一个是同一个类内部方法自调用，比如 Service 里的 saveA 调用了本类方法 saveB，saveB 上的 @Transactional 不会生效，因为事务代理是通过外部调用才切入的，内部 this 调用绕过了代理。解决办法是把事务方法拆到另一个 Service 类里，或者注入自身代理对象。
第二个是异常被 catch 吞掉。事务方法里有 try-catch，捕获了异常但没有往外抛，事务框架感知不到异常，自然不会回滚。正确做法是 catch 到业务异常后继续抛出，或者在 catch 里手动调用 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()。
第三个是方法被 private 修饰。Spring 的声明式事务基于动态代理，private 方法根本不会被代理拦截，所以事务方法必须是 public。遇到奇怪的插入了一部分数据、后续报错但没回滚的情况，优先排查这三点。
6.2 MyBatis 映射和参数类型问题
MyBatis 用多了你就会发现，90%的报错都集中在映射文件和参数类型上。比如 XML 里写 resultType 写错了包路径，启动时不容易发现，但一调用接口就报 “Unknown column” 或 “could not set property”。我的排查习惯是：先在 Navicat 或 MySQL 命令行执行一遍那条 SQL，确认 SQL 本身没问题，再去看映射关系。
还有一个特别容易踩的细节：UPDATE 语句中如果有动态参数，参数顺序和数量要和 @Param 指定的名称完全匹配，否则 MyBatis 会报 “Parameter 'xxx' not found”。建议小于三个参数直接用 @Param 注解命名，多于三个参数用一个 DTO 对象传进去，别靠参数顺序硬扛，不然重构时真的会疯。
6.3 前后端联调时的接口字段规范问题
前后端联调最难受的不是技术问题，而是字段名对不上。后端返回 createdAt，前端要 createTime，结果页面表格每一列都是空白。我后来统一在商品详情和列表接口用驼峰命名，后端实体开启 map-underscore-to-camel-case，让数据库下划线字段自动映射到实体的驼峰属性，同时在所有返回 DTO 里保持一致。前端拿到数据后不再做字段名转换，省了大量调试时间。
统一返回结构也很重要。我的所有接口返回都是{ code: 200, message: "success", data: ... }，异常由全局异常处理器统一捕获。前端 axios 响应拦截器里看到 code 不是 200 就直接弹错误提示，业务代码里只需要关心 data，非常干净。
6.4 项目落地后的一些个人体会
这个系统做完之后，我的最大感受是：库存类系统的难点根本不在 CRUD，而在“并发正确性”和“流程状态一致性”。很多项目表面上表结构设计得挺漂亮，但一遇到高并发或者操作频繁，数据就乱了。这次真正把批次库存扣减的 SQL 条件更新方案落在项目里以后，后面再遇到秒杀扣库存、预约名额占用这类场景，我心里都有底了。
另外建议大家给系统加一张操作日志表，记录谁在什么时间做了什么操作，特别是入出库、修改库存这些敏感动作。排查线上问题的时候，操作日志比任何字段都管用。系统上线之后还可以继续扩展：库存不足时自动通知管理员、接收方在小程序端自助确认签收、对接公众号推送捐赠回执，这些都是围绕核心流程可以自然延伸的方向。这次我把需求拆解和实现过程完整记录下来，既是项目复盘，也是希望给各位一个可以直接借鉴的系统设计思路。
