ClassHelper/docs/app/schedules.md

title, description

title	description
课表	周课表与「今天」时间轴、单双周、学期周数、课表来源，以及上课时段是怎么判定的。

课表

课表不只是"给学生们看看"的表格 —— 「上课时段」的判定完全基于它。 课表排错，提醒就会在该弹的时候不弹。所以这一页值得读完。

两个视图

视图	在哪	内容
周视图	Web 端「课表管理」、客户端「课表 → 本周」	节次 × 星期 的 7 列表格
今天时间轴	客户端「课表 → 今天」	大时钟 + 当前状态卡 + 时间轴（已结束 / 正在上 / 下一节）

「今天」时间轴是客户端默认打开的那一屏：

• 大时钟：时:分（大字）+ 秒（小字），下面一行是日期 / 星期 / 第 N 教学周。
• 当前状态卡：「正在上 XXX」+ 时段地点 + 距下课 X 分钟；没课时显示"今天的课都上完了"或"今天没有课程安排"。
• 时间轴：左侧时间栏（开始 / 结束）+ 竖向轨道与节点 + 右侧课卡。已结束的置灰、 正在上的用强调色实底 + 进度条 + 距下课倒计时、下一节用橙色标记 + "还有多久开始"。

单双周

一门课可以设成每周（默认）、单周或双周。判定口径是 第 1 周 = 单周。

从 ClassIsland 导入时，WeekCountDiv（0=每周 / 1=单周 / 2=双周）会换算成这套 ALL / ODD / EVEN。 3 周及以上的轮换没法用单双周表达，导入时会给出 warning 并按"每周"处理 —— 如果学校里真的是三周轮换，目前只能用两份课表 + 手工切换的方式绕过。

学期周数

每个班有自己的学期周数（Class.termWeeks，默认 20，上限 30），只有管理员能改。

它决定三件事：课表的周次下拉能选到第几周、weekEnd 的默认值、以及"现在是第几教学周"。 周次换算的起点是服务端 .env 里的 TERM_START_DATE（当学期第 1 教学周的周一）。

TERM_START_DATE 设错，整套周次都错。 它不在界面上改，要改 .env 后重启服务端。 上限三处必须一致（MAX_TERM_WEEK、周次校验、班级设置），曾经出现过"班级能设到 40 周、 而课表只到 30 周"的错位。

上课时段是怎么判定的

服务端有一个接口专门回答"这个班现在是不是在上课"：

GET /api/schedules/current?classId=<班级 id>[&at=<ISO 时间>]

返回 { inClass, current, next, week, serverTime }。at 参数可以覆盖判定时刻，用来联调与测试。

判定结果被用在三处，规则完全一致：

1. 客户端灵动岛：上课时段普通通知不显示（窗口直接隐藏）并进队列，下课自动补弹；
2. 服务端发布接口：上课时段发紧急通知会被拦（409 URGENT_DURING_CLASS），确认后放行；
3. Web 端：提交紧急通知前先查一次状态，命中就弹全屏二次确认。

课表来源

课表由管理端维护，支持手工录入与离线 JSON 导入。升级会保留旧联动课表并将其来源归为 manual。

排课 / 改课 / 导入

• 手工排课在 课表管理（管理员 / 本班班主任）。科目下拉是全校统一的 18 科目录， 选中一个该班还没有的科目会自动建课。
• 从 ClassIsland 档案导入最省事，课表、节次时间、单双周会一起进来， 见表格与课表导入。
• 课表变更后会广播 schedule:updated，客户端与灵动岛立刻刷新。