SpringBoot+SSM合同管理系统实战：从数据库设计到权限控制

1. 合同管理系统凭什么成为Java毕设和企业的"双料宠儿"

如果你在CSDN、GitHub或者各类技术社区混过一阵，大概率会发现"基于SpringBoot的合同信息管理系统"这类项目几乎成了Java方向的标配选题。做毕设的选它，因为难度适中、模块清晰、展示效果好；企业里也在用，因为稍微改改就能当内部工具有。我自己带过好几个类似项目，从学生作业到公司内部的管理后台都有涉及，对这个题目可以说是相当熟悉了。

先说清楚这套系统的定位：基于Java + SpringBoot + SSM（Spring + SpringMVC + MyBatis）框架搭建的合同信息管理平台，核心目标是解决企业合同资料分散、状态难追踪、到期无提醒、统计靠Excel的痛点。功能上覆盖合同录入、审批流转、签订登记、履行跟踪、变更记录、到期提醒、附件存档、多角色权限控制、统计分析等全流程。对刚接触JavaWeb开发的同学来说，它是理解SSM分层架构和SpringBoot自动配置的一个很好的载体；对在职开发来说，它又是一个可以直接落地的管理类系统样板。

很多同学拿到这个题目，第一反应是"合同管理不就是增删改查吗？"真正动手之后才发现，增删改查只是冰山一角。合同管理系统最核心的难点不在CRUD，而在于状态流转的设计——一份合同从草稿、待审批、审批通过、履行中、已完结到作废，每个状态的迁移规则是什么？谁有权限触发迁移？迁移后要记录什么日志？这些业务规则一旦理不清，代码写得再漂亮也是空中楼阁。

所以这篇博文不打算给你平铺直叙地截图讲页面，而是从需求分析、技术选型、数据库设计、核心功能实现、权限设计到踩坑实录，把这类系统从零到一的开发思路完整梳理一遍。无论你是拿它做毕业设计，还是想在企业内部搭建一个轻量合规的合同管理系统，都能从中找到可以直接"抄"的方案。

2. 技术选型不能只看"流行"：SpringBoot+SSM的正确打开方式

2.1 先澄清一个常见误区：SpringBoot和SSM不是二选一

很多初学者把SpringBoot和SSM当成两条相反的路线，动不动就问"用SpringBoot还是SSM？"这是理解上的偏差。SSM指的是Spring + SpringMVC + MyBatis这三件套的组合，而SpringBoot本质上是Spring体系的快速配置工具，它默认帮你整合了SpringMVC，同时通过自动配置让MyBatis的集成变得极其简单。

所以"SpringBoot+SSM"这个说法，准确的表述其实是：以SpringBoot作为项目骨架，SpringBoot内部使用SpringMVC处理Web请求，用MyBatis作为持久层框架操作数据库。说白了，SpringBoot负责"把项目搭起来"，SSM负责"具体怎么干活"。我见过不少同学在项目描述里写"基于SpringBoot+SSM"，答辩时被老师问这两者什么关系，支支吾吾答不上来，这是很掉分的点，建议你先把这个逻辑想透。

2.2 为什么用MyBatis而不是JPA

在Java持久层框架的选型上，MyBatis和JPA（Hibernate）常年被人拿来对比。合同管理系统这类业务，我推荐MyBatis，理由很实在：

• 合同相关的查询条件非常复杂且组合多变：按合同编号、甲方名称、乙方名称、合同类型、签订时间区间、金额区间、状态——这些条件经常会任意组合出现。MyBatis的<where>标签配合动态SQL，处理这种多条件检索非常顺手，而JPA用Specification或QueryDSL虽然也能做，但写起来理解成本更高。
• 合同明细表的字段很多（几十个字段不夸张），涉及多表联查、汇总统计、报表查询时，MyBatis直接写SQL的方式更直观，SQL调优时也更好控制。
• 对毕设场景来说，MyBatis的XML文件和Mapper接口的分工非常清晰，代码review和答辩讲解都更方便。

当然JPA也有它的优势，比如开发速度极快、表结构自动生成、对象关系映射省心。但合同系统里那些带着业务逻辑的复杂查询，很多时候不是用ORM"映射"出来的，而是需要你明确知道SQL到底怎么走索引。MyBatis把SQL主动权还给开发者，这点在项目落地阶段非常重要。

