本项目是一个专为临床护理场景设计的自动化排班工具，它把交班时间点作为刚性边界、把长期医嘱的执行间隔作为优化核心，用 Google OR-Tools 的 CP-SAT 求解器生成合法且贴近实际工作习惯的时间表。我们不做经验式拖拽排班，也不依赖人工试错；而是把护士交接班规则、医嘱类型约束（如 Q4H、BID）、班次时长分布、单班任务上限、时间偏差容忍度等全部写成可验证的逻辑条件，交由求解器在数秒内给出满足全部硬约束、逼近软目标的排班方案。交付形态是命令行（CLI）主入口，支持 YAML 配置、JSON/CSV/HTML 多格式导出，含冲突检测、负载统计、可视化热力图与时间轴。技术栈以 Python 3.10+ 为基础，关键依赖包括 or-tools（约束建模与求解）、rich（终端交互）、pyyaml（配置解析）和 jinja2（HTML 渲染），所有模块按职责分层，结构清晰可扩展。

定位与能力范围

我们明确不覆盖护士人力排班（谁上哪天哪班）、不处理临时医嘱或口头医嘱、不对接 HIS 或电子病历系统实时接口。本项目的边界非常聚焦：只解决「已确定班次、已分配护士、已有长期医嘱」前提下的「具体执行时刻」生成问题。也就是说，当护士站已经知道今天白班有 3 人、夜班有 2 人，每位患者有哪些 Q4H、TID、Q12H 类型的医嘱，系统就负责算出，这些医嘱该在什么时间点由哪位护士执行，才能既不跨交班、不超负荷、不违反间隔要求，又让工作量尽量均衡、执行时间尽量靠近护士习惯时段。

这个定位决定了它天然适配两类使用者：一是护理信息系统的开发者，可将本项目作为排程引擎嵌入自有平台；二是科室护士长或信息科人员，可直接用 CLI 快速生成试点排班、验证规则合理性、输出 HTML 报告供晨会讨论。

核心功能

所有功能都围绕“生成—验证—呈现—调整”闭环展开，不是一次性脚本，而是可反复迭代的排程工作流：

功能类别	具体能力	说明
排程生成	generate  子命令	支持指定患者数、医嘱数、天数、班次配置；可干运行（--dry-run）跳过求解，快速检查输入合法性
结果查看	show-schedule  子命令	表格化展示完整排班；支持按护士 ID、按班次、按日期筛选；默认带颜色标识任务类型与时间偏差
合规验证	validate  子命令	对已有 JSON 排班文件做全量硬约束校验（如是否跨班次、是否超任务上限、间隔是否达标），输出通过/失败详情
冲突分析	conflict-report  子命令	单独列出时间间隔冲突、班次边界冲突、护士负载超限等异常项；加 --show-intervals 可标出每条医嘱的实际执行窗口与理论窗口偏差
统计洞察	schedule-inspector  子命令	统计每位护士日均任务数、各班次总任务量、医嘱类型分布、时间集中度（热力图基础数据）等，支持 --show-abnormal 突出异常值
配置管理	config-init  子命令	一键生成标准 8 小时三班倒或 12 小时两班倒 YAML 模板，支持自定义输出路径，避免手写配置出错

这些能力不是孤立按钮，而是同一套约束模型的不同切面输出。比如 validate 和 conflict-report 共享同一组校验逻辑，schedule-inspector 的统计维度直接来自 show-schedule 的底层数据结构。

使用与配置

上手只需三步：安装、生成、查看。不需要 Web 服务、不需要数据库、不修改系统环境。

pip install -r requirements.txt

生成一个 7 天、20 名患者、每位患者平均 5 条医嘱的排班：

python -m cli.main generate --patients 20 --orders-per-patient 5 --days 7

结果默认存为 output/schedule.json。立刻用表格查看：

python -m cli.main show-schedule --schedule output/schedule.json

若要定制班次，先初始化配置：

python -m cli.main config-init --type 8h-shift --output my-shifts.yaml

再传入该配置运行：

python -m cli.main generate --patients 20 --shift-config my-shifts.yaml

