Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
88 Commits 1 Branch 15 Tags
35b252249d07e910a0e84563845de10747a674be
Commit Graph
13 Commits
Author SHA1 Message Date
LoveChengke c0ebf88138 chore(release): 1.3.3 发布并退役旧联动 2026-10-17 03:06:46 +08:00
LoveChengke 9d5ac7adf9 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
LoveChengke 3880eee08e feat(desktop,island,shared): 灵动岛支持多条通知竖排列表 + 触摸模式 + 收回动画，产物加凭据门禁 
灵动岛列表：多条通知时展开为竖排列表，默认显示 3 条，点「展开更多」铺到屏幕容纳
上限，放不下的收进「更多请前往应用内操作」。卡片高度由主进程与渲染进程各算一次
同一个数 —— 度量表 ISLAND_LIST_METRICS 与排序权重 PRIORITY_RANK 放在 shared，
窗口包围盒随之长高（不够高会把底部按钮裁掉）。

触摸模式：触摸屏上手指既不产生 mousemove、也不移动系统光标，原先两条命中链路都会
让窗口永远停在穿透态、手指点不开岛。现按 navigator.maxTouchPoints 上报后，主进程把
窗口贴合岛体并始终接收输入；非触摸屏机器完全不走这条路。

收回动画：main 先发 island:closing，渲染进程形变收敛后回 closing-done 才淡出，
不再靠猜时长（rAF 被节流时会把卡片缩到一半窗口就没了）。

安全门禁：新增 scripts/check-bundle-secrets.mjs 并接进 build:desktop ——
dist 产物会被打进 app.asar 发到每台学生机、且可解包，冒烟凭据一律改由环境变量注入，
产物里出现种子口令即构建失败。
 2026-10-02 00:25:10 +08:00
LoveChengke 80a0efbcfe fix(smoke): 冒烟不再悄悄改掉演示班级密码（先试已知密码，必要时才重置并恢复） 
- 现状问题：pnpm verify:desktop 会用管理员接口把被测班级密码改成 smoke123456 且不恢复，
  导致演示实例的「班级码 G101 / 123456」在跑完冒烟后登录失败（本次验证时实际踩到）。
- 现在先按 [冒烟密码, 种子默认 123456] 依次探测：命中就直接用，**完全不改数据**；
  只有当两者都不通时才临时重置，并在脚本收尾（含失败分支）恢复为 123456 并打印日志。
- README 冒烟章节补充说明；演示实例的 G101 密码已恢复为 123456。

验证：verify:desktop 62/62（日志显示「班级账号就绪：G101」即未改动数据）、离线复跑 56/56；
打包便携版 62/62（packaged=true）且跑完后 G101/123456 仍可登录。
 2026-09-12 21:06:58 +08:00
LoveChengke 93447922dc fix(island): 失焦收起加 500ms 宽限期 + 冒烟不再改写班级码（打包产物验证稳定） 
- 灵动岛窗口 blur 处理增加 BLUR_GRACE_MS = 500：激活后 500ms 内的失焦一律忽略。
  实机/打包产物上偶发"刚展开就被系统换前台造成的 blur 立刻收起"，
  表现为"下课后自动弹出通知详情"变成 pill（截图比例也随之异常）；
  宽限期后该用例稳定，且"点击屏幕任意位置收起"用例（展开后等 700ms 再触发 blur）仍正常。
- 桌面冒烟准备班级账号时**永不修改班级码**（只按需重置密码）：
  班级码是给学生用的凭据，不应被测试工具改写；实测产物验证不再依赖固定班级码。

验证: verify:desktop 53/53（首轮）与 47/47（二次启动）全绿
 2026-09-12 17:48:32 +08:00
LoveChengke b07ee4f8d7 test(desktop): 个性化全参数 + 退出无残留的自动化验证（verify:desktop 40 → 47 项） 
新增 7 项真实断言（全部读真实窗口属性，而非界面显示）:
- 透明度 → win.getOpacity 实际 0.62
- 主题色 → 渲染进程 CSS 变量 --island-accent = #ff7043
- 停靠位置 → 左上 8,8 / 右上 1164,8 / 底部居中 586,800 / 顶部居中 586,8
- 置顶开关 → isAlwaysOnTop 关/开
- 动画开关 → 关闭后 60ms 内即到位(404x316)，无逐帧过渡
- 动画速度 → speed=0.5 收回 435ms vs speed=2 收回 128ms
- 持久化 → saveConfig/getConfig 全字段往返一致

