1 Fork 0

Files

T

LoveChengke 227117ccb3 fix(integrations,grades,clients,web,client,plugin): 课表同步改为按需（修「课表被反复删改」）+ 客户端页合并 + 成绩排名（1.3.1）

线上问题的根因
- ClassIsland 插件默认每 15 秒上报一次，每次都带全量课表，上报完还顺手把课表镜像回教室
  （本机 `UploadSchedule` / `MirrorSchedule` 两个开关默认都是开）。于是教室的课表每 15 秒被重写、
  服务端也每 15 秒 merge + 清理一次幽灵行 —— 老师看到的就是"课表被反复删改"。
- 现在两个方向都只由 Web 端的一次性待办触发，插件侧那两个开关整体删除；
  定时上报只报**运行状态**（当前上什么课），不带课表。

课表同步（#3）
- 新增 `IntegrationDevice.requestMirrorSchedule` + `POST /integrations/devices/:id/mirror-schedule`
  （「下发课表」），与既有的 `request-schedule`（「获取课表」）对称；拉取成功即清标记
- 插件 `ClassPlanWriter.Apply(..., force: true)`：停用同一天同一单双周相位下冲突的旧课表
  —— **只停用不删除**，内容原样留在档案里，老师随时能重新启用
- 插件设置页删掉「自动上报课表」「镜像回 ClassIsland」两个开关，改为一句说明

「客户端」页（#4）
- 把「ClassIsland 联动」与「客户端设备」合成一页 `ClientHubView.vue`：一个班一张卡片，
  两条链路状态放一起，勾选可批量下发课表 / 更新，点卡片进详情做逐台操作
- 「下发提醒」也搬了过来；入口权限用 `classisland:notify`（默认 ADMIN + TEACHER），
  页内按钮再各自按 device:manage / remote:control / client:update-push 显示或禁用
- 两个旧页面 `meta.hidden: true` **保留路由**（安装包缓存管理、联动步骤说明仍在），
  从详情抽屉里给链接 —— 不删功能

成绩（#5/#6/#7）
- 新增 `Exam`（班级 + 考试名 + `countInTotal`）与迁移；`GET/PUT /api/grades/exams`、
  `GET /api/grades/ranking`（两条都**不挂权限键**，班级端的有效权限是空集，边界在 service 里）
- 排名口径写在服务端：**同一学生同一科目只取最高分**（补录 / 重考会多行，不去重等于"总分多一科"）、
  并列同名次（1、2、2、4）
- 「成绩录入」页加「考试口径」开关（按班级 + 考试名记住）；客户端「成绩」页新增总分榜 + 单科榜
- `updateStudentGradeQuery` 改成只有教师 / 管理员能改 —— 原先班级端自己也能改
- 客户端的成绩查询开关改为只读（只显示服务端下发的状态）

其他（#2/#5/#8/#9）
- 全校学期开始日期改成 `AppSetting` 的 `term.startDate`，管理员在「学期周次」页直接改、立刻重算周次
  （原先这一级只能来自 `.env`）
- 大模型助手发紧急通知补上「上课时段 3 秒全屏警告」：判据抽成 `composables/useClassInSession.ts`，
  与手动发布页共用
- 客户端去掉「关怀模式」「自动更新」两个开关（教室机器是统一投放的终端）
- 修掉「选中设置二级菜单后收起分组、高亮块仍留在原地」：底片只在路由 / 滚动 / 缩放时重测，
   而收起分组动不了 `.aside` 的盒子 —— 补上"子项被 overflow:hidden 裁掉"的判据 + 观察分组 `<ul>` 高度
- `src/types/express.d.ts` 里 `req.device` 改成引用 `DeviceContext`：原先手抄了一份结构，
  往接口加字段时两边就漂了，而报错会落在 `getDevice()` 的 `return device;` 上，看不出真正原因

验收：`lint` / `typecheck` / `check:icons` / `docs:check` 全绿；
后端端到端 **247/247**、联动链路 **44/44**、插件静态契约 **76/76**、
Web 真实点击 **34/34**（含新增的「客户端」页用例）、客户端冒烟 **90/90**。

2026-10-11 16:21:38 +08:00

15 KiB

Raw Blame History

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 一键切换
权限组：39 个权限键，建组分配账号 —— 没分组的按角色默认生效，分组后只按组的并集算
客户端（合并页）：一个班一张卡片，大屏与灵动岛两条链路一起看；勾选可批量下发课表 / 更新，点进去做逐台操作
课表同步按需：点「下发课表」把课表写进教室并停用冲突的旧课表，点「获取课表」把教室的课表取回来 —— 没有"一直同步"
客户端设备：每台教室机器的版本、在线状态与最后心跳；一键推送更新，可下发关机 / 重启 / 注销 / 锁屏
大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库
通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级
系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态）
关怀模式：字号与控件整体放大
手机小屏适配，可「添加到主屏幕」当应用用

教室里的桌面客户端

班级码登录 —— 学生没有个人账号，一台教室机器代表一个班
课表：「今天」时间轴（大时钟 + 正在上 / 下一节 + 距下课倒计时）与周视图
作业看板：按科目分卡、可全屏铺满、字号可调，也能切回列表
通知中心：未读红点、优先级标签、点击自动标为已读
成绩总览：全班成绩表格 + 柱状图 + 等级分布；按考试看单科排名，老师开启后还有总分排名
教室机器可直接录入作业、勾选未交名单
离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口
浅色 / 深色主题，跟随系统

灵动岛（桌面通知浮窗）

通知、新作业、叫人都会上岛：先是胶囊，点开是详情卡
多条消息展开为竖排列表，按重要程度排序，放不下时提示去应用内看
上课时段不打扰：普通通知暂存到下课再弹；紧急通知与叫人立刻弹
尺寸、圆角、字号、主题色、停靠位置（顶部 / 底部 × 左 / 中 / 右）都可以调
纯黑 / 毛玻璃 / 主题色渐变三种底
触摸屏（希沃白板这类一体机）也能点开

ClassIsland 联动

教室机器上报课表与上课状态，Web 端能看到「现在在上什么」
老师发的提醒在教室大屏上全屏弹出，支持语音朗读，播完回执不重复弹
可以把 ClassHelper排好的课表镜像回 ClassIsland，不影响老师原有的课表
提醒弹在客户端还是 ClassIsland，由教室那台机器自己选

部署与运维

Windows 一键安装：内置 Node 运行时，双击安装、开机自启、自动建库建号
Linux 一键安装 + classhelper 运维命令（systemd 托管，升级 / 回滚 / 备份）
Docker Compose（MySQL 版与 SQLite 版各一份）
SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照
客户端批量更新不依赖外网：安装包由服务端下载缓存，教室机从服务端取，校验 sha256 后空闲时自动装

软件截图

下面这些图都是脚本把程序真的跑起来截的（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 ⭐

15 KiB Raw Blame History Unescape Escape