YAML 配置完全开放：班次起止时间、交接点、医嘱类型定义（如 Q4H 对应 4 小时间隔、±30 分钟窗口）、护士最大单班任务数（默认 8）等，全部可调。说明文档里有字段级解释，不需猜含义。

约束规则与求解逻辑

我们把规则分为两类，对应真实护理管理中的“不可妥协”与“尽量做到”：

• 硬约束（必须 100% 满足）
  执行时间严格落在班次起止之间；不能在交接时刻（如 16:00）前后 1 分钟内安排任务；同一护士同一班次最多执行 8 个任务；Q4H 医嘱两次执行时间差必须在 [3h45m, 4h15m] 内（即允许 ±15 分钟偏差）。

• 软约束（求解器尽力优化）
  所有护士的日均任务数方差最小化；每位护士的执行时间尽量靠近其历史偏好时段（配置中可设 preferred_start_hour: 9）；避免同一患者在 15 分钟内被安排多个任务。

CP-SAT 求解器不是暴力穷举，而是基于约束传播剪枝搜索空间。对 20 患者 × 7 天 × 平均 5 医嘱的典型场景，通常在 3～8 秒内返回首个可行解，支持设置超时阈值（--timeout-seconds）主动中断。

数据与输出形态

排班结果以结构化 JSON 为事实源，包含完整上下文：患者 ID、医嘱类型、执行护士、班次类型、计划时间、实际排定时间、偏差分钟数、是否在优先窗口内等字段。所有导出功能均基于此 JSON：

输出格式	用途	特点
JSON	系统集成、二次开发	字段完整，含原始约束参数与求解元数据（如耗时、状态）
CSV	Excel 查看、台账归档	UTF-8 BOM 编码，首行为中文表头，兼容国内办公软件
HTML	晨会汇报、科室公示	自动渲染时间轴（横轴时间、纵轴护士）、热力图（颜色深浅代表任务密度）、冲突高亮图

例如 HTML 时间轴中，某护士某天 10:15 执行一条 Q4H 医嘱，若理论应为 10:00，则单元格显示 10:15 (+15) 并标黄；若偏差超 ±15 分钟，则标红并附提示。这不是示意，是真实字段计算结果。

工程结构与可维护性

代码按关注点分层，每个目录职责单一，便于团队协作与后续扩展：

目录	职责	关键内容
constraint_engine/	约束建模与求解封装	model_builder.py  定义变量与约束，solver_runner.py 调用 or-tools，constraint_rules.py 映射业务规则到数学表达式
cli/	命令行界面	main.py  为入口，各子命令（generate, validate 等）独立模块，参数校验与错误提示统一处理
visual/	可视化渲染	html_generator.py  用 Jinja2 模板生成响应式 HTML，heatmap.py 计算密度矩阵，不依赖前端框架
config/	配置加载与校验	config_loader.py  解析 YAML 并做业务级校验（如班次时间是否重叠、医嘱间隔是否为正整数）
utils/	通用工具	时间解析、日期计算、JSON 序列化增强、日志配置等，无业务逻辑

测试覆盖率达 94%，所有 CLI 子命令、约束校验逻辑、配置解析均有单元测试；性能基准放在 benchmarks/ 下，方便对比不同规模输入的求解耗时。

限制与说明

本项目当前不支持以下场景，未来版本可能演进但不在 v1 范围内：
- 不支持动态增减护士或患者（输入规模固定）
- 不支持多科室联合排班（如 ICU 与普通病房共享护士）
- 不支持医嘱优先级叠加（如危重患者医嘱自动提级）
- 不提供 Web UI 或 REST API（CLI 是唯一交付界面）

所有约束规则、配置字段含义、输出字段定义，均在项目文档中逐条说明。遇到问题，优先查阅 docs/constraint-rules.md（硬/软约束明细）、docs/config-format.md（YAML 字段字典）、docs/cli-reference.md（所有命令参数详解）。没有黑盒，每一步推导都可追溯。

项目地址：
https://github.com/nexorin9/nursing-schedule-generator