需求 5 的'退出无残留'改为进程退出后实测:
- 删除 userData 目录（SingletonLock/IndexedDB 文件锁）成功 → 无句柄残留
- 用同一配置目录二次启动成功并再次全绿 → 单实例锁与进程均已释放

验收: verify:desktop 47/47（二次启动 41/41）, verify:e2e 125/125, verify:web 18/18
文档: README 客户端冒烟验证表刷新为最新实测值 + 新增退出无残留说明
 2026-09-12 16:09:56 +08:00
LoveChengke d11f8e43a1 chore(release): 客户端班级账号收尾 + README/安装包产物更新 
- 客户端设置页展示班级码与登录方式（班级账号 / 个人学生账号）
- 冒烟脚本复用已有班级凭据（现成的班级码 + 密码可直接登录时不再改密码，避免污染实例）
- README: 学生端班级账号章节、功能页面/API/验收/命令计数(verify:e2e 125)同步
- 安装包 README 默认账号补充班级码 G101/G102/G203 + 班级密码 123456

验收: pnpm verify:e2e 125/125, verify:web 18/18, verify:desktop 40/40,
      打包产物实测(portable.exe): 40/40, login=高一(1)班 classSession=true
 2026-09-12 16:02:37 +08:00
LoveChengke 1073436ad6 feat(class-account): 学生端主体改为班级（班级码 + 班级密码）+ 数据按班级隔离 
服务端:
- Class 新增 code(唯一)/passwordHash 与迁移(老数据回填 C00001 形式, 未设密码禁止登录)
- POST /auth/class-login: 班级码 + 班级密码 -> classSession 会话(sub=classId)
- PATCH /classes/:id/class-account: 管理员改班级码/重置密码(唯一性、格式校验)
- auth 中间件/socket 握手支持班级会话(sub 为 classId, 回查 Class 表, 加入 user:{classId} 房间)
- lib/session.ts: 班级设备代全班操作(通知已读/作业完成/成绩总览按全班读写), 普通学生账号行为不变
- 叫人消息同时广播到 user:{classId}, 班级设备立即上岛
- 班级列表/详情按权限返回班级码与密码状态(哈希不外泄)

客户端:
- 登录页改为班级码 + 班级密码(个人学生入口移除, /auth/login 接口保留兼容)
- 作业按钮/成绩标题按班级会话显示(全班标记完成 / 本班成绩)
- 冒烟脚本自动准备班级账号凭据(兼容全新与升级安装)

Web 管理端:
- 班级管理新增「班级账号」列与设置弹窗(改班级码/重置密码/随机生成)
- 新建班级可选自定义班级码, 默认由服务端生成

验证: verify:e2e 125/125(新增班级账号 18 项) verify:web 18/18 verify:desktop 40/40
      (login=高一(1)班 classSession=true)
文档: README 新增「学生端班级账号」章节、API/迁移/验收/默认账号更新; 安装包 README 同步
 2026-09-12 15:51:08 +08:00
LoveChengke 30e4c36809 feat(rbac): 落地角色权限模型（需求 7）——班级/人员/名单/成绩收紧到管理员，班主任管本班课表，科任仅作业·叫人·通知 
## 权限矩阵（前后端共用一份）

- 新增 `packages/shared/src/permissions.ts`：`ClassRole`（ADMIN/HEAD/SUBJECT/STUDENT/NONE）、
  `resolveClassRole()`、`canManageClasses/AssignTeachers/Roster/Schedule/Courses/PublishContent/ManageGrades/Import`
  与 `PERMISSION_MATRIX`（README 与验收脚本据此展开）。
- 后端 `lib/access.ts`：新增 `resolveUserClassRole()`（`Class.teacherId` → 班主任，`ClassTeacher` → 科任）
  与 `assertCanManageClasses/AssignTeachers/Roster/Schedule/PublishContent/ManageGrades`；
  各 service 在**服务层**断言（路由仅做角色过滤），越权统一 403。
