版本:v1.0(2026-07-07) 前置阅读:architecture.md(需求、资料模型、引擎设计、技术栈皆以该文件为准) 使用方式:开发 AI(Opus 4.8 / Sonnet 5)每次领取一张任务卡,实作 → 依「验收标准」自我验证 → 回报 → 经用户验收后才进下一张。 任务卡状态标记:
[ ]未开始 /[~]进行中 /[x]已验收。开发者完成后请直接更新本档的核取方块。
Course_Scheduling_System/
├── docker-compose.yml # 正式部署用(6 容器:web/api/worker/worker-ops/postgres/redis)
├── docker-compose.dev.yml # 开发用(热重载)
├── .env.example # 仅需改:管理员密码、校名、SMTP(选填)
├── Caddyfile
├── docs/ # 本规划文件 + 用户文件
│ ├── architecture.md
│ ├── tasks.md
│ └── deploy/ # 中文部署图文教学
├── backend/
│ ├── pyproject.toml # uv 管理;ruff + pytest 设置
│ ├── alembic/ # 资料库迁移
│ ├── app/
│ │ ├── core/ # 设置、DB session、auth、安全
│ │ ├── models/ # SQLAlchemy models(对应 architecture.md §2.2)
│ │ ├── schemas/ # Pydantic schemas
│ │ ├── api/ # routers(依资源分档:teachers.py、timetables.py …)
│ │ ├── services/ # 商业逻辑(冲突检查、代课推荐、导入导出…)
│ │ ├── solver/ # OR-Tools CP-SAT 排课引擎(独立、不 import app 其他层)
│ │ │ ├── model_builder.py # 约束建模
│ │ │ ├── conflict_explainer.py # 无解冲突定位
│ │ │ └── preflight.py # 排课前置检查
│ │ ├── workers/ # RQ 任务(排课、寄信、备份)
│ │ └── main.py
│ └── tests/
│ ├── fixtures/ # 三套学制验证资料集(见测试策略)
│ ├── unit/
│ └── solver/ # 引擎正确性测试
├── frontend/
│ ├── package.json # pnpm;Vue 3 + TS + Vite + Pinia + Naive UI
│ ├── src/
│ │ ├── api/ # API client(openapi-typescript 产生型别)
│ │ ├── stores/
│ │ ├── components/
│ │ │ └── timetable/ # TimetableGrid 拖拉课表元件(核心)
│ │ ├── views/ # 依信息架构分页(见 architecture.md §5.1)
│ │ └── router/
│ └── e2e/ # Playwright
└── .github/workflows/ci.yml # lint + test + 双架构 image build
| Milestone | 目标 | 完成的可见成果 |
|---|---|---|
| M0 专案骨架 | 可跑起来的空壳 | docker compose up -d 后可登录看到空仪表板 |
| M1 基础资料 | 建置学校资料 | 设置精灵走完,教师/班级/科目/场地齐备 |
| M2 手动排课 | 拖拉排课可用 | 手动排完一张班级课表并发布,教师可查询 |
| M3 自动排课 | 引擎上线 | 一键自动排课出草稿,无解时给人话报告 |
| M4 调代课 | 学期中日常运作 | 请假→代课→通知→确认 全流程 |
| M5 报表与上线 | 对外可发行 | 导出/备份/部署文件完成,可发布 v1.0 |
| M6 v1.1 加固 | 排课季前的体验与韧性 | ops 伫列拆分、部分排课不炸锅等五项,发布 v1.1(范围见 docs/roadmap.md) |
- 描述:建立上述目录结构;
docker-compose.yml(5 容器)与docker-compose.dev.yml;FastAPI hello endpoint(GET /api/health);Vue 3 空专案由 Caddy 服务;Alembic 初始化;.env.example。 - 模组:根目录、
backend/app/main.py、frontend/、Caddyfile - 验收标准:
- 全新机器上
cp .env.example .env && docker compose up -d后,浏览器开http://localhost见前端页面,/api/health回{"status":"ok"} docker compose ps五容器皆 healthy- dev compose 支援前后端热重载
- 全新机器上
- 测试方式:CI 内
docker compose up+ curl 烟雾测试
- 描述:
user/user_rolemodel 与迁移;bcrypt + session cookie 登录;RBAC 依赖注入(admin/scheduler/director/teacher);首次启动以.env建立 admin;首次登录强制改密码;登录页 UI。 - 模组:
app/core/auth.py、app/api/auth.py、app/models/user.py、frontend/src/views/Login.vue - 验收标准:
- admin 可登录/登出;错误密码 5 次锁定 15 分钟
- 未登录呼叫受保护 API 回 401;teacher 角色呼叫 scheduler API 回 403
- 首次登录被导向改密码页,改完才能进系统
- 测试方式:pytest(auth 流程 8+ 案例)+ Playwright 登录 E2E
- 描述:GitHub Actions:ruff + mypy + pytest / eslint + vitest / Playwright / 双架构(amd64+arm64)image build push。pre-commit 设置。
- 验收标准:PR 触发全部检查;main 分支 push 产出 image;README 挂 CI badge
- 测试方式:开测试 PR 验证
- 描述:健检发现三项「现在改便宜、日后改痛」的地基问题:
- Session 撤销:session token 由
{"uid"}改为{"uid", "pv": password_hash[-12:]},get_current_user验证pv与现行密码一致,不符回 401(改密码即失效所有旧 session); - naming_convention:
Base.metadata加入标准约束命名惯例(ix/uq/ck/fk/pk),确保跨资料库迁移可靠; - 时区政策落地(architecture.md D6):
.env.example与 config 增TZ=Asia/Taipei设置;compose 传入容器。
- Session 撤销:session token 由
- 顺手项:CI 增加「PostgreSQL service container 跑
alembic upgrade head」迁移验证步骤;前端client.ts加 401 全域处理(清 store → 导向登录)。 - 模组:
app/core/{security,auth,db,config}.py、tests/、.github/workflows/ci.yml、frontend/src/api/client.ts - 验收标准:
- 登录后改密码,以「旧 cookie」呼叫
/api/auth/me回 401(新增 pytest 案例) Base.metadata.naming_convention已定义,alembic upgrade head在 PostgreSQL 全新资料库成功(CI 验证)- session 过期或被撤销后,前端任何 API 操作自动导回登录页
- 既有 15 个 auth 测试不退步
- 登录后改密码,以「旧 cookie」呼叫
- 测试方式:pytest + CI 迁移 job
- 描述:
semester/period_table/periodCRUD(model+API+UI);节次表视觉化编辑器(表格点击标记节次类型:一般课/午休/导师时间/固定用途);五种学制范本资料(JSON seed,含默认节次表与科目清单);同学期多套节次表(完全中学)。 - 模组:
app/models/{semester,period}.py、app/api/semesters.py、frontend/src/views/settings/PeriodTable.vue - 验收标准:
- 可建立 115 学年第 1 学期,选「小学范本」自动带入 40 分节次表(含周三下午空)
- 可将周五第 7 节改为「导师时间」,排课时段检查 API 即反映
- 可为同学期建第二套节次表并指派给不同班级群
- 测试方式:pytest CRUD + 范本载入;Vitest 元件测试
- 描述:四实体完整 CRUD(对应 architecture.md §2.2 栏位);教师任教科目多选、行政职减课、业界师资标记;班级的学制标签与群科(技高);场地类型与容量;清单页支援搜寻/排序。
- 模组:
app/models/、app/api/、frontend/src/views/basedata/ - 验收标准:
- 四实体皆可增删改查,删除有引用检查(被配课引用的教师不可删,提示改为「离职」状态)
- 教师页可设置「不可排时段」与「偏好时段」(周×节 点击格子)
- 技高班级可填群科;小学班级可指定导师
- 测试方式:pytest(含引用完整性案例)
- 描述:教师、班级、科目三种 Excel 范本(系统内可下载,含填写说明列与范例列);上传→逐列验证→错误清单(「第 N 列:XX 原因」)→全对才交易式入库;导入教师时可勾选「同时建立帐号」(默认密码规则+强制首登改密)。
- 模组:
app/services/importer.py、frontend/src/views/basedata/Import.vue - 验收标准:
- 下载范本→填 30 位教师→上传→全数入库且帐号建立
- 故意填错(科目不存在、重复姓名+身分末四码)→回报确切列号与原因,资料库零写入
- 范本栏位有中文说明列,导入时自动略过
- 测试方式:pytest 用 fixtures 内的正确/错误 Excel 档
- 描述:首次登录(无任何学期资料时)自动进入五步骤精灵(architecture.md §5.2);每步可略过/回上一步;完成后导向配课管理;之后可从系统管理重新启动精灵。
- 模组:
frontend/src/views/wizard/、app/api/wizard.py(进度状态) - 验收标准:
- 全新系统登录即入精灵;五步走完后仪表板显示资料摘要(N 位教师、N 个班级)
- 中途关浏览器,再登录从上次步骤继续
- 用户测试:不看文件 30 分钟内完成初中范本建置(以 fixtures 资料模拟)
- 测试方式:Playwright E2E 全精灵流程
- 描述:从既有学期复制教师/班级/科目/场地/节次表到新学期(可勾选项目);班级年级自动 +1(可关闭),毕业年级提示移除。
- 验收标准:复制后两学期资料独立(改 A 学期教师不影响 B);年级进位正确
- 测试方式:pytest
- 领域背景(用户提供):台湾完全中学通常全校统一 50 分/节(初中部配合高中部作息),故多数学校只需一套节次表;真正需要多套表的是附设小学部、K-12 实验学校、进修部/夜间部。设计原则:默认路径零负担,弹性只在需要时浮现。
- 描述:班级尚无「所属节次表」关联,M2 冲突检查/排课引擎无从得知每班合法时段。实作:
class_units.period_table_id(nullable FK,空=学期默认节次表)+ 迁移;- 班级表单增「节次表」下拉——仅于该学期有 ≥2 套节次表时显示(单一表学校完全看不到此栏位);Excel 班级范本增「节次表」栏(选填,以名称对应);
- 提供 helper
resolve_period_table(class_unit)(指定表 → 回退学期默认表),无论单表或多表学校,M2 起所有时段逻辑一律走此函式; - 删除节次表时检查是否被班级引用(引用中则挡)。
- 模组:
app/models/basedata.py、app/api/basedata.py、app/services/importer.py、frontend/src/views/basedata/ClassesTab.vue - 验收标准:
- 完全中学情境:同学期两套节次表(初中 45 分/高中 50 分),301 班指到初中表、501 班指到高中表,各自 available-slots 正确
- 未指派节次表的班级回退学期默认表
- 被班级引用的节次表删除时回 409
- Excel 导入班级可指定节次表名称,名称不存在时报列号错误
- 测试方式:pytest(完全中学 fixture 情境)
- 背景:
user.pydocstring 承诺的 User↔Teacher 绑定在 M1 未实作(导入建帐号仅存 display_name,无外键)。此绑定是 M2-5「教师查本人课表」、M4 全部(请假自登、代课确认、通知收件人)的前提。另用户需求:教师需有联络栏位以利调代课通知。 - 描述:
teachers.user_id(nullable FK → users,ondelete=SET NULL,同学期唯一 uq(semester_id, user_id));Excel 导入「同时建立帐号」时自动绑定;教师表单(admin/scheduler)可选择绑定既有帐号;teachers.email/teachers.phone/teachers.line_id(皆 nullable String)——联络信息挂教师(学期快照),因外聘/业界师资可能无系统帐号;- Excel 教师范本增 Email/手机/LINE ID 三选填栏;教师表单增栏位;
semester_copy复制 user_id 与三个联络栏位(绑定跨学期延续);- helper
current_teacher(db, user, semester_id):由登录者解析其在指定学期的教师主档(M2-5/M4 共用)。
- 模组:
app/models/basedata.py、app/services/{importer,semester_copy}.py、app/api/basedata.py、frontend/src/views/basedata/TeachersTab.vue - 验收标准:
- 导入 30 位教师勾「建立帐号」→ 每笔
teachers.user_id正确绑定新帐号 - 开新学期复制后,新学期教师仍绑定同一帐号、联络信息完整
- 同一帐号在同学期绑第二位教师 → 409
- Email 格式错误时表单与导入均回报错误
- 导入 30 位教师勾「建立帐号」→ 每笔
- 测试方式:pytest(绑定/复制/唯一性);既有导入测试不退步
- 描述:
scheduling_unit/course_assignment/assignment_teacher/block_rulemodel 与 CRUD;配课建立 UI(班级选科目→指定教师→周节数→连堂→场地需求);跑班群组建立(选多班级组成 group,群组内建多笔配课);教师课时即时统计侧栏(配课数 vs 基本课时,超/不足变色);Excel 批次导入配课。 - 模组:
app/models/assignment.py、app/api/assignments.py、frontend/src/views/scheduling/Assignments.vue - 验收标准:
- 可建立「301 班 × 国文 × 王师 × 每周 5 节」与「高二多元选修跑班群组(3 班 5 组)」
- 可建立「机械科实习 × 2 位协同教师 × 每周 6 节含 3 连堂×2」
- 王师配 22 节、基本课时 20 → 侧栏显示「+2 超课时」红字
- 班级周配课总节数 > 可排节次数(经
resolve_period_table+regular_slots)时警告 - 跑班群组成员班级的节次表不一致 → 建立被拒(architecture.md D7 第 4 点)
- 测试方式:pytest(含跑班/协同/连堂三种结构)
- 描述:前端核心元件:CSS Grid 周课表,依节次表渲染(含反灰不排课时段);格位卡片(科目/教师/场地/锁定图示);HTML5 拖拉(从未排清单拖入、格间移动、拖出移除);视觉状态(可放绿框/冲突红框+原因浮窗);响应式(平板可用,手机唯读)。纯展示+事件元件,不含商业逻辑。
- 模组:
frontend/src/components/timetable/ - 验收标准:
- Storybook(或示范页)展示:小学 40 分节次表与技高 50 分节次表各一张
- 拖曳过程触发
check事件、放下触发drop事件,由父层决定结果 - Vitest 元件测试涵盖渲染/拖放事件/锁定显示
- 测试方式:Vitest + 示范页人工查看
- 描述:
timetable/schedule_entrymodel;冲突检查服务(H1–H10 硬约束的单格检查版,architecture.md §3.2);教师/场地冲突在跨节次表时以墙钟时间区间重叠判定(architecture.md D7,同表退化为 period_no 相等);API:建立草稿、格位增删改、POST /timetables/{id}/check-conflict(<100ms)、锁定/解锁;跑班群组拖一格连动全组。 - 模组:
app/services/conflict_checker.py、app/api/timetables.py - 验收标准:
- 王师已在周一第一节有课,再排他班同时段 → 回冲突「教师王师 周一第一节 已有 302 班数学」 (时段一律以节次表中的名称呈现:早自习/午休/第一节,不可用内部 period_no 索引)
- 连堂课拖至跨午休位置 → 拒绝并说明
- 跑班群组某组拖到新时段,全组连动;任一组冲突则整组拒绝
- check-conflict 在 60 班资料量下 p95 < 100ms
- 跨节次表冲突:王师在小学部(40 分/节)周一第 4 节 10:30–11:10 有课,再排他至高中部(50 分/节)周一第 3 节 10:10–11:00 → 回报冲突(墙钟时间重叠)
- 测试方式:pytest 覆盖 H1–H10 每项至少 2 案例(过/不过);效能测试脚本
- 描述:整合 M2-2 元件与 M2-3 API 成完整工作台(architecture.md §5.1 线框):左侧未排课务清单(含剩余节数)、三视角切换(班级/教师/场地)、草稿自动储存、复原/重做(前端 command stack)。
- 模组:
frontend/src/views/scheduling/Workbench.vue - 验收标准:
- 以初中 fixtures 手动排完一个班整周课表,未排清单归零
- 三视角资料一致(班级视角排的课,教师视角立即可见)
- Ctrl+Z 可复原最近 20 步
- 测试方式:Playwright E2E「排完一班」情境
- 描述:多草稿并存(复制/改名/删除);发布(draft→published,同学期旧 published 转 archived);发布前完整性检查(未排完课务列警告,可强制发布);全员课表查询页(班级/教师/场地,唯读,手机可用);audit_log 记录发布。
- 验收标准:
- 两份草稿可并存互不影响;发布 B 后,查询页显示 B,A 仍可编辑
- 有 3 节未排时发布 → 出现警告清单,确认后仍可发布
- teacher 角色登录手机浏览器可查本人课表
- 测试方式:pytest 状态转换 + Playwright
- 背景:测试策略总则承诺的三套 fixtures(标注「M1 期间建立,全案共用」)实际从未建立——
backend/tests/fixtures/目录不存在,M1–M2 测试皆为各档就地造小数据。M3-1/2/3/5 与 M5-4 的验收全部以「三套 fixtures」为前提;不先补齐,每张 M3 卡会各自造资料、解的质量彼此不可比。 - 描述:以 Python builder 函式(非静态 JSON,直接用 models 写入测试 session)实作三套资料集:
elementary_small:小学 6 班(包班+科任、周三下午空、导师时间);junior_high_mid:初中 12 班(领域课程+弹性课程+兼行政减课教师);vocational_high:技高 15 班 3 科(3 连堂实习+实习工场+业界师资 unavailable 时段+跑班群组);- 各附烟雾测试证明资料自洽:teacher_loads 无超课时、class_loads 不超可排节数、跑班群组同节次表。
- 模组:
backend/tests/fixtures/{__init__,elementary,junior_high,vocational}.py - 验收标准:
- 三套 builder 可在干净测试 DB 建出完整学期(节次表/教师/班级/科目/场地/配课/连堂/时段规则)
- 烟雾测试通过(资料自洽,可被 CP-SAT 排出全解)
- 既有 135 个后端测试不退步
- 测试方式:pytest
- 描述:
solver/模组骨架:从 DB 读取学期资料转为纯 dataclass 问题描述(solver 不碰 SQLAlchemy;DB→dataclass 转换层放app/services/solver_data.py,因 loader 必须 import models,放 solver/ 内会违反验收 3);pre-flight 必要条件检查(教师配课数≤可排格数、场地供需、班级节数,architecture.md §3.4)+ 班级人数>场地容量警告(D8);检查报告 API。 - 补遗(M2 健检 2026-07-10):
schedule_entries.room_id(nullable FK,空=沿用配课的 room_id)+ 迁移——§2.2 承诺格位带场地但 M2 未实作;solver 对「指定场地类型而未绑定场地」的配课需逐格指派场地,结果无处可存(M4 教室异动也需要)。conflict_checker_build_occupancy与课表序列化改以coalesce(entry.room_id, assignment.room_id)取场地。 - pre-flight「教师可排格数」定义:单一节次表(绝大多数学校)=一般课格数 − unavailable 格数;跨表任教的教师以墙钟区间联集去重计数(D7 重叠矩阵)。
- 模组:
app/solver/preflight.py、app/solver/problem.py、app/services/solver_data.py - 验收标准:
- 三套 fixtures(M3-0)皆可转出问题描述且 pre-flight 通过
- 人为制造「王师 22 节但可排 20 格」→ 报告明确指出教师、数字
- solver 模组
import不到app.api/app.models(以 import-linter 或测试保证) - 手动排课将格位放到与配课不同的场地后,check-conflict 以格位场地判定占用
- 测试方式:pytest
- 描述:实作 H1–H10 硬约束建模(architecture.md §3.2);连堂以区间建模;跑班同步;锁定格位;场地互斥(D8);教师/场地跨节次表以 D7 重叠矩阵建模;求解取出结果转 schedule_entry 列表(含逐格 room_id)。
- 补遗(M2 健检 2026-07-10):
ortools依赖此卡才加入 pyproject(M3-1 不需要,保持 pre-flight 轻量);注意 wheel 体积(~50MB)与 arm64 wheel 可用性,重建映像验证;- H10 精确定义以独立 validator 为准:同班同科目每日「单节」数 ≤ 上限,连堂(block_rule 产生)的节数不计入;M2-3 手动 conflict_checker 目前把既有连堂 span 也计入每日计数,与此不一致,此卡顺手对齐(改法:占用索引的 subj_count 排除 span>1 或挂 block_rule 的格位)。
- 模组:
app/solver/model_builder.py - 验收标准:
- 三套 fixtures 各自可解,且逐项验证解零硬约束违反(以独立 validator 检查,不信任 solver 自己)
- 技高 fixture 的 3 连堂课全部连续且不跨午休;实习工场同时段不超容量
- 锁定 5 格后重解,该 5 格位置不变
- 12 班初中 fixture 在 CI 机器 60 秒内解出
- 测试方式:
tests/solver/+validator.py(独立验证器,亦供日后回归)
- 描述:实作 S1–S8 软约束(architecture.md §3.2)加权目标;权重设置存 DB(
constraint_config,含 H10 每日上限值),UI 于 v2 才做,先用默认值;解出后产出「软约束达成度报告」(各项得分/满分、未达成明细)。补遗:subjects.is_major(主科标记,S5 用)+ 迁移 + 科目表单勾选——现行 Subject 无此栏位。 - 验收标准:
- 同 fixture 开/关 S2(同科分散)比较:开启后同班同科目同日 ≥2 节的数量显著下降
- 教师 avoid 时段在有替代方案时被避开
- 报告列出「王师周四第7节被排课(偏好未达成)」等人话明细
- 测试方式:pytest 比较性测试(断言方向性,不断言绝对分数)
- 描述:排课任务走 RQ:
POST /timetables/{id}/auto-schedule入伫列;CP-SAT callback 每 5 秒写进度(已找到解的目标值、经过时间)至 Redis;前端进度页(polling)含「提前结束取目前最佳解」与「取消」;timeout 默认 10 分钟可设置;结果写回为新草稿。输入输出流定义(M2 健检 2026-07-10):以来源草稿为输入;locked格位作为固定约束(H9)复制至结果草稿并保持锁定;未锁定的既有格位以 CP-SAT hint(AddHint)喂入以提高解的稳定性(重排时尽量少动);结果草稿命名「{来源名} 自排结果」,来源草稿不动。 - 模组:
app/workers/solve_job.py、frontend/src/views/scheduling/AutoSchedule.vue - 验收标准:
- 启动排课后 UI 显示进度;点「提前结束」拿到当前最佳解草稿
- 排课期间 Web 其他功能不受影响(worker 隔离)
- worker 容器被 kill 后任务标记失败,UI 有明确错误而非永久转圈
- 测试方式:pytest(RQ 假伫列)+ Playwright 长流程
- 描述:冲突定位(architecture.md §3.4):无解时指出是哪几条硬约束凑在一起,转译为教务语言建议;「部分排课」模式(用户勾选可放宽的约束类别,将其转为高权重软约束,未排入课务列清单)。
- 模组:
app/solver/conflict_explainer.py - 验收标准:
- ✅ 制造「音乐教室需求 30 节 > 实际可用 28 节」的 fixture → 报告指出场地与数字
- ✅ 制造教师时段矛盾 → 报告指出该教师(两位协同教师都点名)
- ✅ 部分排课模式:同 fixture 产出 97.8%(88/90)排入的草稿 + 未排清单
- 测试方式:pytest(3 种人造无解情境 + 部分排课 + pre-flight 短路);Playwright ×2;真实 PostgreSQL + RQ 实测
补遗(实作后)
- 改用删除法,不用 assumption / unsat core。原设计是每类硬约束挂 assumption literal 取 unsat core,实测不可行:enforcement literal 让 presolve 认不出鸽笼结构,同一份资料纯硬约束 0.8 秒证完,挂 assumption 后 60 秒证不完(换过三种编码皆然)。改成「把一组约束整个关掉、重建干净模型重解」,整套定位约 2~3 秒,且每条结论都被一次真实求解验证过。
- 旋钮只取教学组长改得动的东西:
H4教师不可排时段、H3场地互斥、H10每日科目上限、H9锁定格位。H1/H2没有旋钮可转,其成因 pre-flight 已算得出来。 H1/H2/H3永不可放宽——那是物理不是政策(API 收到会回 400)。- 逾时且零解时也跑定位:带软约束目标函数的 CP-SAT 常证不出 INFEASIBLE,一律以纯硬约束探测一次,才分得出「不可能」与「只是慢」。这是实机验证才发现的——单元测试里的小问题秒证无解,看不到这个坑。
- 部分排课的惩罚量级:未排入(10000) ≫ 放宽的约束(1000) ≫ 软约束(1~8);因此其
objective与一般模式尺度不同,UI 显示「未排 N 节」而非目标值。 - 部分排课的 pre-flight 只挡结构性错误(连堂放不进、群组节数不一致、某类型场地挂零)。
- 部分排课结果一律再过
validator:除了被放宽的那类,其余硬约束零违反。
- 描述:
leave_request/affected_periodmodel;教师自登/组长代登 UI;依 published 课表展开受影响节次(半天/多天/跨周假);销假(级联取消处置并通知,architecture.md §5.3 状态机)。 - 验收标准:
- 王师请周三整天假 → 自动列出周三 5 节受影响课
- 请假 3 天跨周末 → 只展开上课日节次
- 销假后已指派代课的教师收到取消通知
- 测试方式:pytest(日期边界:周末、学期起讫外拒绝)
补遗(实作后)
affected_period是快照,不是 join(这是 M4 的地基决策):展开当下把配课/教师/班级/场地/节次名称/起讫时间一并写死。理由与 D4 一致——课表可以重新发布,但「王师 11/12 第三节原本要上 301 班国文」是既成事实,不该随课表改版漂移,更不该让一笔已指派的代课隔天指向另一门课。溯源指标(schedule_entry_id/course_assignment_id)课表删除时 SET NULL,快照栏位仍在。真机验过:删掉已发布课表后,受影响节次原封不动。- 只看已发布课表:草稿随时会变,拿草稿找代课老师没意义。课表未发布时假单照样成立,只是展开 0 节。
- 上课日由节次表决定,不写死周一~周五:六日制学校的周六有课由
num_weekdays判定(周末跳过 =isoweekday() > num_weekdays)。 - 半天假以墙钟时间区间重叠判定;节次表没填起讫时间时保守列入(宁可多列一节让组长删,也不要漏掉一节变成没老师的教室)。多日假只有头尾两天受时间限制,中间整天。
- 销假级联:已完成的节次不动(课上过了,课时照算);已指派代课的转为已取消并合并通知代课教师(一人多节一封信);当事人另收销假通知。这条在 M4-1 就做掉,不留到 M4-3。
- 通知只落地、不寄送:
notifications.notify()是 M4-3NotificationChannel的写入点;写入永远成功,寄送(站内铃铛/Email)可失败可重试,不绑同一交易。 - RBAC:教师自登只能登自己、只看自己;组长/主任可代登代销看全校。教师端请假页手机可用(路由守卫新增
leaves为教师可进页面)。 - 前端:日期一律附星期(「2026-11-11(周三)」),否则看不出跨六天为何只有一天有课;已取消状态改用淡色文字,不与「待处理」抢眼(Naive 的 tag
type="default"在此仍沿用前次主题色,故不用 tag)。日期用本机格式不用toISOString(UTC 会让台湾凌晨倒退一天)。
- 描述:逐节处理 UI(代课/调课/并班/自习/不处理);代课推荐服务:硬性过滤(该时段空堂、当日未请假)→ 排序(同科目 > 当日已在校 > 本月代课课时少),每位候选附排序理由;调课(swap)验证(architecture.md §5.3);指派即生效(不设邀请/婉拒流程,2026-07-09 用户定案:组长实务上已事先口头征得同意,通知仅为正式告知+确认收到)。
- 模组:
app/services/substitution_recommender.py、frontend/src/views/substitution/ - 验收标准:
- 推荐清单第一名必为空堂+同科;已满 6 节者排序靠后
- swap 后任一方冲突 → 拒绝并说明是谁在哪一节冲突
- 该时段全校无人空堂 → 显示「无可代教师」并建议并班/自习
- 测试方式:pytest 推荐排序表格测试(10+ 情境)
补遗(实作后)
- 「周格 vs 特定日期」的落差用独立的
availability.py收敛(Fable 5 M3 审查点名的 M4 最大架构工作):可用性判断叠三层——周课表有没有课(D7 墙钟重叠)、当天自己有没有请假、当天有没有被指派代别班。今日看板(M4-4)与代课推荐共用这一层。 - 当日请假必须读假单本身的日期/时间窗,不是展开的
affected_period——这是实作时测试抓到的真 bug:老师请整天假、但某节恰好是他的空堂时,affected_period不涵盖那一格(它只在有课的节次才存在),若照它判断会把一位不在校的老师找来代课。改为直接比对leave_request的 start/end 日期时间(与leaves.expand同一套半天窗语意)。 - 推荐排序:同科目 > 当天已在校 > 本月代课课时少 > 姓名(稳定)。每位候选附人话理由(「同科目教师 · 当天已在校 · 本月已代 2 节」),不是黑箱分数。
- swap(调课)验四件事:乙在甲那节无课、swap_entry 确是乙的课、甲在补课那节无课也没请假、补课日星期与该节课相符。任一撞课指名道姓拒绝。swap 交换的节次以快照保存(swap_date/period_name/class_names/subject_name),课表改版不影响已成立的调课。
- 课时政策:代课计、并班/自习/不处理不计(可覆写),供 M4-5 月结。
substitution是处置真相来源,affected_period.handler_teacher_id/status为冗余指标。 - 指派即生效:建立处置 → 节次转『已确认』+ 记处理教师 → 通知处理教师(站内落地,M4-3 才寄送)。撤回处置退回待处理并通知取消。无邀请/婉拒(2026-07-09 定案)。
- 描述:
notificationmodel;通知寄送走NotificationChannel介面(architecture.md §5.3,MVP 实作站内+Email 两个 channel,v2 增 webhook/LINE adapter);收件人解析经teachers.user_id(站内)与teachers.email(Email,M2-0 栏位);站内通知(铃铛、未读数、轮询);Email 寄送走 RQ(SMTP 设置于系统管理,未设置则仅站内通知并提示);通知模板(代课指派/取消、课表发布);教师「确认收到」页(手机可用,一键确认);组长看板显示各笔确认状态,未确认者可一键再次提醒。 - 验收标准:
- 指派代课后,教师站内+Email 双通知,点连结直达确认页,一键「确认收到」
- 组长于看板可见确认/未确认状态;对未确认者按「再次提醒」重发通知
- SMTP 未设置时系统正常运作(仅站内通知)
- 测试方式:pytest(mailhog 容器拦信)+ Playwright 手机视窗尺寸
补遗(实作后)
- NotificationChannel 分层:
notifications.notify()建立站内通知列(永远送达)后,逐一经CHANNELS(InAppChannelno-op +EmailChannel)派送;v2 加 webhook/LINE 只需再实作一个 channel 并 append。 - Email 的交易语意:EmailChannel 不直接 enqueue,而是把信放进
session.info的寄件匣;SQLAlchemy 的after_commit事件才排入 RQ,after_rollback则丢弃——交易回复(rollback)就不会寄出一封对应到不存在通知的信(双写问题的正解)。已测交易回复不寄、commit 才寄。 - 站内永远可用,Email 是加分:SMTP 未设置时
email.send回 False、email_job只记 log,整个调代课流程照常。这是验收③,实机在 mailhog 上验过双通道。 - SMTP 设置存
app_settings(全域 key/value,非学期范围);密码留空 = 不变更,回传不含明文。管理员专属。POST /settings/smtp/test当场寄测试信回报结果(不走 RQ)。 - 确认收到 = 通知层已读确认,不影响课务(指派即生效,2026-07-09 定案)。教师铃铛(轮询 20s + 未读数 badge)、组长看板(确认状态 + 对未确认者「再次提醒」重发,已确认则 409)。
- 开发用 mailhog:docker-compose 加
mailhog(profiledev,不影响正式部署);docker compose --profile dev up才启动,Web UI :8025。 - E2E 教训:共用 e2e_teacher 帐号 + 发布课表的测试会用「最近学期」默认互相污染;测试中途失败会跳过收尾清理,故改用
test.afterEach兜底删除学期。另 Naive 的 message toast 与 tag 同字串会触发 strict-mode(getByText 命中两个),toast 文案要与 tag 区隔。
- 描述:仪表板「今日调代课看板」(今日全部异动:谁代谁的课、教室异动);当日调代课通知单打印(A4,传统公告格式);历史查询(依教师/日期/假别筛选)。
- 验收标准:
- 看板即时反映今日已确认处置;无异动显示「今日无调代课」
- 打印版面 A4 一页内,含节次/班级/原教师/代课教师
- 测试方式:Playwright 快照
补遗(实作后)
- 看板/日志不新增真相,只摊平:
substitution_log.py把「受影响节次 + 处置」join 成一列列可读纪录,今日看板与历史查询共用同一LogEntry。真相仍在affected_period(快照)与substitution(处置决定)。 - 「今日」以学校时区判定(config.tz,默认 Asia/Taipei),不是 UTC——台湾凌晨的 UTC 仍是前一天(D6)。前端深连结可带
?date=&semester_id=指定任一天,未带则后端以school_today()为准。 - 看板含待处理节次,好让组长一眼看出还有几节没排代课;排除已销假(cancelled)的节次(那天没有异动)。打印通知单则只列已安排的处置(公告只公告已定案的)。
- 历史查询的
teacher_id同时比对缺课当事人与接手代课者——查一位教师,他缺的课与他代的课都算相关(以冗余的affected_period.handler_teacher_id命中接手方)。 - A4 打印页是独立路由
/daily-board/print(不套侧边栏版面),window.open新分页开启;@media print隐藏工具列、设@page A4。校名取自 config.school_name,随看板回应带出(免另设置)。 - 踩雷:
date/start_time栏位名遮蔽 datetime 型别——dataclass/pydantic 内栏位命名为date后,同类别后续以date标注型别会被 mypy 视为「用变数当型别」而报错。以模组别名_Date = date标注型别解决。
- 描述:月结统计:依教师汇total(代课节数、计费节数——并班/自习不计、假别、经费来源标记);Excel 导出;教师个人可查本人明细。
- 验收标准:
- fixture 一个月 20 笔处置 → 统计数字与手算一致(含不计费项排除)
- 导出 Excel 栏位:教师/日期/节次/班级/科目/原教师/假别/计费
- 测试方式:pytest 计算正确性(边界:跨月假单拆月计)
补遗(实作后)
- 两个数字:代课节数(所有接手处置:代课/调课/并班)vs 计费节数(
counts_toward_hours为真者)。自习/不处理没有处理教师,不计入任何人;并班有接手者但默认不计费(可覆写)。「并班/自习不计」指的是计费,不是代课节数。 - 跨月假单自动拆月:以每一个
affected_period自己的日期分月,不是以假单分月。王师请 1/30~2/2,1 月的节次进 1 月报表、2 月的进 2 月,无需特别处理。 - 销假的节次不计但已完成的保留:
leaves.cancel把未完成节次转cancelled(那堂课没上)、保留completed(课上过了课时照算);统计以affected_period.status != cancelled过滤,不看假单状态(才不会漏掉部分销假的已完成节次)。 - RBAC:组长/主任看全校并导出 Excel(
/substitution-stats+/export);教师只能查自己(/substitution-stats/mine,以 current_teacher 绑定解析,无绑定回空报表)。前端同一页依角色分流:管理者有教师筛选+导出钮,教师版隐藏。教师页加入路由守卫白名单。 - Excel 两张表:汇总(教师/代课节数/计费节数)+ 明细(教师/日期/节次/班级/科目/原教师/假别/处置/计费/经费来源);沿用 importer 的 openpyxl Workbook + FastAPI Response(Content-Disposition attachment)。前端以
window.open带 cookie 触发下载。 - 深连结:统计页与看板页一样支援
?year=&month=&semester_id=,便于分享与测试。
- 条件 A(已修)——「已完成」不落盘,改读取时推导:§5.3 的「已确认→已完成:上课日结束自动转换」原本无任何程序写入
completed,导致两道完整性保护失效(销假会抹掉已上过课的课时、可事后改派已上完的代课)。改为app/core/clock.py的is_past_slot(date,end_time)(以 config.tz 判定):leaves.cancel对已上过的节次不转 cancelled、substitutions.assign/clear对已上过的节次回 409;显示层leaves.effective_status()把 resolved+已过推导为 completed。M5-2 的 RQ scheduler 上线后可再补夜间 sweep 落盘,但正确性不依赖排程。 - 条件 B(已修)——swap 补课判定漏比对教师:
availability._already_covering的 swap 分支原本只比对swap_date+period_no,任一笔调课成立后补课日该节次会误判全校已占用。改为 joinAffectedPeriod→LeaveRequest加teacher_id(补课方=该调课请假的当事人)+status=registered+ 节次未取消。 - 条件 C(已修)——公平计数含幽灵代课:
_monthly_sub_counts未排除已销假节次,销假后那笔代课仍计入「本月已代 N 节」,与 M4-5 统计口径不一。加status != cancelled。公平计数维持以计费节数(counts_toward_hours)计,与显示的「本月已代 N 节」一致。 - 条件 E(已处理):(1) 看板与统计口径差已记于补遗(唯一分歧=销假假单中已完成的节次:不上看板但计课时,合理);(2) swap 补课可用性退化为 period_no 比对,跨节次表学校有 D7 精度损失,列 v1.x;(3)
notifications的 after_commit enqueue 失败改为logger.warning留痕,不再无声吞掉。 - 条件 D(排入 M5-0):学期中重新发布课表后,未来日期的
affected_period仍指向旧格位——见 M5-0。
- 描述:一次备妥 M5 各卡的共用基础设施,避免每张卡各自处理环境。
- PDF/字型基础:worker 映像安装 WeasyPrint 系统依赖(Pango/Cairo/gdk-pixbuf)与中文内嵌字型(Noto Sans TC / Noto Serif TC),供 M5-1 PDF、M5-2 之后的报表共用。字型与重量级原生依赖只装在 worker(导出走背景任务),api 映像维持精简。
- RQ scheduler 骨架:立起定时任务排程器(M5-2 每日备份、条件 A 选配夜间 sweep 都挂这里);docker-compose 加 scheduler 服务,先跑一个 heartbeat/no-op 周期任务验证存活。
- 效能 fixture:以 M3-0 的学制 builder 长出 60 班规模资料集,供 M5-1「60 班批次 < 60 秒」与 M5-4 压测共用;先确认 builder 能产生该规模。
- 条件 D:重新发布重展开受影响节次:
leaves.expand只在登记当下依当时 published 课表展开;学期中重新发布课表后,今日之后的 pending/resolved 受影响节次仍指向旧格位(代课老师被派去上已移走的课)。M5-0 先做最小防护——publish 时侦测该学期「今日之后」的受影响节次数 > 0 就于回应与 UI 加警告;完整重跑 expand+diff+通知列为后续增强。
- 验收标准:
- worker 容器内
python -c "import weasyprint"成功,且以内嵌字型渲染中文 PDF 无 tofu(目视一张测试页) - scheduler 服务启动后,周期任务有触发纪录(log)
- 60 班 fixture builder 产出资料,基本查询正常
- worker 容器内
- 测试方式:容器内 smoke test(WeasyPrint 导入 + 中文 PDF)、scheduler 存活纪录、fixture builder pytest
补遗(实作后)
- 多阶段 Dockerfile(base / worker):api 用
base(精简),worker 用worker(额外装 Pango/Cairo/gdk-pixbuf +fonts-noto-cjk+ poppler-utils +pip .[export]的 WeasyPrint)。compose 与 CI 皆以target:指定;CI 另推-worker映像。app/services/pdf.py的render_pdf延迟导入 weasyprint,api 导入不会失败(导出一律走 worker 背景任务)。实机验证:worker 容器内 weasyprint 69.0 导入成功,渲染繁中 PDF→PNG 目视无 tofu(排课/调代课/王小明/国文/甲乙丙丁…/艺术与人文 皆清晰)。 - 排程器骨架:worker 已
with_scheduler=True;不加独立容器(单校部署少一个行程),改用「执行时排下一次」的自我续期心跳(固定 job_id,重启不堆叠),ensure_scheduled()于 worker 启动时排入。M5-2 每日备份、条件 A 选配夜间 sweep 都挂此模式。实机验证:ScheduledJobRegistry 含scheduler-heartbeat,手动触发 job 状态 FINISHED 且自我重排成功。 - 60 班效能 fixture:
tests/fixtures/scale.py的build_large_school(num_classes=60),以贪婪「最少负载且不超 base」指派教师(不保证可完全排课,量为主);pytest 验 60 班 660 配课、无教师超课时。 - 条件 D 最小防护(已做):
timetable_publish.stale_future_affected_count算「今日之后、依先前课表展开」的待处理/已指派受影响节次;发布回应加stale_affected,前端发布成功后 >0 则跳警告 toast(请至今日看板/调代课纪录重新查看)。完整解(重跑 expand+diff+通知)仍列后续增强。
- 描述:班级/教师/场地课表导出 Excel(openpyxl)、PDF(WeasyPrint,A4 直式含校名/学期/打印日)、PNG;全校总表 Excel;批次导出(全部班级一键 zip)。
- 验收标准:
- 三种格式与界面课表内容一致;PDF 中文无乱码(内嵌字型)
- 60 班批次导出 < 60 秒
- 测试方式:pytest 内容比对(Excel 读回验证)+ 人工查看 PDF 版面
补遗(实作后)
- 共用格线模型:
timetable_export.py把已发布课表(D4 快照)摊成Grid(节次列 × 星期栏,连堂以 span 合并),三种对象(班级=科目/教师/教室、教师=科目/班级/教室、场地=科目/班级/教师)与三种格式共用,确保内容一致(验收①)。 - Excel 在 api、PDF/PNG 在 worker:openpyxl 轻量,班级/教师/场地/全校总表/批次 zip 皆 api 同步产生。PDF 需 WeasyPrint(系统依赖+中文字型只在 worker,见 M5-0),故 PDF/PNG 由 api 以
queue.render_export阻塞式派到 worker 渲染再取回(RQ result);PNG = WeasyPrint 出 PDF 后 popplerpdftoppm转单页。 - 全校总表 vs 批次:总表=一个 Excel 每班一分页;批次=每班各一 Excel 打包 zip。单一课表导出开放所有登录者(课表本就全校可查),总表/批次限教学组长以上。
- 中文档名:Content-Disposition 用 RFC 5987
filename*=UTF-8'',前端以 fetch blob 下载并解出档名(顺带处理 4xx/5xx 与载入状态)。 - 验收②:60 班批次为 CPU-bound(60 个 openpyxl workbook),与资料库无关,pytest 用
build_large_school实测 < 60 秒。验收①:E2E 下载班级 PNG(走 worker WeasyPrint→pdftoppm)存档目视:标题/校名/学期/打印日、节次×星期格线、早自习/午休淡色、周三第一节显示国文/王老师,繁中无 tofu。
- 描述:每日 02:00 自动 pg_dump(保留 30 份,RQ scheduler);管理 UI:立即备份/下载/上传还原(还原前自动先备份现状+二次确认);还原后强制全员重新登录。
- 验收标准:
- 备份→改资料→还原→资料回到备份点
- 上传非法档案被拒绝且系统无损
- 自动备份保留数正确轮替
- 测试方式:pytest + docker 整合测试
补遗(实作后)
- pg 工具版本:基底映像已是 Debian trixie(非 bookworm),其 main 内含 postgresql-client 17;pg_dump 17 可备份 postgres:16 服务器(client ≥ server 允许)。原想从 PGDG 装 client 16,但 PGDG 的 libpq5 18 在 trixie 有相依冲突,故直接用发行版的 client。pg 工具只装在 worker 映像(与 M5-1 的 WeasyPrint 同层),api 维持精简。
- 跨版本还原的可忽略错误:pg_dump 17 的备份含
SET transaction_timeout(v17 GUC),pg_restore 进 v16 服务器会喷一个可忽略错误、exit code=1。依 pg_restore 惯例(0=全成功、1=完成但有忽略错误、>1=失败)放行 exit 1 并记 log,资料仍正确还原(实测 revert OK)。 - api/worker 分工:清单/下载/上传由 api 直接读写共挂的
backupsvolume;pg_dump/pg_restore 派到 worker(queue.run_backup/run_restore阻塞式)。每日备份挂 M5-0 的排程器(schedule_daily_backup于 backup_hour 排 enqueue_at,执行后自我续期;固定 job_id 重启不堆叠)。 - 强制全员重新登录:session 是无状态签章 cookie,还原资料库不会使其失效。改在 Redis 记一个「最小有效签发时间」(
session_epoch),还原后设为现在;get_current_user拒绝签发早于此的 session。Redis 只是被还原的 PostgreSQL 之外的存放点。auth 端有 5 秒行程内快取(fail-open),故强制登出有 ≤5 秒传播延迟(可接受)。 - 还原后补写稽核的坑:还原会
pg_terminate_backend中止所有其他连线(含本请求的 DB 连线),且还原本身会覆盖整个资料库——所以还原前写的稽核会被盖掉、还原后用旧连线写会失败。正解:还原后engine.dispose()再开新连线,把稽核写进还原后的资料库。 - 非法上传(验收②):
save_uploaded先验PGDMP魔数,非法直接拒绝、档案不落地、不碰资料库;还原既有备份前也再验一次档头。 - 实机验证(docker 整合):worker 内 pg_dump 17.10;备份→插入学期→还原→笔数回到备份点 ✅;轮替 3→keep=1→1 ✅;api POST /backups(RQ 阻塞)→201、POST restore→200(自动 presafe 备份)、/auth/me 由 200 转 401(强制登出,~5s)、重登 200 ✅;非法上传 400 且无档案落地(pytest)。
- 描述:
docs/deploy/中文图文:Docker 安装(Win/Linux/NAS)、三步骤安装、升级、备份策略、VPS+HTTPS 选配、常见问题;README(中文为主+英文摘要);CHANGELOG;GitHub Release 流程(tag→CI 出双架构 image);LICENSE(MIT);CONTRIBUTING.md。 - 验收标准:
- 依文件在干净 VM 从零安装成功(实测)
docker compose pull && up -d从前一版升级,资料完整、迁移自动执行
- 测试方式:干净环境实测(记录于 PR)
补遗(实作后)
- 同一份 compose,两种部署:为让验收②的
docker compose pull有意义,docker-compose.yml的 web/api/worker 三服务同时挂image:(GHCR)与build:——clone 原始码者up -d仍在本机建置(行为不变),只需档案者pull && up -d拉官方映像。映像版本由.env的IMAGE_TAG(默认 latest,建议正式部署钉选版本号)决定。 - CI 补版本标签:原
imagesjob 只推:latest与:sha,IMAGE_TAG=v1.0.0会拉不到映像。三个映像各补推:${github.ref_name}(main push=main、版本标签=v1.0.0),版本钉选才真的成立;版本标签仍为唯一触发双架构(amd64+arm64)的条件。 - HTTPS 选配做成一个设置:Caddyfile 站台位址写死
:80且烘进映像,拉映像的学校改不到。改为{$SITE_ADDRESS::80}环境变数(默认:80内网 HTTP;于.env设SITE_ADDRESS=网域名即自动申请/续期 Let's Encrypt 凭证)。compose 补 443 埠映射与caddydatavolume(凭证持久化,避免重启触发速率限制)。实测:默认(无网域)重建 web 后/api/health与首页皆 200、web healthy,内网 HTTP 部署未受影响;docker compose config在有/无SITE_ADDRESS两路径皆正确解析。 - 文件产出:
docs/deploy/(index/install/upgrade/backup/https/faq 六篇中文,含 Win/Linux/Synology/QNAP 安装、异地备援、退回旧版与资料表结构变更提醒、VPS 对外埠与资安)、改写README.md(英文摘要+功能总览+双部署快速开始+文件索引)、新增CHANGELOG.md(Keep a Changelog,汇整 M0–M5)、CONTRIBUTING.md(开发环境/质量门槛/任务卡制/发布新版本流程)。LICENSE(MIT)M0 已具备。 - 验收①「干净 VM 实测」的界线:compose 解析、web 重建与默认 HTTP 服务已在本机 Docker 验过;真正的「全新 VM 从零 pull 安装」需待版本标签推上 GHCR 后才可端到端跑(目前尚无 release tag),此步骤留给实际发布时(或用户)在干净环境验收并记录于 PR。
- 描述:Playwright 全流程情境:精灵建置→导入→配课→自动排课→发布→请假→代课→月统计;效能验收;无障碍基本检查(键盘可操作、对比度)。
- 验收标准:
- 三套 fixtures 全流程 E2E 绿灯
- 60 班规模:页面载入 p95 < 2s、check-conflict p95 < 100ms、自动排课 < 10 分钟
- 以 4GB RAM 容器限制跑全流程不 OOM
- 测试方式:CI E2E + 压测脚本
补遗(实作后)
- 验收①分两面落实:(a) 后端
tests/test_full_flow.py对三套学制 fixtures(小学/初中/技高)各跑完整管线——求解 → validator 验零硬违反 → 发布快照 → 挑一位有课教师请整天假 → 依已发布课表展开受影响节次 → 用推荐挑空堂教师指派代课 → 月结统计数字对上;证明下游链路能吃真实求解结果并在三种学制一致成立(M3 只证到「解得出」)。(b) 前端full-journey.spec.ts一个学期连续走完自动排课(真实 solver worker)→ 版本发布 → 课表查询 → 请假+代课(API)→ 月结(UI),截图目视:自排「已找到 16 个解、产生草稿A 自排结果」、月结页「国文师1 代 国文师2 事假 1 节、计费 1 节」。个别旅程细节仍由既有 26 支 spec 深入覆盖。 - 踩雷:全流程测试的两个时间性地雷。(1) 求解要用 hard-only config(
SolverConfig.hard_only()),否则挂软约束目标函数的 CP-SAT 会为了逼近最佳跑到max_seconds天花板——三套 fixtures 各跑 120 秒共 6 分钟;改 hard-only 后全部 15 秒。(2) 学期起讫必须设在今日之后:代课处置会用clock.is_past_slot拒绝已结束的节次,起初用 2025 的日期整批被判为「已结束」而指派失败。 - 验收②(check-conflict p95<100ms):
tests/test_perf_scale.py以build_large_school(60)(660 配课)塞入 >1500 格合法占用,量 30 次单格冲突检查 p95。页面载入 p95<2s:perf-page-load.spec.ts对灌了 60 班的执行中全栈量测。方法学校正:最初用重复page.goto全页重载量到配课页 p95≈2.9s——那是每次重新下载/解析 ~1.4MB SPA bundle 的成本(CPU 竞争下放大),不是用户实际的换页延迟。改量应用内导览(bundle 已暖):配课页/课表查询 p95≈85–89ms;冷启首载(含 bundle)另记 1069ms,两者皆 <2s。1.4MB bundle 的冷启成本仍列 Backlog(按元件 import 缩小)。自排<10 分:60 班求解耗时不放进 CI 单元测试(以免每次跑十分钟),由 M3 的 junior_high <60s 建模测试 + 全流程实测共同保证。 - 验收③(4GB 不 OOM):新增
docker-compose.limits.yml(叠在正式 compose 上,mem_limit合计 3.2GB:worker 1.5G/api 768M/postgres 512M/redis 256M/web 128M,留 ~0.8G 余裕)。以此上限重建全栈跑完整旅程(含真实 solver),docker stats峰值 api 132M/768M、postgres 36M/512M、worker 于小校求解下宽裕;全五容器OOMKilled=false、Restarts=0。此档亦作为 4GB 主机/NAS 部署参考。 - 无障碍基本检查:
a11y.spec.ts三案——(1) 仅键盘(Tab/输入/Enter)完成登录直达仪表板;(2) 连续 Tab 焦点可达可互动元素;(3) 以 WCAG 相对亮度公式量对比:内文 ≥4.5:1(1.4.3 正常文字)。诚实揭露(Fable 5 M5 复审 H):主要按钮白字 on 主题绿(#18a058)≈ 3.4:1,只达 1.4.11 非文字元件的 3:1 底线,未达 AA 文字标准 4.5:1;测试仅以 ≥3:1 为最低防线并注明此限制,主题色调整列 Backlog(v1.x)。 - 质量门槛:后端 ruff/mypy 干净、pytest 371 passed(+4);前端 eslint/vue-tsc build/vitest 11 绿;Playwright 全套(既有 26 + 新增 a11y 3 / 全旅程 1 / 页面载入 1)。
M5 完成后由 Fable 5 做独立技术审查,判决「有条件可发行」:核心(备份资料路径、导出正确性、排程时区)健全,裂缝集中在伫列互踩与发行流程未演练。以下 A/B/D/E/F 已修(各附回归测试 tests/test_m5_hardening.py),H 诚实化,C 待用户决定公开时机一起走。
- A(已修)——单一伫列阻塞式派工互踩,逾时的还原仍会晚点偷跑:排课占住单一 worker 时,还原排在后面;api 逾时回失败,worker 空下来后却仍执行还原→资料库被无预警覆盖。修:
queue._run_blocking/render_export逾时后job.cancel()(不留在伫列里等著跑);queue.solver_busy()侦测排课进行/排队中,backups._restore在还原前检查,进行中回 409「排课进行中,请待排课完成后再还原」。分出 ops 伫列 + 第二 worker 行程为更完整解,但会引入行程/容器/记忆体(4GB 预算)复杂度,列 Backlog 专卡处理;A 的资料安全洞已由 cancel + 409 封死。 - B(已修)——每日备份链一次失败即永久静默断裂:
daily_backup_job先备份再排下一次,任一次失败→例外→下次永不排入→自动备份无声停止。修:daily_backup_job改 try/finally 先在 finally 排下一次;scheduler.heartbeat同改 try/finally,并顺带自愈——每小时检查DAILY_BACKUP_JOB_ID不在ScheduledJobRegistry就补排。 - D(已修)——
:latest对 ARM 用户是地雷:main push 只建 amd64 却覆盖:latest,ARM NAS(IMAGE_TAG=latest)pull 到无 arm64 manifest 会起不来。修:CIimagesjob 以 channel 区分——main push 推:main,:latest只在版本标签(双架构)时更新。 - E(已修)——pg_restore exit 1 容忍面太宽、警告不进 UI:exit 1 涵盖任何被忽略错误,某张表 COPY 失败也是 exit 1,只凭 returncode 会把资料缺漏报成成功。修:
backup._classify_restore_stderr白名单化——只容忍「设置参数不认得」(跨版本 GUC),其余pg_restore: error一律视为失败(presafe 在,可回退);可忽略警告经RestoreResult.warnings上接,前端System.vue以对话框显示给管理员(不再只留 log)。 - F(已修)——session_epoch 落盘耐久性:Redis 默认 RDB 条件下这个单一 SET 可能一小时未落盘,还原后 Redis 崩溃→epoch 遗失→旧 cookie 复活。修:
force_logout_all设 key 后补bgsave()(尽力而为,失败不挡)。 - H(已诚实化)——a11y 对比主张过度:主色按钮实为文字(适用 4.5:1)却套了 3:1 非文字门槛。已在
a11y.spec.ts与上方补遗如实标注「达 3:1、未达 AA 文字 4.5:1」;主题色调整列 Backlog。 - C(待处理,发行阻挡-流程,非程序):repo 私有→
raw.githubusercontent匿名 404、GHCR 映像 private→docker compose pull被拒、IMAGE_TAG=v1.0.0依赖的版本标签从未推过(双架构 arm64 build 一次都没跑),验收①「干净 VM 从零 pull 安装」实质未验。处置:发行前 repo/GHCR 转 public + 先打v1.0.0-rc1演练(验双架构 build + 干净环境 pull 安装)再打v1.0.0。留待用户决定公开时机一起走。 - v1.x 可延(Fable 5 判定合理,不阻挡发行):G(还原溯源 append-only log、stale 提示持久化;presafe 档名时戳现已足够)、以及既有 Backlog。
修正后质量门槛:pytest 392 passed(+21,含 test_m5_hardening 12)、ruff/mypy 干净;前端 eslint/vue-tsc build/vitest 绿;Playwright 全套回归;docker 实测 A(排课中还原被 409 挡)、B(备份失败链仍存活)。M5 里程碑完成,有条件可发行(待清 C)。
公开发行 v1.0.0 前,Fable 5 做全系统(非逐卡)总体检。核心健全:逐一核对每个 API 端点的 RBAC——管理类全由 viewer/editor/admin_only 守住,教师类全部限缩本人(_get_leave、_get_own_notification、substitution-stats/mine 忽略用户端 teacher_id),跨学期写入有 semester_id 校验,无 IDOR 洞;无 SQL 注入面(全 ORM)、无 v-html/XSS;正式 compose 只对外 80/443;.env 不进映像;15 个迁移 downgrade 全部有实作(可逆)。判「有条件可发行」——裂缝集中在「交给非信息背景教师自架时的安全默认」。发行阻挡 A/B/C + F 已修(回归测试 tests/test_config_hardening.py 9 个):
- A(SECRET_KEY 默认无防呆):
config.py加_harden验证器——secret_key 落在不安全值集合(dev-insecure-change-me/please-change-this-.../空)即以secrets.token_hex(32)取代并logger.warning。避免以公开金钥签署 session。 - B(HTTPS 部署 cookie 未带 Secure):
site_address为真实网域且未显式设cookie_secure→ 自动 True;docker-compose.yml把SITE_ADDRESS也传给 api;.env.example补COOKIE_SECURE说明。 - C(无请求体上限→单校 OOM):Caddyfile 加
request_body { max_size 200MB }(容得下真实 .dump 还原与 Excel 导入);backup.md注明超大 DB 还原改用 volume 复制法。相关端点皆需 editor/admin,属内部误操作等级。 - F(第三方授权揭露):新增
THIRD-PARTY-NOTICES.md(psycopg=LGPL、poppler/pdftoppm=GPL 子行程、Noto CJK=OFL,皆动态相依/子行程使用,MIT 相容),README 连结。 - D/E/G 列 v1.x(下方 Backlog)。
目标:2026 年 8 月排课季前发布 v1.1。依序做,M6-2 先定容器架构,后面的文件与 E2E 叠在其上。 CI 已含 e2e job(30 tests),每张卡完成后 push 即有全栈回归把关;仍须遵守既有 DoD(含真 PostgreSQL 实测与截图目视)。
- 描述:多处测试硬编未来日期,真实日期越过后
clock.is_past_slot会拒绝代课指派,CI 将无声转红。已知:frontend/e2e/substitution-stats.spec.ts(DAY='2026-11-11')、full-journey.spec.ts、backend/tests/test_full_flow.py(_SEM_START=2026-09-01、_SEM_END=2027-01-31)等;开工先全案扫一次(grep2026-/2027-)。改为以「执行当日」推算:请假日=下一个周三(或其他固定星期),学期起讫=今天前后推(起=今天往前一个月、讫=往后六个月之类),集中成 helper(前端e2e/helpers.ts、后端 conftest 或 fixtures)供各 spec 共用。 - 验收标准:
- 全案无「会过期」的硬编日期(节次表等与日历无关的常数不在此列)
- 日期 helper 有单元测试(含「今天就是周三」边界)
- 全套 pytest 与 e2e 绿
- 测试方式:pytest + Playwright 全套;人工查看 grep 结果确认无漏网
- 实作后(commit 待补):两支 helper——
backend/tests/dates.py与frontend/e2e/dates.ts(同一套规则),由「执行当日」推算出一个基准周(距今 ≥14 天:确保基准周每一节都还没上过,不受执行时刻影响)。范围比卡上预估大:后端 8 个测试档、前端 9 支 spec 全数改用 helper 常数。 - 基准周必须「当周到下周三同月」——这是硬需求,不是美观:代课推荐的公平计数与月结统计都以「受影响节次那一天的月份」为范围(
_monthly_sub_counts用affected.date.replace(day=1))。第一版 helper 只保证「距今 ≥14 天」,今天(2026-07-14)推出来的基准周刚好是 WED=7/29、WED2=8/5 跨月,于是test_fewer_monthly_sub_periods_ranks_higher(林师本月已代 1 节、陈师 0 节)与test_cancelling_leave_keeps_already_taught_period当场翻车——动态化第一天就抓到自己的设计缺陷。修正:base_monday()往后找到「周一 +9 天仍同月」的那一周;跨月案例改由cross_month_wednesday()(相邻两个周三分属前后月)专门负责,月结拆帐测试仍验得到。 - 顺手修掉一个假 fallback:
full-journey.spec.ts的leaveDay || '2026-11-11'是死路径(两边同值),真正该做的是「请假日跟著该格位的星期走」,已改为dayOfBaseWeek(entry.weekday)。 manual-shots.spec.ts(手册截图产生器,非回归):改为向示范站查学期,取「学期内、今日之后的第一个周三」;学期已过期则明确报错要求重建示范资料,不再静默产出错的图。- 验证:pytest 452 绿(+59,含 helper 的参数化单元测试:每种「今天」落点、跨年、闰年、以及「不论今天是哪一天,WED/WED2 都同月」40 组)、ruff/mypy 干净;前端 eslint/vue-tsc/vitest 绿;干净全栈(schedci,:8090)e2e 30/30 绿;截图目视确认 UI 显示的是动态算出的「2026-08-05(周三)」而非硬编日期。
- 描述:单一 RQ worker 循序执行,排课(可达数分钟)期间导出/备份逾时失败(M5 复审 A 的正解)。拆
ops伫列:导出(render_export)、备份/还原(_run_blocking)、email 改走ops;自动排课独走default。同一 worker 映像加第二个容器(如worker-ops,command带伫列名;app/workers/worker.py支援指定伫列)。资料安全语意不变:排课中还原仍须 409(还原覆盖整个 DB,与排课写回互斥),solver_busy()只看default伫列即可;每日备份排程器要决定归属(建议 ops)。更新docker-compose.yml(5→6 容器)、docker-compose.limits.yml(worker-ops 建议 512M,总和仍 ≤4GB)、部署/升级文件(docs/deploy/)、CONTRIBUTING 架构描述。 - 验收标准:
- 真实 60 班自动排课进行中,导出 Excel/PNG 与「立即备份」数秒内成功(docker 实测)
- 排课进行中还原仍被 409 挡下(既有测试不退步)
- 排课中 worker-ops 被 kill,导出回明确错误而非无声卡死;重启后恢复
- limits compose 全栈跑 M5-4 旅程无 OOMKilled
- 测试方式:pytest(伫列路由单元测试)+ docker 全栈实测(排课中导出/备份/还原)+ e2e 全套
- 实作后:
queue.py分出default(只跑run_auto_schedule)与ops(导出render_export、备份/还原_run_blocking、寄信enqueue_email);worker.py收伫列名参数(python -m app.workers.worker [ops]),entrypointworker角色把余下参数透传;compose 新增worker-ops(同一 worker 映像,command: ["worker","ops"]),5→6 容器。 - 排程器改挂 ops worker:定时任务(每日备份、心跳)都是维运工作,排进
ops并由worker-ops以with_scheduler=True捞回执行。排课 worker 不跑排程器——它一忙就是好几分钟,不该负责「准时」的事。 - 升级路径的隐形杀手:M6-2 之前每日备份排在
default的 ScheduledJobRegistry。排程器改看ops后,旧的那笔再也没人捞——每日备份会在升级当天静默断裂(备份最不能忍的失败模式)。_drop_legacy_default_schedules()于 ops worker 启动时以固定 job_id 精准移除旧排程再重排(不碰别人的 job),附回归测试。 solver_busy()的 409 保留,但理由改写:分伫列后还原不再「排在排课后面」,可是仍必须挡——这是资料安全不是排队:pg_restore 覆盖整个资料库,而排课 worker 正要把结果写回同一个库。- 验证(docker 全栈,六容器 + limits 3.7GB):60 班自动排课进行中打维运端点——① 导出 Excel 0.0s、② 导出 PNG(ops worker WeasyPrint 渲染)4.0s、③ 立即备份(ops worker pg_dump)0.5s、④ 还原被 409 挡下;排课全程
running未被打断。旧架构下 ①②③ 会排在排课后面直到逾时失败——这就是这张卡的全部意义。 另验 ops worker 停摆:导出/备份回明确 502(「背景忙碌或逾时」,90s/120s 上限后)而非无声卡死,重启后 3.6s 恢复。limits 下跑全套 e2e 30/30 绿,六容器 OOMKilled 全 false、Restarts 全 0(worker-ops 峰值远低于 512MB 上限)。 - 质量门槛:pytest 463(+11,
test_queue_split.py)、ruff/mypy 干净;前端 eslint/vue-tsc/vitest 绿;docker compose config与 limits 叠加皆通过。 - 文件:
docs/architecture.md新增 D9 伫列分工(含容器图改绘)、deploy/README、install、upgrade(显著警语:v1.1 多一个容器,只换映像不换 compose 会让导出/备份/寄信全部逾时失败)、faq(新增「导出一直失败怎么查」)、README、CONTRIBUTING(新增背景任务该走哪条伫列的准则)。
- 描述:(a)
model_builder对候选为空的课直接 raiseSolverInputError,整个部分排课失败——改为部分排课模式下建模前把该课移入未排清单,其余正常;非部分排课维持 raise(讯息要进 log,顺手修 Backlog「check_feasibility 吞讯息」)。(b) 未排清单目前只活在 Redis 24h(progress.pyTTL),草稿可被 force 发布后就没有任何纪录——改为随结果草稿持久化(建议 timetables 加 JSON 栏或子表,Alembic 迁移),版本页与发布警告都改读持久来源。(c)_unscheduled()按 assignment 逐笔记,跑班群组掉一格记 N 笔——按排课单位去重,「未排 N 节」不再灌水。 - 验收标准:
- 一门完全被挡死的课(如未放宽 H4 的协同教学)→ 部分排课成功,该课列未排清单并注明原因
- Redis 清空后,草稿的未排清单仍可查;force 发布后版本页可见「发布时未排 N 节」
- 跑班群组掉 1 格只记 1 笔(单元测试)
- validator 全套与既有 solver 测试不退步
- 测试方式:pytest(solver + API)+ 真 PostgreSQL 实测 + e2e auto-schedule spec 扩充
- 实作后(2026-07-14):
- (a) 完全排不下的课不再炸整锅:
_make_lesson_vars对候选为空的 lesson,只在部分排课模式下改为_force_drop()(建一个恒为 1 的 drop 变数,不建 x/pos 变数),列入未排清单并带上原因;一般模式维持 raise。部分排课的承诺就是「排不下的列清单、其他照排」,先前却在最需要它的时候整锅失败。 - (b) 未排清单持久化:
timetables.unscheduledJSONB(迁移 0016,真 PG 验过 upgrade/downgrade 可逆),由write_result随结果草稿写入。但 Backlog 的描述与现况不符,已据实修正:「哪些课没排」其实一直查得到——completeness()从 DB 重算(配课应排节数 vs 已排格位),对草稿与已发布课表皆可,不依赖 Redis。真正只活在 Redis 24h 的是排不下的原因(只有建模当下的 solver 知道)。故设计为:未排清单仍以 DB 推导为唯一真相(连手动改过的课表都算得对),持久化的 solver 纪录只补上「为什么」——completeness()的每笔unplaced多一个reason栏。 - (c) 跑班群组不灌水:
extract()的未排节数改以排课单位计数(先前按 assignment 逐笔记)。顺带发现群组的subject_name只印第一门选修会误导(一个群组是「多门选修同时段开」),改为列出所有科目(「选修A、选修B」)。 - 顺手修:
check_feasibility吞掉SolverInputError讯息 → 改为记 log(不记的话,未来任何建模 bug 都会伪装成「这份资料无解」)。Backlog 该项结案。
- (a) 完全排不下的课不再炸整锅:
- 验证:pytest 468(+5,
tests/solver/test_partial_hardening.py)、ruff/mypy 干净;前端 eslint/vue-tsc/vitest 绿;迁移 0016 对真 PostgreSQL upgrade→downgrade→upgrade 全过;e2e 31/31(新增partial-unscheduled.spec.ts),截图目视确认自排页未排表列出「美术 · 找不到任何可排的 1 连堂时段」、版本页发布警告的「原因」栏同样显示该句,且 force 发布后completeness仍查得到。
- 描述:
semester_copy.py不带学期起讫日与constraint_config(软约束权重回默认),新学期忘补起讫日会让「今日」判定全错。复制对话框加起讫日栏位(必填,默认带「上学期 +半年」推算值);constraint_config随复制带过去。 - 验收标准:
- 复制后新学期有正确起讫日与相同软约束权重(真 PG 实测)
- 前端对话框有起讫日栏位与默认值
- e2e copy-semester spec 扩充验证
- 测试方式:pytest + e2e
- 实作后(2026-07-14):
SemesterCopyRequest加start_date/end_date(pydantic 验证结束不早于开始 → 422)与constraint_config: bool = True;copy_semester()以 keyword-only 收起讫日,并复制constraint_configs各列。起讫日刻意不沿用来源(那是上学期的日期),由呼叫端明确给。前端复制对话框新增起讫日 date-picker,默认值为来源学期往后推半年(halfYearLater()),并在下方提示「请确认实际校历后修改」;起讫日未填时「建立新学期」停用(漏填不会报错,但请假展开、今日看板、代课「已上过」判定会整个算错,而界面上看不出来)。复制项目多一个「排课偏好设置」勾选——先前新学期会悄悄回到默认权重,上学期调好的偏好就白调了。 - 验证:pytest 472(+4:起讫日写入、颠倒日期 422、偏好跟著复制、明确不勾选时回默认)、ruff/mypy 干净;前端 eslint/vue-tsc/build/vitest 绿;e2e 31/31(
copy-semester.spec.ts扩充为验起讫日默认值 +6 个月、实际写入、偏好设置跟著走),截图目视确认对话框带出「2027-03-01 ~ 2027-07-20」。真 PostgreSQL 实测:来源设 cap=4/S2=55/S5=30 → 复制后新学期起讫 2027-02-15~2027-06-30、偏好完全一致;颠倒日期回 422。
- 描述:一次出货六个 S 级项目——①班级名称加
uq(semester_id, name)(迁移前先清重复,API 撞名回 409);②/api/docs/openapi.json默认关闭,.env显式开启(API_DOCS_ENABLED,dev compose 带开);③主题主色调深至白字对比 ≥4.5:1(不动整体设计),a11y.spec.ts按钮门槛提到 4.5 并移除「未达 AA」注记;④冲突定位把should_stop传进conflict_explainer逐步试解回圈,按取消得 cancelled;⑤(M6-3 已修,本卡不必再做);⑥check_feasibility的SolverInputError讯息记 logsubstitution-log/leaves等清单查询加服务器端上限(如 limit≤1000,完整分页留 v1.2)。 - 验收标准:逐项——重复班名 409 且迁移可从有重复资料的库升级;正式 compose 下
/api/docs404、设置开启后可用;a11y 测试以 4.5 门槛绿;定位中按取消 ≤数秒内回 cancelled;清单超限回截断结果与提示 - 测试方式:pytest(每项至少一测)+ e2e(a11y、取消路径)+ 真 PG 迁移实测
- 实作后(2026-07-14):
- ① 班名唯一:
uq(semester_id, name)(迁移 0017)+ API 建立/改名 409 + Excel 导入逐列挡下(档案内重复、与既有班级重复都指出是第几列,不让它撞 DB 约束变成看不懂的错误)。迁移必须先处理既有重复资料——有重复班名的学校正是最需要这个约束的人,不能让他们一升级就失败。重复者依 id 保留第一笔、其余改名为「301 (2)」…,且会避开资料库里已存在的同名;不删任何资料。真 PG 实测最恶劣情况(三个 301 + 一个既有的「301 (2)」)→ 得到 301 / 301 (3) / 301 (4) / 301 (2) / 302,零重复、约束建立、可逆。 - ②
/api/docs默认关闭:api_docs_enabled=False(docs_url=None→ 路由不存在,404);.env可显式打开,docker-compose.dev.yml带开。端点本身都有权限守著,公开它不是漏洞,但没必要把整套内部 API 摊在网路上(尤其 VPS + 公开网域)。正式栈实测/api/docs→ 404。 - ③ 主色达 AA:新增
frontend/src/theme.ts——Naive 默认#18a058白字只有 ~3.4:1(那是 1.4.11 非文字元件的门槛,而按钮上的字就是文字)。压深到#0d7a43(5.41:1),hover#0e8449(4.76:1)也达标,色相不动。a11y.spec.ts门槛从权宜的 3:1 提到 AA 的 4.5:1,并移除 M5 留下的「未达 AA」诚实揭露——现在真的达了。 - ④ 定位可取消:
explain()收should_stop,每次试解前检查并掷Cancelled;solve_job 接住后把任务标为 cancelled(而非 failed)。定位最长跑一分钟,先前完全不看取消旗标——用户按了取消只能干等,最后还收到一份他已经说不要的报告。 - ⑥ 清单上限:
substitution_log.query(limit=MAX_ROWS)与GET /leaves(MAX_LEAVE_ROWS)各 1000,下到 SQL 的.limit()(测试以 limit=1 验证真的生效,不是个没人用的参数)。完整分页 UI 留 v1.2。
- ① 班名唯一:
- 验证:pytest 482(+10,
tests/test_m6_hardening.py)、ruff/mypy 干净;前端 eslint/vue-tsc/build/vitest 绿;e2e 31/31;真 PG 迁移实测(含重复资料与可逆);正式栈/api/docs404;截图目视新主色。 - e2e 抓到一个既有的测试脚本缺陷:
substitutions.spec.ts的klass()看似 get-or-create,其实每次都 POST——place('王师','国文','701')会把「701」再建一次。先前靠著「允许重复班名」蒙混过去(实际上悄悄建了两个 701),加了唯一约束后当场 409。已改为真正的 get-or-create。连带wizard.spec也曾红一次:它断言仪表板显示的学期,而 substitutions 失败后没跑清理、残留的学期把仪表板顶掉了——是连锁伤害,不是第二个 bug。
- 描述:A(阻挡)ops 伫列无 worker 时 fail-fast;B(阻挡)dev compose 没有任何行程守 ops;C 核心相依钉主版号上限;D 清单截断提示。
- 验收标准:停掉 worker-ops 后导出/备份/还原立即回一句说得出处置的错误(不是逾时);dev compose 起得动导出/备份;相依装得起来且全测绿;清单取到上限时界面讲明被截断。
- 测试方式:pytest + vitest + 六容器栈实测(含实跑一次完整还原)
- 实作后(2026-07-14):
- A:
ops_worker_available()(rq.Worker.count(connection, queue=ops_queue))。render_export与_run_blocking(备份/还原)在派工前检查,没有 worker 就立刻掷RenderError/BackupJobError,讯息直接点名 worker-ops 与 docker-compose.yml。派工前挡下对还原尤其要紧:任务若躺在伫列里,晚点 worker 起来会无预警覆盖资料库。enqueue_email只logger.error不掷例外——它的呼叫点在交易 commit 之后,站内通知已送达,不能为了一封信让已成功的操作看起来像失败(信照排,worker-ops 一起来就补寄)。api 启动时另做一次背景检查(给 6×2 秒宽限期,避开 compose 平行启动的假警报)写进 log。判断不了时(Redis 抖动)一律放行——误判成「没有 worker」会挡掉本来会成功的导出,比让它照原路逾时更糟。 - 原本的升级陷阱比 M6-2 卡上写的更严重:旧 compose 的
command: ["worker"]在新映像下不只不守 ops,也不跑排程器——每日自动备份是静默停摆的(导出逾时至少还很吵)。这正是 fail-fast 必须做进 v1.1 的理由:文件警语挡不住没读文件的人。 - B:
docker-compose.dev.yml的 worker 改command: ["worker", "ops", "default"](单行程守两条伫列;正式环境才拆两个容器)。先前 dev 完全没有行程在守 ops,导出、备份、寄信、定时任务全失效——repo 已公开,这会是外部贡献者的第一印象。 - C:核心相依全部钉主版号上限(fastapi/sqlalchemy/redis/rq/pydantic/psycopg/alembic/uvicorn/bcrypt/openpyxl/itsdangerous)。踩过:
redis未设上限 → 某次重建装到 redis-py 8 → 导出/备份在新环境一律逾时。映像每次发行重新建置,不钉上限等于「上游哪天发大版,用户的部署自己坏掉」。 - D:
SubstitutionLog与Leaves取到上限笔数(1000)时各显示一行截断提示(要看更早的请缩小日期区间/改用调代课纪录查询)。M6-5 卡上写了「与提示」却只做了截断——不讲的话,组长会以为「这学期就只有这些纪录」。
- A:
- 验证:pytest 488(+6,
test_queue_split.py:count=0 → 导出/备份/还原立即掷含「worker-ops」的错且没有派工、email 不掷例外仍派工并记 error、Redis 异常时放行)、ruff/mypy 干净;前端 eslint/vue-tsc/build 绿、vitest 15(+4:两个界面各验「达上限提示/未达上限不提示」);e2e 31/31。六容器栈实测:①停 worker-ops → 导出 502/0.07s、备份 502/0.014s、还原 502/0.016s,讯息完整(先前是 90~180 秒的谜样逾时);②docker compose start worker-ops→ 导出 200(43KB PNG);③实跑一次完整还原(M6-2 之后从未在新架构验过):还原 4.05s、presafe 备份自动产生、学期/班级/已发布课表格位全数回复、旧 session 401「系统已还原或重设,请重新登录」、重新登录后资料正确;顺带确认备份清单里有backup_20260714_020000_auto.dump——每日排程确实跑在 worker-ops 上。
- 描述:还原成功后,api log 会喷一段
ERROR: Exception in ASGI application+AdminShutdowntraceback。功能完全正常(回应 200、资料正确、后续请求正常),但刚按下「还原」的教学组长是全系统最紧张的那一刻——他去看 log 想确认成功与否,迎面一段红字,只会以为还原坏了。这不是资料问题,是信任问题,不该带著发行。 - 根因:
pg_restore --clean会中止资料库上的所有连线,包含本请求验证身分时开的那条 session(路由本身没宣告db,但admin_only→get_active_user→Depends(get_db)有)。FastAPI 0.106 起,yield 依赖的收尾是在回应送出后才执行,届时db.close()对一条已死的连线送出 ROLLBACK →AdminShutdown逸出成 ASGI 例外。因为回应早已送出,用户拿到的是正确的 200——只有 log 难看。 - 修法(两层):
- 根因:
_restore()在派工前先db.close()。还原期间本来就用不到这条 session(稽核一向另开新连线写进还原后的资料库)。路由多宣告一个db: Session = Depends(get_db)——FastAPI 对同一个 callable 有请求内快取,拿到的就是admin_only内部那条 session,不是第二条。关闭前先把user.id/user.username取成纯量,避免user成为 detached instance。 - 防线:
get_db()的finally吞掉close()的例外并记一行 warning。收尾发生在回应送出后,此时掷例外只会变成一段没有请求可归属的 traceback;真正的失败会在查询当下就报错,不会被这里盖掉。这道防线也涵盖「还原期间其他用户的 in-flight 请求」。
- 根因:
- 验证:pytest 490(+2:①拦下请求 session,断言
run_restore被呼叫的那一刻它已经关了;②get_db收尾遇上 close 失败不掷出、只记 warning)、ruff/mypy 干净;e2e 31/31。六容器栈实测:建学期 152/班级 799 → 备份 → 删学期 → 还原 → api log 全程零 traceback、零 ERROR(先前必喷),回应 200/3.5s、学期与班级回复、旧 session 401、稽核以新连线写入(admin | 还原自 …;现状已备份为 …)。
- 描述:
/settings/system只剩左侧选单,内容区一片空白——备份、还原、SMTP、重设精灵四项功能全都点不进去。System.vue呼叫useDialog()(M5 复审 fca20ca 加的,用来显示还原后的可忽略警告),但App.vue从来没挂<n-dialog-provider>;Naive 会在 setup 直接掷错,整页渲染不出来。 - 为什么溜过所有测试:这一页没有任何 e2e 覆盖(31 支 spec 没一支碰它),vitest 也没测。备份/还原的验证一直是走 API,从没走过 UI。是「重拍手册截图」这件事把它逼出来的——截图产生器截到一张白界面。
- 修法:
App.vue补上<n-dialog-provider>;seed_e2e新增e2e_admin帐号(卡片是 admin-only);新增system-settings.spec.ts——三张卡片渲染 + 立即备份(真的打到 worker-ops 的 pg_dump)+ 删除备份。第一个断言就是核心:页面只要 setup 掷错就是全白,必红。 - 验证:pytest 490、vitest 15、e2e 32/32(+1)、ruff/mypy/eslint/vue-tsc 干净;截图目视系统管理页三张卡片完整。
- 描述:M6-5 把主色调深后,手册的 10 张截图全成了旧主色;且截图产生器
manual-shots.spec.ts依赖一台「已经灌好示范资料」的测试站——那些资料当初是手动灌的、没留脚本,导致要重拍时没人知道当初的资料长什么样。 - 修法:示范资料(115 学年度、8 位教师、701~703 班、24 笔配课)与首次登录改密都收进 spec 本身,幂等且可重跑;发布用的 locator 不再写死草稿名;工作台改先排一半的课(空白课表讲不了「拖拉排课」);备份页先真的备一份再截。整套从空资料库一次跑完 = 10 张图。
- 验证:
docker compose -p manual up -d(空 DB)→E2E_BASE_URL=... npm run e2e:manual→ 10 张全新截图,逐张目视:新主色、真实资料、课时「刚好」不再满江红、看板有实际代课纪录、系统管理页完整。
- 描述:M6-8 的教训(整页坏掉两个版本没人发现,因为没有 e2e)促成一次全面清点——把 20 个前端路由对照 e2e 实际造访的页面。结果 18 个有覆盖,唯一没有的是
/change-password:所有测试都走 API 改密码,从没有人点过那个界面。而它是每一位新用户进入系统的第一个界面,坏掉的话连门都进不来。 - 这一页的特殊性:只有在「被强制改密」状态下进得去(路由守卫会把非强制状态的人导回仪表板),所以测试必须用一个处于首次登录状态的帐号。
seed_e2e新增e2e_newuser,且每次 seed 都强制重设回首次登录——测试必然会把这个状态用掉(它就是去改密码的),不重设的话第二次跑 e2e 会失败。 - 测试涵盖:登录后被导向改密页 → 页面真的渲染(核心:整页空白就必红)→ 后端也挡(未改密前功能性 API 回 403,不是只靠前端守卫)→ 想绕去别页会被送回来 → 密码太短/两次不一致/原密码错误各自的讯息 → 成功后离开该页且 API 通了 → 新密码真的能用且不再被要求改密。
- 顺带抓到一只 bug 并修掉:送出钮同时挂了
attr-type="submit"(触发表单 submit)与@click,确认栏又另外挂@keyup.enter,于是onSubmit每次送出都跑两遍。在成功路径上等于送出两次改密请求,第二次必然因为密码已被改掉而回「原密码错误」——新用户设置密码时,会同时看到「密码已更新」和一则红色错误。改为只走表单 submit 这一条路(按钮仍是type=submit,输入框按 Enter 照样触发),并加上送出中不受理的防连点。测试以「同一次送出只出现一则讯息」守住。 - 验证:pytest 490、vitest 15、e2e 33/33(+1)、ruff/mypy/eslint/vue-tsc 干净;
seed_e2e连跑两次验幂等(第二次显示「已重设回首次登录状态」);截图目视改密页渲染正确;Enter 键送出路径在测试中实际走过。
- 三套学制验证资料集(
backend/tests/fixtures/,M1 期间建立,全案共用):elementary_small:小学 6 班(包班+科任+周三下午空+导师时间)junior_high_mid:初中 12 班(领域课程+弹性课程+兼行政减课教师)vocational_high:技高 15 班 3 科(3 连堂实习+工场容量限制+业界师资限定时段+跑班)
- 排课引擎双重验证:所有 solver 测试以独立
validator.py逐项检查硬约束,绝不以 solver 自身状态为准;validator 同时用于「导入外部课表检查冲突」功能的基础。 - 测试金字塔:pytest 单元(服务层/引擎)为主体;Vitest 覆盖 TimetableGrid 等核心元件;Playwright 仅覆盖六大关键旅程(登录、精灵、手排、自排、调代课、导出)。
- 每张任务卡的完成定义(DoD):功能实作 + 卡上验收标准自验通过 + 新增测试绿灯 + 既有测试不退步 + ruff/eslint 干净。
- 开工前先读
docs/architecture.md对应章节;规格冲突时以 architecture.md 为准并回报矛盾。 - 一次只做一张卡;卡外的好点子记入本档末尾「Backlog」区,不顺手实作。
- UI 文案一律繁体中文台湾教务用语(节次、科任、配课、课时、跑班)。
- 资料库 schema 变更必附 Alembic 迁移,且可从前一版顺向升级。
- 完成后更新本档核取方块为
[x],并在 PR/回报中逐条对照验收标准说明验证方式与结果。 - UI 验收由 AI 以 Playwright 直接执行(2026-07-09 起,用户已授权):对含 UI 的任务卡,撰写 Playwright 验收脚本,以 headed + slowMo 模式在用户萤幕上可见地执行,关键步骤截图存
frontend/e2e/screenshots/(gitignore),AI 读取截图确认后向用户回报;脚本存入frontend/e2e/累积为回归测试套件(即 M5-4 的分摊)。用户仅需在旁观看并对 UX/文案给回馈,不再手动逐步操作。
- 【Fable 5 总体检 D】CORS
cors_origins内建 localhost 且不可由 .env 设置;同源部署下无害,v1.x 改为可设置并于正式部署收敛。 - 【Fable 5 总体检 E】清单查询未分页 → M6-5 已加服务器端上限 1000(下到 SQL),
audit-logs本来就有 limit;完整分页 UI 仍列 v1.2(单校规模下上限已足够)。 【Fable 5 总体检 G】已于 M6-5 修毕(2026-07-14):默认关闭(404),/api/docs与 openapi 在正式环境公开.env的API_DOCS_ENABLED可显式打开,dev compose 带开。- 【Fable 5 总体检 C 后续】
restore-upload目前await file.read()整包进记忆体;v1.x 改为串流落地,免大备份占满 api 记忆体(现以 Caddy 200MB 上限 + 超大 DB 走 volume 复制法缓解)。 - 【Fable 5 M5 复审 A 正解】背景任务分
default(排课)/ops(导出/备份/还原)两伫列 + 第二个 worker 行程,让快慢任务隔离——目前排课占住单一 worker 时,组长导出课表会逾时失败(已由 cancel-on-timeout + 还原前 409 封死资料安全洞,但导出体验仍受影响)。需评估行程管理、4GB 记忆体预算与部署文件(5→6 容器或单容器双进程)。 - ~~【Fable 5 M5 复审 H】主题主色
#18a058白字按钮对比仅 ~3.4:1~~ 已于 M6-5 修毕:主色压深至#0d7a43(5.41:1),a11y 测试门槛提到 AA 的 4.5:1。 - 【Fable 5 M5 复审 G】还原溯源:
backup_dir加 append-onlyrestore.log(谁于何时还原哪份),因目前稽核写进还原后 DB 有溯源断点(presafe 档名时戳暂可佐证);条件 D 的 stale 警告改为今日看板持久徽章而非一闪即逝的 toast。 - 前端 bundle 偏大(~1.4MB,主因
app.use(naive)全量注册 Naive UI)。M2 课表页完成后改为按元件 import 或用naive-ui/es自动导入,缩小体积。 M0-3 CI 的 Playwright E2E job 尚未加入已完成(2026-07-13,Fable 5):CI 新增e2ejob——runner 上以 buildx 建三映像(GHA cache 与imagesjob 共用 scope,PR 才验得到 PR 自己的程序码)、docker compose up -d --wait起全栈、python -m app.scripts.seed_e2e建测试帐号(幂等,含精灵标完成)、跑 Playwrightchromiumproject(30 tests;manual-shots/perf-page-load以 project 分组排除——前者需另备示范资料站,后者为 60 班压测、门槛受 runner 效能影响易 flaky)。失败上传 playwright-report/trace/失败截图/容器 log;imagesjob 改为 needs e2e,E2E 红灯不发映像。本机等价验证:干净栈(project schedci,:8090)→ seed 两次验幂等 → 30/30 绿(1.8m)。CI 首跑即抓到一只真虫:redis-py 8(pyprojectredis>=5.2无上限,重建映像静默升级)下,RQlatest_result(timeout=)的阻塞 XREAD 在「共用 client + 多执行绪并发」时被污染,Timeout reading from socket——worker 6 秒完成 PNG 渲染,api 却等到逾时回 500(容器内最小重现:阻塞 XREAD + 并行 ping 同一 client,5 秒炸)。本机因渲染 2 秒内结束撞不到 race 窗口而全绿——正是 e2e 进 CI 要抓的环境性回归。修法:queue._wait_result()以 XREVRANGE 每 0.5s 轮询取代阻塞读(render_export 与 _run_blocking 共用),不依赖 blocked-client 唤醒,任何 client 版本皆稳。前端 CI 用描述已过时,顺手处理(2026-07-13):lock 档其实早已入库;CI 的 frontend 与 e2e job 改用npm install(未提交 package-lock.json)npm ci+ npm 快取(以npm ci --dry-run验证 lock 与 package.json 同步)。已由 e2e job 涵盖(2026-07-13):e2e job 即为「compose 起全栈 + healthcheck + 真实用户流程」的烟雾测试超集。docker compose up端到端烟雾测试尚未纳入 CI- LINE 通知 adapter(v2):LINE Notify 已停用(2025-03),改走 LINE 官方帐号 Messaging API:各校自申请 OA 取得 channel token 填入系统设置;教师加 OA 好友后以绑定码绑定取得推播用 userId(
teachers.line_id为人工联络用,不能直接推播)。实作为NotificationChannel的一个 adapter。 开新学期复制目前不带学期起讫日已于 M6-4 修毕(2026-07-14):复制对话框加起讫日栏位(必填,默认带来源 +半年)。班级名称同学期无唯一性约束(可建两个「301」)已于 M6-5 修毕:uq(semester_id, name)(迁移 0017,会先为既有重复资料改名)+ API/导入挡下。- 跑班群组内配课的
periods_per_week未强制一致(M3-0 发现):群组是「同时段开课」,placements_for一次放入全部成员配课,节数不一致时较短的一笔会先被 H8 周节数守恒挡下,语意暧昧。class_loads已取群组内最长者计算班级占用;M3-2 的 pre-flight 已加group_shape_mismatch错误、建模则直接拒绝。仍建议在配课建立/修改的 API 就挡下(409),让用户当场知道。 - 映像因 ortools 膨胀到 660MB(M3-2):ortools 连带拉进 numpy/pandas/protobuf。实际只有 worker 容器需要排课引擎,api 容器不需要。可拆成两个映像(共用 base + worker 额外装 ortools),或改用
ortools的精简发行版。部署频宽敏感时再处理。 开新学期复制不带已于 M6-4 修毕:复制对话框加「排课偏好设置」勾选(默认带)。constraint_config(M3-3)- 软约束权重设置 UI(M3-3,v2):目前只有
GET/PUT /api/solver/config,没有界面。等 M3-4 的自动排课页上线后,把权重滑杆放在该页的「进阶设置」折叠区。 - 科目 Excel 导入没有「主科」栏(M3-3):
subjects.is_major只能在科目表单勾选。导入范本可加一个选填栏。 - 一门课整学期固定一间教室(M3-2 建模选择):
y[配课, 教室]是每笔配课一个变数,而非逐格挑教室。符合实务(课表上一门课就在一间教室),变数量也小得多。若日后需要「同一门课不同节在不同教室」,改为y[配课, 节次, 教室]即可,约束式不变。 teacher_time_rule无节次表维度(M2 健检 2026-07-10):(weekday, period_no) 的墙钟意义随班级节次表浮动,多表学校中同一条规则在初中部与高中部指到不同时间。v1 定案:规则以「该笔配课班级的节次表」解读(现行 conflict_checker 行为,M3-2 建模比照,单表学校无此问题);日后如有跨表教师的实际需求,再改为墙钟区间定义(schema 需加 period_table_id 或改存时间区间)。【Fable 5 审查】部分排课宣称「永远有解」,但已于 M6-3 修毕(2026-07-14):部分排课模式改为_make_lesson_vars在候选为空时先 raise_force_drop列入未排清单并注明原因;一般模式维持 raise。【Fable 5 审查】跑班群组在部分排课掉一格时,「未排 N 节」会灌水数倍已于 M6-3 修毕:未排节数改以排课单位计数。【Fable 5 审查】冲突定位期间(最长 60 秒)不检查已于 M6-5 修毕:每次试解前检查,取消得 cancelled。should_stop- 【Fable 5 审查】
check_feasibility吞掉SolverInputError的讯息:未来任何建模 bug 都会伪装成「资料无解」。至少把原始讯息记入 log / conflict detail。 - 【Fable 5 审查】
test_purity.py只收level == 0的 import,相对导入(from ..models import ...)可完全绕过纯度扫描。 【Fable 5 审查】未排清单只活在 Redis(24h TTL)已于 M6-3 处理,但叙述须更正(2026-07-14):「哪些课没排」其实一直查得到——completeness()从 DB 重算,对草稿与已发布课表皆可。真正会遗失的是排不下的原因(只有 solver 知道),已随草稿存进timetables.unscheduled(迁移 0016)并在完整性报告中呈现。- 【Fable 5 审查】「validator/report 与 model_builder 零共用程序码」严格说不成立:三者共用
problem.py的slots_overlap(D7 判定)与course_key(排课单位语意)。独立性涵盖约束编码,不涵盖这两个定义层谓词。应为它们补直接的边界单元测试。 - 求解前先跑一次 hard-only 可行性探测(约 1 秒):既能提早回报「这份资料无解」,又能把该解当成正式求解的 warm start。目前是在失败之后才探测。
- 部分排课的 timeout 几乎必定用满:CP-SAT 找到最佳的「未排 2 节」很快,但要证明「不可能只少排 1 节」很慢。可考虑找到解后以未排节数为上界再收敛,或给部分排课独立的较短默认时限。
- 冲突定位的旋钮清单未含「班级可排节次」与「连堂结构」;
structural模式目前只列最吃紧的班级/教师,没有具体到「哪一门课改成连堂就好」。 【E2E 进 CI 后的定时炸弹,2026-07-13 发现】多支 e2e spec 硬编未来日期已于 M6-1 修毕(2026-07-14):前后端各一支dateshelper 由执行当日推算基准周,全案 17 个测试档改用;引信拆除。
M3 完成后由 Fable 5 做独立技术审查,判决「有条件可进 M4」。以下 5 项已修:
- A. H10 双轨判定:
conflict_checker写死cap=2,solver 却读constraint_config。学校把上限设成 3,自动排课排得出来、手动拖曳却报违规。改为由check_conflict读学期设置(hot path 加一次查询,p95 仍 <100ms)。M4 调代课直接重用这支检查器,这条裂缝必须先补。 - B. 软约束权重无上限:
PUT /solver/config接受{"S2": 20000},而部分排课的「整节不排入」惩罚是 10000 → solver 会理性地丢课换分散度。新增MAX_WEIGHT = 100(API 挡、load_config读取时夹),并在Relaxation.__post_init__断言量级顺序。 - C.
unknown静默降级:试解逾时回unknown时被当成「不可行」,但complete没有跟著降,structural于是宣称「即使放宽所有可调整的项目仍然无解」——一句从未被证明的话。新增_Prober追踪certain,任何unknown都让complete=False,structural 措辞随之收敛。 - D. pre-flight 场地供给不看科目适用性:唯一的专科教室绑「美术」,音乐课要求专科教室 → 检查放行、建模必然失败、定位找不到该场地、报告文不对题。改为依「候选场地集合」分组比对供需(与
_candidate_rooms同义),新增room_no_candidate结构性错误(部分排课亦挡)。 - E.
_room_numbers混用池需求与单间供给:多间同类型教室时,原因卡会凭空放大缺口。改为整池计算并在讯息中列出教室名。
验证:pytest 273(+11,含 unknown 路径 4 个测试)、真实 PostgreSQL 打过 A/B/D 端点、e2e 16 绿。