Spring Boot家装项目管理系统：从需求到远程调试的完整实战

做装修公司信息化这行快十年，见过太多工地上“人盯人”的管理方式了。项目经理翻着手机找聊天记录报进度，老板想看一眼各工地资金占用情况得等财务月底拉Excel，客户三天两头问“我家装到哪一步了”却得不到准确答复——这些都是装修公司项目管理的真实痛点。所以当看到一个基于 Spring Boot 的家装项目管理系统设计题时，我觉得这是个特别贴合实际业务的毕业设计方向。这篇文章就把从需求拆解、技术选型、数据库设计到远程调试、文档撰写的完整链路讲透，给正在做同类毕设或者想用 Spring Boot 落地小团队管理系统的同学一个可以照着走的参考。

文章会覆盖这几个内容：装修公司的业务痛点到底在哪里，怎么把它们翻译成系统功能；Spring Boot 3.x 版本怎么选，MyBatis-Plus 在项目里怎么用最省心；核心表结构怎么设计才能撑得起装修项目全流程；报表统计、文件上传、前后端分离联调这些关键点怎么实现；最后重点讲远程调试的完整实操步骤，还有毕业设计文档和答辩准备那些容易忽略但特别拉分的事。

1. 先把装修公司的业务跑一遍：痛点在哪，系统就建在哪

1.1 装修项目的完整链路里，哪些环节在漏信息

不把业务理顺，做出来的系统大概率是个“登录+增删改查”的空壳。装修公司一个典型项目从获客到交付，大体走这条线：市场部获取线索、销售约谈量房、设计师出方案和报价、客户签合同交首期款、项目经理进场施工（水电、泥瓦、木工、油漆、安装）、主材进场、竣工验收、进入售后维保。

这条链路上信息流失最严重的地方，我一个个说，你对照着看就知道系统该抓哪些点。

第一，获客线索几乎都在销售个人微信里。销售离职，线索直接带走，公司没有任何沉淀。第二，设计师改了七八版方案，最终稿到底是谁的、改了哪些地方，没有版本记录。第三，工地实际进度靠项目经理口头汇报，老板想核实只能自己去现场，材料用了多少、还剩多少，没有台账。第四，增项变更没有一个规范的审批流，口头答应工人干了，结算的时候才发现预算超了，毛利率算不准。第五，客户体验差，不知道家里装到什么程度，也没人主动同步进度，投诉全积压到竣工阶段集中爆发。

1.2 从业务痛点反推功能清单，而不是从“别人系统有什么”抄功能

需求分析最忌讳的就是抄别人的菜单。正确的顺序是：先列业务痛点，再想每个痛点对应什么功能，最后才落到模块划分。

我按这个逻辑把这个家装项目管理系统的核心功能拆成这么几块：

• 客户与线索管理：记录客户来源、意向等级、跟进记录、当前状态，销售离职了客户池子还在公司手里。
• 装修项目全生命周期管理：项目从签约、开工、施工到竣工的全流程信息，包含项目编号、所属客户、设计师、项目经理、状态字段。
• 合同与预算管理：合同金额、各期付款节点和比例、预算清单（按分部工程拆项），增项变更单走审批留痕。
• 施工节点与进度管理：预设标准节点模板（水电验收、防水闭水、瓦工验收、木工验收、油漆验收、竣工验收），每个节点上报实际开始/结束时间、上传验收照片、记录验收结论。
• 材料管理：材料品牌型号、采购数量、供应商、到货情况，做到每个项目的材料有账可查。
• 数据统计看板：按项目经理、按项目状态、按月维度的项目数量/合同金额/回款统计，这些数据一出来，管理层才能做决策。

这套功能列表不是拍脑袋，每一行都能对应到前面说的业务痛点。答辩的时候如果老师问“为什么设计这个模块”，你就把痛点摆出来，比空谈“为了系统完整性”有说服力得多。

2. Spring Boot 版本选型与项目初始化：新项目为什么直接上 3.x

