LoveChengke
817af02357
功能级准入改为「权限键」，`requireRole` 退成默认模板。 权限组 - 权限目录（39 键：键 / 中文名 / 分类 / 默认角色）收口到 shared，路由挂 requirePermission / requireAnyPermission - 有效权限每请求实时算，改完分组立刻生效：ADMIN 全集且 permission:manage、system:manage 不可剥夺； CLASS_DEVICE 空集（不受分组影响）；有分组 = 并集（因此也能用来**收回**权限）；无分组 = 角色默认模板 - 新增「权限组」页：组增删改、成员分配、生效权限预览 - 班级维度的科目规则（assertCanManageSubjectContent）故意不可被权限组覆盖 客户端设备（ClassHelper 桌面端） - 设备身份是 deviceKey（首次启动生成的 UUID，saveConfig 拒绝改写、退出登录也保留） - 心跳走「DB 记状态 + 客户端定时拉」，不引入新的长连接：30 秒一次，在线窗口 90 秒 - 远控命令 shutdown / restart / logoff / lock：服务端有效期 10 分钟，客户端弹默认选中「取消」的对话框、 60 秒未确认按取消处理，执行后必须回执（重复回执幂等），同一台机器同一条命令只弹一次 - 新增「客户端设备」页：版本一览、一键推送更新、下发远控 客户端安装包由服务端下载并缓存（教室机常常没有外网，浏览器也受 CSP 限制） - POST /api/update/client/fetch 由服务端下载到 data/client-releases/<版本>/ 并登记 sha256 + size - 自动安装三条护栏：没有 sha256 就拒收、必须等到非上课且主窗口隐藏满 5 分钟、冒烟模式永不安装 大模型助手：只解析、不落库 - POST /api/ai/interpret 返回**待确认**的结构化动作（建作业 / 发通知 / 叫人）， 真正落库仍调既有端点 —— 权限断言、上课时段紧急通知保护、ClassIsland 推送全部自动复用 - 模型给的 params 用与手动入口**同一份** zod 再校验（模型输出不可信） - API Key 走 AES-256-GCM（密钥由 JWT_SECRET 经 scrypt 派生）加密存 AppSetting，只进不出 - provider=mock 是离线确定性解析，自动化验收一律用它；每次解析写一条 AiAudit（不含密钥） 系统与运维 - 开发者模式（服务端内存缓存开关，热路径不查库；开启后 500 才附 error.stack）、运行诊断（绝不回传密钥） - 开机自启动运行期可改：Windows 改 HKCU\...\Run、Linux systemctl enable/disable， **非安装形态一律返回 supported:false**，不往开发机的注册表里写自启项 - 服务端侧栏折叠只用 CSS 收拢（不重建 DOM），关怀模式只放大字号与控件、不动任何几何令牌 客户端 - 崩溃自愈：渲染进程挂掉 / 超 10 秒无响应先静默重建主窗口（10 分钟最多 3 次）， 未捕获异常只在「没在上课、没人看着」时才重启进程；冒烟模式绝不重启（会杀掉验证实例） - 上线补弹离线期间收到的消息只做一次：起点只在「可达 → 不可达」的边界写，恢复时取最近 5 条按时间升序推 发布内容批量 - POST /notifications/bulk、POST /homeworks/bulk：**单班失败不影响整批**，逐班返回结果 - 作业的科目名跨班**按名匹配**已有课程，找不到就整班记失败，绝不自动建课 （自动建课会把创建者写成任课老师，等于越权改任教关系） - 通知与作业同口径按「所属日期」归档，新增 /notifications/days 与 /notifications/creators BREAKING CHANGE: 能不能做某件事不再看角色名，而是看权限键（GET /api/permissions/me）。 未分组的账号按角色默认模板生效，行为与 1.2.0 一致；分组之后生效集合只由组的并集决定。 服务端首次启动会自动应用 1 个数据库迁移（权限组 3 表 / AppSetting / 客户端设备·命令·安装包 / AiAudit / Notification.assignDate / User.careMode，历史通知按本地日期回填），升级前请先备份。
ClassHelper
ClassHelper是给中小学班级用的一套信息管理系统。
老师发一条通知，教室那台机器上的灵动岛和 ClassIsland 会同时弹出来；
学生打开客户端就能看到当天的课表和作业。
🚀 软件下载 | 📚 使用文档 | 🧭 完整参考 | 💬 反馈问题
它由什么组成
一份代码，四个交付物：
| 装在哪 | 是什么 | 谁在用 |
|---|---|---|
| 教师的电脑 / 学校服务器 | 服务端（Express + Prisma + Socket.IO），同时托管 Web 管理端 | 其它三端 |
| 浏览器（手机也行） | Web 管理端（Vue 3 + Element Plus，PWA 可安装） | 老师、班主任、管理员 |
| 教室那台机器 / 学生电脑 | 桌面客户端（Electron + Vue 3），含「灵动岛」浮窗、托盘、离线缓存 | 教室大屏、学生 |
| 教室机器上的 ClassIsland | 联动插件（.NET 8 / C#），上报课表与上课状态、把老师的提醒弹到大屏上 | 教室机器 |
老师在 Web 端发布内容 → 服务端落库并按班级房间广播 → 客户端与灵动岛实时更新； 落到 ClassIsland 上的那部分走设备令牌的独立通道，教室网络不好也不影响。
功能
Web 管理端（老师 / 管理员）
- 仪表盘：本班人数、课程、课表、作业、通知、成绩一屏概览
- 班级管理：建班自动生成班级码与班级密码，随时更换班主任、按科目配置各科任课老师
- 学生 / 教师管理：单个录入或导入名单（xlsx / xls / csv / tsv）
- 课表管理：按周排课、单双周，可直接从 ClassIsland 档案导入课表与节次时间
- 作业发布：按「所属日期」归类，支持附件与未交名单
- 通知发布：三档优先级；在上课时段发紧急通知会被拦下来并要求二次确认
- 叫人：点名某位同学到办公室，分「普通」与「紧急」两级
- 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计
- ClassIsland 联动：签发设备令牌、下发提醒、把课表镜像回教室大屏
- 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换
- 手机小屏适配，可「添加到主屏幕」当应用用
教室里的桌面客户端
- 班级码登录 —— 学生没有个人账号，一台教室机器代表一个班
- 课表：「今天」时间轴（大时钟 + 正在上 / 下一节 + 距下课倒计时）与周视图
- 作业看板：按科目分卡、可全屏铺满、字号可调，也能切回列表
- 通知中心：未读红点、优先级标签、点击自动标为已读
- 成绩总览：全班成绩表格 + 柱状图 + 等级分布
- 教室机器可直接录入作业、勾选未交名单
- 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
- 浅色 / 深色主题，跟随系统
灵动岛（桌面通知浮窗）
- 通知、新作业、叫人都会上岛：先是胶囊，点开是详情卡
- 多条消息展开为竖排列表，按重要程度排序，放不下时提示去应用内看
- 上课时段不打扰：普通通知暂存到下课再弹；紧急通知与叫人立刻弹
- 尺寸、圆角、字号、主题色、停靠位置（顶部 / 底部 × 左 / 中 / 右）都可以调
- 纯黑 / 毛玻璃 / 主题色渐变三种底
- 触摸屏（希沃白板这类一体机）也能点开
ClassIsland 联动
- 教室机器上报课表与上课状态，Web 端能看到「现在在上什么」
- 老师发的提醒在教室大屏上全屏弹出，支持语音朗读，播完回执不重复弹
- 可以把 ClassHelper排好的课表镜像回 ClassIsland，不影响老师原有的课表
- 提醒弹在客户端还是 ClassIsland，由教室那台机器自己选
部署与运维
- Windows 一键安装：内置 Node 运行时，双击安装、开机自启、自动建库建号
- Linux 一键安装 +
classhelper运维命令（systemd 托管，升级 / 回滚 / 备份） - Docker Compose（MySQL 版与 SQLite 版各一份）
- SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照
软件截图
下面这些图都是脚本把程序真的跑起来截的（
node website/tools/capture-shots.mjs与客户端冒烟），不是示意图。
Web 管理端
展开其余页面……
| 页面 | 截图 |
|---|---|
| 仪表盘 | |
| 班级管理 |  |
| 学生管理 |  |
| 教师管理 |  |
| 课表管理 | |
| 作业发布 |  |
| 通知发布 |  |
| 成绩录入 |  |
| ClassIsland 联动 |  |
| 数据库管理 |  |
教室里的客户端
展开其余页面……
| 页面 | 截图 |
|---|---|
| 作业看板 |  |
| 通知 |  |
| 成绩 |  |
| 设置 · 灵动岛 |  |
| 设置 · 外观（深色主题） |  |
灵动岛
| 形态 | 截图 | 说明 |
|---|---|---|
| 新消息胶囊 |  |
非上课时段直接出现，点一下展开 |
| 点开后的详情 |  |
标题、内容、时间 + 打开应用 / 标为已读 / 知道了 |
| 多条消息列表 |  |
按重要程度排序，默认显示三条 |
| 上课期间的紧急通知 |  |
卡片内部红色呼吸光晕，无需点击 |
| 下课后补弹 |  |
上课期间暂存的通知，下课后自动弹出来 |
| 老师叫人 |  |
「请 XXX 同学找 XXX 老师」 |
| 新作业 |  |
教室机器自己录的那条不会弹给自己 |
手机上
展开……
| 场景 | 截图 |
|---|---|
| 仪表盘 |  |
| 通知发布 |  |
开始使用
| 装在哪 | 装什么 | 从 Releases 里拿 |
|---|---|---|
| 教师的电脑 / 学校服务器 | 服务端（内含 Web 管理端与 Node 运行时） | ClassHelper-<版本>-x64-server-setup.exe |
| 教室机器 / 学生电脑 | 学生客户端 | ClassHelper-<版本>-x64-client-setup.exe，或 -client-portable.exe 免安装 |
| 教室机器的 ClassIsland | 联动插件 | ClassHelper.ClassIslandPlugin.cipx |
也可以在官网的下载页上挑： 选一个版本，四个包排成四张卡，文件名、体积与 SHA256 清单都在那儿 —— 那一页的清单是当场读 GitHub Releases 的，显示什么就能下什么。
服务端装上就算跑起来了：双击安装程序，建库、建号、开机自启都由它自己办，
装完在浏览器打开 http://<服务器地址>:4000 就能登录。教师的电脑、学校的服务器、
一台常年开机的机器都可以装。
Linux 服务器有更省事的路子，一行命令装成 systemd 服务，并带上 classhelper 运维命令：
curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
先体检、不改动系统的话，在末尾加上 --check。也可以走 Docker Compose，
完整步骤见部署指南与 Linux 运维手册。
获取帮助
- 使用文档：docs/ —— 分四块：第一次装、已经在用了、负责运维、要改代码
- 完整参考：docs/reference.md —— 功能口径、REST API、权限矩阵、验收证据
- 遇到问题 / 想提需求：提交 Issue
开发
| 层 | 选型 |
|---|---|
| 后端 | Node.js ≥ 20.19 + Express 5 + Prisma 7（SQLite / MySQL）+ Socket.IO |
| Web 管理端 | Vue 3 + Vite + Element Plus + Pinia |
| 桌面客户端 | Electron 44 + Vue 3 + IndexedDB 离线缓存（含独立的灵动岛渲染进程） |
| ClassIsland 插件 | .NET 8 / C# + Avalonia（ClassIsland 插件 API 2.0） |
| 共享契约 | packages/shared：类型、常量、权限矩阵、动效令牌 |
pnpm install
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
pnpm db:generate
pnpm --filter @classhelper/server db:deploy # 根 scripts 里没有 db:deploy
pnpm build:shared # 三端与 seed 的前置产物
pnpm db:seed
pnpm dev # 后端 4000 + Web 端 5173
pnpm db:seed 会写一套演示数据（1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩）：
| 角色 | 账号 | 密码 |
|---|---|---|
| 管理员 | admin |
admin123 |
| 教师 | teacher1 |
teacher123 |
| ClassHelper 班级端（班级） | 班级码 G101 |
123456 |
- AGENTS.md —— 工程约定与本机踩坑，改代码前先读它
- docs/reference.md —— 完整参考（功能行为、接口、验收记录）
- docs/dev/architecture.md —— 架构总览
致谢
灵动岛的视觉与架构参考 WinIsland（Windows 上的动态岛）； 动效语言取自 beUI；产品官网的版式参考 ClassIsland 官网。 三端的深色主题、图标与动效令牌都是照这些参考自己实现的，没有引入它们的运行时依赖。
如果这个项目对你有帮助，欢迎点亮 Star ⭐