2.3 环境版本的建议

SpringBoot版本选择上，如果从零起一个新项目，建议用SpringBoot 2.5.x或2.7.x系列，不要一上来就追最新版。原因很实际：网上能查到的资料、大多数第三方starter的兼容版本、以及你后来可能用到的分页插件、代码生成器等工具，对2.x系列的适配度是最高的。SpringBoot 3.x虽然已经出来很久，但它基于Jakarta EE规范，很多老教程和工具链还停留在javax命名空间，用起来会白白吃掉大量排查时间。

配套环境给一套我实测过很多次的版本组合：

这里想多说一句：前端到底用Thymeleaf模板渲染还是Vue写前后端分离，决定了项目的形态和你的工作量。如果目标是快速交付、结构清晰、答辩时能讲明白，Thymeleaf + Vue单页嵌入的方式非常讨巧——不用单独起前端服务，后端Controller直接返回视图，页面里局部用Vue做交互。如果想练手前后端分离、为找工作做技术积累，那就老老实实拆成SpringBoot后端API + Vue前端工程。我的建议是：除非你对前端已经很熟练，否则毕设阶段别搞复杂的工程化Vue项目，Thymeleaf足以展示系统能"跑起来"。

3. 数据库建模：合同状态机是灵魂，别只会建表存字段

3.1 核心表的划分思路

很多人拿到需求后第一件事就是建一张合同表，把字段一股脑塞进去。真这么干的话，你会在后续开发中不停被"维护麻烦、查询混乱、统计困难"打脸。合理的做法是按业务域拆表，我通常会把合同系统拆成这几类核心表：

• 合同主表（contract）：合同编号、合同名称、合同类型、甲方ID、乙方名称、合同金额（总金额、已付金额、未付金额）、签订日期、生效日期、到期日期、状态、创建人、审批人等。合同主表是最核心的，但绝对不要把附件路径、审批历史直接塞在这里，否则会越来越臃肿。
• 合同明细表（contract_item）：当一份合同下有多条标的物或分期交付计划时使用。比如一份采购合同，可能包含设备A、设备B、服务C，每个标的物金额不同、交付时间不同，丢在主表里会破坏数据的一致性，就必须拆出明细表。
• 附件表（contract_attachment）：合同扫描件、PDF、验收单、付款凭证等。附件不建议直接存大字段，而是存文件路径或OSS的URL，数据库里只记录attach_name、attach_path、upload_time、uploader等元信息。
• 审批记录表（approval_record）：记录合同从提交到审批完成的每一步——谁提交的、谁审批的、审批结果是同意还是驳回、审批意见是什么、什么时间点的。这张表是合同管理系统的"黑匣子"，出了问题回头看流程全靠它。
• 变更记录表（contract_change_record）：合同在中途被修改（金额调整、日期顺延、条款补充）时，不能直接update原记录，而是留下变更历史和变更前后的对比信息。做合规管理时这条很重要。

3.2 状态机设计：让合同状态"有规矩地流动"

合同状态是整个系统里最容易被轻视、却是业务灵魂的东西。我推荐的合同状态集合是：草稿→待审批→审批通过→履行中→已完结，另有旁路状态：审批驳回、已作废。这些状态之间不是任意跳转的，比如一份"已完结"的合同，不允许直接改成"待审批"；"已作废"的合同也不能重新激活。

这里强烈建议在代码中引入状态模式或至少用一张状态流转映射表来控制迁移，而不是在Service里散落一堆if-else。简单做法是这样：

