Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
83 Commits 1 Branch 15 Tags
227117ccb3926aa4ccd720fddb9821bd910524a9
Commit Graph
8 Commits
Author SHA1 Message Date
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
LoveChengke 817af02357 feat(permissions,clients,ai,system,server,web,client,shared)!: 权限组 + 客户端设备远控与自动更新 + 大模型助手 + 系统诊断（1.3.0） 
功能级准入改为「权限键」，`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，历史通知按本地日期回填），升级前请先备份。
 2026-10-11 11:49:32 +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 ce9bed73f4 feat(shared,web-admin,desktop-client,build): beUI 动效层与两端深色主题，全项目图标改用设计导出的新图标 
动效层：把 beUI 的动效语言移植到两端，令牌放在 packages/shared/src/motion.ts（纯常量，后端也引用得到）。弹簧用数值积分生成 CSS linear()，纯 CSS 即可驱动，不必每组件一个 rAF 循环；两端各一份 composables/motion.ts 负责 DOM 部分，在 app.mount() 之前注入 :root。含 reduced-motion 全局降级与 hover 能力探测；灵动岛只移植单调曲线。

深色主题：Web 管理端补齐，机制与桌面客户端一致；语义色令牌只覆盖颜色，不动圆角与动效令牌。默认跟随系统，用户手动点过之后以用户为准。

图标：build/classhelper.{png,ico} 成为全项目唯一图形源，pnpm icons 从它派生各端图标与界面内品牌标。版本号统一到 1.1.2。
 2026-10-06 15:32:01 +08:00
LoveChengke 79d73c5889 chore(release): 版本号统一到 1.1.1（服务端 CSP 白屏修复） 
对齐 1.1.0 的做法把版本号统一：5 份 package.json、deploy/package.runtime.json、
两份 .env.example 的 APP_VERSION、两个 docker-compose 的镜像标签、ClassIsland 插件的
manifest.yml 与 BridgeService.PluginVersion（verify:classisland-plugin 有 manifest↔代码
一致性断言，已跑 68/68）、README 首页版本、以及文档与脚本里的安装包名示例，共 28 处。

刻意不动：docs/linux-deploy.md 排障条目里"1.1.0 的服务端在 HTTP 直连访问时会下发 CSP
upgrade-insecure-requests…"——那句说的是**出问题的那个版本**，改成 1.1.1 反而是错的。
 2026-10-05 20:05:39 +08:00
LoveChengke 9a38f86cd3 feat(server,web,desktop,shared,deploy,docs): Linux 一键安装与 classhelper 运维命令、更新检查、图表去 echarts，版本统一 1.1.0 
Linux 交付链（新增）
- deploy/install.sh：一键安装器（CLASSHELPER 大字 TUI、native/docker 双形态、向导选安装目录/
  端口/数据库/初始管理员密码）；识别 apt/yum/dnf 只补缺的依赖、建独立系统用户、下载内置 Node
  运行时（glibc < 2.28 的 CentOS 7 自动改用 unofficial-builds 的 glibc-217 构建）、幂等覆盖安装
  （保留 config.env 与 data/，不重置密钥）、全程写 /var/log/classhelper/install.log；
  `--check` 只体检（不需要 root）、`--yes` 无人值守、`--package` 支持内网离线分发。
- deploy/classhelper：运维命令 —— status / doctor / password / backup(list,restore,schedule) /
  upgrade / rollback / start|stop|restart|reload / logs / config / port / key rotate / uninstall /
  completion / help。特权操作一律校验 EUID，关键动作写 /var/log/classhelper/audit.log。
- deploy/tools/admin-cli.mjs：离线账号工具（改密、列账号、VACUUM INTO 一致性快照、哈希回滚），
  直连数据库 —— 服务停机也能救急，不需要先有一个能登录的账号。
- deploy/{classhelper.service,profile.d,logrotate.d,systemd}/ 模板 + Dockerfile.linux-package。
- scripts/dist-server.mjs 增加 --platform linux（根脚本 `pnpm dist:server:linux`），产物
  classhelper-server-linux-x64-<版本>.tar.gz + 同名 .sha256；新增 GitHub Actions workflow 在
  ubuntu runner 上构建并挂 Release（@libsql/linux-* 这类平台相关依赖只能在 Linux 上装）。
- docs/linux-deploy.md：安装 / 运维命令 / 升级回滚 / 备份恢复 / 排障 / 安全清单 /
  Ubuntu 22.04 与 Rocky 9 的验收清单。deploy/install-linux.sh 改为转发壳，不留两份实现。

三处必须知道的取舍（已写进 AGENTS.md §5 第 59 条）
- 配置真身在 /etc/classhelper/config.env，安装目录里的 .env 是指向它的软链：Web 端
  「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是同一份配置 ——
  两处不是同一个文件时，切换会「看起来成功、重启后又连回旧库」。classhelper doctor 有专门断言。
- 升级/回滚替换程序文件用「改名 + 就位」而不是 rm+cp：升级时正在运行的就是 bin/classhelper
  自己，直接删掉同名文件会让 bash 读到半个脚本。
- 交叉构建（在非 Linux 机器上打 Linux 包）会在包内写 .cross-built 标记、doctor 据此提示：
  已核对 @libsql/linux-x64-gnu 与 -musl 就位且无 win32 残留，但 prisma CLI 的原生 schema engine
  是宿主平台的，Web 端「数据库一键切换」那一步存疑；正式产物一律走 CI。

更新检查（此前只在工作区，本次一并提交）
- 服务端 modules/update：由服务端转发 GitHub Releases（Web 端 CSP 不允许直连），离线/限流/超时
  一律收敛成 ok:false + 一句人话，失败结果同样进缓存；?force=1 只对管理员生效（避免刷爆匿名限流）。
- 版本比较放 @classhelper/shared（compareVersions / isNewerVersion），三端共用；服务端版本号
  改由 lib/version.ts 读 package.json，不再在 app.ts 里写字面量。
- Web 端顶栏「检查更新」弹窗、客户端「关于」页的检查更新与诊断信息。

Web 端 / 客户端
- 成绩图表改用自包含的轻量组件（ScoreBarChart / ScoreLineChart），不再全量引入 echarts
  （原先 echarts 占桌面端渲染产物 1.12MB、Web 端 1.13MB）；柱状图是纯 HTML/CSS，折线图是
  viewBox SVG，均无 resize 监听。
- Element Plus 图标改为按需注册（两端各一份 icons.ts），新增 scripts/check-icons.mjs 静态门禁
  并挂进两端 build —— 漏注册的后果是界面静默渲染空白，只在控制台一条 warning。

版本号统一 1.1.0
- 5 份 package.json、deploy/package.runtime.json、.env.example 的 APP_VERSION、
  docker-compose 与两个 Dockerfile 的镜像标签、Linux 安装包名示例、README 首页版本；
- ClassIsland 插件 manifest.yml 与 BridgeService.PluginVersion 同步（verify:classisland-plugin
  有 manifest ↔ code 的一致性断言）；
- 刻意保持不变的是**历史性表述与举例**：docs/mysql.md 的「自 v1.0.0 起内置 MySQL 适配器」、
  shared/utils.ts 讲版本比较用的 1.0.0 / 1.0.0-fix、README 验收表里的实测记录。
 2026-10-05 16:39:38 +08:00
LoveChengke 572295c297 feat(server,web,desktop,shared,deploy,plugin): 数据库管理模块 + 客户端深色模式/设置拆子路由/首启引导，版本统一 1.0.0 
- 服务端新增 database 模块（/api/database/*，仅 ADMIN）：全库 JSON 快照（备份 / 恢复 / 导入导出 / 定时备份
  共用同一格式，14 张表按拓扑序导出、恢复时关外键检查）、连接测试与目标库校验、一键 SQLite ⇄ MySQL 切换
  （备份 → 导出 → 测试连接 → 校验空库 → 改 schema → 子进程 generate / tsc / db push → 写数据，全部成功才改写
  .env，中途失败回滚 schema）；XML 快照与 SQLite 数据文件均可下载；打包形态随包带上 prisma CLI 与 typescript
  （prisma-client 生成物是 .ts，需再编进 dist/generated，安装包因之变大）
- Web 管理端新增「数据库管理」页（仅管理员），并加首次登录新手引导（el-tour，可跳过、可随时重看，版本号写
  localStorage，改版后老用户会再收到一次）
- 客户端设置改版：侧边栏改为分组折叠菜单，设置拆成 6 个子路由
  （/settings/{general,appearance,island,reminder,account,about}），新增深色模式（主题持久化到主进程配置，
  主窗口底色跟主题走，避免"先白后黑"闪一下），新增「关于」页（应用信息 / 诊断信息）
- 客户端新增首启六步引导（OnboardingWelcome，状态存主进程配置 onboardingDone）
- 客户端主窗口初始尺寸与 ClassIsland 对齐（1242x582 / minHeight 540 / 居中）
- 版本号统一提升到 1.0.0：5 个 package.json、部署配置与镜像标签（.env.example / docker-compose / Dockerfile）、
  服务端 /health 与首页、插件 manifest.yml 与 BridgeService.PluginVersion、文档里的安装包名
- 文档与验收同步：AGENTS.md 补第 37~51 条约定（深色主题实现边界、设置子路由、数据库管理三件事、侧栏与窗口
  尺寸、引导在自动化里的判据等），README 补「数据库管理 / 新手引导 / 设置改版」三节；verify:e2e 增补 13 条
  数据库管理用例，客户端冒烟与 Web UI 冒烟跟进子路由、深色主题、侧栏与引导

验证：pnpm lint 0 error；pnpm typecheck 全过；verify:e2e 186/186；verify:classisland-plugin 68/68；
build:desktop 通过（含产物凭据门禁）；verify:desktop 99/102（3 项为上课时段下的"真实通知链路"用例，
客户端按产品规则暂存普通通知所致，见下）；插件 dotnet 编译 0 错误。

注：verify:desktop 的「真实通知链路 / 标记已读」三项要求当前不在上课时段——本次运行时种子课表恰有
「周五 10:55-11:40 生物」正在进行，客户端正确地暂存了普通通知（AGENTS.md 第 18 条），属时间相关用例，
与本次改动无关。
 2026-10-02 11:18:47 +08:00
LoveChengke d0830f6830 feat(integrations,classisland,server,web,desktop): ClassIsland 联动插件——上报课表与上课状态、下发提醒并回执、教室端推送通道 
教室机器上的 ClassIsland 现在可以直接和班级小助手互通：插件走 /api/integrations/classisland/*，用设备令牌（X-ClassIsland-Token，库里只存 sha256）独立鉴权，不占用 JWT 通道。

- 服务端：新增 integrations 模块（上报 / 待弹出 / 回执 / 课表镜像 / 回写），两个迁移（设备令牌表、Class.notificationChannel）；通知、叫人、联动页下发统一复用 pushToClassIsland，避免"某个页面发的通知不联动"
- 插件：packages/classisland-plugin（.NET 8，独立于 pnpm workspace）——BridgeService 上报与提醒轮询、ScheduleMapper/ClassPlanWriter 课表镜像、Avalonia 设置页、ClassHelperNotificationProvider 在 ClassIsland 上弹出提醒；本地/内网地址强制直连，躲开系统代理返回的假 404
- 客户端：设置页可选提醒通道（both / client / classisland），并订阅相应实时事件
- Web 端：新增「ClassIsland 联动」页（设备管理与提醒下发）
- 校验与打包：verify:classisland（需后端）、verify:classisland-plugin（静态契约 54 项）、build/dist:classisland-plugin 产出 .cipx
- 文档：README 与 AGENTS.md 同步新增联动说明，docs/screenshots/classisland 留三张真机截图

门禁：pnpm lint 0 error、pnpm typecheck 四包通过、verify:classisland-plugin 54/54 通过。运行期仍需在装了 ClassIsland 的机器上实测（步骤见 AGENTS.md §8）。
 2026-09-27 14:59:12 +08:00