2.1 版本选择背后的逻辑，以及“springboot版本太高”是个什么坑

你现在新建项目，我建议直接上 Spring Boot 3.x，配套 JDK 17。理由很简单：Spring Boot 2.7 的 OSS 支持已经到期，新项目没必要从一个生命周期结束的版本起步。JDK 17 又是目前使用率最高的 LTS 版本，生态已经非常成熟。

但网上经常看到“springboot版本太高”的吐槽，这里面的坑确实存在，集中在两类问题上。

一类是包名变化。Spring Boot 3 从 Java EE 迁移到 Jakarta EE，原来javax.servlet.*全变成jakarta.servlet.*。网上大量 2.x 时代的老教程、老代码，你复制过来直接报红，因为 import 语句里的 javax 根本找不到了。解决方案就是统一替换成 jakarta，IDEA 里有批量替换功能，几分钟搞定。

另一类是 starter 依赖的兼容性。很多第三方 starter 更新有滞后，像早期版本的 mybatis-spring-boot-starter 就不兼容 Spring Boot 3。所以引入依赖时不要无脑用老版本的坐标，直接去 mvnrepository 查对应 groupId 的最新 release 版本，或者用 starter 官方文档推荐的版本号。

应对思路很简单：遇到问题先确认“是不是 Spring Boot 3 和这个库的兼容版本问题”，然后去官方文档或 mvnrepository 查最新版，别在一个老依赖上死磕。

2.2 环境准备与初始化清单，含国内源配置

初始化项目我建议用 start.spring.io 生成。网络条件允许就直接网页生成，如果访问慢，阿里云也有对应的脚手架镜像。生成时依赖这么选就够了，别贪多：

• Spring Web：提供 REST 接口能力
• MySQL Driver：数据库连接驱动，毕设标配 MySQL 8.0
• Lombok：省掉大量 getter/setter 样板代码，让代码干净很多
• Spring Data JPA 或 MyBatis：二选一。如果你对 SQL 比较熟，我更推荐 MyBatis + MyBatis-Plus 组合，后面细说

环境版本方面，我实际用下来这套组合最省心：JDK 17、Maven 3.9+、IDEA 2023 以上版本、MySQL 8.0。Maven 依赖下载慢的话，在 settings.xml 里配阿里云镜像，这一步能帮你节省大量等待时间。

2.3 MyBatis-Plus 在毕设里的价值：少写 70% 的 CRUD 样板代码

为什么毕设推荐 MyBatis-Plus 而不是纯 MyBatis？核心原因是省时间。毕业设计周期本来就不长，你不可能把所有时间花在写 BaseMapper 的 insert 和 selectById 上。MyBatis-Plus 内置了通用 Mapper 方法和 Service CRUD 封装，单表操作几乎不用自己写 XML SQL。分页插件也是内置的，配置MapperScan和分页拦截器，代码就三五行的量。

分页插件配置代码示例如下：

@Configuration @MapperScan("com.example.decoration.mapper") public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }

配好之后，查询项目列表分页就是Page<Project> page = projectMapper.selectPage(new Page<>(current, size), queryWrapper)这样的写法。逻辑删除、乐观锁插件都有内置注解，这些在答辩时都是加分项。

有一点要提醒：MyBatis-Plus 只适合单表 CRUD，一旦涉及多表关联统计，比如按项目经理分组统计合同金额这种报表，还是得老老实实写自定义 SQL。所以项目里要留 resources/mapper/xml 目录，把它当成“复杂查询专区”，项目结构从一开始就规划清楚，后面不会乱。

3. 数据模型设计：用建表逻辑把装修业务彻底讲透

3.1 核心表结构与字段设计思路

数据库设计是整个系统的大梁。梁不正，后面写多少业务代码都别扭。这个系统我规划为 9 张核心表：