- 收紧项：班级增删改、班主任/科任分配、学生名单与账号 → 仅 ADMIN；
  课表/课程增删改 → ADMIN 或本班班主任；成绩录入/修改/批量 → 仅 ADMIN（按需求清单）；
  作业/通知/叫人 → ADMIN、班主任、科任皆可。
- 读权限保持不变：教师仍可查看自己班级的课表/作业/通知/成绩列表与统计。

## 前端按同一矩阵隐藏入口

- 侧边栏：教师端不再显示「班级管理 / 学生管理 / 成绩录入」（管理员仍是 7 项）。
- 班级页：新建/编辑/删除按钮仅管理员可见；课表页：增删改按钮仅"管理员或本班班主任"可见；
  成绩页：录入/批量/删除按钮仅管理员可见。
- **叫人入口调整**：教师需要叫人，而「学生管理」是管理员专属，因此教师入口移到
  「通知发布 → 叫人」（选班级 → 选学生 → 快捷短语/自定义消息；名单走 `/classes/:id/students`，
  不使用管理员专属的 `/students`）；管理员在学生管理页仍保留逐行「叫人」。

## 顺手修掉的两个真实缺陷

- `NotificationsView.openCreate()`：班级列表异步加载期间点「发布通知」会导致「目标班级」为空、
  校验失败且**静默不发布**；现在打开弹窗前会确保班级已加载（冒烟同步等待下拉就绪）。
- `desktop-client/scripts/smoke.mjs`：上一次冒烟被强杀后配置目录仍被句柄占用，`rmSync` 报 ENOTEMPTY
  直接让冒烟启动失败；改为按进程号使用独立目录并容错清理。

## 验证

- `pnpm verify:e2e` **82/82** ✅：新增 14 项角色权限断言（班主任/科任建班被拒、班主任删班被拒、
  班主任/科任分配人员被拒、管理员分配与取消成功、科任管理课表被拒、科任可布置作业、
  科任/班主任录入成绩被拒、管理员录入成功），并把历史用例中"仅管理员可执行"的操作切到管理员令牌。
- `pnpm verify:web` **17/17** ✅：新增「教师端隐藏无权入口」断言（可见菜单=仪表盘/课表/作业/通知，
  越权入口=[]），叫人入口改到通知页后仍验证弹窗、8 条快捷短语、自定义输入与可选中态。
- `pnpm verify:desktop` **34/34** ✅；`lint` / `format:check` / `typecheck` 全绿。
- 数据清理：清掉历史遗留的测试班级与 4 条探针课表，演示数据恢复为 3 个班级。
 2026-09-12 15:02:02 +08:00
LoveChengke 38c7660dd9 fix(desktop-client): 灵动岛反馈修正——红晕改为卡片内部 inset（窗口边缘零外溢）、紧急通知补展开动画、普通通知去掉上岛入场动画、点空白处/右上角按钮回缩为胶囊、上课时段严格不显示；冒烟用独立 userData 以免与运行中的客户端抢单实例锁 2026-09-12 09:39:33 +08:00
LoveChengke 3a9f8812fc feat: 客户端灵动岛 + 上课时段紧急通知二次确认，并修复打包/校验脚本在 Electron 宿主下的多个缺陷 
## 客户端灵动岛（动态岛）

- 新增独立透明置顶窗口：桌面中上方常驻、不占任务栏、不抢焦点（268x44 胶囊 / 404x316 详情 / 424x344 紧急）
- 三种形态与动画：隐藏 ↔ 胶囊 ↔ 详情，尺寸用 easeOutCubic 260ms 逐帧缓动、透明度单独淡入淡出
  （尺寸与淡入使用各自动画令牌，避免互相打断导致窗口卡在胶囊尺寸）
- 行为：普通通知变「新消息 · 共 N 条」胶囊，点击展开详情；上课时段自动隐藏并进入待发队列，
  下课后自动弹出；紧急通知无论是否上课立即展开（红色呼吸光晕 + 紧急角标，无需点击）
- 上课状态来自 GET /api/schedules/current（10s 心跳 + 下课时长定时器），
  新增 src/main/island.ts（控制器/IPC）、src/preload/island.ts、src/island/IslandApp.vue、
  src/renderer/island/bridge.ts、island.html 与多页 Vite 构建

