夜雨聆风在医院日常运营中，一个看似简单却长期困扰一线人员的问题反复出现：急诊医生被告知「某科室还有空床」，但患者实际转运过去后却无法立即入住。问题不在沟通不畅，而在于传统床位统计方式只反映「名义床位数」，忽略了大量动态、隐性、流程性的约束条件。这些隐藏在数据表单背后的「不可用」床位，被形象地称为床位「暗池」。bed-dark-pool-detector 正是为穿透这一信息黑箱而生的开源工具，它不替代医院信息系统（HIS），而是作为轻量级增强层，实时融合多源临床运营数据，构建更贴近真实业务逻辑的床位可用性模型。
项目概述：让「有床」真正等于「能住」
bed-dark-pool-detector 是一个面向医疗场景的开源软件系统，核心目标是将床位状态从静态数字还原为动态业务事实。它并非床位预约系统或电子病历模块，而是一个专注「供需匹配可见性」的分析型工具。系统通过持续采集出院记录、当前床位占用状态、跨科转科流水等三类关键运营数据，自动识别四类典型暗池情形：
已安排出院但尚未完成离院手续的床位 受专科资质限制（如仅限 ICU 医师收治）的床位 处于感染防控消杀等待期的隔离床位 患者已转入新科室但原床位未在系统中释放的“流程悬停”床位
所有这些因素共同导致名义空床数与实际可分配床位之间存在显著偏差。本项目将该偏差量化为「暗池深度」，并通过 API、命令行与可视化看板三种形式即时输出结果，辅助急诊分诊、住院登记和床位调度人员做出更可靠的决策。
技术亮点：分层清晰、开箱即用、兼顾工程与临床语义
该项目采用典型的分层架构设计，各模块职责明确，既保障了技术可维护性，也贴合医院信息系统的集成习惯。
数据适配层：兼容异构系统，降低接入门槛
医院现有系统往往由不同厂商建设，数据格式差异大。项目为此提供了标准化适配接口：- BedStatusAdapter 支持从 CSV 文件、关系型数据库（如 PostgreSQL、MySQL）或 REST API 接入实时床位状态- DischargeAdapter 和 TransferAdapter 分别处理出院与转科事件流，确保时间戳、科室编码、患者 ID 等关键字段对齐- DataLoader 统一协调多源数据加载与初步清洗，避免重复解析逻辑
引擎层：用规则+配置表达临床逻辑
可用性判断并非简单加减法，而是融合临床规则的复合计算：- AvailabilityEngine 基于配置定义的约束优先级（例如：消杀等待 > 转科未释放 > 预约未离院），逐层过滤名义空床，输出「实际可用床位数」- DarkPoolDetector 不仅计算差值，还引入异常标记机制，当某科室连续 3 小时暗池深度超过阈值，自动触发预警标识，便于人工复核- 全部规则与阈值均通过 config.yaml 或 .env 文件配置，无需修改代码即可适配不同医院的管理规范
API 与 CLI 双驱动：开发者友好，一线人员易用
系统同时提供两种交互范式：- API 层基于 FastAPI 构建，接口简洁稳定：
curl http://localhost:8000/api/dark-pool返回结构化 JSON，含各科室暗池深度、主要成因归类及置信度评分，方便嵌入医院内部工作台或大屏系统- CLI 层使用 Typer 实现，终端操作直观高效：
python cli.py recommend --patient-age 65 --urgency-level critical直接输出当前最适配的收治科室建议，支持按患者特征参数化筛选
Web 看板：聚焦关键指标，拒绝信息过载
前端采用轻量方案，无须 Node.js 构建：- 热力图展示「科室 × 时间段」维度的床位可用率趋势，帮助预判高峰压力- 甘特图追踪急诊患者从分诊到实际入住的全流程耗时，定位流转瓶颈- 暗池评分表格以颜色分级呈现各科室风险等级，并标注主导成因（如「消杀延迟」「转科滞后」）- 所有图表 30 秒自动刷新，确保决策依据始终为最新状态
技术栈选择务实克制：Python 3.11+ 提供类型安全与性能平衡；SQLAlchemy 抽象数据库访问，降低迁移成本；Chart.js 渲染图表，依赖少、体积小；Rich 库提升 CLI 输出可读性，支持彩色状态标签与进度条。
应用场景：可用于急诊协同、住院调度、质控分析等多类医院运营环节
本项目适合需要提升床位资源透明度与响应效率的各类医疗管理场景：- 急诊科分诊决策支持：当接收到新患者时，快速调用 /api/recommendations 获取实时推荐科室，减少电话反复确认- 住院处床位统筹：结合热力图与暗池评分，提前向高风险科室发出准备提示，缩短患者等待时间- 医院感染管理部门：通过消杀相关暗池数据，评估隔离床位周转效率与清洁流程合规性- 信息科系统整合：作为 HIS 或 EMR 的补充分析模块，通过标准 API 对接，不侵入主业务流程- 教学与科研：示例数据集（data/ 目录下）覆盖完整床位生命周期事件，可用于临床流程建模与算法验证
需强调的是，本系统不生成医嘱、不修改患者主索引、不对接医保结算，其定位是「洞察层」而非「执行层」，因此部署风险低、合规边界清晰。
使用指南：五分钟完成本地体验
项目开箱即用程度高，无需复杂依赖或云服务。以下为完整本地运行流程：
安装依赖
cd bed-dark-pool-detectorpip install -r requirements.txtcp .env.example .envcp config.yaml.example config.yaml根据实际数据源修改 .env 中的数据库连接串或 API 地址，调整 config.yaml 内的科室白名单与暗池阈值。
运行 CLI 快速验证
python cli.py list-beds输出当前各科室名义床位、已用床位、实际可用床位及暗池深度。
python cli.py analyze执行全量暗池检测并打印分析摘要，含最大暗池科室、高频成因分布等。
启动 Web 服务查看看板
python scripts/run_api.py服务启动后，浏览器访问 http://localhost:8000/static/index.html 即可查看交互式看板。所有图表数据均来自本地 API 接口，无外部请求。
集成自有数据源
若已有数据库，只需在 .env 中配置：
DB_URL=postgresql://user:pass@localhost:5432/hospital_db并确保 beds、discharges、transfers 三张表结构与示例 CSV 字段一致（详见 data/ 目录）。适配器将自动完成字段映射与时间解析。
总结：用开源方法解决医疗信息化中的「最后一公里」问题
bed-dark-pool-detector 并非宏大平台，而是一个精准切口的工具型项目。它直面医院运营管理中最常被忽视的细节矛盾，数据口径与业务现实之间的鸿沟。通过将临床知识（如转科流程、感控要求）转化为可配置、可验证、可量化的计算逻辑，系统把抽象的「床位紧张」具象为可追溯、可干预的具体原因。这种「小而深」的设计思路，降低了医院信息科的试用成本，也为后续对接更复杂的智能排程、预测预警等高级功能提供了可信的数据基座。
项目采用 MIT 许可证完全开源，代码结构清晰、测试覆盖完整（含 test_adapters.py、test_engine.py 等模块化单元测试），支持二次开发与私有化部署。无论是医院信息工程师希望快速验证床位分析效果，还是医疗 AI 团队需要构建下游预测模型的数据管道，它都提供了一个扎实、透明、可信赖的技术起点。
项目当前免费开源，若您对项目有疑问、使用上的困惑或想深入交流，欢迎私信我们，或加入社群讨论。
项目地址：https://github.com/nexorin9/bed-dark-pool-detector
