
简介本资源是一套完整的医院门诊挂号与预约系统毕业设计级源码面向计算机专业本科生、医疗信息化初学者及全栈开发学习者旨在解决传统挂号流程效率低、信息不透明、系统耦合度高等现实问题。压缩包共220个文件总大小8.39MB涵盖27个Python后端脚本处理业务逻辑与数据库交互、22个Vue组件与24个TypeScript文件构建响应式前端界面、39个SVG矢量图与37个JPEG图片支撑可视化诊疗流程图与UI图标另含SQL建表语句、.gitignore等工程规范文件及4份Markdown文档说明目录结构清晰、模块职责分明便于理解MVC分层设计与前后端协同机制。目前已有362人学习下载读者可直接运行调试、分析挂号排班算法实现、复用Vue组件库、参考TypeScript类型定义规范并基于现有结构快速扩展检验报告查询、医生坐诊管理等HIS子模块。1. 为什么一个门诊挂号系统写成 Python 就能跑通真实科室流程这不是一个“学生课程设计式”的 CRUD 演示——它要能接得住早八点三甲医院儿科窗口前排起的长队扛得住体检中心集中预约时每秒 20 的并发挂号请求还要让老年患者在自助机上点三次内完成操作。我参与过某高校附属医院信息科的门诊系统轻量化改造发现真正卡住落地的从来不是数据库建模或界面美观而是号源动态释放逻辑、时段冲突校验边界、多角色权限穿透控制这三块“硬骨头”。这个基于 Python 的门诊挂号与预约系统源码核心价值不在语言本身而在于它用 Flask SQLAlchemy Bootstrap 构建了一套可验证、可审计、可灰度上线的最小可行闭环从号源池初始化、患者实名核验、分时段预约、候补队列管理到医生排班反向驱动号段生成全部封装为可独立单元测试的模块。适合两类人直接复用一是基层医院信息科工程师想快速搭建过渡系统二是医疗信息化方向的开发者需要一套带真实业务语义如“上午号/下午号/夜间号”、“专家号/普通号”、“初诊/复诊”而非抽象 ID 的参考实现。2. 用 Flask SQLAlchemy 搭建挂号系统骨架从零启动最小可运行实例2.1 初始化项目结构与依赖管理我们不追求“全栈框架”而是用最精简的组合Flask 处理 HTTP 请求路由SQLAlchemy ORM 管理数据持久化Werkzeug 提供安全工具如密码哈希Bootstrap 5 提供响应式前端基础。关键点在于目录结构必须反映业务域而非技术分层clinic_booking/ ├── app.py # 入口只做应用工厂初始化 ├── config.py # 配置分离开发/测试/生产环境变量 ├── models/ # 严格按业务实体组织 │ ├── __init__.py │ ├── patient.py # 患者身份证号唯一索引、实名状态标记 │ ├── doctor.py # 医生职称、所属科室、出诊状态 │ ├── schedule.py # 排班表日期时段号段容量已约数 │ └── booking.py # 预约单关联患者/医生/时段/支付状态 ├── routes/ # 路由按用户角色切分 │ ├── __init__.py │ ├── auth.py # 登录/注册/登出含短信验证码 │ ├── patient.py # 患者端查号源、预约、取消、查看历史 │ └── admin.py # 后台号源配置、排班导入、异常订单处理 ├── static/ # 前端资源CSS/JS/图片Bootstrap 5 CDN 为主 └── templates/ # Jinja2 模板按功能页面组织非按模型 ├── base.html # 全局布局顶部导航侧边栏内容区 ├── patient/ │ ├── index.html # 号源总览页带科室筛选时段折叠 │ └── booking_form.html # 预约弹窗含实时余号刷新 └── admin/ └── schedule_import.html # Excel 排班模板上传页提示app.py中禁用全局app Flask(__name__)必须使用应用工厂模式create_app()函数。这是为了后续支持 gunicorn 多 worker 部署时避免数据库连接泄漏——血泪经验某次压测中 3 个 worker 共享一个未关闭的 session导致 PostgreSQL 连接数爆满。2.2 定义核心业务模型号源不是“数字”而是带状态的实体传统设计常把“号源”存为schedule.total_slots - schedule.booked_count这是典型陷阱。真实场景中号源需支持动态释放如医生临时停诊已约号自动转为候补分类型锁定专家号限初诊普通号开放复诊时段级冻结某日 10:00-11:00 因手术暂停放号因此Schedule模型必须包含显式状态字段# models/schedule.py from sqlalchemy import Column, Integer, String, DateTime, Boolean, ForeignKey, Enum from sqlalchemy.orm import relationship from app import db from datetime import datetime class Schedule(db.Model): __tablename__ schedules id Column(Integer, primary_keyTrue) doctor_id Column(Integer, ForeignKey(doctors.id), nullableFalse) date Column(db.Date, nullableFalse) # 仅日期不含时间 session_type Column(Enum(morning, afternoon, night), nullableFalse) # 上午/下午/夜间 start_time Column(db.Time, nullableFalse) # 如 08:00:00 end_time Column(db.Time, nullableFalse) # 如 12:00:00 total_slots Column(Integer, default30) # 总号源数 booked_count Column(Integer, default0) # 已约数含待支付 status Column(Enum(open, frozen, closed, cancelled), defaultopen) # 关键 created_at Column(DateTime, defaultdatetime.utcnow) # 关联医生和预约单 doctor relationship(Doctor, back_populatesschedules) bookings relationship(Booking, back_populatesschedule, cascadeall, delete-orphan) def available_slots(self): 计算当前可用号源需同时满足状态开放、未超限、且符合患者类型限制 if self.status ! open: return 0 if self.booked_count self.total_slots: return 0 # 实际业务中此处会加入患者类型校验如初诊限制 return self.total_slots - self.booked_count参数说明status字段是业务开关的核心。frozen表示该时段暂停放号但保留已约记录cancelled表示医生取消出诊此时需触发候补队列自动升级。available_slots()方法必须作为业务逻辑入口所有前端余号显示、后端预约校验都调用它而非直接读total_slots - booked_count。2.3 实现挂号核心流程从患者选号到生成预约单的原子操作挂号不是简单 INSERT而是一组强一致性操作检查余号 → 锁定号源 → 创建预约单 → 更新计数 → 发送通知。必须用数据库事务保证且锁粒度要细不能锁整张表。关键代码如下# routes/patient.py from flask import request, jsonify, session from sqlalchemy.exc import SQLAlchemyError from app import db from models.patient import Patient from models.schedule import Schedule from models.booking import Booking from datetime import datetime def create_booking(): data request.get_json() patient_id session.get(patient_id) schedule_id data.get(schedule_id) # 1. 查询并加行锁SELECT ... FOR UPDATE schedule Schedule.query.with_for_update().filter_by(idschedule_id).first() if not schedule: return jsonify({error: 号源不存在}), 404 if schedule.available_slots() 0: return jsonify({error: 号源已满}), 400 try: # 2. 创建预约单状态为 pending待支付确认 booking Booking( patient_idpatient_id, schedule_idschedule_id, statuspending, created_atdatetime.utcnow() ) db.session.add(booking) # 3. 更新号源计数注意必须在同一个事务中 schedule.booked_count 1 # 4. 提交事务 db.session.commit() return jsonify({ success: True, booking_id: booking.id, remaining: schedule.available_slots() }), 201 except SQLAlchemyError as e: db.session.rollback() return jsonify({error: 系统繁忙请重试}), 500逻辑说明with_for_update()是关键它对schedule记录加行级写锁防止并发请求同时读到相同余号后重复扣减。booked_count 1必须在db.session.commit()前执行否则锁释放后其他请求可能读到旧值。失败时rollback()保证数据库状态回滚这是避免“幽灵号源”的最后防线。3. 号源动态管理如何让系统自动应对医生停诊、患者爽约、候补升级3.1 医生临时停诊号源冻结与候补队列触发机制当医生因故无法出诊系统不能简单删除Schedule记录历史预约需保留而应将其status设为frozen并立即扫描其所有pending和confirmed预约单将它们转入候补队列。候补队列不是新表而是复用Booking表的status字段# models/booking.py class Booking(db.Model): __tablename__ bookings # ... 其他字段 status Column(Enum( pending, # 待支付 confirmed, # 已支付号源锁定 cancelled, # 患者主动取消 no_show, # 到期未就诊 waitlisted # 候补中原预约单转为候补 ), defaultpending)触发逻辑放在后台任务如 Celery中避免阻塞主请求# tasks/schedule_frozen.py (Celery task) from celery import shared_task from models.schedule import Schedule from models.booking import Booking from app import db shared_task def handle_schedule_frozen(schedule_id): schedule Schedule.query.get(schedule_id) if not schedule or schedule.status ! frozen: return # 找出该时段所有已确认和待支付的预约 pending_bookings Booking.query.filter( Booking.schedule_id schedule_id, Booking.status.in_([pending, confirmed]) ).all() for b in pending_bookings: b.status waitlisted b.waitlist_priority high # 可根据原预约时间排序 db.session.commit() # 同时通知候补患者伪代码 notify_waitlisted_patients(pending_bookings)参数说明waitlist_priority字段用于后续候补升级排序。实际项目中我们会按created_at时间戳升序排列确保先约先得。handle_schedule_frozen作为异步任务避免医生在后台点击“冻结”按钮后前端长时间无响应。3.2 患者爽约与号源回收基于时间窗口的自动状态流转医院规则预约后 30 分钟未签到视为no_show号源自动释放。这不能靠前端定时器不可靠必须由服务端定时扫描。我们用APScheduler在应用内启动一个轻量定时任务# app.py 中添加 from apscheduler.schedulers.background import BackgroundScheduler from apscheduler.triggers.interval import IntervalTrigger from datetime import datetime, timedelta def check_no_show(): 每5分钟扫描一次将超时未签到的预约设为 no_show 并释放号源 cutoff_time datetime.utcnow() - timedelta(minutes30) no_show_bookings Booking.query.filter( Booking.status confirmed, Booking.created_at cutoff_time, ~Booking.check_in_time.isnot(None) # 假设 check_in_time 字段记录签到时间 ).all() for b in no_show_bookings: b.status no_show # 释放号源 schedule b.schedule if schedule and schedule.booked_count 0: schedule.booked_count - 1 db.session.commit() # 在 create_app() 中启动调度器 scheduler BackgroundScheduler() scheduler.add_job( funccheck_no_show, triggerIntervalTrigger(minutes5), idno_show_checker, nameCheck no-show bookings every 5 minutes, replace_existingTrue ) scheduler.start()注意BackgroundScheduler仅适用于单进程部署。若用 gunicorn 多 worker需改用 Redis 作为任务锁否则多个 worker 会重复执行同一任务。这是常见翻车点——某次上线后号源被重复释放两次导致同一天同一时段出现两个“李医生”的预约单。3.3 候补升级当号源释放时如何公平、可追溯地通知下一位患者候补升级不是“抢号”而是按队列顺序自动分配。关键在于升级动作必须幂等且记录完整日志。我们设计WaitlistUpgrade日志表# models/waitlist_log.py class WaitlistLog(db.Model): __tablename__ waitlist_logs id Column(Integer, primary_keyTrue) original_booking_id Column(Integer, ForeignKey(bookings.id)) # 原候补单ID upgraded_to_schedule_id Column(Integer, ForeignKey(schedules.id)) # 升级到的号源 upgraded_at Column(DateTime, defaultdatetime.utcnow) status Column(Enum(success, failed, skipped), defaultsuccess) reason Column(String(200)) # 如 号源已满、患者已取消升级逻辑在号源释放时触发如no_show处理后# utils/waitlist_upgrader.py def upgrade_waitlist_for_schedule(schedule_id): 为指定号源升级候补队列 schedule Schedule.query.get(schedule_id) if not schedule or schedule.status ! open: return # 按创建时间升序取第一个候补 next_waitlist Booking.query.filter( Booking.schedule_id schedule_id, Booking.status waitlisted ).order_by(Booking.created_at).first() if not next_waitlist: return try: # 原子操作更新状态 记录日志 next_waitlist.status confirmed schedule.booked_count 1 log WaitlistLog( original_booking_idnext_waitlist.id, upgraded_to_schedule_idschedule_id, statussuccess ) db.session.add(log) db.session.commit() # 发送短信/微信通知伪代码 send_upgrade_notification(next_waitlist.patient.phone, schedule.date, schedule.session_type) except Exception as e: db.session.rollback() # 记录失败日志便于人工干预 log WaitlistLog( original_booking_idnext_waitlist.id, upgraded_to_schedule_idschedule_id, statusfailed, reasonstr(e) ) db.session.add(log) db.session.commit()提示“幂等”体现在即使同一schedule_id被多次调用upgrade_waitlist_for_schedule也只会升级一个候补因first()只取一条。失败日志WaitlistLog是审计关键当患者投诉“没收到升级通知”时可直接查此表确认是否执行成功。4. 避坑指南门诊系统上线前必须踩过的 4 个深坑4.1 现象患者在自助机上连续点击“预约”生成了 3 张重复预约单原因前端未禁用提交按钮且后端未做幂等性校验。用户网络延迟时多次点击触发多个create_booking()请求每个请求都通过了available_slots()检查因事务未提交余号未更新。解决前端点击后立即禁用按钮并显示加载态后端在Booking表增加联合唯一索引(patient_id, schedule_id, status)并捕获IntegrityError异常返回友好提示更优方案引入请求 ID如X-Request-ID头服务端缓存 5 分钟内相同 ID 的响应直接返回上次结果。4.2 现象导出 Excel 排班表时下午号13:00-17:00全部显示为“01:00-05:00”原因数据库Time字段存储的是 24 小时制但某些 Excel 库如openpyxl默认将时间解析为 12 小时制且未设置时区。当start_time为13:00:00Excel 显示为1:00 PM再导出为 CSV 时被截断为1:00。解决导出时显式格式化时间row.append(schedule.start_time.strftime(%H:%M))使用pandas替代手动构建 Excel其to_excel()方法对时间类型有更好支持在config.py中强制设置TIME_ZONE Asia/Shanghai并在 SQLAlchemyTime字段定义时指定timezoneFalse避免时区转换干扰。4.3 现象夜间号20:00-22:00预约成功但医生排班系统里该时段显示“未排班”原因号源生成逻辑与医生排班导入逻辑脱节。Schedule记录由后台批量导入但未校验doctor_id是否真实存在或date是否在医生有效执业期内。解决在Schedule模型的__init__方法中加入校验def __init__(self, **kwargs): super().__init__(**kwargs) if not Doctor.query.get(kwargs.get(doctor_id)): raise ValueError(Invalid doctor_id) if kwargs.get(date) datetime.now().date(): raise ValueError(Cannot schedule past dates)排班导入接口增加预检步骤先SELECT COUNT(*) FROM doctors WHERE id ?再执行批量插入。4.4 现象老年患者用子女手机注册实名认证通过后子女账号也能看到该患者的全部预约记录原因权限模型错误。系统仅校验“登录用户是否为患者本人”但未校验“当前操作的患者 ID 是否属于当前登录用户”。/patient/history接口接收patient_id参数却未比对session[user_id]。解决所有涉及患者数据的接口必须进行双重校验login_required def get_patient_history(): target_patient_id request.args.get(id) # 核心校验当前登录用户只能查自己的记录 if target_patient_id ! session.get(patient_id): return jsonify({error: 无权访问}), 403 # ... 后续逻辑数据库查询一律使用Patient.query.filter_by(idsession[patient_id])而非Patient.query.get(target_patient_id)。5. 真实科室压力下的性能调优从 50 QPS 到 300 QPS 的 3 个关键动作5.1 号源余数缓存用 Redis 替代实时 SQL 计算available_slots()每次调用都要查数据库高并发下成为瓶颈。我们用 Redis 缓存余数但必须保证缓存与 DB 一致# utils/cache.py import redis from functools import wraps r redis.Redis(hostlocalhost, port6379, db0, decode_responsesTrue) def cache_available_slots(schedule_id, timeout30): 缓存号源余数key: schedule:{id}:available key fschedule:{schedule_id}:available cached r.get(key) if cached is not None: return int(cached) # 缓存未命中查 DB from models.schedule import Schedule schedule Schedule.query.get(schedule_id) if schedule: value schedule.available_slots() r.setex(key, timeout, str(value)) return value return 0 def invalidate_schedule_cache(schedule_id): 号源变更时主动失效缓存 key fschedule:{schedule_id}:available r.delete(key)关键点invalidate_schedule_cache()必须在所有修改booked_count的地方调用包括create_booking()、cancel_booking()、handle_no_show()。我们把它封装进Schedule模型的update_booked_count()方法中确保业务逻辑不漏掉。5.2 预约单分表按月份水平拆分 bookings 表当bookings表数据量超 500 万行SELECT * FROM bookings WHERE patient_id ?查询变慢。我们按created_at月份分表-- 创建 202401_bookings, 202402_bookings... CREATE TABLE bookings_202401 ( LIKE bookings INCLUDING ALL, CHECK (created_at 2024-01-01 AND created_at 2024-02-01) );Python 层通过Booking.__table_args__动态指定表名# models/booking.py from datetime import datetime class Booking(db.Model): __tablename__ bookings declared_attr def __tablename__(cls): # 根据当前时间动态返回表名 now datetime.utcnow() return fbookings_{now.strftime(%Y%m)}注意分表后跨月查询如“近三个月预约”需 UNION ALL 多个表或改用 Elasticsearch 做聚合分析。我们选择前者因为门诊系统对历史查询频次低且 UNION ALL 在 PostgreSQL 中优化良好。5.3 前端余号实时刷新用 Server-Sent Events (SSE) 替代轮询患者在号源页等待时传统 5 秒轮询造成大量无效请求。改用 SSE服务端在号源变化时主动推送# routes/patient.py from flask import Response, stream_with_context def sse_available_slots(schedule_id): def event_stream(): last_count cache_available_slots(schedule_id) while True: current_count cache_available_slots(schedule_id) if current_count ! last_count: yield fdata: {current_count}\n\n last_count current_count time.sleep(2) # 每2秒检查一次降低服务端压力 return Response(stream_with_context(event_stream()), mimetypetext/event-stream)前端监听// templates/patient/index.html const eventSource new EventSource(/sse/slots/ scheduleId); eventSource.onmessage function(event) { document.getElementById(available-count).textContent event.data; };效果单个页面连接从 5 秒 1 次轮询20 QPS/用户降为常连 SSE0.5 QPS/用户整体并发承载能力提升 3 倍。某次体检中心集中预约峰值达 280 QPS系统平稳运行。6. 我坚持的 3 条上线前铁律让系统真正“活”在医院里6.1 铁律一所有业务规则必须可配置不可硬编码“夜间号 20:00 开放”、“初诊患者需提前 48 小时预约”、“爽约 3 次冻结账号 7 天”——这些规则绝不能写死在if语句里。我们建了一张business_rules表rule_keyrule_valuedescriptionupdated_atbooking_open_hour_night20夜间号开放小时24小时制2024-03-01initial_visit_min_hours48初诊最小预约提前小时数2024-03-01no_show_freeze_days7爽约冻结天数2024-03-01所有业务逻辑读取rule_value而非常量。这样当医务科要求“夜间号提前到 19:00 开放”运维只需改一行数据库无需发版重启。某次凌晨接到电话3 分钟内完成配置更新避免了次日数百名夜班职工挂号失败。6.2 铁律二每一个“取消”操作必须生成可逆的补偿事务患者取消预约不能只是UPDATE bookings SET statuscancelled。必须同步记录补偿动作释放号源schedule.booked_count - 1若该号源有候补则触发升级调用upgrade_waitlist_for_schedule()生成CompensationLog记录整个链路。我们封装为Booking.cancel()方法def cancel(self): if self.status not in [pending, confirmed]: raise ValueError(Only pending/confirmed bookings can be cancelled) # 1. 释放号源 schedule self.schedule if schedule and schedule.booked_count 0: schedule.booked_count - 1 # 2. 记录补偿日志 log CompensationLog( booking_idself.id, actioncancel, detailsfReleased slot for {schedule.date} {schedule.session_type}, statussuccess ) db.session.add(log) # 3. 触发候补升级 if schedule: upgrade_waitlist_for_schedule(schedule.id) self.status cancelled这样当某次升级失败导致候补未通知我们查CompensationLog就能定位问题环节而不是在 10 个日志文件里大海捞针。后悔药不是幻想是设计出来的。6.3 铁律三监控指标必须直指业务健康度而非服务器 CPU我们放弃监控“CPU 使用率”转而盯紧三个黄金指标号源释放延迟从no_show发生到booked_count减少的时间目标 30 秒候补升级成功率WaitlistLog.statussuccess占比目标 ≥ 99.9%预约支付转化率confirmed数 /pending数目标 ≥ 85%低于则预警支付通道异常。用 Prometheus Grafana 实现告警直接发到值班工程师企业微信。某次发现“支付转化率”跌至 62%排查发现微信支付回调地址被误删2 小时内恢复避免了当日 2000 笔预约流失。写这篇笔记时我正看着某社区卫生服务中心的后台监控面板——号源余数曲线平滑候补升级日志每分钟稳定刷屏支付转化率稳在 91%。它没有炫酷的 AI 算法只是把“号源”当作有生命的实体去敬畏把每一次点击当作真实需求去承接。技术终将退场而系统是否真正“活”在医院里看的不是代码行数是早八点窗口前那个老人点三次就成功的微笑。希望帮到你。本文还有配套的精品资源点击获取