Spring Boot宠物医院管理系统：从需求分析到接口设计的完整实践

前阵子一位做传统生意转行的朋友找到我，说他接了一家宠物医院的数字化改造小活，想让我帮忙看看系统该怎么搭。我去现场转了一圈，印象最深的是：前台手写预约登记、病历纸堆了两大箱、药房盘点靠感觉、收费还在用Excel对账——整个就诊流程全靠人肉衔接。这个场景在很多中小型宠物医院其实非常普遍，也正是“基于SpringBoot的宠物医院管理系统”这类项目存在的意义。这类系统看起来是个典型的CRUD管理系统，但它真正考验的并不是增删改查本身，而是业务流程的梳理和事务数据的一致性设计。这篇文章我就以这个项目为例，把从需求拆解、技术选型、数据库设计到核心代码实现的完整过程梳理一遍，给正准备做类似管理系统、或者拿它当毕业设计题目和转行练手项目的朋友一份可以直接照着落地的参考。

1. 场景痛点与功能拆解：先搞清楚这个系统到底在管什么

很多同学拿到“宠物医院管理系统”这个题目，第一反应就是打开IDE开始建实体类，结果做着做着发现东缺一块西缺一块。这里我先劝一句：这类业务系统，流程图比代码值钱。你先把自己代入宠物医院的前台、医生、药房这三个角色，想清楚每个人每天在忙什么，系统要替他们省掉什么，功能边界自然就出来了。

1.1 三类核心角色与权限边界

完整的宠物医院管理系统，我建议按权限拆成四种角色，不要上来就搞一个超级管理员走天下：

这里有一个容易被忽略的点：医院系统的角色权限一定要落到操作级别，而不是菜单级别。我见过不少项目只控制“谁能看到菜单”，进去之后所有按钮都能点，这在实际使用中会出大问题。比如前台能改处方、医生能直接改药品价格，一旦发生纠纷，数据责任都说不清楚。所以权限设计要拆到按钮级别，后端做接口鉴权，前端做菜单和按钮双控制。

1.2 从就诊动线反推功能清单

把角色划分清楚之后，下一步是画一条完整的就诊动线。以最常见的“新客户带宠物看病”为例：

1. 客户到店，前台先建宠物档案（如果没有的话），同时登记主人信息；
2. 前台为宠物预约挂号，选择一个时间段和科室；
3. 医生在预约列表看到待接诊记录，开始问诊；
4. 医生录入病历和检查结果，同时开出处方（药品明细）；
5. 药房看到处方后核对库存，确认发药；
6. 前台根据处方明细和诊疗费生成收费单，收款结算。

这一条线走下来，系统至少要包含这七个功能模块：宠物档案管理、预约挂号管理、接诊管理、病历/处方管理、药品库存管理、收费结算管理、系统管理（用户/角色/日志）。

功能优先级上，我建议分三档落地（参考下表）：

提示：如果你是拿它做毕业论文/设计，P2里的数据统计和微信端往往是答辩加分项，建议至少做一块统计分析，图表直接用后端接口返回数据，前端接一个图表库展示，效果非常直观。

1.3 对外延展：系统定位决定了设计深度

还有一个容易纠结的问题：这个系统到底是内部管理系统，还是带C端业务的平台？如果只是医院内部用，不做在线预约，那用户端就是一个后台管理系统，不用考虑微信登录、Token过期、并发抢号这些复杂场景。如果要做C端，哪怕只是“微信公众号预约”，就得增加用户端接口、验证码登录、预约锁号这些设计，工程量和复杂度完全不是一个量级。

我的建议是：首版先做纯内部管理系统，把预约当成“前台代客预约”，也就是前台在系统里人工录入预约信息，不做用户自助。原因有两点：第一，内部系统的边界清晰，权限模型好设计，适合作为骨架；第二，等到内部数据跑顺了，再拆一个接口层给C端，是水到渠成的事，而反过来一上来就做C端，前台内部流程还没理顺，系统很容易变成两层皮。

