初识这个项目：社区医疗服务为什么要上小程序
这两年社区医疗的需求越来越细，居民不再满足于“能挂个号、能拿点药”，而是希望在家门口解决建档、随访、慢病管理、预约接种这类高频小事。但很多社区卫生服务中心的系统还停留在PC端，医生录完档案，居民自己看不到；居民想约个复查，得打电话或者跑一趟。我年初接手的就是这么一个场景：某社区服务中心想把手头的医疗服务搬上微信小程序，让居民在手机上完成预约、查档案、收随访提醒，同时让医生端能高效处理日常服务记录。
项目标题写的是“基于SpringBoot的社区医疗服务管理小程序的设计与开发”，说白了就是一套“后端SpringBoot + 前端微信小程序”的全栈应用。SpringBoot负责业务逻辑、数据存储、接口输出，小程序负责居民和医生的操作界面。这种组合到今天已经很成熟，但在社区医疗这个细分场景里，真正难的不是技术选型，而是把医疗服务的流程理清楚，再把流程落地成稳定、好用、医生愿意用的小程序。
这篇博文我打算把自己从需求梳理、架构设计、数据库建模、接口开发、小程序联调到上线部署的完整过程写出来。里面会包含我实际敲过的关键代码、踩过的坑、以及那些文档里不会写的经验。适合正在做类似毕业设计、中小型医疗管理系统，或者想快速上手“SpringBoot+小程序”整套开发流程的人参考。
1. 整体设计与技术选型拆解
1.1 业务场景梳理：先把“人”和“事”分清
做医疗类系统，最忌讳一上来就建表写接口。我第一周基本没写代码，天天对着社区服务中心的医生和护士聊流程。这个项目涉及的“人”一共三类：居民、社区医生、管理员。涉及的核心“事”有六类：
- 居民健康档案管理，包括基本信息、既往病史、过敏史、家族史；
- 门诊/随访预约，居民发起预约，医生确认或改期；
- 慢病随访任务，比如高血压、糖尿病患者按周期随访；
- 疫苗接种预约与提醒；
- 健康宣教内容推送；
- 统计报表，供管理员查看服务量、慢病覆盖情况。
这六件事听上去互不关联，实际上都围绕一条主线：居民健康档案。预约要关联档案，随访要读取档案，宣教要根据档案中的慢病类型定向推送。所以我后来设计系统时，把“居民”和“档案”解耦——居民表只存微信登录相关的身份信息，档案表单独维护，一个居民绑定一条档案。这样做的好处是：小程序端登录只需要静默授权拿到手机号，再通过手机号关联档案，避免把微信身份强耦合到医疗数据结构里。
1.2 技术栈选型思路：为什么是SpringBoot而不是别的
作为服务端框架，SpringBoot在这个项目里几乎没有悬念。社区医疗系统对稳定性要求高，SpringBoot生态成熟，社区资料多，团队招人也好招。更重要的是Spring Boot + MyBatis Plus这套组合，写CRUD接口效率非常高，配合代码生成器，基础接口半天就能铺完。
小程序端选的是微信原生框架。没有用uni-app或者Taro，原因比较简单：这个项目只做微信生态，不需要跨平台；原生语法虽然啰嗦，但调试方便，权限 API（比如手机号获取、订阅消息）的支持最直接。如果以后要做支付宝小程序，再重构不迟。
数据库我用的是MySQL 8.0，缓存用了Redis，主要用于验证码存储和热点数据的缓存、以及短信发送频率限制。部署上直接用了Docker Compose，把MySQL、Redis、后端应用以及Nginx打包部署在单台云服务器上，足够支撑数千名居民的日常访问。
1.3 整体架构：前后端分离 + 统一安全校验
架构上没有搞花活儿，就是标准的前后端分离：
小程序前端（微信原生） ↓ HTTPS + JSON Nginx（反向代理 + 静态资源） ↓ SpringBoot 应用层（Controller → Service → Mapper） ↓ MySQL（核心数据） + Redis（缓存与验证码）安全校验这块我用了Sa-Token，而不是Spring Security。原因很直接：Sa-Token的学习成本低，默认支持小程序场景下的Token鉴权，注解式拦截（@SaCheckLogin）用起来非常顺手。对比过Spring Security，功能是强，但配置繁琐，对这个体量的项目反而拖慢进度。每个请求通过拦截器校验Token，再通过ThreadLocal获取当前用户ID，后续业务代码直接拿用户信息即可。
2. 核心功能模块设计与实现
2.1 小程序端的五个功能分区
小程序的页面结构我拆成了五个Tab：首页、预约、档案、消息、我的。这五个Tab基本覆盖居民的所有操作。
首页承担“服务入口+宣教推送”的角色。顶部是用户姓名和档案概览卡片，下面按照业务频次排列功能菜单：预约挂号、慢病随访、疫苗接种、健康档案、报告查询。再往下是健康宣教文章流，由运营人员在管理后台发布。
预约模块分成两个入口：门诊预约和疫苗预约。门诊预约需要选择科室、医生、日期和时段；疫苗预约则按疫苗批次来选，显示剩余库存。预约提交后状态是“待确认”，医生确认后状态变为“已确认”，同时通过订阅消息通知居民。
档案模块做的事情偏展示，居民可以查看自己的基础信息、既往史、过敏史、家族史、体检记录。这里有个隐私细节：所有档案字段在前端展示时都禁止截屏保存，后端返回的数据只包含当前居民自己的档案，且页面离开后清除渲染缓存。
消息模块主要展示系统通知和随访提醒。随访提醒是本项目的重头戏，后面单独讲。
“我的”模块包含登录信息、账号绑定、意见反馈和设置。
2.2 医生端：以“待办”为中心的工作台
医生端的小程序没有做成独立App，而是在同一个微信小程序里通过角色判断显示不同首页。医生角色的首页顶部是“今日待办”：待确认的预约、待处理的随访任务、待复核的档案变更。这块设计是跟医生反复确认后才确定的。
医生最反感的是在一堆菜单里翻找待办。所以我用了“一个中心，三个入口”——中心就是待办列表，让医生登录后第一眼看到所有需要处理的事情；三个入口分别是预约管理、随访管理、档案管理，方便按模块查询历史数据。
随访管理在医生端做得比较重。每个慢病患者有一个随访计划，比如高血压患者要求每两周随访一次，糖尿病每四周一次。系统会根据上次随访日期和计划周期自动生成随访任务，推送到医生端的待办列表。医生打开随访任务，可以看到患者的详细档案、历次随访记录，填完本次血压/血糖数值、用药情况、生活方式评估后，一键提交。随访记录会同步到患者档案的时间线中。
2.3 管理后台：用简单的表格支撑日常运营
管理后台用了若依（RuoYi）的前后端分离版作为基础脚手架，然后裁剪改造。后台用户分管理员、护士、医生三种角色，管理员可以维护医生排班、科室信息、疫苗库存、宣教文章、通知公告，也可以查看各类统计报表。
报表做的不复杂，但关键指标都有控制台展示：今日预约数、今日随访完成数、慢病在管人数、疫苗库存预警等。统计报表我用了简单的SQL聚合，没有引入额外的BI组件。毕竟数据量在几千到几万人这个量级，用不着重型OLAP。
3. 关键数据模型与接口设计
3.1 数据库表结构：这几张表撑起了整个系统
我建了十几张表，核心的六张需要重点关注。
居民用户表（resident）存的是微信身份和基础联系信息。表结构里特别注意了手机号这个字段——微信小程序获取到的手机号需要解密后才能使用，我直接存明文，但接口返回时做了脱敏（中间四位打码），避免被截屏泄露。健康档案表（health_profile）则单独存放医疗属性较强的数据。这种拆分的好处是：当社区服务中心未来对接区域健康平台时，档案表可以独立导出，不影响用户身份体系。
预约表（appointment）是系统里读写频率最高的表。设计它的时候我踩了一个坑：一开始把门诊预约和疫苗预约塞在同一张表里，结果业务一扩展，很多字段互相冲突。后来拆成了appointment和vaccine_appointment两张表，本质上是两种业务，只是前端入口都叫“预约”。随访任务表（followup_task）关联档案ID、医生ID和计划周期，状态分为待处理、已完成、已逾期。随访记录表（followup_record）存每一次随访的详细指标和结论。
消息通知表（message_center）做了站内信和微信订阅消息的双通道设计：站内信保证用户在小程序内能查到历史消息；微信订阅消息负责提醒。这里有个重要的业务规则：订阅消息每次发送前必须先请求用户授权同意，且一次性订阅模板只能发送一次，不能存起来反复用。所以我在“消息”页面放了“开启提醒”的按钮，每次开启授权只代表下一次能收到，收到后状态自动失效。这个逻辑需要在代码里做好状态流转，不然用户会以为打开了开关却没收到提醒，投诉率很高。
3.2 接口设计规范：统一返回结构 + 异常处理
后端所有接口统一返回Result结构，包含code、message、data三个字段。code为200表示成功，401表示未登录或Token过期，403表示无权限，500表示业务异常。前端小程序封装了request方法，统一从header中携带Token，业务层则通过全局异常处理器把异常转换成统一的JSON返回，避免前端到处写try-catch。
举个例子，居民登录接口大概是这样的：
@RestController @RequestMapping("/api/resident/auth") public class ResidentAuthController { @PostMapping("/login") public Result<String> login(@RequestBody LoginDTO dto) { // 1. 校验短信验证码 String code = redisService.get(RedisKey.SMS_CODE + dto.getPhone()); if (code == null || !code.equals(dto.getCode())) { return Result.error("验证码错误或已过期"); } // 2. 根据手机号查找居民，不存在则创建 Resident resident = residentService.findByPhone(dto.getPhone()); if (resident == null) { resident = residentService.registerByPhone(dto.getPhone()); } // 3. 签发Token String token = tokenHelper.createToken(resident.getId()); return Result.success(token); } }用手机号+验证码登录，比微信一键登录更适合社区医疗场景。因为很多居民是老年人，手机上可能微信都没有绑定手机号，甚至没有完成微信实名认证。短信验证码登录虽然成本每条约几分钱，但门槛低，亲切感强。
3.3 权限控制与数据隔离：怎么保证医生只能看自己患者的数据
这个项目的权限体系用Sa-Token做了两层控制。第一层是角色控制，登录后获取当前用户角色（resident、doctor、admin），使用@SaCheckRole注解限制接口访问。第二层是数据范围控制，医生只能访问自己名下居民的数据。常见做法是在查询条件中强制追加doctor_id = 当前登录医生ID，但这容易漏——一旦某个SQL漏了这个条件，就是医疗数据越权事故。
我更推荐在Service层做一个数据权限校验工具类。比如医生查询患者档案时，先查doctor_patient_rel表，确认该医生与患者存在归属关系，再返回数据。这个判断放在Service层而不是Controller层，这样就算以后新增调用入口，安全逻辑也不会被绕过。
在设计医生和居民的关联关系时，特意建立了医生-患者关系表，包含居民ID、医生ID、绑定类型（家庭医生签约或临时服务）、绑定时间。模型很灵活，既能支持“签约家庭医生”的长期关系，也支持临时就诊产生的短时关系。随访任务判断归属时就以这个表为准。
4. 核心流程的实操过程与关键代码
4.1 居民预约就诊的完整链路
这条链路值得完整走一遍，因为它串起了小程序端、后端接口、通知系统和医生端。
居民在小程序预约页选择科室和医生，查看排班后选择一个时段，提交预约。此时后端创建一条状态为PENDING的预约记录，同时创建一条站内消息：“您已提交预约申请，待医生确认。”医生端待办列表展示该预约。医生看到后，有两种操作：确认或者拒绝（需填写拒绝原因）。确认后，小程序端通过订阅消息推送通知居民，同时预约状态变为CONFIRMED。居民到时间后线下就诊，医生在诊后把就诊结果录入系统，这时预约状态变为COMPLETED，系统根据就诊结果更新健康档案的相关内容。
这个链路里，费心思的是时间段的排班逻辑。排班配置表用weekday + time_slot + doctor_id来定义一周循环的排班。比如医生周一上午出诊，配置一条记录：weekday=1, slot=1, doctor_id=5。居民预约时，需要判断该时段是否还有余号。我最初用同步锁防超卖，写了个synchronized，但分布式环境下没用。后来改成Redis的乐观锁，用decr操作扣减剩余号，号码不够直接返回“该时段已约满”。实测下来效率高过了数据库行锁。
4.2 慢病随访任务的自动化生成
慢病随访是本项目里最体现“医疗服务管理”价值的功能，也是技术上的一个亮点。
随访任务不是人工一个个建的，而是通过定时任务自动生成的。我用Spring自带的@Scheduled注解，每天凌晨2点跑一次生成任务。具体逻辑是：查询所有慢病管理中的患者，根据其随访周期（高血压：14天，糖尿病：28天），计算上次随访日期，若今天距离上次随访日期已超过计划周期，则生成一条待处理随访任务。生成任务时做去重，避免重复生成。
核心代码大致如下：
@Component public class FollowUpTaskGenerator { @Scheduled(cron = "0 0 2 * * ?") public void generateTasks() { List<ChronicPatientVO> patients = residentService.listChronicPatients(); LocalDate today = LocalDate.now(); for (ChronicPatientVO patient : patients) { LocalDate lastFollowUp = patient.getLastFollowUpDate(); int interval = patient.getFollowUpIntervalDays(); if (lastFollowUp == null || ChronoUnit.DAYS.between(lastFollowUp, today) >= interval) { followUpTaskService.createTask( patient.getResidentId(), patient.getDoctorId(), patient.getDiseaseType()); } } } }任务生成后，医生端的待办列表就会实时出现新的待办项。这里有个体验细节：医生打开小程序后如果看到一堆逾期任务，血压就上来了。所以我在前端把任务按紧急程度用红色标记“已逾期”，黄色标记“今日应完成”，灰色标记“下次随访还有X天”。虽然功能不变，但视觉上的分诊缓解了医生的心理压力，实际使用反馈很好。
4.3 微信订阅消息的双通道提醒
随访任务生成后，系统不仅要让医生知道，还要提醒患者。提醒通道用微信订阅消息。前端在“设置提醒”页请求用户授权，授权一次系统才能发送一次消息。所以我的策略是：一次随访任务生成时，先发送一条“随访提醒”消息，告知患者“您有一项随访任务待完成，请与家庭医生联系”；患者完成随访后，再发送一条“随访结果已更新”的消息。这样两次提醒刚好用完用户授权的订阅次数，没有浪费，用户也不会被过度打扰。
实现上，订阅消息发送是异步的，用了一个简单的消息队列——直接塞进线程池，通过@Async异步发送。社区医疗场景下的消息量并不大，没必要引入RabbitMQ这种重型中间件。如果一定要考虑高可靠，可以把待发送消息先写入message_outbox表，再由定时任务扫表发送，发送成功标记为已发送，发送失败标记失败原因并支持重试。我在项目里为了快速上线暂时用线程池，后续有需要可以平滑升级到消息表模式。
5. 部署上线中的坑与问题排查实录
5.1 微信小程序合法域名与Nginx配置的纠缠
第一个坑出现在联调阶段。微信小程序要求所有请求必须走HTTPS，并且域名必须在小程序后台配置白名单。开发阶段可以勾选“不校验合法域名”，但体验版和正式版必须合规。我把后端挂在云服务器上，使用Nginx配置了HTTPS证书，反向代理到SpringBoot的8080端口。
看起来很简单，但第一次真机测试时微信报错“request: fail url not in domain list”。排查了半天，发现是Nginx配置里使用了HTTP/2并强制跳转，小程序请求到达时被301跳转了一下，微信对跳转后的新域名校验失败。解决办法是在Nginx的location中直接proxy_pass到后端，避免任何跳转，小程序的baseUrl直接写成https的最终地址。另外SSL证书要确认是否完整链，有些免费证书缺少中间证书会导致安卓真机请求失败，iOS反而正常。这类问题很难从后端日志看出来，因为请求根本没到达SpringBoot。建议用curl -vI检查完整链路。
5.2 数据库连接池参数调优
上线一周后，某个下午数据库连接池突然打满，出现大量“Connection is not available, request timed out”的报错。排查后发现是默认的HikariCP配置最大连接数只有10，而小程序端多个页面会并发请求接口，加上有些慢查询没优化，连接被占用时间过长。我把max-pool-size调整到了30，并给几个高频查询加了索引。
更关键的是查出一个慢查询：居民首页概览需要联查档案、最近的随访记录、未读消息数。原来的写法是三条SQL分别查询，网络IO和数据库解析开销叠加，导致接口耗时超过3秒。优化后改成一条SQL用UNION和LEFT JOIN合并，或者拆成两条并行查询，配合CompletableFuture异步调用，最终接口稳定在800毫秒左右。移动端弱网环境下这种优化感知特别明显。
5.3 角色混用带来的权限漏洞
还有一个安全上的教训。起初我在小程序端只做了角色判断，通过某个接口返回当前用户的角色，然后在代码里用if判断显示不同首页。但后端的某些管理接口只用了@SaCheckLogin注解，没有加角色限制。结果发现普通居民用户只要拿着自己的Token调用管理端接口，能查到医生端的预约列表。虽然没发生真实的数据泄露，但这个漏洞让我出了一身冷汗。
修复方案是全面Review所有Controller接口，给每个管理接口加上@SaCheckRole("admin")或@SaCheckRole("doctor")。另外Sa-Token本身支持TokenSession，可以把角色信息直接写入TokenSession，前端拿到的用户信息里也包含角色，但后端校验绝不信任前端的角色字段。这是一条铁律。
5.4 关于隐私合规的几点自查
最后说说医疗数据合规。小程序类目选择了“医疗——就医服务”，需要提供相关资质证明。个人开发者和非医疗资质主体无法直接上线医疗类小程序，这点建议尽早了解清楚，别等做完了才发现发布不了。
在这个项目里，我做了几层合规处理：传输层全链路HTTPS；存储层不保存微信原始手机号以外的隐私字段；健康档案数据默认只有居民本人和其签约医生可见；强制日志脱敏，不让敏感字段出现在日志中；居民端提供了档案导出与注销功能，注销后30天内可以恢复，超过30天彻底删除。
我还做了一个很有用的功能：给每位居民一个“数据授权”开关。未授权时，医生只能看到基础联系方式，无法查看详细既往史和用药记录。这个开关在首次建档时弹出，由居民自主决定，也方便通过监管审查。
6. 经验沉淀与后续扩展思路
6.1 复盘整个项目交付过程
从需求调研到上线试运行，整个项目耗时约两个半月，不算长，但覆盖了从0到1的全流程。我认为做得对的地方有三点：一是坚持了“先画业务流程图，再写代码”的原则，尤其是把预约和随访的完整状态机定义清楚，后续几乎没出现过状态错乱的bug；二是所有接口授权统一走Sa-Token，省去了很多重复的鉴权代码；三是前后端人员每天联调一次，没有出现“接口文档和实际出入太大”这种拖后腿的问题。
需要承认的不足也有：前端代码质量一般，因为赶进度，很多页面直接复制修改，导致后续维护时组件复用性不高；测试覆盖不完整，尤其是定时任务相关逻辑，因为手工不好触发，差点漏了逾期随访任务不会自动更新的Bug。
6.2 如果时间重来，或者你想继续扩展
这个项目后续有很多延伸方向。我列一下我觉得最有价值的几个：
第一，把慢病管理做得更智能。比如结合居民历史血压数据，用简单规则引擎判断风险等级，自动生成健康建议。不需要上机器学习，规则就能覆盖大多数场景。
第二，对接区域卫生信息平台。社区医疗不同于三甲医院，它的数据最终要向上汇总，如果预留了标准化HL7 FHIR或当地卫生数据交换标准，未来做区域共享会容易很多。
第三，增加家庭账户能力。很多随访场景是子女帮父母预约和查看报告，现在的机制是家庭绑定关系，需要加一个家庭成员管理模块，让授权人代替老人操作。
第四，体检数据的OCR识别录入。社区体检报告很多是纸质版，如果小程序端能拍照自动识别并录入体检指标，会极大减轻护士的工作量。这个直接用现成的OCR服务就能实现。
我在做这个项目的过程中，最深的体会是：医疗软件的核心不在技术多炫，而在于把医生从繁琐的事务中解脱出来，把居民的健康数据管理得清清楚楚。SpringBoot和小程序只是工具，真正有价值的是对业务流程的尊重和耐心。如果你也在做类似的项目，先把业务聊透、把状态机画对，技术上的东西其实都是水到渠成的。
