简介面向医院信息化场景的医疗挂号系统源码包基于Python开发适合计算机专业学生、Python开发初学者以及医疗系统项目人员用于课程设计、实验实训或业务原型搭建。系统围绕线上挂号、在线缴费、医生按序接诊和管理员后台管理四个主要功能展开采用DAO层隔离数据访问与业务逻辑患者端和医生端独立成模块结构上适合学习完整的小型管理类项目的实现思路。压缩包为RAR格式共六十个文件整体约574KB主要包含十六个Python源码、十九个字节码、十二张PNG界面图片、七个XML配置及三个GIF动图源码覆盖数据访问层、医生登录主页面、患者登录主页面等核心代码图片与动图配合展示界面和操作流程。目前已有6907人浏览学习关注度较扎实。借助分层源码与患者端单元测试文件读者可直观理解数据读写、业务处理与界面调用如何协作也能据此快速改造或扩展功能作为毕业设计、课程项目或医疗挂号系统的实用起步参考。1. 医疗挂号系统难在哪不是把页面做出来而是让号源不乱一个上午门诊放 30 个号开号瞬间几百人同时刷新最后数据库里不能出现第 31 个号有人退号这个号要立刻回到池子里让别人能挂同一笔支付回调发两次系统不能给同一个病人开两张单。医疗挂号系统的真正难点从来不在“挂号”这个动作本身而在于号源怎么不超卖、状态怎么不混乱、重复请求怎么被挡住。这套用 Python 写的源码核心就是围绕这几件事组织起来的。它面向的读者很明确正在做课程设计或毕业设计、想进入医疗信息化方向或者单纯想用一个小系统把事务、并发、权限这些工程问题完整练一遍的人。2. 选型与建模为什么这套系统用 Django核心表怎么拆2.1 选型理由从 Flask 换到 Django 的那一步很多人一上来会选 Flask觉得轻。但把“挂号系统”拆开看需求就会发现这里面到处是重活用户要分医生、患者、管理员三种角色挂号单要管状态流转数据表要频繁加字段后台要有人维护科室和排班。Flask 默认给不了你 ORM 迁移、Admin 后台、权限校验框架这些全要自己拼拼到后面代码比 Django 还重。我一般会直接选 Django原因很具体事务管理成熟atomic块和select_for_update组合起来能挡住并发超卖这是挂号系统最核心的安全底线Admin 后台可以零成本给医院信息科的人维护基础数据不用专门写管理界面自带的用户体系和权限框架做医生、患者角色区分时省掉一大半轮子迁移机制让后续加字段、改约束不容易把数据弄丢。FastAPI 也不是不能做异步性能确实好但现实是团队里多数人熟悉的是 Django 那套 MTV 结构而且挂号系统的瓶颈在数据库一致性不在接口吞吐量。除非你预计每天有几十万并发挂号这种极端场景否则 Django 加 DRF 是更稳的起点。2.2 核心模型科室、医生、排班、挂号单先想清楚业务上有哪些对象。一个综合门诊的基本链条是科室 → 医生 → 排班 → 号源 → 挂号单。很多初学者会把“号源”做成一个独立表每个时间段生成几十条记录。能跑但管理和释放都很啰嗦。更常见的做法是排班表里直接放总量和已约数两个字段挂号时在事务里做校验和更新。下面是一套能跑的模型设计我用的是 Django 默认的 User 作为患者身份医生和患者共用用户体系通过一个 Profile 字段区分# hospitals/models.py from django.conf import settings from django.db import models class Department(models.Model): name models.CharField(科室名称, max_length64, uniqueTrue) location models.CharField(位置, max_length128, blankTrue) is_active models.BooleanField(是否启用, defaultTrue) def __str__(self): return self.name class Doctor(models.Model): user models.OneToOneField( settings.AUTH_USER_MODEL, on_deletemodels.CASCADE, related_namedoctor_profile, ) department models.ForeignKey( Department, on_deletemodels.PROTECT, related_namedoctors, verbose_name所属科室, ) title models.CharField(职称, max_length32, blankTrue) def __str__(self): return f{self.user.last_name} {self.title}.strip() class Schedule(models.Model): SESSION_AM am SESSION_PM pm SESSION_CHOICES [ (SESSION_AM, 上午), (SESSION_PM, 下午), ] doctor models.ForeignKey( Doctor, on_deletemodels.CASCADE, related_nameschedules, verbose_name医生, ) work_date models.DateField(出诊日期) session models.CharField(时段, max_length2, choicesSESSION_CHOICES) total_quota models.PositiveIntegerField(号源总量, default30) appointed_count models.PositiveIntegerField(已约人数, default0) is_active models.BooleanField(是否可挂, defaultTrue) class Meta: # 同一医生同一天同一时段只能有一条排班天然防重复 constraints [ models.UniqueConstraint( fields[doctor, work_date, session], nameuniq_doctor_date_session, ) ] verbose_name 排班 verbose_name_plural 排班 property def remaining(self): return self.total_quota - self.appointed_count class Appointment(models.Model): STATUS_PENDING pending # 待支付 STATUS_PAID paid # 已支付 STATUS_CANCELLED cancelled # 已取消未支付被取消/超时释放 STATUS_REFUNDED refunded # 已退号 STATUS_VISITED visited # 已就诊 STATUS_CHOICES [ (STATUS_PENDING, 待支付), (STATUS_PAID, 已支付), (STATUS_CANCELLED, 已取消), (STATUS_REFUNDED, 已退号), (STATUS_VISITED, 已就诊), ] order_no models.CharField(订单号, max_length64, uniqueTrue) patient models.ForeignKey( settings.AUTH_USER_MODEL, on_deletemodels.PROTECT, related_nameappointments, verbose_name患者, ) schedule models.ForeignKey( Schedule, on_deletemodels.PROTECT, related_nameappointments, verbose_name排班, ) status models.CharField(状态, max_length16, choicesSTATUS_CHOICES, defaultSTATUS_PENDING) created_at models.DateTimeField(创建时间, auto_now_addTrue) paid_at models.DateTimeField(支付时间, nullTrue, blankTrue) cancelled_at models.DateTimeField(取消/退号时间, nullTrue, blankTrue) def __str__(self): return f{self.order_no} - {self.get_status_display()}几个字段选择的理由说一下。Department.name加唯一约束防止后台有人把“内科”建了两遍Doctor.user用一对一关联到 Django 用户而不是单独建一张包含账号密码的医生表是为了复用自带的登录和权限体系Schedule的唯一约束是三层联合唯一后续生成排班脚本只要按这个规则插入就不会出现同一天上午两条数据Appointment里不直接冗余医生姓名和科室而是通过schedule外键间接取避免挂号和退号时数据不一致。注意两个细节on_deletemodels.PROTECT用于医生、排班这类业务数据有挂号和排班记录时不允许删科室防止把历史记录连带删掉Order_no必须唯一它是支付回调和对账的锚点。2.3 挂号单的状态机一条记录如何走完一生挂号单不要设计成只有“已挂”和“已取消”两种状态真实场景里会出现“创建了但没付钱”的中间态。每次状态变更都要有节点这样才能回答业务问题号源被谁占着占了多少分钟为什么退了下面这套状态取值是医疗挂号系统里最常见的设计。状态含义进入条件允许退出到pending待支付号源被临时锁定用户提交挂号单paid / cancelledpaid已支付号源正式占用支付回调成功refunded / visitedcancelled已取消号源已释放用户取消或超时未支付终态refunded已退号号源已释放已支付后退号终态visited已就诊医生标记就诊完成终态这个状态机最关键的约束是pending只能到paid或cancelled不能直接跳到refundedpaid状态下才可以退号visited是终态不允许再退。代码里我不会用硬编码字符串到处比较而是把状态常量放在模型类里比如Appointment.STATUS_PAID这样在视图、任务、测试里引用改一个名字时不会改漏。状态机是后面所有并发控制的地基。超卖拦截、重复支付回调、退号校验本质都是“先查当前状态再决定是否放行”。如果你的源码里每个接口都自己判断状态规则就会散落各处早晚有一个入口漏校验。这就是很多人项目里出现“已就诊的号又被退了”这类问题的根源。3. 把挂号主流程写成代码排班生成、锁号下单、支付确认、退号释放3.1 生成一周排班与号源池脚本怎么写排班数据不能靠后台手工一条条点那会疯掉。常见做法是写一个 Django 管理命令按医生的出诊规则批量生成一周排班。下面的命令按“周一至周五出诊上午 30 个号、下午 20 个号”的规则生成# hospitals/management/commands/generate_schedule.py from datetime import timedelta from django.core.management.base import BaseCommand from django.utils import timezone from hospitals.models import Doctor, Schedule class Command(BaseCommand): help 为每位医生生成指定日期之后一周的排班 def add_arguments(self, parser): parser.add_argument(--start-date, typestr, help起始日期格式 YYYY-MM-DD默认今天) def handle(self, *args, **options): start timezone.localdate() if options[start_date]: start timezone.datetime.strptime(options[start_date], %Y-%m-%d).date() created_count 0 for doctor in Doctor.objects.filter(user__is_activeTrue): for offset in range(7): work_date start timedelta(daysoffset) if work_date.weekday() 5: # 周一0周六5周日6 continue for session, quota in [(am, 30), (pm, 20)]: _, created Schedule.objects.get_or_create( doctordoctor, work_datework_date, sessionsession, defaults{total_quota: quota}, ) if created: created_count 1 self.stdout.write(f生成排班 {created_count} 条)逻辑说明命令里的get_or_create依赖模型上的三层联合唯一约束重复执行不会生成重复排班defaults只在创建时写入如果某天号源总量要从 30 改成 40要单独写更新逻辑不能靠这个命令覆盖已存在的记录。参数说明--start-date接受YYYY-MM-DD字符串便于测试时指定一个固定日期weekday()返回值 5、6 对应周六周日跳过每个医生每天生成上午 30、下午 20 两个时段。跑法就是python manage.py generate_schedule。3.2 挂号下单用行锁挡住并发超卖假设号源总数为 30当前已约 30两个请求同时进来如果先查再写两个请求都会看到“还剩 0 个名额”然后各自创建一条挂号单就超卖了。解决这个问题的经典手段是对排班行加锁让后到的请求等待前一个事务提交后再读最新值。# hospitals/services.py import uuid from django.db import transaction from django.db.models import F from django.utils import timezone from hospitals.models import Appointment, Schedule class FullQuotaError(Exception): 号源已满 transaction.atomic def create_appointment(schedule_id, patient_user): # 行锁直到事务提交前其他请求的 select_for_update 都会阻塞 schedule Schedule.objects.select_for_update().get(idschedule_id) if not schedule.is_active: raise FullQuotaError(该排班已停挂) if schedule.appointed_count schedule.total_quota: raise FullQuotaError(号源已挂完) order_no f{timezone.now():%Y%m%d%H%M%S}{uuid.uuid4().hex[:8]} appointment Appointment.objects.create( order_noorder_no, patientpatient_user, scheduleschedule, statusAppointment.STATUS_PENDING, ) # 用 F 表达式在数据库层原子自增避免 count count 1 的并发覆盖 Schedule.objects.filter(pkschedule.pk).update( appointed_countF(appointed_count) 1 ) return appointment逻辑说明select_for_update()必须在transaction.atomic()块内否则锁不生效它锁的是Schedule这一行后到的挂号请求会在这里排队等前一个事务提交拿到锁后再检查appointed_count从源头杜绝超卖。appointed_count的更新用F()而不是从schedule.appointed_count 1写入是为了避免“读改写”两步之间的覆盖丢失。参数说明schedule_id传排班主键patient_user是 Django 的 User 对象不能传字符串函数以transaction.atomic整体包裹创建挂号单和自增计数在同一个事务里任何一步失败都会回滚。注意事项锁住排班行之后不要在锁内做耗时操作比如调用支付接口或发短信否则会长时间占住数据库连接拖垮整个系统。这里只做本地记录创建支付请求由前端发起异步回调再确认。3.3 支付确认与退号释放用户支付完成后支付平台会回调一个确认通知。回调可能因为网络重试发送多次处理函数必须幂等。核心思路是加锁读出挂号单如果状态不是pending说明已经处理过直接返回成功不再重复改状态。transaction.atomic def confirm_payment(order_no, paid_atNone): appt Appointment.objects.select_for_update().get(order_noorder_no) if appt.status ! Appointment.STATUS_PENDING: # 重复回调状态已不是待支付直接返回不重复处理 return appt appt.status Appointment.STATUS_PAID appt.paid_at paid_at or timezone.now() appt.save(update_fields[status, paid_at]) return appt退号逻辑同样要先读状态再变更。只有paid状态允许退号退号后释放号源。已经visited就不允许退防止医生已经接诊完患者再来退号退款。transaction.atomic def refund_appointment(order_no): appt Appointment.objects.select_for_update().get(order_noorder_no) if appt.status ! Appointment.STATUS_PAID: raise ValueError(只有已支付状态才能退号) appt.status Appointment.STATUS_REFUNDED appt.cancelled_at timezone.now() appt.save(update_fields[status, cancelled_at]) Schedule.objects.filter(pkappt.schedule_id).update( appointed_countF(appointed_count) - 1 ) # 此处触发退款任务建议走异步队列不要阻塞事务 trigger_refund_async(appt.order_no) return appt这个函数里有一个常见坑appt.schedule_id是外键字段在数据库层的主键值用filter(pkappt.schedule_id).update(...)不会再把整个Schedule对象加载回来性能没问题但如果你在更新后继续访问appt.schedule.appointed_count拿到的其实是之前缓存的内存对象不是数据库里减去之后的真实值。要重新加载需要appt.schedule.refresh_from_db()。参数说明update_fields只更新指定字段避免把created_at这类自动字段意外覆盖也减少写操作退单异步任务里要传order_no而不是把整个对象传进去因为任务执行时事务已经提交懒加载外键可能会失效。3.4 超过 15 分钟未支付的号怎么自动回收待支付状态不能一直占着号源。常见做法是写一个管理命令扫描超时未支付且出诊日期在未来的挂号单把它们置为cancelled并释放号源然后由系统定时任务每分钟执行一次。# hospitals/management/commands/release_expired.py from datetime import timedelta from django.core.management.base import BaseCommand from django.db import transaction from django.db.models import F from django.utils import timezone from hospitals.models import Appointment, Schedule class Command(BaseCommand): help 释放超过15分钟未支付的号源 def handle(self, *args, **options): now timezone.now() deadline now - timedelta(minutes15) expired_list Appointment.objects.filter( statusAppointment.STATUS_PENDING, created_at__ltedeadline, schedule__work_date__gtenow.date(), ).select_related(schedule) released 0 for appt in expired_list: with transaction.atomic(): locked Appointment.objects.select_for_update().get(pkappt.pk) if locked.status ! Appointment.STATUS_PENDING: continue locked.status Appointment.STATUS_CANCELLED locked.cancelled_at now locked.save(update_fields[status, cancelled_at]) Schedule.objects.filter(pklocked.schedule_id).update( appointed_countF(appointed_count) - 1 ) released 1 self.stdout.write(f本次释放 {released} 个号源)逻辑说明外层用filter圈定候选内层再select_for_update加锁重新校验一次状态是因为候选集合是事务外查出来的两个任务同时扫同一批数据时内层校验能保证只有第一个事务能成功释放。调度方式很简单在服务器 crontab 里写* * * * * python manage.py release_expired即可只要任务本身能幂等重复执行是安全的。4. 权限、接口与前端对接让系统真正能被用起来4.1 三种角色的权限设计数据库模型做完还要回答一个问题谁能看排班谁能挂哪个医生的号谁能改号源总量Django 自带的权限体系在User上但我们这里需要按业务角色区分而不是只靠is_staff。常见做法是普通登录用户默认是患者医生通过Doctor表关联管理员用 Django 的is_staff标识并限制只能访问后台管理界面。患者访问自己的挂号单必须校验appointment.patient request.user不能只检查“已登录”。因为用户 A 完全可能遍历接口把用户 B 的挂号单查出来。自定义权限类如下# hospitals/permissions.py from rest_framework.permissions import BasePermission, SAFE_METHODS class IsPatient(BasePermission): 患者本人可操作自己的挂号单 def has_object_permission(self, request, view, obj): return request.user.is_authenticated and obj.patient_id request.user.id class IsDoctorOrReadOnly(BasePermission): 医生可查看排班和挂自己号的患者但不能随意改排班 def has_permission(self, request, view): if request.method in SAFE_METHODS: return request.user.is_authenticated return False参数说明has_object_permission用于对象级权限DRF 在调用get_object()时会执行obj.patient_id取的是数据库外键值不触发关联查询IsDoctorOrReadOnly只允许医生查看修改排班统一通过 Django Admin 管理这样权限面更小不容易出漏洞。4.2 给前端一套够用的 REST API端点与返回结构前端小程序或 Vue 页面需要一套结构稳定的接口。端点设计我习惯按资源划分挂号这个动作单独做成一个 POST因为它涉及状态变更和号源占用不能简单归为“创建资源”。方法路径鉴权说明GET/api/departments/登录科室列表GET/api/departments/{id}/doctors/登录科室下医生列表GET/api/schedules/?doctor_iddate登录查询排班与剩余号源POST/api/appointments/患者提交挂号单body 传 schedule_idGET/api/appointments/?status患者我的挂号记录POST/api/appointments/{order_no}/cancel/患者待支付状态下取消POST/api/appointments/{order_no}/refund/患者已支付状态下退号排班接口的一个重要设计是剩余号源必须实时计算不能在前端展示“30”然后用户点了才发现没号。返回体里要携带remaining字段{ id: 123, doctor: 张医生, department: 内科, work_date: 2025-06-02, session: am, total_quota: 30, appointed_count: 28, remaining: 2 }这里的remaining用Schedule.remaining这个模型属性序列化。有个小坑如果用 ORM 对象直接序列化remaining是 Python 属性DRF 的SerializerMethodField可以读它但要注意避免 N1 查询。排班列表接口记得加select_related(doctor__user, doctor__department)否则每条排班都会多出两三次 SQL。4.3 支付回调的幂等保护支付回调这块最容易翻车。支付平台的回调顺序不保证可能先收到“支付成功”又收到“订单已关闭”这种互相矛盾的通知也可能同一笔成功通知重复投递。处理原则是以“状态是否允许迁移”为准而不是以通知本身为准。上面confirm_payment的写法已经体现了这个原则。在此基础上回调接口还应该记录原始报文方便出问题时对账。常见做法是建一张PaymentCallbackLog表每个回调都把 headers、body 原样存进去。代码不必复杂核心是一条插入语句加一个唯一索引class PaymentCallbackLog(models.Model): order_no models.CharField(max_length64) payload models.TextField() created_at models.DateTimeField(auto_now_addTrue) class Meta: indexes [models.Index(fields[order_no])]先落日志再调用状态更新逻辑。这样即使回调处理函数出了 bug原始数据还在可以事后重放排查。5. 医疗挂号系统避坑排查五个最容易翻车的地方5.1 号源超卖现象并发测试时 30 个号源开号瞬间 35 个人提示挂号成功。原因没有加行锁多个请求同时读到appointed_count29都判断可以挂号然后各自写入。本质是“先查后写”的非原子操作。解决把“查排班 → 校验余号 → 创建记录 → 自增计数”放进同一个事务并用select_for_update()锁住排班行。注意select_for_update()不能脱离事务函数必须由transaction.atomic()包裹。锁的粒度只到单个排班行并发挂不同医生号源互不阻塞。5.2 状态错乱已就诊的号还能退现象医生已经接诊完患者还能在 App 里退号号源池里多出一个多余的号。原因退号接口只校验了“订单存在”没有校验当前状态或者校验了但状态判断条件太少。refund接口没有挡住visited和cancelled状态。解决退号前先锁单检查status STATUS_PAID只允许已支付状态退号。同时把状态流转逻辑收敛到 service 层函数里不要在视图里到处手写判断。判断状态的口诀是每个状态变更都要回答“从哪个状态来、到哪个状态去、不允许从哪个状态直接跳”。5.3 排班重复生成现象管理命令跑了两遍同一个医生同一天上午出现两排排班号源变成两倍。原因生成脚本用了先 delete 再 insert或者直接create()没有利用数据库唯一约束。第一次跑完再跑一次时约束没有兜底。解决在Schedule.Meta里定义UniqueConstraint生成脚本改用get_or_create并把total_quota放进defaults。这样重复执行只会更新或跳过不会新增。这里真正兜底的是数据库约束不是业务代码判断。如果已经产生重复数据需要用脚本按分组的 id 去重然后回填appointed_count。5.4 同一秒内重复提交现象用户连点两次“立即挂号”生成了两个订单号占掉两个号源。原因前端没有做按钮防抖后端也没有防重机制。虽然每个订单的事务本身不会超卖但同一个用户被允许重复创建订单占用了多余号源。解决第一层是前端按钮 loading第二层是后端加短期幂等。常见做法是在Appointment上按patient schedule加一个条件唯一约束只在pending或paid状态生效。Django 的UniqueConstraint支持condition写起来是这样class Appointment(models.Model): # ... class Meta: constraints [ models.UniqueConstraint( fields[patient, schedule], conditionmodels.Q(status__in[pending, paid]), nameuniq_patient_schedule_active, ) ]这个约束的语义是同一患者同一排班最多只能有一条未结束pending/paid的挂号单。取消或退号后状态变更约束自动放行可以重新挂号。5.5 时区把日期切错了现象晚上 23:30 创建挂号单订单日期变成了第二天排班查询时上午的号源算到了昨天。原因项目里有的地方用datetime.now()有的地方用timezone.now()还有的地方直接用date.today()。Django 的USE_TZTrue时datetime.now()拿到的是本地无时区时间存在数据库里会被按 UTC 解释差 8 小时。日期一旦错位号源锁定和释放就全乱。解决全项目统一用django.utils.timezone.now()和timezone.localdate()不要自己 importdatetime取当前时间。业务上需要“当日日期”时用timezone.localdate()。测试环境里如果发现日期不对先查settings.py里的TIME_ZONE和USE_TZ而不是先怀疑业务代码。这个坑在本地开发时几乎不出现一部署到 UTC 服务器就翻车属于典型的部署期血泪经验。6. 上线前用并发测试和检查清单把系统验透6.1 用一段并发脚本检验超卖发版前最重要的一件事是模拟几十个用户同时挂同一个号源。下面这段脚本用 curl 并发发送 50 个请求观察最终成功次数和号源余量。# tests/concurrent_appointment.sh TOKEN登录后拿到的access_token SCHEDULE_ID3 for i in $(seq 1 50); do curl -s -X POST http://127.0.0.1:8000/api/appointments/ \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {\schedule_id\: $SCHEDULE_ID} done wait跑完去数据库里查两条指标一是Appointment里这个排班的 pending 加 paid 条数二是Schedule.appointed_count的最终值。如果号源总量是 30最终值必须恰好是 30不能多也不能少。再跑一次退款脚本把退掉的号挂回去确认appointed_count能正确减回来。并发脚本里的和wait实现并发关键是把SCHEDULE_ID保持同一个。6.2 上线前十分钟核对清单我会在每次部署前把下面这些点逐条过一遍比临时补代码管用得多select_for_update()是否都在transaction.atomic()内所有状态变更是否都经过 service 层函数视图中没有散落的status...赋值生成排班的脚本是否可重复执行重复跑不会产生重复数据支付回调的日志表是否记录原始报文服务器时区与TIME_ZONE配置是否一致有没有直接用datetime.now()的地方待支付超时释放任务是否已经在 crontab 里配置并手动跑通过一次Admin 后台是否给非管理员设了只读权限避免有人手滑改掉号源总量。我自己的习惯是数据库里预置一批测试号源专门用一个测试账号跑完“挂号 → 支付回调 → 退号 → 再挂号”全流程用脚本断言每一步的状态。这套流程每次上线前跑一遍能挡住绝大多数把号源搞乱的低级错误。希望这篇文章帮你把这个方向摸透少踩几个坑。本文还有配套的精品资源点击获取
