feat(shared,server,web,client,plugin)!: 角色与权限重构 + 学期周次 + 课表方向反转（1.2.0）

学生、任课关系、周次口径三处长期靠约定维持的事情，改为由数据模型保证。学生不是账号 - 拆出独立 Student 表，没有 passwordHash / role / 任何登录字段 - 「学生不能登录」由表结构保证，不再靠「登录前判 role 再 403」的代码分支 - 三张个人数据表外键 userId → studentId；删掉 Enrollment 与 ClassTeacher - 学生一律称「学号」、教师一律称「工号」，「学生账号」这个概念消失任课关系唯一来源 = Course（班级 + 科目 + 教师） - 班主任 = Class.teacherId，科任 = Course.teacherId，同一人两处指向同一账号、不重复建号 - 作业与成绩按科目再收一道：挂科目只由该科任课老师改，没挂科目归班主任 / 管理员 - 新增「任课教师分配」与「班级教师批量导入」（带「使用工号匹配」开关）成绩与名单 - 成绩等级：百分制 / 等级制 A·B·C·D / 自定义，支持单个与批量改等级 - 按学号查成绩明细（教师端 + 班级端 + 设备令牌），受按班开关控制 - 调班 / 转出（单个与批量）+ 可查历史；学号不变、历史作业成绩留原归属 - 毕业归档页（按年度记录毕业班级 / 毕业生 / 转出学生 / 该届通知与作业） - 学年升级（未毕业不归档、数据沿用）；班级称呼改为「2026级1班」 ClassHelper 班级端在线状态 - Web 端显示班级 / 设备名 / 设备号 / 在线离线 / 最后在线 / 最后心跳 - lastHeartbeatAt 驱动 60 秒在线窗口，与只表示「带状态上报」的 lastSeenAt 分开学期周次 - 新增 TermWeek（classId 空串 = 全校默认），管理员可用日期范围选择器逐周配置 - 一键按开学日期生成整学期；联网拉取调休建议（只给建议、不改数据，无外网失败属正常） - 改周次后随课表下发给教室的 ClassHelper 班级端课表方向反转 - 主方向改为「服务端 → 教室」自动下发；教室不再自动回传 - 取教室课表改为手动动作（点击前弹警告），插件按待办标记在下一次心跳补报改名 - 班级小助手 → ClassHelper：界面、窗口标题、托盘、灵动岛、EXE、安装包、安装目录、systemd 描述、插件清单与设置页、官网、文档站、README BREAKING CHANGE: 产品名与 EXE 名变更（班级小助手.exe → ClassHelper.exe），安装目录随之改变，不支持覆盖安装，需先卸载旧版。服务端首次启动会自动应用 6 个数据库迁移（学生行按 id 原样搬迁，历史数据不丢），升级前请先备份。
2026-10-06 19:41:18 +08:00
1 parent 17f55864bf
commit 9d5ac7adf9
@@ -1,15 +1,15 @@
-# 班级小助手联动插件
+# ClassHelper 联动插件