• sys_user：用户表，含用户名、密码、角色、真实姓名、手机号。角色区分管理员、销售、设计师、项目经理。
• customer：客户表，含姓名、电话、意向楼盘、户型面积、意向等级、跟进状态、归属销售。手机号建普通索引，因为这是高频查询维度。
• decoration_project：装修项目表，这是全系统的中枢表。
• contract：合同表，含合同编号、项目ID、合同总金额、付款节点约定、签约日期。
• project_budget_item：项目预算明细表，按分部工程记录预算项单价和数量。
• project_node：施工节点表，预设每个项目要经历的节点，以及每个节点的计划起止时间。
• node_progress：节点进度上报表，记录实际施工起止时间、上报人、验收结果、验收照片路径。
• material_info：材料信息表，维护常用材料品牌型号。
• material_purchase：材料采购单表，关联项目、材料、供应商、数量、单价、到货状态。

3.2 中枢表 design 细节：decoration_project 字段怎么定

decoration_project表我建议这么设计，字段有讲究：

• id：主键
• project_no：项目编号，业务编号，比如 ZX202501001，展示和检索都用它
• customer_id：关联客户表
• designer_id和manager_id：分别关联 sys_user 表的设计师和项目经理。注意这里用两个外键指向同一张用户表，查询时需要用两次 join 区分别名
• contract_id：关联合同表
• project_status：项目状态，见下方状态机说明
• decoration_type：装饰类型，全包/半包/清包，不同模式下工作流有差异
• house_area：房屋面积
• budget_total：预算总额
• start_date：计划开工日期
• plan_end_date：计划竣工日期
• actual_end_date：实际竣工日期，可为空

项目经理和设计师都指向用户表这一点，建模时容易忽略。如果用户表里没有角色概念，后面权限和数据隔离就无从谈起。另外，预算总额这个字段是冗余设计，它可以从预算明细表聚合出来，但为了方便项目列表页展示和统计，直接冗余在项目表上是值得的，查询时少一次聚合计算。

3.3 施工节点表的设计：为什么它撑起进度管理

施工节点这块，难点在于每个项目的节点模板都可能不同。大平层和别墅的标准节点不一样，全包和半包的介入节点也不一样。

解决方案是节点数据在项目创建时“复制”生成。系统里维护一张工长模板表，比如node_template，里面存“通用住宅装修标准节点模板”下的节点清单：水电改造、防水闭水、瓦工贴砖、木工吊顶、油漆涂刷、主材安装、竣工预检。创建装修项目时，程序读取模板，为每个节点生成一条project_node记录，并把项目ID绑定上去。这样每个项目都有自己独立的节点实例，改一个项目不影响其他项目，实际业务也正是如此——每家的施工进度本来就独立。

project_node表关键字段：

• project_id
• node_name：节点名称
• plan_start_date、plan_end_date：计划时间，创建项目时根据工期倒排
• actual_start_date、actual_end_date：实际上报时间，项目经理在端点上报
• node_status：待开始/进行中/已完成/已逾期
• check_result：默认待验收，通过/整改

项目列表页展示“当前进度”，就是查询当前节点状态。

3.4 状态机设计：项目状态字段别裸奔

项目状态字段project_status看起来就是一个 int 或 varchar，但真正好的设计要有状态机约束。状态集合是有限的：待签约、待开工、施工中、待竣工验收、已竣工、已售后。状态跳转不是任意变更，比如“已竣工”不能跳回“施工中”，除非走整改单流程。

实现上可以用一个枚举类来集中管理状态和允许的流转，在 Service 层做校验：

