稚一说实话，这类“SpringBoot+Vue 前后端分离管理平台”项目，这几年在毕设和课设里的出现频率非常高，社区疫情返乡管控系统又是其中天然带有完整业务闭环的一种。它不像商城、博客那样千篇一律，业务场景非常明确：返乡人员要申报信息，社区工作人员要审核，管理员要汇总和跟踪。作为一个平时会带几个项目、也帮人看过不少源码的开发者，我想把这个项目从架构选型、数据库设计、核心接口到前后端联调的真实过程拆开讲一遍，重点说清楚哪些地方容易踩坑，哪些细节在答辩时能加分。这不是一份只会复制粘贴的教程，而是一篇从需求出发的实战拆解。
1. 为什么要选 SpringBoot + Vue 这个组合
1.1 三个组件的分工与优势
先把最基础的问题说明白：SpringBoot、Vue、MySQL 在这个项目里分别扮演什么角色。SpringBoot 负责接收前端请求，处理业务逻辑，读写数据库，最后把数据以 JSON 格式返回给前端。它最大的优势是省事，内置了 Tomcat，不用像老式 Spring 项目那样写一堆 XML 配置，一条 main 方法就能把服务跑起来。这对做毕设和入门学习的同学尤其友好，因为你不需要在环境搭建上消耗太多精力，可以把时间留给核心业务。
Vue 负责页面部分，核心价值是组件化。登录页、申报表单、审核列表、统计看板都可以拆成独立组件，数据和视图之间是双向绑定的，页面表单里输入什么，数据对象里马上就有，减少了大量操作 DOM 的琐碎代码。前端通过 axios 向后端发 HTTP 请求拿到数据，再把数据渲染到表格和图表中。Vue 生态里的 Element UI 或 Element Plus 组件库，又能直接提供现成的表格、表单、弹窗和分页组件，做管理后台的效率是传统 JSP 页面完全没法比的。
MySQL 在这里就是那个“账本”，所有账号、社区信息、返乡申报、健康上报、审核日志都存在里面。这类管理系统的核心其实是数据的增删改查，MySQL 的逻辑简单直接，SQL 也直观，配合可视化工具能很快看到数据全貌，很适合作为前后端项目的起步数据库。
1.2 前后端分离到底“分离”了什么
很多初学者会把前后端分离理解成“前端一个项目，后端一个项目，两个文件夹”，这只是最表面的现象。真正的分离，是开发职责和部署方式的分离。后端团队只写接口，不关心页面长什么样；前端团队只调接口，不关心 SQL 怎么写。两边通过一份接口文档或者自动生成的接口描述来协作。
在这个返乡管控系统里，典型的前后端交互流程是：用户登录时，前端把账号密码发送给后端的 /api/auth/login 接口，后端校验通过后返回一个 Token 字符串，前端把 Token 存到本地，之后所有请求都在请求头带上它。后端收到请求先验证 Token 是否有效，有效才放行。这个过程本身就是“分离”后的标准玩法。毕设答辩时，如果你能把这条链路讲清楚，老师基本会认为你是真做过项目的人，而不是只贴了代码。
1.3 为什么这套技术栈适合毕设和课设
选择技术栈不能只看“火不火”，要看它和你的目标合不合适。社区疫情返乡管控系统这种业务，本质上是一个典型的管理信息系统，核心功能是表单填报、状态流转、数据查询和统计，不涉及到高并发、大数据量、复杂算法。SpringBoot 加 MySQL 处理这种场景绰绰有余，代码写起来简单，出现问题时也容易排查。
Vue 的学习曲线也比较平稳，会了 HTML、CSS、JavaScript 的基础后，上手 Vue 的模板语法并不难。就算遇到不会的组件用法，官方文档和社区案例都非常多，几乎你能搜到的每个报错都有人遇到过。这套组合的包容性很强：后端可以只写 Controller、Service、Mapper 三层，前端可以从 Vue CLI 起步，整体项目结构清晰，工作量可控，不会出现“做到一半做不下去”的情况。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 需求拆解与整体设计思路
2.1 角色权限模型必须先定
管理平台最忌讳上来就写代码，角色都没想清楚，后面所有功能都是白做。我建议先把系统里的角色定义成三类：系统管理员、社区工作人员、返乡申报人员。为什么是三类？因为返乡管控的业务参与方就这么清晰，多了容易乱，少了又没法体现权限区分价值。
系统管理员负责最顶层的管理，可以看到所有社区的数据，拥有用户管理、社区管理、数据统计、系统配置这些权限。社区工作人员是中间的审核者，他们只能看到自己所在社区范围内的申报数据，负责审核申报信息、监督健康上报、查看本社区的进度统计。返乡申报人员是数据的来源，能提交申报、修改个人信息、填写每日健康状况、查看自己的审核状态和处理结果。
这里有一个很关键的设计点：权限不只是区分“能不能看某个菜单”，还要区分“能看哪些数据”。社区工作人员都能进审核页面，但 A 社区的工作人员不应该看到 B 社区的数据。所以用户的表里最好存一个 community_id 字段，所有查询都要带社区过滤条件。答辩的时候老师很喜欢追问数据权限的问题，如果你能主动提到这一点，会非常加分。
2.2 业务闭环是如何流动的
返乡管控系统的核心不是单个功能，而是多个功能串联成的一条业务闭环。我把它拆成四步：
第一步，返乡人员在登录后填写返乡申报表单，内容包括姓名、手机号、来源地、返乡时间、交通方式、健康状态等，提交后生成一条状态为“待审核”的记录。第二步，社区工作人员在待办列表中看到这条记录，核对信息后选择“通过”或“驳回”。通过后，申报记录变成“已通过”，同时系统自动创建一条健康跟踪记录。第三步，返乡人员每天填写健康上报，报告体温、是否出现症状、是否有异常接触等信息。第四步，管理员在统计看板中看到各社区的返乡人数、审核通过率、每日上报率等汇总数据。
这个流程看起来简单，但每一条状态变化都要考虑业务规则。比如“待审核”的记录能不能被申报人自己撤销？撤销之后的状态要不要写日志？“已通过”的健康跟踪阶段，漏报几天应该怎么提示？如果这些规则没有提前设计，代码写着写着就会自相矛盾。
2.3 数据库表设计要留有余地
数据库是这类系统最不能敷衍的部分。我见过太多毕设项目把所有信息堆在一张表里，后面加个需求就得改表结构，非常痛苦。合理的分表方式可以参考下面这套设计：
首先是一张社区表 community，用来维护社区基础信息，字段包括社区名称、地址、联系电话。第二张是用户表 user，除了账号密码，还要有真实姓名、手机号、角色、所属社区 ID、状态字段。密码一定不要存明文，建议使用 BCrypt 加密存储，这是安全性最基本的要求，也是项目亮点。
第三张是返乡申报表 declaration，核心字段包括用户 ID、社区 ID、来源地、交通方式、预计到达时间、健康状态、审核状态、审核人、审核时间、备注。这里的状态字段我建议用数字或短字符串，比如 0 表示草稿，1 表示待审核，2 表示通过，3 表示驳回，后面写代码时用常量去判断，比直接写中文要清晰得多。
第四张是健康上报表 health_report，记录用户 ID、关联的申报 ID、上报日期、体温、是否有症状、症状描述、是否有异常接触史。第五张是审核日志表 audit_log，记录申报 ID、操作人 ID、操作前状态、操作后状态、审核意见、操作时间。很多人会忽略日志表，其实它是整个系统里最体现工程素养的部分，有了它就能回答“这条数据是谁在什么时候改成这样的”这个问题。
最后是简单的通知表或者消息表，用于存放系统提示，比如“您的申报已通过审核”。需要注意的是，所有涉及时间的字段都建议用 datetime 类型，并统一存数据库服务器时间，前后端之间传输时使用统一的时间格式，否则联调阶段一定会出现时间差八小时的问题。
3. 实操过程：核心环节怎么落地
3.1 后端工程搭建
创建一个 SpringBoot 项目并不复杂，但依赖选择上要有明确的目的性。社区疫情返乡管控系统我用的是 Java 8 或 11 加 SpringBoot 2.x 的组合，因为稳定且教程最多。核心依赖包括 Spring Web、MyBatis-Plus、MySQL 驱动、Lombok，以及用于生成和校验 Token 的 JWT 工具库。
application.yml 里有一个重点关注项：数据库连接配置。这是我排查过无数次的坑点，建议连接串里明确指定 serverTimezone=Asia/Shanghai 和编码参数，否则 MySQL 8 以上版本经常会出现时间不对或中文乱码问题。MyBatis-Plus 的配置也不要忽略，尤其是逻辑删除和驼峰命名映射，才能保证查询结果里的 create_time 能自动映射成 createTime 字段。
后端代码我习惯分为三层：Controller 层只做参数接收和响应封装，Service 层写业务规则，Mapper 层对接数据库。Controller 里不写任何 SQL，Service 里不出现 HTTP 相关的对象。这样分层的好处是，答辩时你能够清晰地告诉老师每一段代码的职责是什么，代码可读性也远远高于把所有逻辑堆在一个类里的写法。
3.2 统一返回体与异常处理
前后端分离项目中，如果没有统一的返回结构，前端处理数据会非常痛苦。我之前见过某个项目，登录成功返回的是 {code:200, data:{token:"..."}}，查询接口又返回数组，报错时返回字符串，前端代码里到处是 if (typeof res === 'string') 这种判断，越写越乱。
所以我一上来就会定义一个统一的返回类 Result<T>，包含三个字段：code、message、data。正常请求返回 code 200，业务失败返回 code 500，登录失效返回 code 401，前端 axios 拦截器统一判断 code，不是 200 就弹提示然后跳转登录页。再配一个全局异常处理器 @RestControllerAdvice，把所有异常统一转换成 Result 结构。这样前端只需要一套处理逻辑，不管是参数校验失败、数据库异常还是空指针，返回格式永远一致。
3.3 JWT 登录认证怎么实现
登录认证是这类系统里躲不开的环节，也是最容易让初学者困惑的部分。简单来说，JWT 就是一段包含用户信息的加密字符串，登录成功后由后端生成，前端保存，之后每次请求带着它，后端验证是合法的才允许访问接口。
具体实现上，我用到的是 JJWT 库，登录成功后把用户 ID、用户名、角色这些信息放进 Token，并设置一个过期时间，比如 24 小时。后端写一个拦截器，在请求进入 Controller 之前先检查请求头里的 Token，如果解析失败或过期，直接返回 401，不会进入业务代码。角色的权限判断也可以在拦截器里做，但更灵活的方式是配合 Spring Security，只是用了 Spring Security 之后项目复杂度会明显上升。对于课设和大多数毕设来说，手写拦截器已经足够，而且更容易讲清楚原理。
这里要提醒一句：不要让前端拿着用户名去查询用户信息来判断登录状态，那样任何人都可以改用户名伪装成管理员。一切以 Token 里的信息为准，前端传过来的用户 ID 只能作为当前用户的参考，真正需要校验的数据要从 Token 中解析。
3.4 返乡申报与审核接口设计
核心接口无非是几个：新增申报、查询申报列表、审核申报、健康上报、统计汇总。以“新增申报”为例，接口路径建议设计成 POST /api/declaration，接收前端传来的表单数据，在 Service 层完成以下操作：
第一步，从 Token 中解析出当前用户 ID，顺手校验这个用户是否存在并且处于正常状态。第二步，将表单数据组装成 declaration 实体，状态设置为“待审核”，社区 ID 从用户表里关联出来，而不是让前端自己传，避免用户恶意选择其他社区。第三步，插入申报记录，然后写入一条操作日志。整个操作在一个事务里，任何一个环节失败都会回滚，保证数据一致性。
“审核接口”稍微复杂一点，需要校验当前操作人是不是该社区的审核人员，再检查这条申报记录当前状态是否为“待审核”。如果已经是“已通过”，就不能重复审核。通过后要把健康上报的初始记录生成出来，并给申报用户生成一条消息通知。这种跨表操作一定要记得加 @Transactional 事务注解，否则中途失败会造成数据不一致。
查询列表接口建议直接用 MyBatis-Plus 的分页插件，只需要传入当前页码、每页大小和筛选条件，就可以返回一个包含总记录数、列表数据的完整分页对象。筛选条件包括状态、社区 ID、申报时间段、关键词等，注意这些字段都要做空值判断，避免拼出错误 SQL。
3.5 前端页面与接口对接
前端项目我建议用 Vue CLI 或 Vite 创建，引入 Element UI 或 Element Plus 作为 UI 组件库。项目内部的基础结构包括：router 目录放路由配置，api 目录放所有后端接口调用，views 目录放页面组件，store 目录放全局状态管理。
axios 封装是前端联调中最值得花时间的部分。请求拦截器里统一加上 Authorization 请求头，从本地存储读取 Token；响应拦截器里统一处理 HTTP 200 但业务 code 非 200 的情况，统一弹出错误提示。如果碰到 401，就清除本地用户信息并跳转登录页。这样每个页面里写请求只需要关心成功拿到数据后怎么渲染，不用重复写错误处理。
登录页面拿到 Token 后，要立刻去调用一次“获取当前用户信息”的接口，把用户名、角色、社区 ID 存到全局状态里，再根据角色动态生成菜单。管理员看到全部菜单，社区工作人员看到审核和健康上报相关菜单，普通返乡人员只能看到自己的申报入口和上报入口。
申报列表页直接用 el-table 渲染，加上 el-pagination 分页组件，切页时重新请求数据。审核操作通过弹窗确认，调审核接口后刷新当前列表。统计页可以用 ECharts 画柱状图或者折线图，这些图表数据都来自后端统计接口，前端只负责把返回的 JSON 转成图表的 data 格式。
4. 前后端联调阶段最容易踩的坑
4.1 日期格式和时区问题
联调阶段排在第一位的坑就是日期格式。后端默认返回的是 ISO 格式字符串，有时候还会因为 Jackson 配置变成时间戳，前端表格里显示一长串数字，或者直接显示 Invalid Date。解决方案很直接，在项目里配置一个全局的日期格式化。具体可以在 application.yml 里配置 spring.jackson.date-format=yyyy-MM-dd HH:mm:ss，同时设置 time-zone=GMT+8，保证后端返回给前端的时间已经是可读字符串。
反过来，前端传日期给后端时也要统一格式。比如申报表单里的“预计到达时间”，前端日期选择器默认输出的是一个标准日期字符串，如果后端接收的是 LocalDateTime 类型，建议在接口入参上使用 @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")，或者在全局配置里统一处理。否则很容易出现“接口 500，前端还不报错”的情况，最后通过日志才能发现是类型转换失败。
4.2 跨域问题
前后端分离项目如果在不同端口运行，比如前端 8080，后端 9090，浏览器默认会拦截跨域请求。很多初学者第一次遇到这个问题，直接把代码甩到网上求助，其实解决办法很简单：后端加一个全局 CORS 配置类，允许指定来源的请求，并允许携带 Authorization 请求头。要注意的是，allowCredentials(true) 时不能同时设置为通配符 * 的允许来源，否则浏览器还是会拦截，这个细节特别容易被忽略。
更省心的方法是把前后端部署到同一个网关域名下，通过路径前缀转发。比如前端访问 /api 时由 Nginx 转发到后端服务，这样浏览器视角里根本不存在跨域问题。但对于本地开发调试来说，后端直接配置 CORS 是最快的方案。
4.3 MyBatis-Plus 分页插件失效
这个坑非常典型：明明在 Mapper 层用了 Page 参数，数据却全量返回，或者分页结果里的 total 永远是 0。原因大概率是 MyBatis-Plus 的分页插件没有装配进 MyBatis 的拦截器链。MyBatis-Plus 3.x 以后需要自己写一个 MybatisPlusInterceptor Bean，并且在拦截器里添加 PaginationInnerInterceptor。如果直接照抄别人配置但却漏了这一步，分页查询就会变成普通查询。
还有一个相关问题是，多表关联查询时如果返回的是自定义 DTO，而不是实体类，分页插件也能正常工作，但需要保证 Page 对象是第一个参数，并且返回值用 IPage 接收。这些细节不复杂，但出错后看日志往往不太明显，只能一处处比对代码。
4.4 前端路由模式导致的刷新白屏
我在项目里用 Vue Router 的 history 模式时，经常出现这样一个问题：本地打开首页没问题，点菜单跳转也没问题，但一刷新当前页面就变成 404 或者白屏。原因很简单，dev 开发服务器或者生产环境的静态服务器没有配置“任何未匹配到的路径都回退到 index.html”的规则。解决方法是开发环境用 hash 模式，地址栏会多个 #，不美观但稳；生产环境用 history 模式，则一定要在部署的 Web 服务器上配置 try_files。如果只是跑毕设或课设演示，直接用 hash 模式最省心，永远不会出现刷新白屏问题。
4.5 演示和答辩时的准备工作
代码写完了，能不能顺利演示是另一回事。我见过不少同学在答辩前一晚发现测试数据不够，或者演示账号登录不了。要避免这种尴尬，我建议准备一份初始化 SQL 脚本，里面必须包含三个角色的演示账号，以及两到三条处于不同审核状态的申报记录，一条待审核，一条已通过，一条已驳回，分别放在不同社区下。演示的时候讲述顺序就固定为：登录管理员账号查看统计看板，切换到社区账号处理待审核数据，再切换成普通用户提交健康上报。一条线走下来，所有核心功能都覆盖了。
代码结构方面，建议在项目根目录写一个清爽的 README，包含项目简介、技术栈、数据库导入方法、启动步骤和演示账号。很多时候老师不一定会在现场仔细看代码，但一定会看文档是否规范。数据库设计文档如果有的话，也建议单独放一份。
5. 后续可以怎么扩展
5.1 增加导入导出功能
管理系统里导出申报名单是很常见的需求，可以用 EasyExcel 或 POI 实现。写一个 GET /api/declaration/export 接口，后端查询条件组装成 Excel 数据流，前端点击按钮后下载文件。实现起来有两个注意点：第一是导出数据量大的时候不要直接在 Controller 里查全表，要分批查询或者限制一次导出的数据范围；第二是日期列要设置 Excel 的日期格式，否则导出后会变成一串数字。
5.2 接入消息通知
现在系统里的消息通知只是写进了一张表，前端登录后轮询新消息。更好的方案是接 WebSocket，后端在审核操作完成时主动推送消息给用户，前端页面不用刷新就能收到提醒。虽然会增加一些代码量，但这块如果能在答辩时演示出来，效果会非常惊艳，而且原理也比较容易说清楚。
5.3 数据大屏与图表可视化
返乡申报系统非常适合做可视化页面，比如各社区待审核数量地图、每日申报量趋势图、健康上报率雷达图。使用 ECharts 实现并不复杂，后端把统计接口的数据结构设计好，前端把 option 配置好就行。可视化页面可以作为首页，登录管理员账号后第一眼就能看到整体情况，比普通表格列表更有说服力。
5.4 我最后想说的经验
写了这么多，最后分享一点我个人在实际接触这类源码后的体会。很多同学拿到一套项目源码后，第一反应是先跑起来，然后到处点点点，看到功能能用就觉得万事大吉。但真正有收获的做法是先看数据库表，再看状态字段是从哪里开始、到哪里结束的，最后才能理解代码为什么长成这个样子。我在调试这类项目时踩过最深的一个坑是：审核通过后，申报人又通过表单修改了来源地，结果统计数据出现前后不一致。后来我统一加了一条约束，已审核的数据不允许直接修改，必须先走撤销或变更流程，并且变更记录全部写入日志表。这套思路不只是为了应付毕业设计，放到真实的管理系统里也是同样的道理。希望这篇拆解能让你不只是把代码跑起来，而是真正理解它为什么这样设计。