2. 技术选型与架构设计：Spring Boot搭配这些组件最省心

这个项目选用Spring Boot几乎是必然选择。跟早期的SSH或者裸Spring MVC相比，Spring Boot用starter机制省掉了一大堆配置，内嵌Tomcat让项目可以一个java -jar直接跑起来，对中小型管理系统来说开发效率高一个量级。但这只是基础，真正要少走弯路的是下半场选型。

2.1 持久层为什么推荐MyBatis Plus

宠物医院管理系统这种业务，90%的数据库操作是单表CRUD加上表关联查询。如果纯用MyBatis，每个实体的增删改查要写一堆重复XML，很枯燥。用Spring Data JPA也行，但复杂查询的同学会觉得不够直白。MyBatis Plus刚好夹在中间：单表CRUD不用写SQL，复杂查询又能自己写XML和注解SQL，不丢控制感。

MyBatis Plus有三个功能对这类项目特别有用：

• 条件构造器（Wrapper）：比如查“状态为待接诊的预约单”，直接LambdaQueryWrapper就能搞定，不用写SQL；
• 分页插件：列表页面离不开分页，它通过MybatisPlusInterceptor内建分页参数拦截，避免手写limit方言；
• 代码生成器：数据库表建好后，可以直接生成Controller、Service、Mapper、实体类，把重复劳动压缩到半小时以内。

我实测下来，用MyBatis Plus能让这个项目至少省出两到三天的纯CRUD时间，省下来的时间应该投入到业务逻辑和界面打磨上。

2.2 整体架构：前后端分离 + 三层后端

这个项目我建议采用前后端分离，后端用经典三层架构：

controller/ // 接收参数、校验权限、返回统一响应 ├── admin/ // 后台管理端接口 service/ // 业务逻辑层，事务都在这层 mapper/ // 数据访问层 entity/ // 数据库对应实体 dto/ // 前端传参对象 vo/ // 返回给前端的视图对象 common/ // 统一返回体、异常处理、工具类 config/ // 安全配置、跨域配置、MyBatis Plus配置

三层架构虽然老生常谈，但在这种业务系统里依然是清晰度最高的方案。需要注意一点：Controller里不要堆业务逻辑。我见过有人把预约校验、库存扣减全部写在Controller里，后期想加一个接口复用逻辑时非常痛苦。正确的做法是Controller只做参数解析和权限校验，业务判断全部下沉到Service，这样事务注解 @Transactional 才能打在正确的边界上。

2.3 前端和鉴权部分的选型建议

前端方面，如果只是内部管理系统，我推荐Vue 3 + Element Plus，这是后台管理系统里效率最高的组合。Element Plus自带表格、表单、对话框、日期选择器，能覆盖管理端80%的界面需求。如果你不懂前端，也可以用模板管理系统（比如若依这类快速开发框架）作基础，但要注意：如果这是你的毕设，不要直接套若依的完整系统当作自己的项目提交，查重和答辩都会很尴尬。更好的方式是参考它的目录结构，自己重写核心模块。

鉴权方案上，Session在前后端分离场景下不太方便，我推荐Spring Security + JWT。登录后服务端签发JWT，前端每次请求带上Authorization头，后端通过过滤器校验。对于这个项目来说，重点是能在方法上用@PreAuthorize("hasRole('DOCTOR')")控制接口权限，以及前端路由/按钮根据角色动态渲染。

3. 数据库设计：核心表、关联关系与状态流转

数据库是这类管理系统项目最容易体现功底的地方。很多新手建表喜欢把所有内容塞进一张大表，或者要么就不敢拆明细表，导致后面统计和追溯非常困难。我按实际项目经验，给出这套表结构设计。

3.1 核心表清单与字段要点

这套表结构的设计逻辑很明确：一切围绕就诊流程展开，一张主单对应多条明细。预约表、病历表、处方表、收费表都是业务主表，而pet和owner属于基础档案，drug和stock_log则是库存侧的独立闭环。

