Repository navigation
ClassHelper v1.3.1（课表同步改为按需 · 客户端页合并 · 成绩排名）
ClassHelper v1.3.1
这一版修掉一个每 15 秒发生一次的线上问题，并把服务端两个割裂的页面合成一页。
原先教室的课表同步是"自动来回"：插件每 15 秒上报一次、每次都带全量课表、上报完还顺手把课表
镜像回 ClassIsland。结果是教室的课表每 15 秒被重写一次、服务端也每 15 秒 merge + 清理一次幽灵行，
老师看到的就是**「课表被反复删改」**。现在两个方向都只在你点按钮时发生一次。
⚠️ 升级须知
服务端升级后会自动应用 2 个数据库迁移（成绩的「考试口径」表Exam、
联动设备的「下发课表」待办requestMirrorSchedule）。升级前请先备份。
ClassIsland 插件要换成 1.3.1 的.cipx（两个本机的课表同步开关已删除，改用服务端下发的待办）。
换完之后教室不再自动镜像课表 —— 要在「客户端」页点「下发课表」才会写进教室。
一、课表同步：从"一直同步"改成"两个按钮"
| 动作 | 在哪点 | 做什么 |
|---|---|---|
| 下发课表 | 「客户端」页的卡片 / 详情 | 把本班课表写进教室，并停用同一天同一单双周相位下冲突的旧课表 |
| 获取课表 | 同上的「获取课表」 | 把教室机器里启用的课表合并进本班课表 |
- 「强制替换」只停用不删除：冲突的课表内容原样留在 ClassIsland 档案里，随时能重新启用；
- 插件侧那两个本机开关（「自动上报课表」「镜像回 ClassIsland」）已删除：定时上报现在只报
运行状态（当前上什么课、ClassIsland 版本），课表只在服务端显式请求时才走一次； - 两个方向都是一次性待办：Web 端点按钮置位，插件在下一次心跳（约 1 分钟内）做一次，做完由服务端清标记。
二、「客户端」页：合并原来的两个菜单
原先「ClassIsland 联动」与「客户端设备」是两页，讲的却是同一个教室的两半（插件管大屏、桌面端管灵动岛）——
给一个班做一件事得先想清楚该进哪一页，批量操作更是无从下手。现在合成一页：
- 一个班一张卡片：大屏与灵动岛两条链路的状态放在一起（在线、版本、当前课程）；
- 批量：勾几个班，一次下发课表 / 一次下发更新；
- 点卡片进详情：签发与重置令牌、启用 / 停用、下发 / 获取课表、远控（关机 / 重启 / 注销 / 锁屏）、移除记录；
- 下发提醒（教室大屏全屏弹出）也搬到了这一页，老师照旧用得到。
入口权限用 classisland:notify（默认管理员 + 教师），页内的设备管理 / 远控 / 下发更新再各自要求
对应的权限键 —— 与后端的三个接口一一对应。
三、成绩：单科排名与总分排名
- 每次导入 / 录入成绩时，可以顺手定下这次考试的「考试口径」：
「所有科目相加，排总分榜」或「只排单科，不合总分」（按「班级 + 考试名」记住）； - 语数外 150 分、音体美 100 分不是一个量纲，所以合不合总分由学校决定，程序不替它默认；
- 排名口径写死在服务端：同一学生同一科目只取最高分（补录 / 重考会产生多行，不去重等于"总分多一科"）、
并列同名次（1、2、2、4）； - 教室机器的「成绩」页可以直接看到全班成绩与排名，不用再按学号一个个查；
- 「能不能看」由班级上的开关控制，而这个开关现在只有教师 / 管理员能在 Web 端改
（原先教室机器自己也能改，等于把"学校说不给看"变成一台机器说了算）。
四、学期开始日期可以在页面上改了
「开学日期填错了」原先只能改 .env 再重启。现在管理员在「学期周次」页直接填写并保存，
当前周次立刻按新日期重算，随时可以纠正 —— 班级仍然可以有自己的开学日期（优先级更高）。
五、大模型助手：补上上课时段的警告
用助手发紧急通知时，原先只有服务端的二次确认，没有手动发布页那个「3 秒倒计时」的全屏警告。
现在两个入口共用同一条上课状态判据 —— 上课时用助手发紧急通知，同样会先弹全屏警告。
六、客户端
- 去掉「自动更新」开关：教室机器是统一投放的终端，版本一致性由管理员在服务端决定；
- 去掉「关怀模式」：那是给 Web 管理端用的，客户端是投在教室大屏上的固定界面；
- 成绩查询开关改成只读：显示服务端下发的状态，本机不再能自己开；
- 修掉一个视觉问题：选中「设置」里的二级菜单后收起分组，高亮块会留在原地不消失。
验收
| 门禁 | 结果 |
|---|---|
lint / typecheck / check:icons / docs:check |
全绿 |
| 后端端到端 | 247/247 |
| ClassIsland 联动链路 | 44/44 |
| 插件静态契约 | 76/76 |
| Web 管理端真实点击 | 34/34（含新增的「客户端」页用例） |
| 客户端冒烟 | 90/90 |
数据库方面：2 个迁移在真实库上跑通，Exam 与 requestMirrorSchedule 都已就位；
端到端验收跑完不留残留数据。
运行期未实测的部分：插件改动已通过编译与静态契约校验，并在本机装了 ClassIsland 2.1.0.1 的
机器上确认「插件加载、订阅、运行无异常」，但**「下发课表强制替换」的完整交互需要在你的教室机器上实测**
（本机验证时服务端指向的是内网地址，拿不到一台在线的真实教室设备）。
产物
| 产物 | 说明 |
|---|---|
ClassHelper-1.3.1-x64-client-setup.exe |
桌面客户端安装包（Windows x64） |
ClassHelper-1.3.1-x64-client-portable.exe |
桌面客户端免安装单文件 |
ClassHelper-1.3.1-x64-server-setup.exe |
服务端安装包（Windows x64，内置 Node 运行时） |
classhelper-server-linux-x64-1.3.1.tar.gz |
服务端 Linux 包（由 GitHub Actions 在 ubuntu-22.04 上构建） |
ClassHelper.ClassIslandPlugin.cipx |
ClassIsland 联动插件（这一版要换） |
SHA256SUMS-1.3.1.txt |
跨组件哈希清单（人读；classhelper upgrade 用的是同名 .sha256） |