附录 E：版本兼容与升级
这里列出当前支持的版本、升级注意事项，以及 ClassIsland 插件与主程序的兼容关系。
版本线
Novora 从 v2.7 起分为三条互相衔接的版本线：
| 版本 | 主题 | 状态 |
|---|---|---|
| v2.7.x | 稳定与质量：Hook 依赖修复、共享类型契约、数据库 schema 门禁 | 已完成（v2.7.6） |
| v2.8.x | 考试管理基础：考试记录、生命周期、诊断日志、界面重组 | 当前版本 |
| v2.9.x 起 | 设备与错误体系、作者中心、远程诊断 | 规划中 |
版本与文档覆盖
| 版本 | 是否仍在维护更新说明 | 文档站更新日志 |
|---|---|---|
| V2.8.0 | 是（当前版本） | 有 |
| V2.7.4 – V2.7.6 | 作为修补批次记录 | 有（合并一篇） |
| V2.7.0 – V2.7.3 | 只做安全与严重问题修复 | 有 |
| V2.6.x 及更早 | 不再更新 | 仅索引链接 |
更早的完整记录见 GitHub Releases。
推荐使用哪个版本
- 新部署：直接使用最新稳定版 V2.8.0。
- 已在运行的部署：保持在与文档一致的版本；升级前阅读对应版本的更新说明。
- 有学校自定义代码：在升级分支上合并上游、解决冲突并测试后再进入生产。
数据库结构版本
Novora 使用 schema 版本门禁管理表结构，不需要手工执行 SQL：
| 组件 | 说明 |
|---|---|
| 核心 schema | V2.7.5 起记录版本号，健康检查会报告当前版本 |
| 考试记录 | V2.8.0 新增 exam_records 等表，升级时自动创建并回填 |
| 考试公告 | V2.8.0 新增 exam_announcements 的排版样式与正文图片，以及 exam_announcement_images 表 |
| 诊断日志 | V2.8.0 新增诊断日志相关表，升级时自动创建 |
首次登录和首次 API 调用时，系统会按需建表或补列。不要从其他教程复制 SQL 手工执行，错误的字段定义会导致后续自动升级失败。
数据维护脚本
日常升级不需要跑这些脚本；只有出现下面两种情况时才需要，跑之前先备份数据库。
| 场景 | 命令 | 说明 |
|---|---|---|
| 旧考试的记录缺少时间窗与时间戳 | npm run backfill:record-timestamps | 回填旧考试的时间窗与记录时间戳 |
| 删除考试后记录表留下孤儿行 | npm run purge:orphan-records | 默认只统计不删除；确认后加 --yes，需要连带删除操作日志时再加 --with-operations |
孤儿行是指「快照里已经删掉、exam_records 里还留着」的记录。界面按快照过滤，正常情况下看不到， 但会一直累积；判断口径与 GET /api/exams?resource=record-consistency 的 orphaned 一致。 实际执行步骤见 Vercel 日常维护与本地更新与维护。
升级路径
一般规则
- 同一大版本内（例如 2.7.3 → 2.7.6）可以直接升级；
- v2.7.x → v2.8.x 可以直接升级，表结构和旧数据会自动兼容；
- 跨越大版本（v1 → v2）前必须单独验证，不能假设所有自定义业务数据自动迁移。
v2.7.3 → v2.8.0 的额外说明
这一版把考试管理从「整体覆盖的 JSON 快照」升级为「关系模型 + 生命周期状态机」，但旧客户端读取契约不变：
exam_data.majors仍是权威存储，旧客户端的离线队列、ETag、三方合并行为不变；exam_records是服务端单向投影，可随时从majors重建，回滚不丢数据；- ClassIsland 插件读取的考试数据格式不变，插件不需要同步升级；
- 设备心跳计算当前考试的逻辑不变。
因此升级后不需要通知教室大屏或插件做额外操作。
操作方式的变化（升级前务必确认）
同一批变化里，面向管理员的操作方式改了，和旧版不一样：
- 新建考试创建即发布，不再需要点「发布」，也不再产生草稿（复制出来的考试例外）；
- 没有「开考」按钮：到计划开始时间由系统自动开考；
- 提前收场改为「申请停止」，由系统按「到点 → 教室端全部结束 → 10 分钟无在线设备」判定后结束， 兜底入口是「强制结束」；
- 复制考试先落草稿，改完再发布。
习惯旧流程的学校，建议升级后先按创建一场大型考试走一遍。
ClassIsland 插件兼容
插件通过 /api/exams 与 Novora 通信，配对令牌有效期 5 分钟。
| 事项 | 说明 |
|---|---|
| API 版本 | 插件使用的接口在 v2.7 / v2.8 保持兼容 |
| 数据格式 | 按班级返回的有效考试时间线格式未变 |
| 配对方式 | 一次性令牌 + 浏览器选择年级班级 |
| 升级主程序后 | 不需要重新配对；设备管理中的关联状态保持 |
| 解除设备绑定后 | 插件凭据被撤销，需要重新配对 |
插件源码在 integrations/ClassIsland.ExamReminder，也可从 ClassIsland.ExamReminder 仓库 获取。
兼容性保留标识
升级时不要重命名以下内容，否则会影响本地缓存、设备绑定和插件兼容：
exam-board-* localStorage 键
exam-board-offline IndexedDB 名称
exam-board:* 浏览器事件名
novora-shell-* Service Worker 缓存前缀
novora-runtime-* Service Worker 运行时缓存前缀Service Worker 缓存前缀在发布新版本时只更新末尾的版本号，不要改变前缀本身。
升级前后的检查清单
升级前：
- [ ] 阅读目标版本的更新说明
- [ ] 备份数据库
- [ ] 记录当前版本号和提交号
- [ ] 避开考试和上课时段
- [ ] 通知使用方
升级后：
- [ ] 管理员登录正常
- [ ] 后台能读取和保存数据
- [ ] 教室大屏显示正确
- [ ] PDF 能正常下载
- [ ] ClassIsland 同步正常（如启用）
- [ ] 设置页的版本号已变化
- [ ] 新建一场考试后是「已发布」状态，没有多出草稿
- [ ] 到点后系统自动开考，操作记录里能看到自动开考与结束
需要帮助时
带上以下信息到官方交流群 1067566386 提问：
当前版本：
目标版本：
部署方式：Vercel / Docker / Node
现象与操作步骤：
请求 ID：不要发送数据库连接串、管理员密码、Deploy Hook 或恢复密钥。