ClassHelper/docs/app/schedules.md

---
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 档案导入最省事，课表、节次时间、单双周会一起进来，
  见[表格与课表导入](imports.md)。
- 课表变更后会广播 `schedule:updated`，客户端与灵动岛立刻刷新。