本项目是面向医院护理管理一线的智能调度工具，专为解决人工床位分配中「科主任偏好难落实、感染隔离易疏漏、护理等级常错配、性别分区易违规」等高频合规风险而设计。我们采用 Google OR-Tools 的 CP-SAT 约束规划求解器作为核心引擎，将床位分配转化为可验证、可追溯、可复现的数学优化问题；输出结构化 JSON 结果、Excel 报表和交互式 HTML 甘特图三类交付物，全部通过命令行一键生成。系统支持硬约束（必须满足，否则方案无效）与软约束（按权重惩罚，支持权衡取舍）双层建模，覆盖性别分区、感染隔离、护理等级匹配、动态时间窗、床位占用状态五大刚性规则，以及科主任偏好、同科室分配、位置偏好、护理等级精确匹配四大柔性目标。技术栈以 Python 3.10+ 为基础，集成 SimPy 做仿真验证、Click 构建 CLI、Rich 实现彩色终端反馈、Jinja2 渲染甘特图模板、Chart.js 驱动前端可视化、openpyxl 导出结构化报表，所有模块均按医疗排班场景深度定制，不依赖 Web 服务或数据库，开箱即用。

定位与能力范围

我们不做通用资源调度平台，也不做轻量级床位看板。本系统明确聚焦于「住院部护士长每日晨会前的床位预分配」这一具体动作：输入当日待入院患者清单、全院可用床位清单、当前约束配置，输出一份带原因分析、可筛选、可打印、含违背报告的推荐方案。它不替代医生下达医嘱，不干预信息系统床位状态同步，也不承担病历质控或医保结算，它的边界非常清晰：在数据已就绪的前提下，把「人脑权衡」变成「模型推演」，把「经验试错」变成「约束显式化」。所有硬约束一旦违反，求解器直接判定方案不可行；所有软约束违背均量化为惩罚值，供管理者判断是否接受折中方案。尤其关键的是，我们内置了帕累托前沿（Pareto Frontier）多目标优化模式，当「最小化未分配人数」与「最小化总惩罚」存在天然冲突时，系统可一次性给出多个非支配解，由护士长根据当日人力、感控压力、科室负荷等现实因素拍板选择。

核心功能

多约束建模：硬规则保底线，软目标促优化

硬约束是系统运行的“安全阀”，任何一项不满足，方案即被拒绝：
- 性别分区：男患者仅可分配至男床或不限性别床位，女患者同理；
- 感染隔离：is_infected=true 的患者必须分配至 is_isolated=true 的床位；
- 护理等级匹配：患者所需等级 ≤ 床位提供等级（特级 > 一级 > 二级 > 三级），允许降级但禁止越级；
- 床位占用状态：is_occupied=true 的床位不可参与本次分配；
- 动态时间窗：支持在 bed_inventory.json 中为每张床定义 time_slots，标记手术、清洁等不可用时段。

软约束则构成优化目标，其权重可配置（默认科主任偏好=10，同科室=8，位置偏好=5，等级精确匹配=3），违背时计入总惩罚值，用于排序与帕累托分析：

软约束名称	默认权重	违背示例	惩罚值
preferred_beds	10	科主任指定XN-102床，患者却被分到XN-105	15
department_assignment	8	心内科患者被分到呼吸科区域	12
position_preference	5	患者要求靠窗，实际分配中间位	10
nursing_level_exact	3	特级患者分配至一级床（降级）	3

甘特图可视化：浏览器打开即用，审阅决策有据可依

生成的 gantt_output.html 是交付核心界面，无需部署服务器，双击即可在 Chrome/Firefox 打开：
- 支持按科室、护理等级、性别三重下拉筛选，快速定位某类患者分布；
- 分页控制支持 25/50/100/200 条每页，适配不同屏幕尺寸；
- A4 横向打印样式已内嵌，导出 PDF 后可直接归档或张贴；
- 顶部固定显示「未分配患者列表及失败原因」，如「P007：无可用特级隔离床」；
- 底部嵌入「软约束违背报告表格」，逐条列出患者ID、违背项、对应惩罚值；
- 甘特图主体以床位为横轴、时间为纵轴（单日视图），色块颜色严格映射护理等级（特级深红/一级番茄红/二级橙色/三级浅绿）与性别（男蓝/女粉），一目了然。

CLI 交互界面：面向运维人员的可靠操作入口

