新高考自动排课 (Gaokao Auto Schedule)
> 把"行政班(语数外) + 走班(选考科目)"建模为约束满足问题(CSP)，自动生成无冲突的
> 行政班 / 教学班 / 教师三套课表，支持 3+1+2 与 3+3 两种模式。
一、新手快速上手（3 步，不用看文档也能跑）
第 1 步 · 跑一个演示，立刻看到效果
python scripts/schedule.py --demo --mode 3+1+2 --out ./output
不加任何输入文件即可运行，内置 450 学生 / 10 行政班的演示数据。
第 2 步 · 打开结果
运行后到 ./output 目录，双击 schedule_result.html 看可视化课表（含行政班 / 教学班 / 教师三个分页）。
第 3 步 · 换成你的真实数据（可选）
1. 用模板生成或自行准备 students.csv / teachers.csv / config.json（模板见 assets/）；
2. 运行：
python scripts/schedule.py --students students.csv --teachers teachers.csv \
--config config.json --out ./output
> ⚠️ 想要 3+3 稳定求解 / 启用 CP-SAT 完整能力，需要 ortools：
> 在已 pip install ortools 的 Python 环境运行 scripts/schedule.py。
> 未安装时自动回退「贪心 + 交换修复」引擎（3+1+2 没问题，3+3 极小概率残留少量未排节次）。
二、效果预览（最终长什么样）
排课引擎会输出三套课表。schedule_result.html 里用颜色区分科目；下面是行政班视图的真实节选（演示数据，3+1+2）：
- 行政班课表：语文/数学/外语在固定班内，选考科目显示为"走班"（学生去教学班上课）。
- 教学班课表：每个选考科目按单科拆成的教学班，显示上课教室与节次。
- 教师课表：每位教师各科任课的节次与地点，用于核对教师不冲突。
完整输出文件见下文「四、输出说明」；想看图文版样例说明见 references/sample_output.md。
三、排课模型（一句话理解）
- 行政班：语文、数学、外语全员必考，在固定行政班内上课。
- 走班（教学班）：选考科目按单科把选修学生集中，按教室容量拆分为若干教学班，学生跨行政班走班上课。
- 核心约束：一名学生同一节次只能在一个地点上课 → 这决定了排课是一个 CSP 问题。
四、输出说明
运行后在 --out 目录生成：
| 文件 | 内容 |
|---|---|
schedule_result.html |
可视化课表，含「行政班 / 教学班 / 教师」三个分页（颜色区分科目） |
timetable_admin.csv |
行政班课表（行=班级，列=40 节次） |
timetable_teacher.csv |
教师课表（行=教师，列=40 节次，含科目与教室） |
timetable_elective.csv |
教学班课表（行=教学班，列=40 节次，含科目/教师/教室） |
conflicts.txt |
仅当校验发现冲突时生成（正常情况不出现） |
引擎内置三重冲突校验（学生 / 教师 / 教室）。若 stdout 显示 未排满节次 > 0 或生成了 conflicts.txt，
按 references/faq.md 的"排课失败排查"逐步诊断。
五、常见调整
- 模式切换：
--mode 3+3处理六选三。 - 规模调整：编辑
config.json的admin_classes、students_per_class、elective_room_count。 - 课时调整：改
required_periods（语数外周课时）/elective_periods（每门选考周课时）。 - 教师资源：提供
teachers.csv指定各科目可用教师（影响教学班拆分与并发上限）。 - 一键造数据：
python scripts/generate_sample_input.py --out ./sample_input --mode 3+1+2。
六、深入参考（按需阅读，新手可先跳过）
| 文档 | 什么时候看 |
|---|---|
references/gaokao_models.md |
想搞懂选科组合、行政班/教学班区别、走班制背景 |
references/constraints.md |
查完整约束清单、参数表、求解器原理、输入/输出格式 |
references/sample_output.md |
想看三套课表的图文样例与字段含义 |
references/faq.md |
排课失败/有冲突/未排满时，先来这里——含反模式与排查清单 |
七、资源索引
scripts/schedule.py—— 核心排课引擎（CP-SAT + 贪心回退 + 冲突校验 + 课表导出）。scripts/generate_sample_input.py—— 生成示例输入（学生/教师/配置）。assets/students_template.csv/assets/teachers_template.csv/assets/config_template.json—— 输入模板。assets/preview_admin.png—— 行政班课表效果预览图。requirements.txt—— 依赖（ortools）。
