考试数据接口
这页面向把考试数据接入班牌、电子屏或校园系统的开发者。只需要教室自动提醒时，使用 ClassIsland 插件。
认证方式
接入方通过配对获得客户端密钥，之后用该密钥访问考试数据。Novora 只保存密钥的 SHA-256 摘要。
| 方式 | 适用场景 |
|---|---|
| 插件配对（推荐） | 长期运行的教室端程序，一次配对长期使用 |
| 管理员会话 | 管理后台自身调用，不用于第三方集成 |
不要把管理员密码写进第三方程序。管理会话会随密码变更和会话过期失效，也不适合长期运行。
主要接口
| 接口 | 方法 | 作用 |
|---|---|---|
/api/exams （action=plugin-pair-start） | POST | 发起配对，返回 5 分钟有效的一次性令牌 |
/api/exams （action=plugin-pair-status） | POST | 查询配对状态 |
/api/exams （action=plugin-bootstrap） | POST | 首次同步，获取学校信息与考试来源 |
/api/exams （action=plugin-api） | POST | 日常同步有效考试时间线 |
/api/time | GET | 获取服务端时间，用于校正本地时钟 |
/plugin/connect?token=... | 页面 | 配对的浏览器侧入口 |
时间校正
教室设备的系统时间可能不准。建议：
- 启动时调用
/api/time获取服务端时间； - 计算本地时间与服务端时间的偏移量；
- 之后所有提醒都用「本地时间 + 偏移量」判断。
插件就是这样做的，可以避免因为电脑时钟偏差导致提醒提前或推迟。
数据范围
接入方只能读到绑定班级的考试安排。接口不会返回：
- 管理员账号、密码或会话；
- 其他班级的考试数据；
- 学校用户列表；
- 数据库连接信息；
- 设备管理中的敏感字段。
如果发现返回范围超出预期，先检查配对时选择的班级，再联系维护人员。
建议的同步策略
| 项目 | 建议值 | 说明 |
|---|---|---|
| 轮询间隔 | 30 秒 | 与官方插件一致，兼顾及时性和服务器压力 |
| 失败重试 | 指数退避 | 网络抖动时不要高频重试 |
| 缓存 | 保留最近一次成功结果 | 断网时仍可显示已有安排 |
| 去重 | 持久化提醒记录 | 避免重启后重复提醒 |
免费额度下的部署对轮询频率敏感。如果接入数量较多，优先考虑提高间隔，而不是增加请求。
断电与重启
教室设备经常会在放学后断电。恢复供电后，程序应当：
- 重新读取本地缓存的考试安排，先显示已有内容；
- 后台请求一次同步，成功后覆盖缓存；
- 重新计算时间偏移；
- 检查是否有错过但尚未结束的考试，避免重复提醒已经结束的场次。
版本兼容
接口在 v2.7 / v2.8 保持兼容，v2.8.0 新增的考试记录与生命周期功能不改变插件读取的数据格式。旧接入方不需要修改。
如果请求中没有发送版本字段，服务端会按 API v1 的兼容路径处理。
安全建议
- 客户端密钥只保存在设备本地，不要写进源码仓库或公开配置文件；
- 只通过 HTTPS（或受控内网）通信；
- 不要把接口响应中的请求 ID 之外的调试信息随意外传；
- 发现密钥泄露时，在后台解除该设备绑定并重新配对。
相关
- 配对细节：ClassIsland 配对与设备绑定
- 插件接口说明：ClassIsland 接口与兼容
- 故障排查：故障排查