所有功能通过 bed-scheduler 命令统一驱动，终端输出全程彩色化、进度可视化：
- bed-scheduler demo：零配置启动，加载内置示例数据，3秒内完成全流程演示；
- bed-scheduler allocate：生产环境主命令，支持 --time-limit 控制求解上限（默认30秒）、--pareto 启用多目标优化、--format json/simple 切换输出粒度；
- bed-scheduler validate：独立校验模块，提前发现数据格式错误、字段缺失、约束逻辑矛盾等隐患；
- 日志分级明确：WARNING（默认，只显示进度条与摘要）、-v（INFO，展示数据统计与约束摘要）、-vv（DEBUG，输出每张床/每位患者的完整属性与约束匹配过程）。

使用与配置

三步启动：数据准备 → 命令执行 → 结果审阅

系统完全离线运行，所有输入均为标准文本文件：
- 床位数据存于 data/bed_inventory.json，需包含 bed_id、gender、is_isolated、nursing_level、is_occupied、time_slots 字段；
- 患者数据存于 data/patients.json，需包含 patient_id、gender、department、nursing_level_required、is_infected、position_preference 字段；
- 约束规则存于 data/constraints_config.yaml，可开关各项硬/软约束，并调整权重与优先级。

安装与运行只需两步：

pip install -r requirements.txt
pip install -e .

执行分配：

bed-scheduler allocate \
  --beds data/bed_inventory.json \
  --patients data/patients.json \
  --constraints data/constraints_config.yaml \
  --output result/

结果目录 result/ 下自动生成三类文件：
- gantt_output.html：甘特图主界面；
- allocation_result.json：结构化结果，含 assignments、unassigned、metadata 三部分；
- allocation_report.xlsx：Excel 报表，含「分配总表」「软约束违背报告」「未分配患者」三个工作表。

工程结构

代码组织严格遵循职责分离原则，每个子模块专注单一能力：
- src/models/：定义 Bed、Patient、ConstraintConfig 三类数据模型，字段与 JSON/YAML 输入一一映射；
- src/data/loader.py：统一加载器，自动校验必填字段、类型转换（如 nursing_level 字符串转枚举）、缺失值填充；
- src/solver/：CP-SAT 核心，cp_sat_formulator.py 将业务约束转为布尔变量与线性表达式，cp_sat_solver.py 封装求解流程与超时控制；
- src/engine/scheduler.py：调度引擎，协调数据加载、模型构建、求解调用、结果后处理四阶段；
- src/visualization/gantt_generator.py：基于 Jinja2 渲染 HTML，Chart.js 动态绘图，所有筛选逻辑由前端 JavaScript 完成；
- src/cli/commands.py：Click 命令注册中心，各子命令（demo/allocate/validate）逻辑解耦，便于单元测试与灰度发布。

环境与运行

系统对运行环境要求极简，仅需 Python 3.10+ 及标准科学计算依赖：
| 组件 | 版本要求 | 作用 |
|------|-----------|------|
| Python | ≥ 3.10 | 运行时基础 |
| OR-Tools | ≥ 9.8 | CP-SAT 求解器核心 |
| Rich | ≥ 13.0 | 彩色终端渲染与进度条 |
| Click | ≥ 8.0 | CLI 命令解析框架 |
| Jinja2 | ≥ 3.0 | HTML 模板渲染 |
| Chart.js | CDN 加载 | 前端甘特图绘制 |
| openpyxl | ≥ 3.1 | Excel 报表导出（可选） |

无外部服务依赖，不写数据库，不启 HTTP 服务，所有状态保存于内存与输出文件。Windows/macOS/Linux 全平台支持，Docker 镜像亦可按需构建（脚本位于 scripts/ 目录）。

限制与说明

本系统不解决以下问题：
- 不替代 HIS 系统床位状态同步，需确保 bed_inventory.json 中 is_occupied 字段实时准确；
- 不提供床位预约、退床、转科等动态变更逻辑，仅处理「静态快照」下的单次分配；
- 不支持跨日连续排程（如术后三天需固定床），时间窗仅限单日内分段标记；
- 甘特图中「时间」维度仅为视觉分组标识，非真实时间轴（暂不支持多日滚动视图）。

所有约束逻辑与字段含义均在项目文档中明确定义，例如 nursing_level 的等级顺序（特级 > 一级 > 二级 > 三级）、position_preference 的合法取值（"window"/"door"/"middle"）、time_slots 的 ISO 8601 时间格式要求等，均无需猜测，查文档即得。

项目地址：
https://github.com/nexorin9/bed-allocation-optimizer