## 上课时段发布紧急通知的二次确认

- 服务端：priority=URGENT 且当前处于上课时间段且未带 confirmDuringClass 时返回
  409 URGENT_DURING_CLASS（携带 current/next/week/serverTime），绕过界面调接口同样被拦截
- 新增 GET /api/schedules/current（inClass/current/next，at 参数用于诊断与测试）
- Web 管理端：全屏警告遮罩（UrgentClassWarning.vue），显示正在上的课时段与待发布标题，
  确认按钮带 3 秒倒计时（圆环进度，倒计时结束前禁用），取消即不发；并发命中 409 同样兜底弹窗

## 打包与验证脚本修复（Electron 宿主环境）

- scripts/lib/node-runtime.mjs：定位真正的 node.exe。此前经 pnpm 运行时 process.execPath 指向
  Electron，dist:server 会把 Electron 复制成安装包内的 node.exe，dist:win 会让 electron-builder 报
  Unknown argument: .../cli.js（改为显式使用真实 Node）
- scripts/lib/electron-env.mjs：启动 Electron 前清理继承的 ELECTRON_RUN_AS_NODE（否则 Electron 退化为
  纯 Node，require('electron') 直接 MODULE_NOT_FOUND），并从 path.txt 定位 electron.exe
  （process.versions.electron 存在时 import 'electron' 返回的是 API 对象而非路径）
- scripts/dist-server.mjs：新增构建产物新鲜度校验（曾出现 server 已重建但打进安装包的 shared/dist 是旧的，
  安装后服务启动即报 does not provide an export named MAX_TERM_WEEK）
- scripts/ui-smoke：新增 live-probe.mjs 真实制造/清理上课时段，Electron 驱动真实点击断言全屏警告文案、
  按钮禁用与 3 秒倒计时时长（实测 2966ms），测试后自动删除探针课表与测试通知

## 验证结果

- pnpm verify:e2e 62/62（新增上课时段拦截、二次确认后发布、普通通知不受限等 8 项）
- pnpm verify:web 8/8（新增上课时段紧急通知全屏警告 + 倒计时）
- pnpm verify:desktop 18/18（新增灵动岛窗口/上课隐藏/下课弹出/紧急立即展开/胶囊点击展开 + 截图）
- 打包后 EXE 冒烟 15/15（packaged: true，退出码 0）
- 服务端安装程序升级安装：.env 与数据库保持不变，/api/schedules/current 正常
- pnpm lint / format:check / typecheck 全部通过
 2026-09-12 08:41:08 +08:00
LoveChengke 5545ef6f55 feat: 生产化改造（服务端安装程序/PWA/Docker+HTTPS）并修复侧边栏点击无反应、SPA 静态托管 dotfiles 两个缺陷 
- 修复 web-admin 与 desktop-client 侧边栏点击无反应：el-menu 的 index 是路径，不能当路由名使用
- 修复 Web 产物目录含点号目录（如 .cache）时 res.sendFile 因 dotfiles:ignore 返回 500
- 后端生产模式：静态托管 Web 端 + SPA 回退、helmet、限流（通用/登录）、trust proxy、
  /healthz 与 /readyz、请求耗时日志、生产环境变量强校验、首启动自动迁移与创建管理员、PID 文件
- Web 管理端 PWA：manifest + service worker + 图标，可在浏览器安装为应用
- 新增服务端 + Web 管理端 Windows 安装程序（内置 Node 运行时、启停与服务脚本、开机自启、卸载保留数据）
- 新增 Docker/Compose/Nginx 部署样例与 docs/production.md
- 新增 UI 回归测试：Web 端 Electron 驱动真实点击 7 项、客户端冒烟 11 项（含侧边栏点击与离线回退）
 2026-09-12 00:20:21 +08:00
LoveChengke 6e4c7c1050 feat(desktop-client): 阶段4-6 Electron EXE 客户端（登录/课表/作业/通知/成绩/设置 + Socket.IO 实时 + IndexedDB 离线缓存与自动同步 + electron-builder 打包） 2026-09-11 22:46:31 +08:00