public enum ProjectStatus { PENDING_SIGN("待签约"), PENDING_START("待开工"), UNDER_CONSTRUCTION("施工中"), PENDING_ACCEPT("待验收"), COMPLETED("已竣工"), AFTER_SERVICE("售后中"); private final String desc; // getter、构造方法省略 }

每次状态更新，先判断当前状态是否允许跳转到目标状态，不允许就直接抛业务异常。这套逻辑写出来，代码质量观感非常加分，答辩时完全可以作为“项目亮点”讲：“项目状态机保证了业务流程的严谨性，不会出现数据状态倒流的异常情况”。

4. 关键实现细节：统计报表、大文件上传、前后端联调

4.1 管理看板：统计 SQL 怎么写得既快又好看

统计报表是装企老板最常看的页面。三个核心指标：在建项目数、签约合同总金额、项目状态分布。数据库层面就靠聚合查询，举一个按项目经理统计的 SQL：

SELECT u.real_name AS manager_name, COUNT(p.id) AS project_count, SUM(c.contract_amount) AS total_contract_amount FROM decoration_project p LEFT JOIN sys_user u ON p.manager_id = u.id LEFT JOIN contract c ON p.contract_id = c.id WHERE p.project_status IN ('施工中', '待验收') GROUP BY u.real_name ORDER BY total_contract_amount DESC

按月统计签约走势的 SQL 稍微变一下，用DATE_FORMAT(sign_date, '%Y-%m')做分组键就行。前端展示直接接 ECharts，柱状图看项目数、折线图看合同金额，数据从/api/dashboard/managerStats这种接口返回 JSON，前端 axios 接住喂给 ECharts 就完事。

4.2 装修图纸和合同扫描件的上传方案

装修项目里涉及户型图、设计方案、效果图、合同扫描件、验收照片，这些文件类型多、单个文件不算小。处理方案是文件存储用本地磁盘目录，数据库只存相对路径，不要存 Base64 或者 byte[] 塞进数据库，不然数据库会迅速膨胀，备份和查询都会被拖慢。

Spring Boot 里配置文件上传大小限制，在 application.yml 中：

spring: servlet: multipart: max-file-size: 50MB max-request-size: 100MB

文件存储路径做成配置项，用自定义属性：

app: upload: path: /data/decoration-system/upload

上传接口接收MultipartFile，生成 UUID 文件名，保存到配置的目录下，按日期分子目录，避免单目录文件过多。文件访问通过 Spring Boot 静态资源映射暴露：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/upload/**") .addResourceHandler("file:" + uploadPath + "/"); } }

一个坑提醒：本地 Windows 开发时路径是D:/xxx，Linux 部署是/data/xxx，千万别把路径写死在代码里，一定走配置项。

4.3 Spring Boot + Vue 前后端分离联调：跨域和统一响应

热词里“springboot vue前后端分离”出现多次，说明这是目前毕设的主流形态。前后端分离后，最常见的问题就是跨域，以及前后端对接时的响应格式不统一导致的沟通成本。

后端统一响应体很有必要，定义一个Result<T>：

@Data public class Result<T> { private Integer code; private String msg; private T data; public static <T> Result<T> success(T data) { ... } public static <T> Result<T> error(String msg) { ... } }

所有 Controller 都返回Result<T>，前端拿到后先判断 code 是否为 200，再取 data。这个约定能让前后端联调效率提升很多。统一异常处理用@RestControllerAdvice，业务异常、参数校验异常、未知异常分别返回不同的 code 和 msg。

跨域问题，Spring Boot 端做一个 CORS 配置类解决，或者更优雅的方式是前端在 Vite 里配置 proxy 代理，把/api开头的请求代理到后端地址，这样前端请求路径不暴露后端端口，生产环境也不会有跨域问题。

// vite.config.js export default defineConfig({ server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } } })

5. 远程调试实战：从原理到一键断点

5.1 远程调用为什么能打断点：JDWP 协议解决的事儿

先弄清楚原理。远程调试的本质是 JVM 通过 JDWP（Java Debug Wire Protocol）协议对外开一个调试端口，本地 IDEA 连接上这个端口后，双方建立起调试会话。本地发出的断点指令、变量查看请求，远程 JVM 响应回来，看起来就像在本地打断点一样。

JDK 9 是个分水岭。之前启动调试参数是这种老写法：

-Xdebug -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n

JDK 9 以后更推荐用单参数形式：

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005

注意address=*:5005里的*:是很多踩坑帖的源头。默认情况下，JDK 9+ 的 JDWP 只监听本地回环地址，不加*:的话，云服务器外部根本连不进来。

5.2 远程启动 Spring Boot 应用的完整配置步骤

部署侧操作步骤，按顺序来：

1. 本地打包，跳过测试：

mvn clean package -DskipTests

2. 把生成的 jar 包上传到服务器，这里用scp就行：

scp target/decoration-system-0.0.1-SNAPSHOT.jar root@your_server_ip:/opt/decoration-system/

3. 远程启动时带上调试参数：

nohup java \ -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \ -jar /opt/decoration-system/decoration-system-0.0.1-SNAPSHOT.jar \ > /opt/decoration-system/app.log 2>&1 &

suspend=n表示应用照常启动，即使没有调试器连接也不阻塞。如果设成suspend=y，JVM 会在启动后挂起等待调试器接入，适合排查启动阶段的问题，但日常调试不建议，连不上整个应用就卡住了。

4. 验证端口是否监听：

netstat -tlnp | grep 5005

有输出说明调试端口已经在监听。同时记得确认云服务器的安全组已经放行 5005 端口，这是被问过最多的问题之一。

5.3 IDEA 侧配置：Remote JVM Debug 的细节

IDEA 侧操作：

1. 菜单 Run → Edit Configurations，点左上角+。
2. 选择 Remote JVM Debug（不同版本 IDEA 名字略有差异，2024 版本是 Remote Debug）。
3. Host 填服务器公网 IP，Port 填 5005。
4. 使用 IntelliJ IDEA 默认生成的 JVM 参数，确认与服务器端参数匹配。
5. 点击 Debug 按钮，IDEA Console 显示Connected to the target VM，就可以像本地调试一样打断点、看变量、步进执行了。

一个很关键的细节：本地代码必须和远程 jar 包的代码版本一致。你本地改了代码没重新打包上传，断点位置就对不上，会各种错乱。所以正确的流程是：改代码 → 打包 → 上传 → 重启远程应用 → 本地 Debug 连接。

5.4 断点不生效的排查链路（实操路线复现）

第一次远程调试时大家都会遇到断点不生效，但这个事不是玄学，按下面链路一步步查基本能定位：

• 先确认远程进程有没有带调试参数：ps -ef | grep java，看命令里是否包含agentlib:jdwp。不含的话说明旧进程没带参数，重启时加上。
• 再确认端口通不通：服务器上netstat -tlnp | grep 5005看监听，本地telnet 服务器IP 5005看能否连通。连不上一般是安全组或防火墙。
• 然后确认类有没有被加载：Spring Boot 里的 Bean 默认不是启动时全加载的，很多 Controller 是第一次请求时才被类加载器加载。先发一个请求把接口触发一次，再打断点重新 Debug，往往就能命中了。
• 最后确认代码版本：本地和远程的 class 不一致，IDEA 会提示“Source code does not match the bytecode”，遇到这个就回去重新打包上传。

这套链路走下来，99% 的远程调试问题都能解决。剩下 1% 基本是网络环境极为特殊的场景，就不在讨论范围了。

6. 毕业设计文档与答辩：源码之外的隐形门槛

6.1 带着“查重眼光”去写文档

拿到源码只是第一步，毕设文档和答辩的表现同样权重很高。常见的文档要求包含：开题报告、需求分析、系统设计、系统实现、测试、总结致谢。很多同学文档写满两千字，写得却是“本系统基于 Java 和 Spring Boot 开发，实现了……”这种空话，查重软件一过，红一片。

更聪明的写法是，把每个模块的“业务逻辑”讲清楚。比如需求分析里的系统用例，与其用大白话介绍“用户登录”“项目列表”，不如写“项目经理通过节点上报功能提交‘水电验收’节点的开始和结束时间，同时可上传现场照片，系统自动更新项目整体进度百分比”。这种带业务场景的描述方式，既能体现你真做了需求调研，又能自然降低查重重复率。

6.2 数据库设计说明书的写作技巧：从字段堆砌到设计理由

数据库设计章节千万别写成字段清单流水账。要解释“为什么这么设计”。举个例子，为什么customer表要单独建立意向等级和跟进状态字段？因为装修行业的客户转化周期长，一个客户从首次接触到签约可能跨越两个月，期间销售要多次跟进，没有意向等级和跟进状态，销售团队就无法做优先级管理。把字段和业务价值绑定，文档的层次感立刻不一样。

索引设计的写作也一样。别写“该表对id建主键索引”这种废话，要写“考虑到客户列表查询按手机号检索次数频繁，对 phone 字段建立普通索引；装饰项目列表页默认按创建时间倒序展示，对 create_time 建立索引以提升排序性能”。

6.3 答辩高频问题与参考回答思路

答辩老师大概率会围绕这几类问题发问，我列几个经典的，大家可以提前准备：

• 为什么选 Spring Boot 而不是传统的 SSM？回答重点：Spring Boot 的自动配置和 starter 机制能大幅简化项目搭建成本，内嵌 Tomcat 让部署变成 java -jar 一条命令，生态成熟，适合快速交付。
• 数据库为什么这样设计？回答重点：先说业务驱动。装修项目有完整的生命周期，所以必须有主项目表承接所有关联数据；合同金额和付款节点是财务核算的基础，所以独立成表；节点进度是客户最关心的信息，所以拆出来支持动态上报。
• 用户密码怎么存储的？回答重点：不能明文存库。Spring Security 的 BCrypt 加密存储，数据库里存的是哈希值，即使数据库泄露也不能直接反推出明文。
• 如果用户量上来了，系统瓶颈在哪？回答重点：先想再说。Java 应用层可以通过横向扩容应付，瓶颈更可能出在数据库层，单表数据量大之后查询变慢，可以考虑分库分表或引入缓存，但毕设阶段的体量其实不需要考虑这些。答出这个“分阶段考虑”的思维，比直接讲一套高大上但落不了地的方案更让老师认可。
• 系统安全性做了哪些考虑？回答重点：登录验证、密码加密、统一异常处理避免信息泄露、部署时注意关闭调试端口、文件上传做类型和大小校验防恶意上传。

答辩不是背书，核心是把“我为什么这么设计、我踩过什么坑、我怎么解决的”讲清楚，这时候远程调试的经历就是很好的素材，实话实说“部署到服务器之后发现 bug 无法复现，通过配置 JDWP 远程调试，一步步排查解决”，比任何标准答案都更能体现真实做项目的能力。

7. 定制交付前的最后一道工序：跑通全流程再交付

远程调试配好、文档写完之后，自己要把整个流程在干净环境里重新走一遍。我处理一个项目交付时，一般会在全新机器上从零部署：装 JDK、装 MySQL、导入初始化 SQL、配配置文件、启动 jar 包、跑一遍核心流程。

这个环节最常暴露几个问题：初始化脚本里有中文乱码，解决办法是在 MySQL 连接串上显式characterEncoding=utf8；配置文件里的路径写的是本机绝对路径，部署到服务器必然报错，所以在文档里专门用一个“部署说明”的独立文档把这些配置项列清楚；还有数据库连接账号权限不足，导入脚本执行失败，排查半天发现是权限没配。这些问题都有共同特征——本地永远复现不了，但换一台干净机器就爆出来。

这也是“全bao定制”里最容易被忽略的一环。交付的源码在作者电脑上跑得很欢，交接之后换个地方就起不来，往往不是代码问题，而是部署环境和配置项的问题。把这些细节处理掉，不论是自己后面往上加功能，还是帮助别人把这个项目跑起来，都会顺畅很多。

作为一个做了多年 Spring Boot 项目交付的人，我个人的体会是：这个项目的价值不只是“一个毕业设计”，它更像是一条装修行业信息化的毛细血管。如果你在准备类似题目，也给一个最后建议——先理解装修公司的业务，再写第一行代码，系统做完后，你要能把这个业务讲得像你自己家装修过一样清楚，这才算真的吃透了。