Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
966c8f9b5dd29672067676bd5ca59b9ef8981a16
ClassHelper/README.md
T
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

14 KiB
Raw Blame History

ClassHelper

ClassHelper · Web 管理端仪表盘

正式版 下载量 Issues
平台 Node.js Vue Electron 仓库大小

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 管理端

Web 管理端 · 课表管理
展开其余页面……
页面 截图
仪表盘 仪表盘
班级管理 班级管理
学生管理 学生管理
教师管理 教师管理
课表管理 课表管理
作业发布 作业发布
通知发布 通知发布
成绩录入 成绩录入
ClassIsland 联动 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

致谢

灵动岛的视觉与架构参考 WinIsland（Windows 上的动态岛）； 动效语言取自 beUI；产品官网的版式参考 ClassIsland 官网。 三端的深色主题、图标与动效令牌都是照这些参考自己实现的，没有引入它们的运行时依赖。

如果这个项目对你有帮助，欢迎点亮 Star ⭐

Reference in new issue View Git Blame Copy Permalink