3.2 最容易设计错的地方：处方明细关联

我重点说一下处方这块，因为这里特别容易犯错。不少初学者会在处方表里设计一个drug_ids字段，用逗号拼接药品ID，这实际上是反设计，后面的统计、汇总、出库对账全都做不了。正确做法是拆出prescription_item明细表，每一行是一个药品：

prescription_item id, prescription_id, drug_id, drug_name(冗余), quantity, price, amount

这里有个细节值得说明：为什么要把drug_name冗余进去？因为药品名称和价格会随药品表的变化而变化，如果不做冗余，老处方单在后续重查看时，药名和价格可能会被最新数据覆盖，这在医疗场景里是严重的合规问题。所以处方明细里的药品名称、价格一律存当时的值，不改。这个设计原则在真实的医疗信息化系统里是标配。

3.3 状态流转设计：要给状态机留足空间

业务主表几乎都要有状态字段。以appointment表为例，状态流转建议这样设计：

待接诊 -> 已接诊 -> 已完成 | | v v 已取消 已取消

也就是说：用户（或前台）可以取消待接诊状态的预约；医生开始接诊后，如果临时有事或者宠物主人爽约，也可以由医生操作取消。状态变更不能直接改状态值就完事，我建议增加一个operation_log或者字段变更记录表，记录“谁在什么时间把状态从A改为B”，这样答辩时老师问“如何保证数据的可追溯性”，你就能直接拿出这张表当证据。

3.4 索引和扩展设计

索引方面，预约表的doctor_id、appointment_date，病历表的pet_id，库存流水表的drug_id和create_time，这些高频查询条件都要建索引。宠物档案表按pet_name模糊查询的场景很多，建议对pet_name建普通索引，有条件的话可以后续引入全文检索。

扩展设计上，记得预留owner.wechat_openid字段、appointment.remind_status字段，方便后期做C端预约和自动提醒。不需要一开始就建一堆空表，但预留好字段能让后面演进时少动表结构。

4. 从预约到结算：核心业务逻辑的落地实现

架构和表结构确定之后，接下来是最核心的部分：把业务逻辑用代码落到实处。我挑几个最不能出错的环节，详细展开实现方案。

4.1 预约模块：防止同一时间段重复预约

预约的并发场景虽然不像秒杀那么极端，但同一名医生在同一个时间段确实可能被重复预约。前端日历上把已约满的时间段禁用只是体验优化，真正要保证数据一致性得靠后端。

我的实现思路分三步：

1. 用户在日历上选择时间段，前端请求“查询某医生某天的预约情况”；
2. 后端查询时，把已满时间段返回，前端置灰；
3. 提交预约时，后端再次校验，并增加数据库层面的唯一约束兜底。

第三点是关键。给appointment表增加一个联合唯一索引：

ALTER TABLE appointment ADD UNIQUE INDEX uk_doctor_time (doctor_id, appointment_date, time_slot);

这样即使两个请求并发提交，数据库层面也会拒绝第二个重复插入。

为了更好体验，预约容量不止1时，可以改造成先查询已预约数量，再判断是否小于上限，并在Service里加一个分布式锁或者悲观锁：

// 伪代码：使用事务，先锁医生当天时间段的记录 Appointment locked = appointmentMapper.selectForUpdate( doctorId, appointmentDate, timeSlot);

selectForUpdate依赖MySQL的悲观锁，在事务内锁定该医生的时间段记录，并发提交时后一个事务会等待，等锁释放后重新检查容量，超出就抛异常。这种场景下悲观锁比乐观锁更简单可靠，因为冲突经常发生，重试的体验反而更差。

4.2 接诊开方：事务边界怎么划才安全

一次接诊动线中，涉及的操作是：更新预约状态为“已接诊”、写入病历主记录、写入处方主记录及处方明细、扣减药品库存。这四个操作必须在一个事务里完成，否则会出现病历写好了、库存没扣到的情况。

