拿到“基于SpringBoot的社区健康管理系统”这个课题的同学，一开始多半会觉得它不过是一套常规的增删改查：用户登录、档案录入、公告发布，完事。但真正动手之后才会发现，光是健康档案、慢性病随访、体检记录这几块业务数据之间怎么咬合，就能卡上两三天。我最近把一个完整的社区健康管理系统从零搭到交付，源码、SQL脚本、毕业论文和远程调试都一并处理过，中间踩了不少坑，也沉淀出一套可以直接复用的做法。这篇就把整个项目从需求拆解到交付联调的链路详细讲一遍，尤其适合正在做SpringBoot毕业设计、或者想拿这类管理系统练手的人做参考。
1. 课题定位先别急着写代码：社区健康管理和医院系统根本不是一回事
1.1 先搞清楚这套系统到底在服务谁
很多同学拿到这类题目，容易直接把“健康管理”理解成“医院挂号管理系统”，于是在功能清单里塞进了排班、挂号、缴费、药房，结果越做越像HIS，业务体量却完全撑不住。
真实场景里，社区健康管理系统一般落在社区卫生服务中心、街道卫生站或者家庭医生签约服务点，核心工作不是看病，而是管人。具体来说，它要处理的是三件事：第一，建立和维护居民的健康档案，把既往病史、过敏史、家族史这些基础信息沉淀下来；第二，对高血压、糖尿病这类慢性病患者做周期性随访，记录每次随访的指标、用药和生活方式；第三，把居民每年体检的数据收进来，用规则判断是否存在异常，形成健康提醒和建议。
搞清楚这一点，系统边界就清楚了。面向的角色也不是“医生+患者”，而是“管理员/社区工作人员”“随访医护”“居民”三方。居民能看到自己的档案和随访计划，工作人员负责录入和维护数据，管理员负责账号、公告和数据统计。
1.2 功能清单怎么定，才不会被答辩老师追问卡住
我整理这套系统时，最终定下的功能边界是这样的：
| 模块 | 核心功能 | 说明 |
|---|---|---|
| 登录注册 | 账号密码登录、验证码、退出 | 居民端和管理端共用一套账号体系 |
| 居民档案管理 | 新增居民基本信息、家庭关联、档案详情 | 身份证号唯一，档案支持导出 |
| 健康档案 | 既往病史、过敏史、家族史、烟酒史维护 | 和居民一对一绑定 |
| 体检管理 | 体检记录录入、历史体检列表、指标异常预警 | 血压、血糖、BMI、血脂等 |
| 慢病随访 | 高血压/糖尿病随访记录、随访计划、逾期提醒 | 随访状态自动流转 |
| 公告管理 | 健康宣教、通知发布与查看 | 管理员发布，居民端展示 |
| 用户管理 | 用户列表、角色分配、重置密码 | 不引入过于复杂的权限框架 |
| 数据统计 | 慢病分类统计、随访完成率、年龄分布 | 用ECharts展示图表 |
这里有一个很关键的经验：毕业设计不是功能越多越好，而是每条功能都要能讲清楚“为什么设计它、数据从哪来、页面怎么操作”。与其加一个做不深的功能，不如把随访逾期提醒和健康指标预警这两个业务亮点做扎实，答辩时这两点通常是最抓眼球的。
1.3 为什么这个课题适合拿SpringBoot做
这套系统的业务复杂度卡在了一个很舒服的位置：有多表关联和状态判断，但又不至于难到做不完。它天然适合SpringBoot+MyBatis-Plus这种组合——SpringBoot负责把配置和启动流程简化掉，MyBatis-Plus把单表CRUD省掉，核心精力可以放在业务规则上。而且它的表结构非常适合用来画ER图、用例图和时序图，这些都是论文里的硬性要求。
2. 表结构设计：健康档案、随访、体检这三块数据的关联是核心中的核心
2.1 核心表清单与角色分离的思路
从第一次设计表结构开始，我就坚持一个原则：用户账号和居民档案必须分开。sys_user管登录账号、密码、角色，resident_profile管居民真实信息，通过resident_id做关联。这样设计的好处是，一个社区工作人员账号可以管理多个居民档案，而一个居民也可能同时在家庭里被登记为家庭成员，账号和业务数据解耦，后续权限细化也方便。
整个系统的核心表我整理成了下面这组：
- sys_user（用户表）：id、username、password、real_name、role、status、create_time
- resident_profile（居民档案表）：id、user_id、name、gender、birth_date、id_card、phone、address、emergency_contact、blood_type、allergy_history、create_time
- health_record（健康档案表）：id、resident_id、past_history、family_history、smoking_history、drinking_history、remark
- physical_exam（体检记录表）：id、resident_id、exam_date、height、weight、bmi、systolic、diastolic、fasting_blood_glucose、total_cholesterol、triglyceride、ecg_result、exam_org、conclusion
- chronic_followup（慢病随访表）：id、resident_id、followup_date、followup_type、disease_type、systolic、diastolic、blood_glucose、medication、drug_name、side_effect、referral、next_followup_date、status
- notice（公告表）：id、title、content、publish_time、publisher
- appointment（随访预约表）：id、resident_id、appoint_date、doctor_name、period、status
这个设计里，最核心的关联就是resident_id。物理体检和慢病随访都只挂在居民档案下，不在业务表里冗余居民姓名或身份证号，查询时再join居民表。这样做确实多写了一点点SQL，但数据一致性好了很多，改名字、改地址这类操作不会造成脏数据。
2.2 关键字段的设计细节
有几个字段当初反复权衡过，这里专门说一下。
第一个是逻辑删除。所有业务表我都加了deleted字段，默认0，删除时改为1。这么做的好处是随访记录这类数据不能物理删除，万一误删要能恢复；引出的问题是MyBatis-Plus的逻辑删除和数据库唯一索引会冲突。比如id_card在resident_profile上有唯一索引时，如果逻辑删除一条记录再插入同ID卡号的新记录，会报唯一冲突。我的处理方案是：唯一索引改成复合唯一，包含deleted字段，或者删除时把id_card加一个固定后缀。
第二个是随访状态。我用了status字段存储：0待随访、1已完成、2失访。每次创建随访计划时状态为0，录入随访结果后置为1，如果超过计划日期且仍未写结果，由查询语句动态判断为“逾期”。这种基于状态+时间戳的设计，比单独存一个is_overdue字段靠谱得多，因为逾期是随时变动的计算结果，不该落库。
第三个是日期类型。体检日期和随访日期用DATE就行，下次随访日期用DATE，但创建时间和更新时间一律用DATETIME。之前有人习惯前端传字符串，后端用String接收，排序和范围查询都会出问题。SpringBoot里我统一用LocalDateTime接收，配合Jackson的全局格式配置，避免了一堆格式坑。
2.3 核心表的DDL参考
送你一份我实际用过的居民档案表脚本，基本可以直接抄：
CREATE TABLE `resident_profile` ( `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键', `user_id` bigint(20) DEFAULT NULL COMMENT '关联用户ID，可空', `name` varchar(50) NOT NULL COMMENT '居民姓名', `gender` tinyint(1) DEFAULT '0' COMMENT '0未知 1男 2女', `birth_date` date DEFAULT NULL COMMENT '出生日期', `id_card` varchar(18) NOT NULL COMMENT '身份证号', `phone` varchar(20) DEFAULT NULL COMMENT '联系电话', `address` varchar(200) DEFAULT NULL COMMENT '现住地址', `emergency_contact` varchar(50) DEFAULT NULL COMMENT '紧急联系人', `emergency_phone` varchar(20) DEFAULT NULL COMMENT '紧急联系电话', `blood_type` varchar(10) DEFAULT NULL COMMENT '血型', `allergy_history` varchar(500) DEFAULT NULL COMMENT '过敏史', `deleted` tinyint(1) DEFAULT '0' COMMENT '逻辑删除', `create_time` datetime DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_id_card` (`id_card`, `deleted`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='居民档案表';为什么唯一索引要写成(id_card, deleted)？这就是2.2里说到的逻辑删除和唯一约束的折中做法。虽然还不能完全避免逻辑删除后重新建档的冲突，但已经能覆盖绝大多数场景。如果你想让方案更严谨，可以把删除操作改成deleted字段存时间戳，删除时写入当前毫秒时间，而不是简单的1。
2.4 体检指标为什么不做成通用KV表
我见过不少系统为了“灵活”，把体检指标设计成exam_item和exam_item_value两张表，理论上可以支持任意指标，但实际做起来非常痛苦：每个居民的体检结果变成了一堆KV行，列表页要把行转列才能展示，统计异常指标时SQL越写越复杂，答辩时也不好解释。
我的建议是：针对毕业设计规模，把常见指标（血压、血糖、BMI、血脂四项）直接建成字段，另外增加一个ext_json的JSON字段，用来存心电图描述、B超结论这些非结构化内容。MySQL从5.7开始就支持JSON类型，查询时可以用json_extract，够用又不至于设计过度。这个方案在清晰度和扩展性之间做到了平衡。
3. 技术选型和工程搭建：SpringBoot版本和MyBatis-Plus这两个决定成败
3.1 版本选择：为什么我停在SpringBoot 2.7.x
我选型时第一件事是定SpringBoot版本。网上现在有很多教程直接上3.x，但我的建议是：毕业设计老老实实用2.7.18，别盲目追新。
原因很实际。第一，国内大量教材、网课和博客写的还是javax.的包，SpringBoot 3.x换成了jakarta.，你抄代码时稍不留神就少一个import，到处都是红色的报错；第二，很多老牌工具和第三方starter对3.x的支持还在磨合，遇到反编译、静态资源处理问题，搜索到的解决方案可能还是针对2.x的；第三，毕业设计考察的是你对框架原理和业务实现的理解，不是你对新版本RESTful规范的追逐。2.7.18是2.x系列的收尾版本，稳定且资料齐全，我所有项目都以它为准。
3.2 MyBatis-Plus：把重复CRUD的体力活砍掉
持久层框架选择MyBatis-Plus，主要看中三件事：BaseMapper内置的单表增删改查、分页插件、逻辑删除注解。
如果不引入它，光是一个居民档案模块的Mapper接口加上XML就得写几十行，而且基本都是模板代码。MyBatis-Plus的LambdaQueryWrapper配合lambda表达式，查询条件读起来也直观。比如查某个居民最近的体检记录：
LambdaQueryWrapper<PhysicalExam> wrapper = new LambdaQueryWrapper<>(); wrapper.eq(PhysicalExam::getResidentId, residentId) .orderByDesc(PhysicalExam::getExamDate) .last("limit 1"); PhysicalExam latestExam = physicalExamMapper.selectOne(wrapper);这段代码意图很清晰：先按居民ID过滤，按体检日期倒序，取第一条就是最近一次体检。没有XML，没有SQL拼接，后期维护成本极低。
3.3 前端方案：Vue3+Element Plus，还是后端模板引擎
前端我选了Vue3 + Vite + Element Plus + Axios的组合。这也给Gitee上找Vue项目模板提供了很大方便，Element Plus的表格和表单组件开箱即用，做后台管理界面效率非常高。
但这里要说一个容易被忽略的点：前后端分离的项目，在本地开发和最终部署是两条路。开发时前端用Vite的代理把/api转发到SpringBoot的8080端口，解决跨域；部署时如果不想额外启一个Nginx，可以直接把Vue构建后的dist目录扔进SpringBoot的src/main/resources/static里，这样打包出的jar自带前端页面，一套Java环境就能跑起来。后续做远程调试时，这种“一个jar包跑全套”的方式会省掉很多环境问题。
具体做法也不复杂：先在前端项目根目录执行npm run build生成dist，然后把dist里的内容复制到后端static目录，顺便在application.yml里配一句：
spring: web: resources: static-locations: classpath:/static/如果Vue用了history路由，还需要在后端写一个简单的转发，把非/api的路径转发到index.html，否则刷新页面会404。
3.4 工程分包：按职责分包比按模块分包更好维护
我见过一些项目把Controller、Service、Mapper直接全堆在三个包里，业务一多就乱。我用的分包方式是先按职责切，再按模块分：
- entity：数据库实体类
- mapper：MyBatis-Plus的Mapper接口
- service / service.impl：业务接口和实现
- controller：接口层，只做参数接收和结果封装
- dto：接收前端参数对象
- vo：返回给前端的视图对象
- common：统一返回值、异常处理、常量
- config：配置类
- utils：工具类
这样的好处是，答辩时老师问“你这个登录逻辑放在哪”，你能直接说出在service.impl里的某个方法，而不是一顿翻。dto和vo分离也是加分项，前端不需要的字段比如创建时间，在vo里不暴露就行。
4. 核心业务实现：权限、档案联动、随访提醒和健康预警
4.1 登录认证与角色权限的轻量实现
这套系统的权限没有引入Spring Security或者Shiro，原因很简单：角色就三种，功能边界清晰，引入重型框架反而增加了复杂度。我用的是JWT + 拦截器 + 自定义注解的轻量方案。
用户登录成功后，后端生成一个token，里面带上userId和role，前端每次请求在Header里带上Authorization。拦截器统一校验token，解析出用户信息放到ThreadLocal里。只有管理员能调用的接口，加一个@RequireRole("ADMIN")注解，拦截器里检查角色，不匹配就返回403。
核心拦截器代码大致是这样：
public class AuthInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行登录接口 if (handler instanceof HandlerMethod) { HandlerMethod handlerMethod = (HandlerMethod) handler; RequireRole requireRole = handlerMethod.getMethodAnnotation(RequireRole.class); String token = request.getHeader("Authorization"); // 校验token...解析出role... if (requireRole != null && !requireRole.value().equals(userRole)) { throw new BusinessException(403, "无权访问"); } } return true; } }这里有个实操经验：跨域配置要用CorsRegistry统一处理，并且注意拦截器在跨域预检请求OPTIONS时要直接放行，否则前端会看到“CORS error”。这个Bug我见过太多次，排查半天最后发现是拦截器把OPTIONS请求挡了。
4.2 健康档案、体检、随访的联动逻辑
这套系统业务上最出彩的地方，是三个模块之间不是孤立的，而是有真实的联动。
第一个联动：录入体检记录时，系统自动把最新体检结果回写到居民健康档案的健康摘要字段。比如一个人最近一次体检显示血压偏高，档案首页就会显示“需要注意血压”。这样居民端打开档案就能看到最新状态，不用翻历史体检单。
第二个联动：完成一次慢病随访后，系统会根据医生在随访记录里填写的下次随访日期，自动生成一条新的随访计划，状态置为待随访。这个逻辑放在Service层，用事务控制：
@Transactional public void completeFollowup(Long followupId, FollowupCompleteDTO dto) { // 1. 更新原随访记录状态、指标、用药情况 // 2. 根据dto.nextFollowupDate生成新的随访计划 ChronicFollowup newPlan = new ChronicFollowup(); newPlan.setResidentId(existing.getResidentId()); newPlan.setFollowupDate(dto.getNextFollowupDate()); newPlan.setStatus(0); chronicFollowupMapper.insert(newPlan); }注意方法上的@Transactional必须加上，因为这里涉及到两步写操作，如果新计划插入失败，原记录更新必须回滚，否则数据就错位了。我在演示时特意讲过这个事务场景，老师听完觉得很扎实。
4.3 随访逾期提醒的计算思路
逾期提醒是社区健康管理里很有业务代表性的一个功能：系统要能在首页展示“今天该随访谁”“谁已经逾期了”。我最初的设计是把“是否逾期”当成字段存起来，每天定时任务去更新，后来发现这是典型的过度设计。
更好的做法是动态计算。在查询待随访列表时，直接用时间来算：
LocalDate today = LocalDate.now(); LambdaQueryWrapper<ChronicFollowup> wrapper = new LambdaQueryWrapper<>(); wrapper.eq(ChronicFollowup::getStatus, 0) // 未完成 .le(ChronicFollowup::getNextFollowupDate, today) // 下次随访日期早于或等于今天 .orderByAsc(ChronicFollowup::getNextFollowupDate);这样写，逾期列表永远是最新的，不需要定时任务，也不会出现“上次更新后又被手动改了日期但状态没变”的脏数据问题。这里也建议大家理解一下：能算出来的状态就不要存，能查出来的数据就不要建字段，这是后端设计里很实用的一条原则。
4.4 一个轻量级的健康预警规则引擎
健康预警是这套系统的第二个亮点。我这个“规则引擎”并不是什么复杂框架，就是策略模式加规则表。
比如体检查出血压偏高，规则是这样的：
- 收缩压大于等于140或舒张压大于等于90，预警级别为高
- 空腹血糖大于等于7.0，预警级别为高
- BMI大于等于28，预警级别为中，并提示控制体重
我做一个RuleService，每种指标对应一个规则类，全部实现统一接口。体检数据入库后，循环执行规则，把命中的结果和提示语存到体检结论里。这样新增一种疾病指标时，只要加一个Rule类，不用改动原有的入库逻辑。
这块在答辩现场很占优势，因为大多数人的毕业设计只是CRUD，而这里体现出了“规则可扩展”的设计思想。不过要注意，规则和代码不要写得过于复杂，否则你自己都讲不清楚，反而扣分。
5. 源码交付、文档配套和远程调试：系统写得再好，跑不起来等于零
5.1 交付的源码工程应该是什么样
源码交付是这个项目的重头戏。我接到过的需求里，至少一半的问题不是“功能没有”，而是“在自己的电脑上跑不起来”。所以交付源码时，我始终按一套固定标准来组织：
根目录下必须有README.md，里面写清楚三点：环境要求（JDK版本、Maven版本、MySQL版本）、启动步骤（先导入SQL再改配置再启动）、测试账号（管理员、工作人员、居民账号各一个）。application.yml里不写真实数据库密码，用占位符加说明。SQL脚本单独放一个sql目录，里面包含建库、建表、初始数据三步，允许任何人一键导入。
很多同学会忽略初始数据，这是大坑。老师拿到你的项目，打开页面发现首页是空的，第一印象就很差。我一般会准备一套演示数据：10个居民、20条体检记录、15条随访记录，覆盖“正常、待随访、已逾期、已完成”四种状态，另外还有几条异常指标数据，专门用来演示预警功能。
5.2 毕业论文和设计文档的目录组织
文档和源码是捆绑交付的，论文写得好不好，直接决定答辩成绩。我建议按这样的结构来组织：
- 摘要：写清课题背景和主要工作，300字左右，关键词4-5个
- 第一章 绪论：研究背景、国内外现状、开发意义
- 第二章 需求分析：可行性分析、功能需求、非功能需求、用例图
- 第三章 系统设计：总体架构图、功能结构图、ER图、数据库表设计
- 第四章 系统实现：按模块贴核心代码并配截图
- 第五章 系统测试：测试环境、测试用例表格、测试结果
最容易丢分的往往不是代码，而是图表。用例图至少要有三个角色各自的操作用例；ER图要覆盖居民档案、体检、随访这几张核心表；时序图重点画“新增体检记录”和“完成随访”两个流程。这些图不需要画得多精美，但必须逻辑正确、和代码对得上。
5.3 远程调试的高效姿势
“远程调试”是交付环节里最容易被低估的一部分。很多同学理解的远程调试是：让对面的人把屏幕共享给你，然后你一步步指挥他操作。这种方式效率极低，一个环境问题能折腾一小时。
我更推荐先做环境自查，再截图或录屏反馈。交付前我会给对方一份自查清单：
| 检查项 | 预期结果 | 常见问题 |
|---|---|---|
| JDK版本 | 1.8或11，64位 | 版本太低或太高 |
| Maven配置 | settings.xml指向国内镜像 | 依赖下载超时 |
| MySQL版本 | 5.7或8.0 | 8.0以上要改驱动配置 |
| SQL脚本导入 | 成功无报错 | 编码混乱、脚本重复执行 |
| 端口占用 | 8080端口空闲 | 本地项目占用同一端口 |
| 数据库账号密码 | 和application.yml一致 | 密码错误、权限不足 |
按这个清单走一遍，大多数问题在正式联调之前就暴露了。剩下真正需要远程介入的，一般是Tomcat端口占用、Redis连接失败（如果引入了的话）、Node版本和前端依赖冲突这三类。这几类都有一个共同特点：日志里已经有明确报错，只是对方不知道去哪看。所以我在调试时第一步永远是让对方面对IDEA的控制台，把红色报错的前三行截图给我，比让他复述“页面打不开”有效得多。
5.4 演示环节的黄金顺序
不管最后是录演示视频还是现场答辩，演示流程都建议固定下来：先登录，展示管理员首页的数据统计；然后进入居民档案，点开一个居民的详情，展示健康档案和体检记录；再进入随访管理，故意展示逾期列表，说明系统能自动算出逾期；最后新增一条体检记录，展示健康预警如何生效。
这套顺序的逻辑是：先展示整体面貌，再展示数据关联，再用业务亮点收尾。演示时不要一上来就点新增、弹表单，那样很无聊。把最有技术含量的“逾期提醒”和“健康预警”放在后面，作为层层递进的高潮，答辩节奏感会好很多。
6. 复盘：这版系统里我踩过的几个坑
6.1 居民信息塞进user表后拆表的教训
第一版设计图省事，把居民姓名、身份证、手机号、地址全部放进了sys_user表，跟登录账号绑在一起。做到随访模块时立刻出问题：一个工作人员的账号要关联多个居民，居民又分属不同家庭，user表里塞业务字段的后果就是表结构越来越臃肿。后来花了半天时间把resider_profile拆出来，重写SQL和Mapper，等于返工了一次。这个教训值得记住：账号体系是账号体系，业务档案是业务档案，永远不要混着建表。
6.2 Lombok版本冲突导致getter/setter失效
项目里用了Lombok，但SpringBoot 2.7版本下如果Lombok版本太低，编译能过、运行时报NoSuchMethodError，而且是找getXxx方法找不到。这种错误很隐蔽，因为代码里看起来一切正常，问题不在你的代码而在注解处理器。解决办法是把Lombok版本明确指定为1.18.30或更高，同时确认IDEA里安装了Lombok插件并且开启了annotation processing。
6.3 日期格式化导致前端展示错乱
前后端分离时，LocalDateTime默认序列化出来是一串带T的格式，比如2025-03-15T10:30:00，前端直接显示在表格里很丑。我在统一返回结构时配置了Jackson的日期格式：
spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8这个配置加完，所有接口的LocalDateTime都会按指定格式序列化。但要注意，LocalDateTime是不受date-format控制的，还需要加一个Jackson的自定义序列化器或者直接用@JsonFormat注解标注。我在体检和随访的VO字段上统一加了@JsonFormat，一步到位。
6.4 批量导入体检数据时的编码乱码
后期为了方便演示，加了一个Excel导入功能，把体检数据批量导入。一开始用EasyExcel导入，明明是正常的中文数据，导入后变成了乱码，排查了大半天发现是CSV格式文件的编码问题。Excel导出的CSV默认是ANSI编码，而项目统一用UTF-8，读进来当然乱码。最后改用EasyExcel读xlsx格式，或者在读取CSV时指定字符集为GBK，问题才解决。这种边角问题不会出现在毕业论文里，却会实打实消耗你的时间，提前避开比较好。
6.5 关于一站式交付的一些体会
这次交付的标题里写着“源码+文档+远程调试”这样的完整服务，这意味着交付的边界不只是代码，还包括对方能否独立跑通、写完论文、通过答辩。所以我在动手之前一定会先确认三件事：功能清单是否有最终版、文档格式有没有模板要求、远程调试需要覆盖到什么程度（比如是代码跑通还是论文改完）。把这些边界谈清楚，后面的效率才会高，不然很容易陷入无止境地改需求。对做毕业设计的同学来说也一样，与其追求功能数量，不如把核心链条打磨完整——毕竟真正决定成绩的，永远是你能讲清楚、能演示出来的那一部分。
这套系统我前后迭代过几次，最大的一次变化就是把居民基本信息从用户表里拆出来，单独建档案表。那次改动之后，体检、随访、档案三个模块的关联一下清晰了很多，答辩的时候讲起来也舒服多了。如果你正在做类似的社区健康类课题，我的建议是先花一个晚上把表关系画明白，再动手写Controller——磨刀真的不误砍柴工。