-把 [ClassIsland](https://classisland.tech) 与 [班级小助手](https://github.com/LoveChengke/ClassHelper) 连起来：
-让班级小助手**读到教室真实的课表与上课状态**，也让老师的提醒**在教室的 ClassIsland 上弹出来**。
+把 [ClassIsland](https://classisland.tech) 与 [ClassHelper](https://github.com/LoveChengke/ClassHelper) 连起来：
+让 ClassHelper**读到教室真实的课表与上课状态**，也让老师的提醒**在教室的 ClassIsland 上弹出来**。

 ## 它能做什么

 | 方向                             | 说明                                                                                                        |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| ClassIsland → 班级小助手         | 上报课表与节次时间、上报上课状态（当前科目 / 下一节 / 本节起止时间）                                        |
-| 班级小助手 → ClassIsland         | 老师在 Web 端下发提醒 → 教室的 ClassIsland 上**全屏弹出**（可语音朗读），播完回执、不重复弹                 |
-| 班级小助手 → ClassIsland（可选） | 把班级小助手上排好的课表**镜像**回 ClassIsland（新建 `班级小助手-<班级名>` 档案课表，不改动老师原有的课表） |
+| ClassIsland → ClassHelper         | 上报课表与节次时间、上报上课状态（当前科目 / 下一节 / 本节起止时间）                                        |
+| ClassHelper → ClassIsland         | 老师在 Web 端下发提醒 → 教室的 ClassIsland 上**全屏弹出**（可语音朗读），播完回执、不重复弹                 |
+| ClassHelper → ClassIsland（可选） | 把 ClassHelper上排好的课表**镜像**回 ClassIsland（新建 `ClassHelper-<班级名>` 档案课表，不改动老师原有的课表） |

 ## 安装

@@ -17,23 +17,23 @@
   - 用打包好的 `ClassHelper.ClassIslandPlugin.cipx`：ClassIsland →「设置 → 插件 → 从文件安装」；
   - 或直接把 `ClassHelper.ClassIslandPlugin/` 目录（含 `manifest.yml` 与 dll）丢进插件目录
     （Windows 默认 `%APPDATA%\ClassIsland\Plugins`，便携版在安装目录下的 `Plugins`）。
-2. 重启 ClassIsland，在「设置 → 插件」里确认「班级小助手联动」已启用。
-3. 打开「设置 → 班级小助手联动」，填入：
-   - **服务器地址**：班级小助手后端地址，例如 `http://127.0.0.1:4000`；
-   - **设备令牌**：在班级小助手 Web 端「ClassIsland 联动」页面为本班新建一台设备后复制（形如 `chci_...`，只显示一次）。
+2. 重启 ClassIsland，在「设置 → 插件」里确认「ClassHelper 联动」已启用。
+3. 打开「设置 → ClassHelper 联动」，填入：
+   - **服务器地址**：ClassHelper后端地址，例如 `http://127.0.0.1:4000`；
+   - **设备令牌**：在 ClassHelper Web 端「ClassIsland 联动」页面为本班新建一台设备后复制（形如 `chci_...`，只显示一次）。
 4. 点「立即上报」验证连接状态；状态卡片显示「已连接」即接入成功。

-## 配置项（全部在「设置 → 班级小助手联动」里）
+## 配置项（全部在「设置 → ClassHelper 联动」里）

 | 配置项                       | 说明                                                                                               |
 | ---------------------------- | -------------------------------------------------------------------------------------------------- |
-| 服务器地址                   | 班级小助手后端地址（含端口；末尾斜杠与多余的 `/api` 后缀都会被自动容错）                           |
+| 服务器地址                   | ClassHelper后端地址（含端口；末尾斜杠与多余的 `/api` 后缀都会被自动容错）                           |
 | 设备令牌                     | 由 Web 端「ClassIsland 联动」页生成；服务端只存 sha256，明文只在页面上出现一次                     |
-| 上报课表到班级小助手         | 把 ClassIsland 里**已启用**的课表同步过去（合并写入：同星期同时间更新，不产生重复行）              |
+| 上报课表到 ClassHelper         | 把 ClassIsland 里**已启用**的课表同步过去（合并写入：同星期同时间更新，不产生重复行）              |
 | 把班级课表镜像回 ClassIsland | 反方向同步，新建带前缀的档案课表；关闭后仍会照常上报「现在上什么课」                               |
 | 自动上报                     | 启动 / 课程事件（上课、下课、放学、状态变化）/ 定时各上报一次；关闭后只能用「立即上报」手动触发    |
 | 上报间隔（秒）               | 定时上报间隔，最小 15 秒，教室机器建议 60 秒                                                       |
-| 接收班级小助手提醒           | **本机总闸**：关掉后本机忽略老师下发的提醒（提醒仍留在班级通知中心）                               |
+| 接收 ClassHelper提醒           | **本机总闸**：关掉后本机忽略老师下发的提醒（提醒仍留在班级通知中心）                               |
 | 语音朗读                     | 是否允许本机朗读（老师下发时也勾了「语音朗读」才会念，两个条件都满足才出声）                       |
 | 默认显示时长（秒）           | 老师未指定时长时用这个值；单条提醒可以在 Web 端单独指定更长的时长                                  |
 | 提醒轮询间隔（秒）           | **老师按下发送 → 教室弹出之间的最大延迟**（插件不持有长连接，是轮询取回的），默认 10 秒、最小 5 秒 |
@@ -48,20 +48,20 @@

 > **课间**：镜像回 ClassIsland 的课表会自动补上课间 —— **每两节之间**一段
 > （上一节下课 → 下一节上课），**最后一节之后不补**（放学）。课间由插件按课目时间算出来，
-> 不依赖班级小助手那边是否维护节次时间表，因此 ClassIsland 档案里一定有完整作息。
+> 不依赖 ClassHelper那边是否维护节次时间表，因此 ClassIsland 档案里一定有完整作息。

 > **两个方向各自需要的开关**：
 >
 > - 服务端 → ClassIsland（镜像课表）：插件「把班级课表镜像回 ClassIsland」**且** Web 端该设备「镜像课表」都打开；
-> - ClassIsland → 服务端（上报课表）：插件「上报课表到班级小助手」打开；
->   关着时是正常行为（日志会写「仅状态（本机「上报课表到班级小助手」开关已关闭）」），不是上报失败；
+> - ClassIsland → 服务端（上报课表）：插件「上报课表到 ClassHelper」打开；
+>   关着时是正常行为（日志会写「仅状态（本机「上报课表到 ClassHelper」开关已关闭）」），不是上报失败；
 > - ClassIsland 里一张课表都没有时不会上报课表（日志会写「ClassIsland 里没有**启用的课表**」）。

 > **提醒到底会不会弹，取决于两个开关：**
 >
 > 1. 教室机器的 **ClassHelper 客户端**在「设置 → 通知显示位置」里选了「只在 ClassHelper 客户端弹」时，
 >    服务端根本不会推过来（此时本插件收不到东西，属正常）；
-> 2. 本插件的「接收班级小助手提醒」关掉时，即使推过来也不弹。
+> 2. 本插件的「接收 ClassHelper提醒」关掉时，即使推过来也不弹。
 >
 > 两者都开着，提醒才会在 ClassIsland 上出现。

@@ -75,7 +75,7 @@
  补上「教室机器关机期间老师发的通知」。上报间隔本身就是心跳，插件因此少一个长连接故障面。
 - **提醒必须由「提醒提供方」发出**：只有通过 `NotificationProviderBase` 发出的提醒，
  才会走 ClassIsland 主界面的全屏特效 / 语音 / 音效那一整套流程，因此插件注册了
-  「班级小助手提醒」提供方（可以在 ClassIsland 的「提醒」设置里整体开关它）。
+  「ClassHelper提醒」提供方（可以在 ClassIsland 的「提醒」设置里整体开关它）。
 - **回执时机 = 真的播完**：回执挂在提醒的 `Completed` / `Canceled` 上，
  中途退出 ClassIsland 不会回执，下次上报会重发 —— 既不静默丢提醒，也不会重复弹。
 - **镜像时重建时间点**：ClassIsland 的 `ClassPlan.Classes[i]` 必须与时间表里
@@ -85,7 +85,7 @@
 - **单双周口径与三端一致**：`WeekCountDiv/WeekCountDivTotal` ⇄ `ALL/ODD/EVEN`
  与 `@classhelper/shared` 的 `weekParityFromDiv` / `weekDivFromParity` 互逆；
  3 周及以上的轮换本系统无法表达，会降级为「每周」并在日志里提示。
- **非破坏性**：镜像只创建 / 更新名字以 `班级小助手-` 开头的课表与时间表；
+- **非破坏性**：镜像只创建 / 更新名字以 `ClassHelper-` 开头的课表与时间表；
  老师手动建的课表不删不改名，同一星期已有启用课表时会在日志里给出重叠提示。

 ## 上机联调记录（ClassIsland 2.1.0.1 实测）
@@ -129,7 +129,7 @@ pnpm verify:classisland-plugin     # 45 项静态契约校验（清单一致性

 ## 常见问题

-**填好令牌后点「立即上报」，提示 `HTTP 404`（响应不是班级小助手的标准格式）**
+**填好令牌后点「立即上报」，提示 `HTTP 404`（响应不是 ClassHelper的标准格式）**
 这台机器上的**系统代理拦了内网请求**。Windows 的代理设置里 `127.0.0.1` 并不在默认绕过列表里，
 于是浏览器/插件对「本地服务」的请求也被送到代理，拿到的是**代理自己的 404 错误页**。
 插件已对本地/内网地址（localhost、回环、10/172.16-31/192.168、链路本地、无点主机名）**强制直连、绕开系统代理**；
@@ -151,7 +151,7 @@ pnpm verify:classisland-plugin     # 45 项静态契约校验（清单一致性
 2. 确认 Web 端「ClassIsland 联动」页面上该设备是「已接入」状态（停用后服务端会直接 403）；
 3. 提醒会在 24 小时后过期，避免教室机器一开机弹出一堆旧通知。

-**课表上报了但班级小助手上没变化**
+**课表上报了但 ClassHelper上没变化**
 确认插件设置里打开了「上报课表到服务端」，且 Web 端该设备的「回传课表」开关也是允许状态。

 **镜像开关打开了，但 ClassIsland 的课表没变**
@@ -160,4 +160,4 @@ pnpm verify:classisland-plugin     # 45 项静态契约校验（清单一致性

 ## 许可

-与班级小助手仓库一致。
+与 ClassHelper仓库一致。