基于Flask的医疗设备管理系统：从选型到部署的完整实践

去年年初我接到一个挺典型的项目一家二甲医院要上一套医疗仪器设备管理系统。对接的信息科主任给我看了他们当时的家底——三张互相打架的Excel表格一台设备在A表里是在用在B表里已经报废了C表里还留着一条六年前的维修记录。最头疼的是计量强检像高压灭菌器、输液泵这类设备强检日期过期了还在病房里用这种风险没人敢担。需求听起来不复杂管台账、管维修、管校准、管报废再加上权限和记录。但真正把系统搭起来之后我才意识到这种看起来是个CRUD的项目坑全藏在细节里。这套系统我最终用Python Flask写完了就是很经典的Flask Flask-SQLAlchemy MySQL组合前端用Jinja2模板配上Bootstrap。第二期又补了Excel导入导出和到期提醒。这篇文章不是课程设计式的功能清单而是把我从选型、建表、写业务代码到上线踩坑的完整过程梳理一遍。如果你正准备做类似的设备管理系统或者想用Flask接一个中小型内部管理系统下面的内容应该能帮你少走不少弯路。1. 为什么是Flask医院设备管理系统选型复盘1.1 先搞清楚系统边界再谈框架我在动手写代码前先花了一周时间跟着设备科的人跑了一圈。医院设备管理听起来是个很垂直的领域但业务边界其实很清晰台账管理设备从采购验收入库到报废处置的全生命周期信息包括资产编号、设备名称、型号规格、出厂编号、生产厂家、采购金额、启用日期、存放科室、当前状态。维修保养报修、派单、维修、验收这个闭环每一次维修都要留得住记录包括故障现象、处理方式、更换配件、费用、维修人员和时间。计量校准与强检医院里相当一部分设备属于强检计量器具血压计、心电图机、输液泵、高压灭菌器这类到期必须校准漏检就是医疗隐患。统计报表设备总值、科室分布、维修费用、报废预警这些领导层要看。权限与审计什么人能改台账、改完留不留痕迹在医疗场景里不是可选项。这里要特别说明一下这套系统管的是设备资产和维修流程不是接医疗设备本身的运行数据血氧、心电波形那种那需要走设备接口和物联网协议完全是另一套技术栈。搞清楚这个边界很重要因为它直接决定了选型——我们要做的是一个典型的Web业务管理系统CRUD为主、报表为辅、并发量极低。1.2 Flask在这个场景下的三个优势选Flask的原因排第一的其实是够用。二三十个科室、几百个操作员系统同时在线人数通常不超过几十个性能在这个项目里从来不是瓶颈。在这个前提下Django自带Admin那种全家桶的优势体现不出来反而是Flask这种框架提供核心其他你来拼的轻量路线更灵活。再就是数据模型的自由度。医院设备管理的数据结构有很强的行业特点比如一台大型设备可能挂在科室名下但归属行政部维修记录、校准记录、折旧记录是三种不同维度的关联表。Flask-SQLAlchemy对这类一对多、多对多关系的建模非常顺手你可以完全按业务去设计模型而不是被框架的约定绑住手脚。第三个是生态。Flask的扩展库基本覆盖了内部管理系统需要的所有能力Flask-Login做登录会话Flask-Migrate做数据库迁移Flask-WTF做表单校验配合Gunicorn就能稳定跑起来。这些东西都是经历过大量项目验证的不会踩到框架选型太小众没人维护这种坑。1.3 顺便说说为什么不选FastAPI那段时间FastAPI风头很正我也确实用它写过接口语言层面我甚至更喜欢FastAPI。但在这个项目里它有几个不合适的地方这套系统需要的是服务端渲染的页面不是前后端分离的API。Flask把模板、表单、会话、路由放在一个进程里逻辑简单直接。FastAPI虽然也能返回HTML但那不是它的主场强行用它等于绕路。FastAPI的优势在异步高并发和类型校验前者我们用不上后者在表单场景里Flask-WTF已经够用。团队维护成本。后续接手系统的人大概率是医院信息科或者外包的毕业生Flask的代码结构对他们来说更友好碰到问题能找到的参考资料也更多。框架适合场景在这个项目中的短板Flask中小型业务系统、服务端渲染大型系统需要自己搭工程结构Django大型全家桶、内容管理约定多行业化数据模型不够直观FastAPIAPI服务、前后端分离模板渲染不是强项异步优势用不上结论一句话架构上没有银弹只有适不适合。这个项目体量决定了Flask是最省力的路径。2. 数据建模设备台账、状态流转与编号生成的细节2.1 核心表结构与字段设计建表之前我定了一个原则台账数据要冗余流程数据要留痕。什么意思设备属于哪个科室、放在什么位置这类信息在台账里要直接冗余存一份不能靠关联表现场算而每一次维修、校准、报废操作必须单独落一条记录不能只更新设备状态就完事。我最终的表结构大概是这样的MySQL SQLAlchemyclass Department(db.Model): __tablename__ department id db.Column(db.Integer, primary_keyTrue) name db.Column(db.String(64), uniqueTrue, nullableFalse) parent_id db.Column(db.Integer, db.ForeignKey(department.id)) manager db.Column(db.String(32)) phone db.Column(db.String(32)) class Equipment(db.Model): __tablename__ equipment id db.Column(db.Integer, primary_keyTrue) asset_no db.Column(db.String(32), uniqueTrue, nullableFalse) # 资产编号 name db.Column(db.String(128), nullableFalse) model db.Column(db.String(64)) # 型号 spec db.Column(db.String(255)) # 规格 factory_no db.Column(db.String(64)) # 出厂编号 manufacturer db.Column(db.String(128)) supplier db.Column(db.String(128)) price db.Column(db.Numeric(12, 2)) purchase_date db.Column(db.Date) enable_date db.Column(db.Date) # 启用日期 department_id db.Column(db.Integer, db.ForeignKey(department.id)) location db.Column(db.String(128)) status db.Column(db.SmallInteger, default1) # 状态见下方枚举 calibration_cycle db.Column(db.SmallInteger, default12) # 校准周期月 last_calibration_date db.Column(db.Date) next_calibration_date db.Column(db.Date) warranty_expiry db.Column(db.Date) remark db.Column(db.Text) class MaintenanceRecord(db.Model): __tablename__ maintenance_record id db.Column(db.Integer, primary_keyTrue) equipment_id db.Column(db.Integer, db.ForeignKey(equipment.id)) report_no db.Column(db.String(32)) # 报修单号 reporter db.Column(db.String(32)) report_time db.Column(db.DateTime, server_defaultdb.func.now()) fault_desc db.Column(db.Text) status db.Column(db.SmallInteger, default1) assignee db.Column(db.String(32)) assign_time db.Column(db.DateTime) repair_result db.Column(db.Text) parts_cost db.Column(db.Numeric(10, 2)) labor_cost db.Column(db.Numeric(10, 2)) finish_time db.Column(db.DateTime)几个字段设计上的关键决策我单独说一下。资产编号直接建了uniqueTrue这是全院唯一的标识任何重复都是数据事故。金额字段用Numeric(12, 2)而不是Float浮点数的精度问题在财务报表里就是事故哪怕只是设备台账也绝不妥协。next_calibration_date单独存一列不靠last_calibration_date calibration_cycle推算因为实际操作中可能存在补做校准、提前校准的情况周期会被打破单独存下一次到期日是最稳妥的。2.2 状态字段为什么用整数枚举不用字符串我见过不少项目用字符串存状态在用、已报废写得到处都是同一个状态能出现好几种叫法报废、已处置、报损统计的时候想哭。我的做法是定义一个常量类数据库里只存数字class EquipStatus: IN_STORAGE 1 IN_USE 2 IN_MAINTENANCE 3 IDLE 4 TO_SCRAP 5 SCRAPPED 6 STATUS_MAP { EquipStatus.IN_STORAGE: 在库, EquipStatus.IN_USE: 在用, EquipStatus.IN_MAINTENANCE: 维修中, EquipStatus.IDLE: 闲置, EquipStatus.TO_SCRAP: 待报废, EquipStatus.SCRAPPED: 已报废, }数据库里存数字页面展示时查STATUS_MAP筛选时下拉框绑定数字值。好处是状态的可选范围被锁死了写代码时传错一个字符串编译器查不出来但传错一个数字至少能通过查表快速暴露。而且医院设备科的人对待报废和已报废的区分异常敏感语义一旦模糊后面的报废流程全乱。2.3 设备编号生成的并发问题设备编号规则跟医院资产科确认后定的SB 四位年份 四位流水号比如SB20240001。听起来简单但这里藏着一个典型的并发问题。假如两个人同时在系统里录入新设备都执行先查当前最大流水号再1就会生成两个一模一样的编号。虽然asset_no有唯一约束第二个插入的人会直接报错但用户不会理解什么叫Duplicate entry只会说系统坏了。正确做法是让编号生成和入库在同一个事务里用数据库层面的原子操作from sqlalchemy import func # 在事务内取当前最大编号并加行锁 with db.session.begin_nested(): max_no db.session.execute( db.select(func.max(Equipment.asset_no)) .where(Equipment.asset_no.like(SB2024%)) .with_for_update() ).scalar() sequence int(max_no[-4:]) 1 if max_no else 1 equipment.asset_no fSB2024{sequence:04d} db.session.add(equipment) db.session.commit()说实话医院这种并发量实际撞车的概率很低。但在代码里养成涉及唯一性生成就必须考虑并发的习惯后面做订单编号、预约号这类并发高的场景时就不会踩同样的坑。3. 三个核心模块的落地代码档案、工单、到期提醒3.1 设备档案列表模糊检索与Excel导入导出设备列表是整套系统使用频率最高的页面。我最初做的是普通分页表格但设备科的人告诉我他们查设备的方式是模糊搜索输入监护两个字就得把心电监护仪、血氧监护仪、颅内压监护仪全列出来。所以查询逻辑组合了多个条件query Equipment.query if keyword: like f%{keyword}% query query.filter(db.or_( Equipment.name.like(like), Equipment.model.like(like), Equipment.asset_no.like(like), Equipment.manufacturer.like(like) )) if dept_id: query query.filter(Equipment.department_id dept_id) if status: query query.filter(Equipment.status status) query query.order_by(Equipment.asset_no)这个逻辑本身简单但如果一开始就想好用db.or_组合多个字段后面就不用反复在模板里加判断条件。Excel导入导出是第二期加的用openpyxl坑主要在校验环节资产编号重复要提示用户第3行和第8行编号重复而不是让数据库直接报错。科室名称映射Excel里写的是心内科数据库里是心血管内科需要做映射表转换。日期格式兼容Excel里的日期可能是字符串2024/1/5也可能是序列号要统一处理。我的做法是不管Excel里是什么格式先统一转成字符串再用datetime.strptime解析。解析失败的行把行号和原因写进一个错误清单全部校验完后一次性返回下载。3.2 维修工单状态机与设备状态联动维修模块是这套系统里最像流程的部分。我把它设计成了四步状态机待派单 - 维修中 - 待验收 - 已完成或已取消。每个状态变化后台要联动做几件事状态从待派单到维修中记录指派人、指派时间。从维修中到待验收填写维修结果、配件费用、人工费用生成完成时间。从待验收到已完成设备状态从维修中自动改回在用或闲置。这里有个容易忽略的联动设备一旦被报修它的状态应该立即变成维修中否则维修人员拿着单子到科室找设备台账上还写在用业务上是说不通的。我一开始没做这个联动设备科的人验收时当场指出来后来补了一条在报修环节就更新设备状态的逻辑。状态变化统一走一个函数避免在视图里各写各的def transition_maintenance(record, to_status, **kwargs): allowed { 1: (2,), # 待派单 - 维修中 2: (3, 5), # 维修中 - 待验收 / 已取消 3: (4,), # 待验收 - 已完成 } if to_status not in allowed.get(record.status, ()): raise ValueError(f非法状态流转: {record.status} - {to_status}) # 这里统一写字段更新、设备状态联动、操作日志这样定义状态机的最大好处是非法流转在代码层就被拦住不会出现已完成的单子还能被改成待派单这种情况。医疗设备维修是有责任追溯的状态流转一旦乱了后面查责任就是一团浆糊。3.3 强检与报废的到期提醒计量校准的到期提醒是这套系统里最贴近人命关天的功能。高压蒸汽灭菌器、输液泵这类设备如果强检过期还在使用出了问题就是重大事件。我的实现思路是查询时计算 定时任务兜底双重保障在设备列表页的查询条件里加一个临期/过期筛选把next_calibration_date在30天内或已过期的设备过滤出来。同时用一个APScheduler定时任务每天早上把临期清单推送到设备科的工作台from apscheduler.schedulers.background import BackgroundScheduler def check_calibration_due(): today date.today() due_soon Equipment.query.filter( Equipment.status.in_([2, 3]), # 只关注在用和维修中的设备 Equipment.next_calibration_date.isnot(None), Equipment.next_calibration_date today timedelta(days30) ).all() # 写入提醒表 / 给管理员发通知 scheduler BackgroundScheduler() scheduler.add_job(check_calibration_due, cron, hour8, minute0) scheduler.start()提醒逻辑有个细节必须注意已报废的设备不能参与临期计算否则统计里会出现一台报废的呼吸机明天校准到期这种让领导怀疑系统的数据。筛选条件里对status的限定就是干这个用的。4. 开发期踩过的四个坑时间、会话、附件、脏数据4.1 时间字段字符串存时间是给自己挖坑这个坑是真实的教训。最开始我为了图省事把purchase_date这类字段用String存写进去的是2024/1/5这种格式。后来要做按年份统计采购金额的报表发现SQL里YEAR(purchase_date)完全不管用只能把数据全部捞出来在Python里做正则解析。那次迁移花了整整一下午从那以后我定了条规矩所有日期字段必须用Date/DateTimeORM层统一处理。还要注意server_default和Python默认值的区别。维修记录的report_time用server_defaultdb.func.now()让数据库写当前时间而不是在Python里传datetime.now()。原因很简单数据库时钟通常更可控而且当多条记录批量插入时Python端默认值容易都是同一个时刻的同一个对象数据库端每个值才是真实的写入时间。4.2 Flask-SQLAlchemy的会话过期问题这个坑是排查时间最长的一个。现象是后台线程里想读设备表结果报了DetachedInstanceError: Instance Equipment is not bound to a Session。原因很直接Flask-SQLAlchemy默认的session生命周期和请求绑定请求结束session就关闭了ORM对象变成detached状态。定时任务里没有请求上下文直接查数据就踩雷。解决办法是给定时任务的入口都包上应用上下文def check_calibration_due(): with app.app_context(): # 所有数据库查询都放在这里 ...如果不涉及数据库查询只是处理已经取出来的数据那就明确地把ORM字段拷贝成普通dict再传给后台逻辑。这个问题的本质是搞清楚你的session归谁管理解了这一点碰到类似错误就知道往哪个方向查。4.3 上传附件与静态文件的路径问题维修单要支持上传照片和维修报告一开始我图省事用绝对本地路径保存文件结果换到另一台机器部署时所有历史附件全找不到了。正确做法是把上传路径做成配置项比如UPLOAD_FOLDER os.environ.get(UPLOAD_FOLDER, os.path.join(BASE_DIR, uploads))同时通过路由暴露文件访问URL不要依赖Flask默认的static目录。生产环境里这块目录要挂到专门的存储盘甚至对象存储上不能跟着代码走。开发环境踩的另一个坑是Flask默认的静态文件服务在生产环境性能很差图片稍微多一点页面就明显变慢。部署时把静态资源全部交给NginxFlask只处理动态请求速度提升非常明显。4.4 Excel导入时的脏数据考验前面提到导入要做校验这里专门说下脏数据的威力。医院给我们的初始Excel有1600多行第一批导入就发现了200多条问题设备名称里全角括号和半角括号混用、科室名有简称和全称两种、日期列里出现2013.5月这种格式、甚至有个别设备的金额是负数后来查是财务上的红字冲销系统里必须允许。面对这种数据最后采取的策略是导入三步走先上传做全量校验、下载错误报告、修完再导入。绝不能让错误数据在导入过程中写进一半就中断否则台账就脏了。这个原则对所有批量数据处理都适用宁可先挡一批也不能让脏数据混进正式库。5. 权限分级与操作留痕医疗场景不能靠自觉5.1 三类角色的权限设计我按实际业务把用户分成了三类系统管理员管理用户账号、科室字典、参数配置不直接操作设备台账。设备科操作员核心用户能做设备建档、编辑、维修派单、校准记录录入。科室普通用户只能查看本科室设备、提交报修申请不能改台账。Flask-Login负责登录会话权限控制自己做。我写了一个简单的角色装饰器from functools import wraps from flask_login import current_user def role_required(*roles): def decorator(fn): wraps(fn) def wrapper(*args, **kwargs): if not current_user.is_authenticated: abort(401) if current_user.role not in roles: abort(403) return fn(*args, **kwargs) return wrapper return decorator app.route(/equipment/new, methods[GET, POST]) login_required role_required(admin, operator) def equipment_new(): ...这个实现已经能挡住大多数场景。但有一点必须强调前端隐藏按钮不等于后端有权限权限校验必须落在视图函数里。有的人只在模板里用if判断显示或隐藏按钮接口照样能被人猜到URL这是做课设常见的毛病在真正的医院环境下绝对不能犯。5.2 科室数据范围权限比角色更细的一层是数据范围权限。科室普通用户不应该看到全院设备列表只能看自己科室的。实现上我在查询层统一加了一个过滤入口def get_visible_equipment_query(user): query Equipment.query if user.role staff: query query.filter(Equipment.department_id user.department_id) return query所有设备列表接口都走这个函数不在每个视图里单独写filter。单独写的问题是容易漏某个入口漏了数据就越权了这种漏洞在权限审计时非常难看。5.3 操作日志的两种实现方式一开始我用了最简单的方案在关键的增删改逻辑里手动写一行db.session.add(OperationLog(...))。后来发现维护成本高经常忘了在某些入口加代码到处都是。后来改成装饰器方案统一记录def log_action(action_desc): def decorator(fn): wraps(fn) def wrapper(*args, **kwargs): resp fn(*args, **kwargs) log OperationLog( user_idcurrent_user.id, actionaction_desc, target_idkwargs.get(equipment_id), detailrequest.form.to_dict() ) db.session.add(log) db.session.commit() return resp return wrapper return decorator用装饰器比手动埋点省心很多。但要注意视图如果抛异常得把日志记录放到异常处理或finally里否则失败的操作反而没留痕审计的时候就会有盲区。操作日志里我额外记录了修改前后的字段快照比如设备状态从在用改成维修中前后值都存下来这是审计的底线。6. 上线部署与日常维护从run()到稳定运行6.1 Gunicorn Nginx部署要点开发环境用Flask自带的app.run()完全没问题上线后不能这么跑。我采用Gunicorn做WSGI服务Nginx做反向代理和静态资源服务。Gunicorn的systemd服务配置[Unit] DescriptionEquipment Management System Afternetwork.target [Service] Userequipment WorkingDirectory/opt/equipment-system ExecStart/opt/venv/bin/gunicorn -w 2 -b 127.0.0.1:8000 app:app Restartalways [Install] WantedBymulti-user.target几个实际部署时注意的点-w 2是worker数一般按CPU核数乘2加1来设但内部系统流量小2个就够开多了反而占内存。绑定地址是127.0.0.1:8000不要让Gunicorn直接对外暴露外面统一走Nginx。Flask的SecretKey、数据库连接串放在环境变量或配置文件里不能写死在代码仓库。Nginx配置里关键是两个locationlocation /static/ { alias /opt/equipment-system/static/; expires 7d; } location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }proxy_set_header X-Forwarded-For必须有否则应用拿不到用户真实IP操作日志里记录的地址全是127.0.0.1。别小看这个审计时需要真实IP的场景很多。6.2 数据库备份与恢复医院系统的数据比代码值钱得多设备台账一旦丢了恢复成本不可想象。我的备份策略是每天凌晨用mysqldump全量备份保留最近30天备份文件同时存本地和另一台机器0 2 * * * mysqldump -u equipment -p*** equip_db | gzip /backup/equip_$(date \%Y\%m\%d).sql.gz恢复也一定要演练。我在部署完成后做过一次完整的恢复测试从备份文件恢复到一台干净的机器确认应用能正常启动、设备列表数据完整。演练的意义在于真正出事的时候你会发现自己既不知道备份文件放在哪也忘了恢复命令怎么写。这种事不能等出了事故再准备。6.3 上线前的检查清单我自己总结了一张清单之后每次部署类似的Flask项目都会过一遍debugFalse不然报错页面会把堆栈信息打印给用户这是安全隐患。更换默认的SecretKey不能留着Flask教程里的默认值。数据库迁移用Flask-Migrate把模型变更生成迁移脚本不在线上手改表结构。时区统一为Asia/Shanghai数据库连接串里显式指定。上传目录权限严格控制防止任何人都能上传可执行文件。定时任务确认单实例运行防止多个worker并发执行导致提醒消息重复推送。这些不是高深技术但每一项都对应着真实的事故。系统稳定运行比功能花哨重要得多这是设备管理系统这类B端项目最核心的价值观。做完这个项目之后我最大的感受是医疗仪器设备管理系统本质上不是一个技术难的项目而是一个业务细节难的项目。你花在理解设备科工作流程上的时间远远多于写代码的时间。如果你正在做类似的系统我建议先花几天跟着业务人员跑一跑看看他们是怎么工作的这比任何框架选型都重要。最后再留一个小技巧设备台账的字段不要一次设计得太满运营过程中一定会不断有新的字段需求用Flask-Migrate保持迁移能力比一开始追求大而全要实在得多。