public enum ContractStatus { DRAFT("草稿", 0), PENDING_APPROVAL("待审批", 1), APPROVED("审批通过", 2), IN_PROGRESS("履行中", 3), COMPLETED("已完结", 4), REJECTED("审批驳回", 5), VOID("已作废", 6); private final String label; private final int code; // 定义允许的流转路径 private static final Map<ContractStatus, Set<ContractStatus>> TRANSITIONS = new EnumMap<>(ContractStatus.class); static { TRANSITIONS.put(DRAFT, EnumSet.of(PENDING_APPROVAL, VOID)); TRANSITIONS.put(PENDING_APPROVAL, EnumSet.of(APPROVED, REJECTED)); TRANSITIONS.put(APPROVED, EnumSet.of(IN_PROGRESS, VOID)); TRANSITIONS.put(IN_PROGRESS, EnumSet.of(COMPLETED, VOID)); TRANSITIONS.put(REJECTED, EnumSet.of(DRAFT, VOID)); TRANSITIONS.put(COMPLETED, EnumSet.noneOf(ContractStatus.class)); TRANSITIONS.put(VOID, EnumSet.noneOf(ContractStatus.class)); } public boolean canTransitionTo(ContractStatus target) { return TRANSITIONS.get(this).contains(target); } }

这样设计的好处是，所有状态迁移规则集中在一处，而不是散落在各个Service方法里。你写"提交审批"、"审批通过"、"合同作废"这些操作时，只要统一调用contractStatus.canTransitionTo(targetStatus)做前置校验，业务非法操作天然被拦截，不需要在十几个方法里重复判断。

3.3 金额字段要用Decimal，别用Float

合同金额涉及财务数据，精度要求极高。Java的float和double在二进制浮点下会有精度丢失，0.1+0.2都能算出0.30000000000000004，放合同金额里是要出大事的。数据库端用DECIMAL(18,2)，Java实体用BigDecimal。只有这种组合才能保证金额计算（比如应付金额汇总、付款比例校验）准确无误。

我曾经见过一个项目用double存合同金额，跑统计报表时总金额莫名多出一分钱，排查了一整天最后发现是浮点精度问题，教训相当惨痛。做合同系统，这类问题属于"不问则已、一问就崩"的暗雷，最好从第一版就用对类型。

3.4 附件存储：本地好还是OSS好

附件处理是合同系统绕不开的一环。廉价的方案是存服务器本地路径，然后把相对路径写进数据库；更规范的方案是接阿里云OSS或腾讯云COS。毕设或内网小系统，本地路径足够了，但要注意几点：

• 不要存绝对路径。服务器上换个目录部署，所有附件引用就全部失效。存相对路径，比如/uploads/contract/2025/xx.pdf，部署时把整个uploads目录随应用一起迁移就行。
• 文件名要重命名。用户上传的原始文件名可能是"最终版合同(1)(2).pdf"，带空格带括号，直接存服务器容易出乱码和路径解析问题。用UUID.randomUUID()生成新文件名，原始文件名单独存字段保留。
• 上传文件做类型和大小校验。只允许pdf/jpg/png等白名单类型，大小限制在20MB以内，避免恶意上传大文件打爆磁盘。

4. 核心功能模块：从合同录入到统计报表的完整闭环

4.1 合同录入与数据校验：不合理的合同提交不出去

合同录入是系统数据的入口，这个口子把不严，后面全是脏数据。我的做法是前端做一层基础校验（必填项、格式、日期先后关系），后端再做一层严格校验——后端校验是底线，前端校验可以被绕过，后端不行。

后端校验至少覆盖这几个维度：

• 必填项：合同名称、甲方乙方、签订日期、生效日期、到期日期、合同类型、合同金额，缺一不可。
• 业务规则校验：生效日期不能早于签订日期，到期日期不能晚于生效日期，已付金额不能大于合同总金额。这类规则用javax.validation的注解表达不了，需要单独写业务校验方法。
• 唯一性校验：合同编号必须唯一。最好加唯一索引兜底，防止并发提交时两张相同编号的合同入库。

日期上还有一个很坑的细节：页面里用户选的日期是字符串"2025-06-01"，后端拿到后转成LocalDate或Date，但传到数据库时要明确时区。如果前后端用了多种日期类型的组合，很容易出现"本地时间正常、数据库里差8小时"的诡异问题。这个后面踩坑章节再展开。

4.2 审批流实现：从简单if-else到轻量流程引擎

合同审批是这类系统最有"业务感"的模块。公司内部使用的话，审批路径通常不复杂：提交人 → 直属主管 → 法务/财务会签 → 总经理终审。但学生项目里如果每个审批人都要写一个方法，代码会非常冗余。

我建议用一个统一的审批Service处理，而不是给每个角色单独写接口：

@Service public class ContractApprovalService { @Autowired private ApprovalRecordMapper approvalRecordMapper; @Transactional public ApprovalResult submitForApproval(Long contractId, Long submitterId) { Contract contract = contractMapper.selectById(contractId); // 1. 状态校验：只有草稿状态才能提交审批 if (!contract.getStatus().canTransitionTo(ContractStatus.PENDING_APPROVAL)) { throw new BusinessException("当前状态不允许提交审批"); } // 2. 数据完整性校验：合同要素不完整不允许进入审批流 validateContractBeforeSubmit(contract); // 3. 更新合同状态 contract.setStatus(ContractStatus.PENDING_APPROVAL); contractMapper.updateStatus(contract); // 4. 写审批记录 approvalRecordMapper.insert(new ApprovalRecord( contractId, submitterId, null, "submit", "提交审批", new Date() )); return ApprovalResult.success(); } @Transactional public ApprovalResult approve(Long contractId, Long approverId, String comment, boolean isApproved) { // 状态校验 -> 更新合同状态 -> 写审批记录 // isApproved为true时合同进入APPROVED，否则进入REJECTED并回退到DRAFT } }

关键点有两个：第一，所有变更动作都必须在事务里完成，状态更新和审批记录写入要同生共死，不允许出现"状态改了但记录没写"的情况；第二，审批记录要记录"提交"“通过”“驳回”每种动作的类型，方便以后重放整个审批链路。对于更复杂的多级审批，可以引入Activiti或Flowable流程引擎，但对于合同管理这个体量，手写状态机加统一审批Service完全够用，而且比引入重型工作流引擎更容易向别人讲清楚。

4.3 到期提醒：定时任务不是随便一个Scheduled就完事

合同到期提醒是这类系统最实用的功能之一，也是答辩时的加分项。实际场景你需要提醒三类事件：合同到期前30天提醒、付款到期日提醒、续签窗口期提醒。

SpringBoot里最简单的实现是@Scheduled注解定时扫描：

@Component public class ContractReminderTask { @Autowired private ContractMapper contractMapper; @Autowired private NotificationService notificationService; // 每天凌晨1点执行一次 @Scheduled(cron = "0 0 1 * * ?") public void scanExpiringContracts() { Date thirtyDaysLater = DateUtils.addDays(new Date(), 30); List<Contract> contracts = contractMapper.selectByExpiryDateBetween(new Date(), thirtyDaysLater); for (Contract contract : contracts) { notificationService.sendReminder(contract); } } }

但这里有个非常大的坑：@Scheduled默认是单线程串行执行的，如果这个方法执行时间过长（比如一次性扫描出上千条待提醒合同、逐个发短信），下一次执行会被阻塞。解决方案是加@Async把发送通知的耗时段落丢进线程池，或者用Spring的TaskScheduler自定义线程池。另外，生产环境如果有多个应用实例部署，所有实例都会执行同一份定时任务，导致重复提醒——这种场景就需要引入分布式锁（基于数据库行锁或Redis），毕设阶段用单实例部署没这个问题，但概念上你得有数。

提醒方式上，最简单的是系统站内信（往通知表插记录，用户登录后红点提示），进阶一点接邮件或短信。我建议至少做站内信+邮件双通道，因为合同负责人很可能不会每天都登录系统，但邮件大概率会看。

4.4 统计报表：给管理者的经营视角

如果合同系统只做登记和审批，它的价值就打折了。真正让管理层觉得"这系统有用"的，是统计报表。常见的维度有：

• 合同金额按月度/季度汇总：结合MySQL的DATE_FORMAT函数按月份分组，统计各月新签合同金额。
• 合同状态分布：饼图展示草稿、审批中、履行中、已完结、已作废的占比。
• 到期合同清单：按到期日期倒序排列未来60天/90天内到期的合同，方便提前安排续签或终止。
• 按业务员维度的合同绩效统计：谁签得多、谁的合同金额高、谁的合同履约率好。

后端实现时，MyBatis写汇总SQL是常规操作：

<select id="countByMonth" resultType="map"> SELECT DATE_FORMAT(sign_date, '%Y-%m') AS month, COUNT(*) AS cnt, SUM(contract_amount) AS totalAmount FROM contract WHERE status IN ('APPROVED', 'IN_PROGRESS', 'COMPLETED') GROUP BY DATE_FORMAT(sign_date, '%Y-%m') ORDER BY month DESC </select>

前端图表推荐用Apache ECharts，支持Vue和原生js，文档丰富，效果也漂亮。别自己用Canvas从头画图表，那是给自己找罪受。

5. 权限与多角色工作流：让该看的人看到，让不该改的人改不了

5.1 RBAC模型落地

合同管理系统天然需要多角色权限：系统管理员负责用户和系统配置；合同专员负责录入和维护合同；审批人（部门主管、法务、财务、总经理）负责审批流转；普通业务员只能看到自己创建或与自己相关的合同；领导层看全部数据。

推荐的标准做法是RBAC（基于角色的访问控制）模型，三张核心表：用户表（user）、角色表（role）、权限表（permission），以及用户-角色关联表和角色-权限关联表。SpringBoot生态里可以引入Spring Security或Shiro做认证和授权，但对于大多数合同管理项目，手写拦截器+自定义注解已经能覆盖需求，而且更容易理解。

一个实用的做法是自定义@RequirePermission注解，拦截器里统一校验：

@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface RequirePermission { String value(); }

在Controller方法上加注解：

@PostMapping("/contract") @RequirePermission("contract:add") public Result addContract(@RequestBody ContractDTO dto) { ... }

拦截器里拿当前登录用户的角色去查权限集合，没有匹配权限直接返回403。这套方案轻量、直观、工作量小，能让答辩老师一眼看懂你的权限控制逻辑。如果你想在简历上写Spring Security，那也可以集成，但配好用户认证、密码加密、会话管理、方法级权限这些环节至少要预留两天时间调试。

5.2 数据权限：同一角色，不同人看到的数据范围不一样

角色权限解决"能做什么"，数据权限解决"看到哪些"。在合同系统里，普通业务员不希望看到公司所有合同，所以查询列表时要做数据范围过滤。最简单的策略：

• 合同表增加create_user_id字段。
• 普通角色查询时强制拼上WHERE create_user_id = 当前用户ID。
• 管理角色或领导角色不加这个过滤，可以看到全部数据。
• 合同专员经过特殊授权可以看所有"履行中"合同但不一定能编辑别人的合同。

实现时可以在MyBatis的SQL里传入一个dataScope参数，也可以做一个简单的数据权限切面，在查询前自动追加过滤条件。这块做得好不好，直接决定系统能不能实际用起来，否则一个普通员工看到全公司合同金额，既不合规也不合适。

5.3 操作日志：可追溯是合同系统的底线

合同数据敏感，谁在什么时间对哪份合同做了什么操作，必须一清二楚。日志分为两类：一类是业务操作日志，就是上面说的审批记录、变更记录；一类是系统操作日志，比如登录日志、修改合同信息、下载附件等。

实现上可以用AOP切面统一记录：

@Aspect @Component public class OperationLogAspect { @Around("@annotation(operationLog)") public Object around(ProceedingJoinPoint joinPoint, OperationLog operationLog) throws Throwable { // 记录操作人、操作时间、操作类型、方法入参 // 执行目标方法 // 记录返回值或异常信息 } }

入参里如果有对象，建议转成JSON存入日志字段，但要注意字段中有文件或大数据时做好忽略。日志存数据库表即可，数据量大了再考虑归档到文件或者冷存储。可追溯这个能力，在答辩时也是个加分项，因为它体现的是"合规意识"。

6. 开发与调试中的踩坑实录：这些坑我替你走过了

6.1 MyBatis分页插件与SpringBoot版本的兼容性

我在一个项目里用PageHelper做分页，启动时一切正常，一跑带limit的查询直接报Page method does not support Mapper interface method之类的错误，排查半天才发现是PageHelper版本和SpringBoot版本不匹配导致拦截器没有正确注册。

建议直接用mybatis-plus内置的分页插件。MyBatis-Plus本身就是在MyBatis上增强的框架，分页、CRUD、代码生成都很好用，配合SpringBoot基本零配置。如果坚持用PageHelper，注意选择与SpringBoot 2.x匹配的版本（1.4.x之后统一支持）。

6.2 日期时间差8小时的问题

这个坑我踩了不下五次。合同系统里前端传"2025-06-01 00:00:00"，SpringBoot后端用@RequestBody接收时如果没配置好JSON的日期解析，直接给你变成Date(2025-06-01 08:00:00)，存到数据库变成了早上8点，页面回显又莫名变了日期。

常规配置组合是：

• 实体类字段用LocalDate或LocalDateTime，避免老旧的java.util.Date在序列化上的时区混乱。
• 统一配置Jackson的日期格式和时区：

spring.jackson.date-format=yyyy-MM-dd HH:mm:ss spring.jackson.time-zone=GMT+8

• 数据库连接串明确时区参数：jdbc:mysql://localhost:3306/contract_db?serverTimezone=Asia/Shanghai。

三者对齐后，日期乱象基本绝迹。

6.3 上传大文件时临时目录被清空

用SpringBoot内嵌Tomcat做文件上传，默认会把上传文件写入系统临时目录（Linux下是/tmp）。如果使用的是某些云服务器或精简系统，/tmp可能被定期清理，导致上传到一半报错。另外一个更实际的坑：当天第一次上传可能正常，但是服务重启后之前上传的临时文件残留，或者上传过程中磁盘被写满，都会带出莫名其妙的异常。

解决方法是配置上传临时目录的存放位置：

spring.servlet.multipart.location=/data/tmp/upload

部署前把这个目录建好并确保写权限。同时spring.servlet.multipart.max-file-size和max-request-size根据实际需求设置，合同扫描件通常比较大，建议分别设20MB和50MB。

6.4 内嵌Tomcat打包部署和独立Tomcat的差异

用SpringBoot打jar包内嵌Tomcat跑很方便，但有些学校或甲方环境要求部署到独立Tomcat的webapps下，这时候需要把打包方式改成war，还要让启动类继承SpringBootServletInitializer并重写configure方法。这个差异很小，但我在帮别人排查问题时发现，很多人卡在这一步把项目打成了jar就硬塞进Tomcat，结果404。

一句话建议：默认用jar包，确实有独立Tomcat需求时再改war，不要上来就对着教程改来改去。

7. 从能跑到能用：合同管理系统还可以往这几个方向延伸

如果你不满足于"跑通就行"，合同管理系统还有很多值得深挖的进阶方向，既能提升系统实用性，也能作为毕设的论文亮点：

• 电子签章集成：对接第三方电子签约平台（如法大大、上上签），实现合同在线签署。这块涉及实名认证、签名控件、CA证书等概念，论文素材非常丰富。
• OCR识别合同关键信息：上传合同扫描件后，用OCR技术自动识别合同编号、双方名称、金额、日期，自动填入表单。Tesseract或者现成的OCR API都能做。
• 合同要素脱敏：普通角色查看合同时，部分敏感字段（如对方身份证信息、银行账号）自动打码，完整的权限体系再加一个字段级别的控制。
• 到期提醒的多样化：站内信、邮件、短信、企业微信/钉钉机器人通知，都有SDK可以对接，做成多通道配置化系统会更专业。
• 合同履约节点管理：把合同拆成"付款节点"“交付节点”“验收节点”，每个节点独立到期提醒，这个功能在企业场景中比单纯提醒合同到期实用得多。

最后分享一点我在实际做这类项目时的体会：代码写一次很容易，但让系统真正符合业务场景，必须在动手前把所有状态流转和数据归属问题理清。合同管理系统的复杂度不在技术本身，而在于你愿不愿意花时间梳理业务规则。把状态机表画清楚、把数据权限边界定明白、把日志链路留完整，哪怕界面朴素一点，这个系统的骨架也是扎实的。往后加新功能，你会发现改起来异常顺手，因为底层的规矩已经立住了。这套思路，换到采购管理、资产管理、项目管理上一样能迁移，这也是我一直建议新手拿合同系统做练手项目的原因——它逼着你去思考"业务是怎么运转的"，而不是光顾着写SQL。