事务边界的正确写法：

@Service public class MedicalService { @Transactional(rollbackFor = Exception.class) public Long completeConsultation(ConsultationRequest request) { // 1. 更新预约状态 appointmentMapper.updateStatus(request.getAppointmentId(), "ALREADY_VISITED"); // 2. 创建病历主记录 MedicalRecord record = new MedicalRecord(); record.setAppointmentId(request.getAppointmentId()); record.setPetId(request.getPetId()); record.setDoctorId(request.getDoctorId()); record.setDiagnosis(request.getDiagnosis()); medicalRecordMapper.insert(record); // 3. 创建处方及明细 Long prescriptionId = createPrescription(record.getId(), request.getItems()); // 4. 扣减库存（关键步骤，见下节） for (PrescriptionItemDTO item : request.getItems()) { drugMapper.deductStock(item.getDrugId(), item.getQuantity()); } return prescriptionId; } }

这里注意注解要用rollbackFor = Exception.class，默认的RuntimeException回滚虽然常见，但如果你catch了异常又没重新抛出，事务照样不会回滚。另外，事务方法不要写成内部自调用，例如在同一个类里A方法调B方法，如果B上有@Transactional不会生效，因为内部调用不会经过代理。我自己踩过这个坑，后来统一规则：事务入口都在Controller调用的Service方法上，拆分出来的私有方法不写事务注解。

4.3 库存扣减：关键细节与超卖防范

药品库存扣减是宠物医院系统里和钱关系最紧密的逻辑。很多人直接在Java里先查询库存，判断够不够，再执行update，这是典型的并发隐患：两个请求同时读到库存为1，都判断“够”，然后都执行扣减，最后库存变成负数。这个顺序写错了，轻则在药房对账时发现问题，重则在处方和库存对不上时引发医疗纠纷。

正确的做法是让数据库来保证原子性，用条件更新实现：

// Mapper 里定义 @Update("UPDATE drug SET stock = stock - #{count} " + "WHERE id = #{drugId} AND stock >= #{count}") int deductStock(@Param("drugId") Long drugId, @Param("count") Integer count);

这样只有当库存充足时，update语句才会更新成功并影响1行，否则影响0行。Service里通过判断返回值来判断扣减是否成功：

int result = drugMapper.deductStock(item.getDrugId(), item.getQuantity()); if (result == 0) { throw new InsufficientStockException(item.getDrugName() + "库存不足"); }

如果事务中途失败，@Transactional会把库存更新一并回滚，不会出现“处方失败但库存被扣”的情况。

还有一个实操心得：药品表里的stock字段只是当前库存值，真正的审计依据在stock_log表。每次扣减库存都要往stock_log里写一条change_type=OUT的记录，记录操作人、操作时间、关联的业务单号。这也是药房盘点时“账实不符”时排查问题的唯一线索。

4.4 权限控制：Spring Security + JWT的最小落地

前端是管理后台，我建议后端用Spring Security框架，结合JWT做无状态鉴权。关键代码分三段：

登录接口校验账号密码，成功后生成JWT：

String token = JwtUtil.createToken(user.getId(), user.getUsername(), role);

这里注意JWT的载荷里放用户ID和角色就够了，不要放敏感信息，过期时间建议设成24小时，管理端不要求频繁登录。

后端接口加鉴权注解：

@PreAuthorize("hasAnyRole('ADMIN','FRONT_DESK')") @PostMapping("/api/appointment") public Result createAppointment(@RequestBody AppointmentDTO dto) { ... }

这样就能从方法级别控制权限。再配合WebSecurityConfigurerAdapter（新版本改成SecurityFilterChain）配置哪些路径放行、哪些路径需要认证，JWT过滤器从请求头解析Token并塞入SecurityContext。

前端的配合是：登录后把角色信息存到Pinia或Vuex，路由表的meta里标记需要的角色，在路由守卫中拦截无权限用户。按钮级别的控制可以用自定义指令，例如v-permission="['ADMIN']"，没权限直接移除按钮。这一点写进文档或论文里，是很好的加分细节。

5. 开发排期、常见问题与答辩/汇报时的演示要点

最后这部分聊点更实际的：项目怎么做完，中途会遇到什么坑，以及怎么把它讲得漂亮。

5.1 单人开发的排期建议

这个项目如果是一个人做，建议按两周紧凑排期，四周围绕打磨：

这里面要特别注意，第一个阶段RESTful接口风格要统一，比如统一用Result响应体，错误码约定200成功、400参数错误、500系统异常，不然前后端联调时接口改来改去非常浪费时间。

5.2 实测中容易踩的坑

我用这套技术栈做同类系统时，前前后后踩了不少坑，列几个典型的：

• 时区问题：数据库连接串要加serverTimezone=Asia/Shanghai，否则日期存进MySQL会偏移8小时，预约时间的展示会很诡异。
• MyBatis Plus字段映射：数据库字段是下划线命名（如appointment_date），实体用驼峰（appointmentDate），记得打开mapUnderscoreToCamelCase=true，不然你查出来的对象全是null。
• 分页失效：MyBatis Plus分页要手动加PaginationInnerInterceptor插件，光加依赖不配置分页不生效，很多人第一次用都会卡在这。
• updateById全字段更新：MyBatis Plus默认是把实体的非null字段更新掉，如果你只改了部分字段且某些字段为null，想保留原值，需要自动填充或者明确用UpdateWrapper按条件更新。
• 跨域问题：前后端分离部署时，会导致跨域请求被浏览器拦截。后端在SecurityConfig里对开发环境放开CORS，定义一个CorsConfigurationSource，允许来源和请求头。

5.3 答辩/演示的最优表达路径

如果是毕业设计答辩或者向客户演示，不要打开系统就从用户管理开始讲。正确的演示顺序应该是：

1. 先用一两分钟讲痛点情景：“一个宠物主人带着生病的小猫到医院，从建档到拿药结算，中间需要哪些信息流转”；
2. 顺着这条动线，在系统里完整走一遍：建档案 -> 预约 -> 接诊 -> 开处方 -> 药房出库 -> 收费；
3. 最后展示一下权限控制和统计报表，强调系统的数据可追溯性。

我发现评委和客户对“端到端走通业务闭环”的演示印象远好过对着菜单念功能。所以演示前一定准备一组含中文数据的模拟数据：宠物名例如“咪咪”、常见疾病例如“猫瘟”“皮肤病”、真实感的药品名，比如“猫三联疫苗”，预置在系统里，演示时不用临时造数，流畅度会高很多。

在这个项目里，我还想额外提一个很容易出彩的设计：操作日志模块。不要简单地记录“谁登录了系统”，而是记录核心业务操作，例如“医生A将预约单#20240601001状态更新为已接诊”。其实做法就是在Service层核心方法中，通过自定义注解或手动调用日志Service记录操作人和业务单号。这项能力在真实的医疗场景中是刚需，也是答辩时一个很好的差异化亮点。

6. 一点实际操作中的体会

整个项目做完下来，我有一个很真实的感受：管理系统的难点根本不在技术，而在对业务边界的理解和流程抽象的准确性。编程技术本身大家都会，差别在于你能不能把前台、医生、药房、结算这四方的协作关系理成一套无冲突的状态流转规则。宠物医院管理系统这个题目之所以经典，就是因为它规模适中、业务角色清晰、流程完整，非常适合用来练习从需求分析到系统落地的完整链路。如果你正在做这个项目，我的建议是开工前多花三天在纸上把ER图和状态流转图画明白，动手写代码时你就会发现，剩下的工作更像是在把已经设计好的业务流程“翻译”成代码，顺畅程度比直接上手写要好太多。