LoveChengke
9d5ac7adf9
学生、任课关系、周次口径三处长期靠约定维持的事情，改为由数据模型保证。 学生不是账号 - 拆出独立 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 原样搬迁，历史数据不丢）， 升级前请先备份。
4.5 KiB
4.5 KiB
title, description
| title | description |
|---|---|
| 实时事件（Socket.IO） | 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。 |
实时事件（Socket.IO）
连接
io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
（客户端在检测到服务器恢复时会触发 onServerRecovered）；灵动岛的上课时段暂存通知由服务端保留、
下课后补发，不依赖重连。
事件清单
事件名定义在 @classhelper/shared 的 SOCKET_EVENTS —— 不要手写字符串。
| 事件 | 方向 | 载荷 |
|---|---|---|
connected |
服务端 → 客户端 | { userId, role, rooms } |
notification:new |
服务端 → 客户端 | NotificationDto |
homework:new |
服务端 → 客户端 | HomeworkDto |
homework:updated |
服务端 → 客户端 | HomeworkDto & { deleted?: boolean } |
homework:status |
服务端 → 客户端 | HomeworkStatusDto & { classId } |
grade:updated |
服务端 → 客户端 | GradeDto |
schedule:updated |
服务端 → 客户端 | { classId, action, schedule? } |
class:updated |
服务端 → 客户端 | { classId, action } |
call:new |
服务端 → 客户端 | 叫人消息（定向到 user:{studentId} / 班级设备） |
classisland:state |
服务端 → 客户端 | ClassIslandStateEvent（教室现在上什么课） |
classisland:notification |
服务端 → 客户端 | ClassIslandNotificationEvent（提醒已下发） |
class:join / class:leave / ping |
客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
房间规则
房间名定义在 SOCKET_ROOMS：
| 房间 | 谁在里面 |
|---|---|
class:{classId} |
这个班的所有在线端 |
user:{userId} |
某个用户自己的连接 |
teacher:{teacherId} |
某个教师 |
role:{role} |
某一角色（ADMIN / TEACHER …） |
students |
全部 ClassHelper 班级端连接 |
teachers |
全部教师端连接 |
服务端通过 realtime/bus.ts 的 emitToClass / emitToUser 发事件 ——
业务模块不直接依赖 Socket.IO 实例，只依赖事件总线。
新增一个实时事件要改三处
① 服务端 shared/src/constants.ts 的 SOCKET_EVENTS 加常量
→ business service 调 bus.emitToXxx(...)
→ realtime/socket.ts 房间映射（如果需要新房间）
② Web 端 web-admin/src/stores/realtime.ts 订阅
③ 客户端 desktop-client/src/renderer/stores/realtime.ts 订阅
→ 灵动岛也依赖它（renderer/island/bridge.ts）
只改服务端不会报错，只是前端静静地不更新 —— 所以这三处必须一起改。 事件名一律取自共享常量，不要手写字符串（拼错一个字就是一个静默失效）。
事件到达之后发生什么
以通知为例：
服务端写库 → bus.emitToClass(classId, notification:new)
├─► Web 端 stores/realtime.ts → 通知列表刷新
└─► 客户端 stores/realtime.ts → 更新内存状态 + 写回 IndexedDB
└─► island/bridge.ts → pushNotificationToIsland()
└─► 主进程 IslandController 决定：隐藏 / 胶囊 / 详情
└─► 灵动岛渲染进程 IslandApp.vue
上课时段的取舍（隐藏还是立即展开）由主进程的 IslandController 按当前上课状态决定，
见通知与提醒与灵动岛。