Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs,scripts,build): 用 docfx 搭文档站并发布到 GitHub Pages，版本号收口成脚本迭代

Browse Source 
文档站（`docs/` 就是 docfx 项目，发布在 https://lovechengke.github.io/ClassHelper/）：

- 四章 + 常见问题 + 完整参考，共 44 页：快速上手（8 页）/ 应用帮助（10 页）/
  管理运维（6 页）/ 开发文档（11 页）。信息架构照 ClassIsland 文档站来：
  顶栏分章、左侧章节导航、右侧本页目录、上一页 / 下一页、站内搜索、深色主题跟随系统；
- 自定义模板覆盖（`templates/classhelper/`）：把 docfx modern 模板那套英文 UI 文案
  （In this article / Improve this doc / Next…）换成中文，补 GitHub 入口与版本徽标，
  并加一层只调排版与配色的 `public/main.css`（不动 DOM 结构）；
- 站点顶栏的版本徽标取自根 `package.json`（`docs/build.mjs` 用 `--metadata` 注入），
  不在文档里写第二份 —— 否则一定漂；
- 404 页单独生成：GitHub Pages 的项目页挂在 `/<仓库名>/` 子路径下，而浏览器是按**被请求的路径**
  解析页面里的相对链接的，所以 `<base>` 必须钉到站点根，由 `build.mjs`（本地 `./`）与
  workflow（CI 传 `/<仓库名>/`）分别注入；
- 构建前清空 `_site`：docfx 只覆盖不清理，删掉或改名的页面会以旧文件留在目录里，
  而 Pages 上传的是整个目录。

版本迭代（**每一次 releases，不是每一次提交**）：

- 新增 `scripts/version.mjs`。这个仓库里同一个版本号散在 **10 个文件**里（5 份 `package.json`、
  `deploy/package.runtime.json`、两个 compose 的镜像 tag、插件 `manifest.yml`、以及插件 C# 里的
  `PluginVersion` 常量），手工改必然漏一处，而漏掉的那处**不会报错**，只在某个不常走的分支上
  表现为"版本号对不上"。现在收口成两条命令：`pnpm version:check`（逐处比对，不一致 exit 1）
  与 `pnpm version:bump patch|minor|major`（一次改写全部 10 处，任何一处匹配不到或匹配到多处
  就直接失败退出，不做尽力而为的部分改写）；
- `AGENTS.md` 新增 §4.4「版本迭代（每一次 releases，不是每一次提交）」：写清版本号落在哪 10 处、
  完整发布命令序列（体检 → 验收 → `dist:all` → 哈希清单 → 推 master → `gh release create` →
  Linux 包由 CI 合并哈希行），以及"已发布的版本号不要复用"的理由。

其它：

- `.github/workflows/docs.yml`：推 master（`docs/**` / `package.json` / workflow 自身有变）即构建并
  部署到 Pages；构建带 `--check`，把 docfx 的警告当错误 —— 最常见的警告是"某个 `.md` 没被任何
  `toc.yml` 引用"，那种页面有内容但没有侧边栏，属于必须修掉的疏漏；
- docs 目录重组后的引用同步：`production` / `mysql` / `linux-deploy` / `winisland-design-tokens`
  移到新位置后，AGENTS.md、`deploy/`、`scripts/`、客户端源码注释里的路径引用一并更新；
- 文档站只发布 `docs/` 这一棵树，页面里指向树外的相对链接（`../AGENTS.md` 等）改成 GitHub 绝对 URL，
  否则上线全是 404；
- 图标派生清单补上文档站模板里的 `logo.png` 与 `favicon.png`（`pnpm icons` 一并生成，
  仍然只有一个图形源 `build/classhelper.{png,ico}`）；
- `docs/_site` 进 `.gitignore` / `.prettierignore` 与 ESLint ignores；
- 根脚本补 `version:check` / `version:bump` / `docs:build` / `docs:serve` / `docs:check`。
This commit is contained in:
LoveChengke committed 2026-10-06 16:27:44 +08:00
1 parent 5b002a4f0b
commit 19c2aa07b2
61 files changed
+4761 -12
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/dev/api.md
+107
View File
@@ -0,0 +1,107 @@
---
title: REST API
description: 班级小助手后端全部接口一览：方法、路径、权限与说明。
---
# REST API
## 通用约定
- 所有接口前缀 `/api`（设备接口也一样）；
- 统一响应体：`{ "success": true, "data": {}, "message": "" }`，错误为 `success: false` + `code`；
- 除登录、健康检查与设备接口外，都需要 `Authorization: Bearer <token>`；
- **ClassIsland 设备接口用 `X-ClassIsland-Token`**，不走 JWT（见[ClassIsland 插件](classisland-plugin.md)）；
- 请求体校验走 zod（`middleware/validate.ts`），错误由 `middleware/error.ts` 统一映射。
## 接口一览
| 方法 | 路径 | 权限 | 说明 |
| --------------------------- | ------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------ |
| POST | `/auth/login` | 公开 | 登录（教师 / 管理员）；`role=STUDENT` 返回 403（学生只有名单，改用班级登录） |
| POST | `/auth/class-login` | 公开 | **班级账号登录**：班级码 + 班级密码 → 班级会话 |
| GET | `/auth/me` | 登录 | 当前用户（学生附带班级 / 年级） |
| PATCH | `/auth/password` | 登录 | 修改自己的密码（班级会话 → 班级密码） |
| POST | `/auth/logout` | 登录 | 退出（无状态，客户端丢弃 token） |
| GET | `/classes` | 登录 | 班级列表（按权限收敛） |
| GET | `/classes/:id` | 班级可见 | 班级详情（学生 / 课程 / 协作教师） |
| POST | `/classes` | 管理员 | 创建班级（自动生成班级码，可指定班主任） |
| PATCH / DELETE | `/classes/:id` | 管理员 / 教师 | 编辑 / 删除班级 |
| PATCH | `/classes/:id/class-account` | 管理员 | 设置 / 重置班级账号（班级码 + 班级密码） |
| PATCH | `/classes/:id/head-teacher` | 管理员 | 设置 / 更换班主任 |
| GET | `/classes/:id/classisland-status` | 班级可见 | 本班 ClassIsland 联动状态（教室客户端设置页用） |
| GET | `/classes/:id/notification-channel` | 班级可见 | 读取「通知显示到哪个端」 |
| PATCH | `/classes/:id/notification-channel` | 班级账号 / 教师 / 管理员 | 设置「通知显示到哪个端」 |
| GET / POST | `/classes/:id/students` | 班级可见 / ADMIN·TEACHER | 学生名单 / 添加学生 |
| DELETE | `/classes/:id/students/:userId` | ADMIN·TEACHER | 移出学生 |
| POST / DELETE | `/classes/:id/teachers[/:teacherId]` | ADMIN·TEACHER | 分配 / 取消协作教师 |
| GET / POST / PATCH / DELETE | `/courses` | 登录（写：班主任 / 管理员） | 课程管理 |
| GET | `/schedules?classId=&week=&dayOfWeek=` | 登录 | 课表列表（`week` 过滤周次范围） |
| GET | `/schedules/grid?classId=&week=` | 登录 | 周视图（7 列结构，供客户端直接渲染） |
| GET | `/schedules/current?classId=&at=` | 登录 | 当前上课状态（`inClass` / `current` / `next`；`at` 为诊断用时间覆盖） |
| POST / PATCH / DELETE | `/schedules[/:id]` | 班主任 / 管理员 | 课表增删改（广播 `schedule:updated`） |
| GET | `/homeworks?classId=&courseId=&date=&pendingOnly=&keyword=` | 登录 | 作业列表（支持按所属日期；学生带完成状态，教师带完成人数） |
| GET | `/homeworks/days?classId=&from=&to=` | 登录 | 哪些天有作业（日期高亮） |
| GET | `/homeworks/:id` | 班级可见 | 作业详情 |
| POST | `/homeworks` | 教师 / 管理员 / **班级账号** | 发布作业（附 `assignDate`；班级账号用于教室机器录入，归属班主任） |
| PATCH / DELETE | `/homeworks/:id` | 教师 / 管理员 | 修改 / 删除（广播 `homework:new` / `homework:updated`） |
| PATCH | `/homeworks/:id/status` | 登录 | 标记完成 / 取消（广播 `homework:status`） |
| GET / PATCH | `/homeworks/:id/submissions` | 登录 | 未交名单：读名单 / 回写全班完成状态 |
| GET | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 登录 | 通知列表（带已读状态） |
| GET | `/notifications/unread-count` | 登录 | 未读数（红点） |
| POST | `/notifications` | 教师 / 管理员 | 发布通知（广播 `notification:new`）；上课时段发紧急通知需 `confirmDuringClass` |
| POST | `/notifications/:id/read`、`/notifications/read-all` | 登录 | 标记已读（班级设备会写全班） |
| DELETE | `/notifications/:id` | 教师 / 管理员 | 删除通知 |
| POST | `/calls` | 教师 / 管理员 | **叫人**（`urgent` 决定 URGENT / HIGH；广播 `notification:new` 与 `call:new`） |
| GET | `/grades/my` | 登录 | 个人成绩（班级会话 → 全班总览） |
| GET | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员 | 班级成绩 |
| GET | `/grades/stats?classId=&courseId=&examName=` | 教师 / 管理员 | 等级分布 + 各课程平均得分率 |
| POST | `/grades`、`/grades/bulk` | 班主任 / 管理员 | 单条 / 批量录入（广播 `grade:updated`） |
| PATCH / DELETE | `/grades/:id` | 班主任 / 管理员 | 修改 / 删除成绩 |
| GET | `/students?classId=&keyword=` | **管理员** | 学生名单 |
| POST / PATCH / DELETE | `/students[/:id]` | **管理员** | 学生名单增删改（无密码概念；重置密码接口已下线 → 404） |
| GET | `/teachers?keyword=` | **管理员** | 教师列表 |
| POST / PATCH / DELETE | `/teachers[/:id]` | **管理员** | 新建 / 编辑 / 删除教师账号 |
| POST | `/teachers/:id/reset-password` | **管理员** | 修改 / 重置教师密码（`newPassword` 可选，留空 = 默认初始密码） |
| GET | `/dashboard/summary`、`/dashboard/term` | 登录 | 仪表盘汇总 / 学期周次 |
| GET | `/imports/template?kind=&format=` | 管理员 / 班主任 | 导入模板下载（`csv` 走 JSON，`xlsx` 走二进制） |
| POST | `/imports/table/preview` | 管理员 / 班主任 | 上传表格（base64）解析预览：列名 + 前 20 行 + 校验问题 + 建议映射 |
| POST | `/imports/table/commit` | 管理员 / 班主任 | 按字段映射与写入模式导入（成绩 / 学生名单 / 教师名单） |
| POST | `/imports/time-layout/preview` | 管理员 / 本班班主任 | 解析 ClassIsland 时间配置 JSON（只解析不落库） |
| GET / POST / DELETE | `/imports/time-layout[/:id]` | 管理员 / 本班班主任 | 时间配置列表 / 导入（`replace` 覆盖、`merge` 合并）/ 删除 |
| POST | `/imports/class-plan/preview`、`/imports/class-plan` | 管理员 / 本班班主任 | ClassIsland 课程表解析预览 / 导入（支持单双周） |
| GET / POST / PATCH / DELETE | `/integrations/devices[/:id]` | 管理员 / 教师 | ClassIsland 联动设备管理（令牌只存 sha256，令牌前缀用于人眼识别） |
| POST | `/integrations/devices/:id/token` | 管理员 / 教师 | 重置设备令牌（旧令牌立即失效，明文只返回一次） |
| POST | `/integrations/classisland/notify` | 管理员 / 教师 | 下发提醒到该班 ClassIsland 设备（广播 `classisland:notification`） |
| GET | `/database/status` | **管理员** | 数据库状态（连接 / 版本 / 体积 / 14 张表行数 / 备份列表 / 定时配置） |
| POST | `/database/test-connection` | **管理员** | 测试任意目标库连通性（provider 仅 sqlite / mysql） |
| GET / POST | `/database/backups` | **管理员** | 备份列表 / 立即备份（gzip JSON 快照，存 `<数据目录>/backups/`） |
| POST / DELETE | `/database/backups/:name/restore` · `/database/backups/:name` | **管理员** | 从备份恢复（整库覆盖）/ 删除备份 |
| GET | `/database/export`、`/database/sqlite-file` | **管理员** | 下载 JSON 快照 / 下载数据库文件（后者仅 SQLite） |
| POST | `/database/import` | **管理员** | 导入快照（base64，整库覆盖；可在 SQLite / MySQL 之间互迁） |
| GET / PUT | `/database/backup-schedule` | **管理员** | 定时备份配置（enabled / intervalHours / keepCount） |
| POST / GET | `/database/switch`、`/database/switch/jobs/:id` | **管理员** | **一键切换数据库**（异步任务）/ 轮询进度 |
| POST | `/integrations/classisland/report` | **设备令牌** | 插件上报状态 + 课表 + 节次时间 |
| GET | `/integrations/classisland/pending` | **设备令牌** | 插件拉取尚未确认的提醒（离线期间老师发的通知，重连后补齐） |
| POST | `/integrations/classisland/ack` | **设备令牌** | 插件确认提醒已弹出（确认后不再补发） |
| GET | `/integrations/classisland/class-plan` | **设备令牌** | 插件拉取本班课表（开启镜像时）用于写回 ClassIsland |
| GET | `/update/check` | 登录 | 更新检查（服务端代查 GitHub 最新 Release；`?force=1` 绕过缓存仅管理员生效） |
| GET | `/health` | 公开 | 健康检查（含版本号与已挂载模块） |
另有三个探针（不带 `/api` 前缀）：`/healthz`（存活）、`/readyz`（就绪）、以及 `/api/health`（详情）。
## 几条容易踩的接口约定
| 约定 | 说明 |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **`POST /homeworks` 故意不加 `requireRole`** | 权限判在 `homeworks.service.createHomework` 里（staff 或本班班级账号），因为教室机器也要能录作业 |
| **班级账号的 `sub` 是班级 id** | 写 `createdBy` 前要换成该班班主任，否则撞 `User` 外键 |
| **登录限流挂在两个入口上** | `/auth/login` 与 `/auth/class-login` 都挂 `loginRateLimiter()` |
| **角色判定在密码校验之前** | 否则"密码错 / 密码对但账号停用"的差异会把学生账号密码变成可离线验证的预言机 |
| **会渲染成链接的字段要校验 scheme** | `Homework.attachmentUrl` 只允许 `http(s)://` 或站内相对路径 |
| **表格导入 8MB ↔ 请求体 12MB** | 文件以 base64 放进 JSON（约 4/3 倍），超限映射成 413 `IMPORT_TOO_LARGE` |
## 相关
- 实时事件见[实时事件（Socket.IO）](realtime.md)；
- 权限矩阵见[角色与权限](permissions.md)；
- 数据模型见[数据模型](data-model.md)。
docs/dev/architecture.md
+160
View File
@@ -0,0 +1,160 @@
---
title: 架构总览
description: 目录结构、技术栈、模块化设计与几条贯穿全局的工程约定。
---
# 架构总览
## 技术栈
| 层 | 选型 | 版本（`package.json` 实际声明） |
| ------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
| 包管理 | pnpm workspace | 11.8.0 |
| 语言 | TypeScript | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x） |
| 后端 | Node.js + Express | ≥ 20.19 / 5.2 |
| ORM | Prisma + driver adapter | 7.10（+ `@prisma/adapter-libsql`，切 MySQL 用 `-mariadb`） |
| 实时 | Socket.IO | 4.8 |
| 认证 | jsonwebtoken + bcryptjs | 9.0 / 3.0 |
| 校验 | zod | 4.6 |
| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 |
| 客户端 | Electron + Vue + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8 |
| 插件 | .NET 8 / C# + Avalonia（ClassIsland 插件 API 2.0） | net8.0 |
| 打包 | electron-builder（nsis / portable）+ NSIS | 26.15 |
| 文档站 | docfx | 2.81 |
## 目录结构
```
class-helper/
├── package.json # 根脚本（dev / build / db:* / verify:* / dist:* / docs:* / icons）
├── pnpm-workspace.yaml # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
├── tsconfig.base.json # 共享 TS 基础配置（ESM + NodeNext + strict）
├── eslint.config.mjs # ESLint 扁平配置（TS + Vue）
├── .prettierrc.json # 单引号 / 110 列 / LF / 尾逗号
├── build/classhelper.{png,ico} # **图标源**（设计导出、手工放入）；pnpm icons 从它派生其余全部图标
├── scripts/
│ ├── use-database.mjs # SQLite ⇄ MySQL provider 切换助手
│ ├── generate-icons.mjs # 启动 Electron 跑 icons/render.cjs（= pnpm icons）
│ ├── icons/render.cjs # 把 classhelper.png 重采样成各端图标（CommonJS）
│ ├── version.mjs # 版本号单一来源的读写与一致性校验（= pnpm version:*）
│ ├── dist-server.mjs # 服务端 + Web 管理端打包（免安装目录 + NSIS 安装程序）
│ ├── verify-packaged.mjs # 对打包后 / 已安装的客户端 EXE 复跑冒烟
│ ├── lib/ # electron-env / node-runtime / smoke-class
│ ├── nsis/server-installer.nsi# 安装程序脚本模板（版本号由 dist-server 注入）
│ └── ui-smoke/ # Web 管理端 UI 真实点击回归（Electron 驱动）
├── deploy/ # 生产部署：Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf
│ ├── install.sh # Linux 一键安装器（TUI；native/docker 双形态；自带 --check 体检）
│ ├── classhelper # 运维命令本体（软链 /usr/local/bin/classhelper）
│ ├── verify-linux.sh # Linux 安装/改密/备份/升级/回滚验收（自统计 N/N 项）
│ ├── tools/admin-cli.mjs # 离线账号工具（改密、列账号、SQLite 一致性快照）
│ ├── classhelper.service # systemd 单元模板
│ └── package.runtime.json # 运行时依赖清单（安装包 / 容器 / Linux 部署共用）
├── docs/ # **文档站**（docfx 项目，发布到 GitHub Pages）
│ ├── docfx.json # docfx 配置
│ ├── toc.yml # 顶栏导航；各子目录各有一份 toc.yml 作为侧栏
│ ├── index.md # 首页
│ ├── get-started/ app/ management/ dev/ # 四个章节
│ ├── templates/classhelper/ # docfx 模板覆盖（_master.tmpl + public/main.css + 图标）
│ ├── screenshots/ # 回归测试自动留档的截图（island / client / web-mobile / classisland）
│ ├── build.mjs # 构建入口（注入版本号与 404 的 base）
│ ├── serve.mjs # 本地预览（:5181）
│ └── _site/ # 构建产物（gitignore）
├── website/ # 产品官网（纯静态，无构建；node website/serve.mjs 本地预览）
│ └── assets/{styles.css,motion.js,main.js,icon.png,shots/}
└── packages/
├── shared/ # 三端共享：类型契约、常量、权限矩阵、动效令牌、工具函数
│ └── src/{types,constants,permissions,motion,island-layout,utils,index}.ts
├── server/ # 后端服务
│ ├── prisma/schema.prisma # 数据模型（14 个 model，只有一份，切库改 provider）
│ ├── prisma/migrations/ # 迁移历史（10 个）
│ ├── prisma/seed.ts # 种子数据（会清空业务表后重建演示数据）
│ ├── scripts/ # verify-e2e.mjs / verify-classisland.mjs / apply-column-migrations.cjs
│ └── src/
│ ├── app.ts # Express 装配（探针 + 限流 + 模块挂载 + 静态托管 + 兜底）
│ ├── index.ts # 启动入口（自检 + HTTP + Socket.IO + 优雅退出）
│ ├── config/env.ts # 环境变量校验（zod）+ 生产配置自检
│ ├── lib/ # access(RBAC) / snapshot(全库 JSON 快照) / db / db-bootstrap /
│ │ # session / web-static / http / jwt / logger / mappers / version …
│ ├── tools/apply-snapshot.ts # 跨库迁移的子进程入口
│ ├── middleware/ # auth / error / validate / security(helmet + 限流 + 耗时日志)
│ ├── realtime/ # socket.ts（房间）+ bus.ts（事件总线）
│ └── modules/ # 15 个功能模块 + registry.ts（模块注册表）
├── classisland-plugin/ # ClassIsland 联动插件（.NET 8 / C#，独立于 pnpm workspace）
│ ├── manifest.yml
│ ├── src/Plugin.cs
│ ├── src/Services/ # BridgeService / ScheduleMapper / ClassPlanWriter /
│ │ # ClassHelperNotificationProvider
│ ├── src/Views/ # BridgeSettingsPage.axaml（Avalonia 设置页）
│ └── src/Interop/ClassHelperClient.cs # HTTP 客户端 + 逐字段对齐服务端 zod 的 DTO
├── web-admin/ # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
│ └── src/{api,stores,router,layouts,views,components,composables,styles}
└── desktop-client/ # 桌面客户端（Electron + Vue 3）
├── electron-builder.yml
├── scripts/{build-main,dev,smoke,dist-win,check-bundle-secrets}.mjs
└── src/
├── main/ # 主进程：窗口 / 单实例 / 配置持久化 / 托盘 / 灵动岛 / 冒烟
├── preload/ # contextBridge 安全桥（index.ts + island.ts）
├── island/ # 灵动岛渲染进程（独立透明置顶窗口）
├── types/desktop.d.ts # 主进程 ↔ 渲染进程契约
└── renderer/ # 渲染进程：api / stores / cache / router / views / island
```
## 模块化设计
后端每个功能是一个独立目录，统一契约：
```ts
// packages/server/src/modules/registry.ts（当前 15 个模块）
export const apiModules: ApiModule[] = [
authModule,
classesModule,
coursesModule,
schedulesModule,
homeworksModule,
notificationsModule,
callsModule,
importsModule,
integrationsModule,
gradesModule,
studentsModule,
teachersModule,
dashboardModule,
databaseModule, // 数据库管理（仅管理员）
updateModule, // 更新检查（服务端唯一出网请求）
].filter((module) => module.enabled !== false);
```
- **新增功能**：新建 `modules/<name>/`（`*.schemas.ts` 校验、`*.service.ts` 业务、`*.module.ts` 路由），
在 registry 里加一行即可，`app.ts` 不用改；
- **下线功能**：删掉那一行，或把 `enabled` 置为 `false`，接口立即从路由表消失；
- **实时推送解耦**：业务模块只调 `realtime/bus.ts` 的 `emitToClass/emitToUser`，不直接依赖 Socket.IO 实例；
- **共享契约**：所有 DTO 与类型集中在 `@classhelper/shared`（改完要 `pnpm build:shared`），三端共用。
## 几条贯穿全局的硬约定
这些都是踩过坑之后固化下来的，改代码前值得先看（完整版在 `AGENTS.md`）：
| 约定 | 为什么 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **统一响应与校验** | 用 `lib/http.ts` 的 `sendOk/sendCreated`，用 `middleware/validate.ts` 挂 zod，错误交给 `middleware/error.ts` |
| **权限判在服务层** | 路由只做角色过滤，班级维度的判断用 `lib/access.ts` 断言 —— 前端隐藏 ≠ 权限 |
| **周一为新一周的第一天** | 周次口径唯一：`resolveCurrentWeek(TERM_START_DATE, now, MAX_TERM_WEEK)` |
| **作业按 `assignDate` 归类** | 用 `createdAt`（UTC）会在晚上把作业算到第二天 |
| **新增实时事件要改三处** | 服务端 bus/socket、Web 端订阅、客户端订阅（灵动岛也依赖） |
| **跨桥接只传纯数据** | 传 Vue 的 `ref.value` 会在进入 preload 之前就抛 `could not be cloned` |
| **桌面端产物里不得有凭据** | asar 可直接解包；构建有 `check-bundle-secrets` 门禁 |
| **图标只有一个图形源** | 别改 `scripts/icons/` 的派生逻辑，换图标就换 `build/classhelper.{png,ico}` |
| **前端不写死颜色** | 深色主题靠语义令牌，写死的颜色在深色下会露馅 |
## 本地开发
```bash
pnpm install
cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
pnpm db:generate && pnpm --filter @classhelper/server db:deploy
pnpm build:shared # 必须先构建 shared，否则后续全部 ERR_MODULE_NOT_FOUND
pnpm db:seed # 演示数据（会清空业务表）
pnpm dev # shared watch + 后端 4000 + Web 端 5173
```
常用命令与端口见[安装服务端](../get-started/server.md)；验收脚本见[验收与测试](testing.md)。
docs/dev/classisland-plugin.md
+146
View File
@@ -0,0 +1,146 @@
---
title: ClassIsland 插件
description: 联动插件的契约、镜像为什么要带节次时间、上课时段暂存，以及部署与调试。
---
# ClassIsland 插件
源码在 `packages/classisland-plugin/`，是一个 **.NET 8 / C#** 的 ClassIsland 插件
（ClassIsland 插件 API 2.0）。它**独立于 pnpm workspace**，不参与 `pnpm install`。
## 三条链路
```
ClassIsland（教室机器）
│ ① 上报：状态 + 课表 + 节次时间（每次上报顺带取回一条待弹提醒）
▼
/api/integrations/classisland/report ← X-ClassIsland-Token（设备令牌，非 JWT）
│
│ ② 下发：老师在 Web 端发提醒 → 落库 → 插件下次上报时取回 → ClassIsland 全屏弹出 → ack
▼
/api/integrations/classisland/pending、/ack
│ ③ 镜像（可选）：服务端把本班课表下发，插件在 ClassIsland 里新建一份档案课表
▼
/api/integrations/classisland/class-plan
```
## 为什么走 HTTP 而不是 IPC
ClassIsland 的跨进程 IPC 数据质量不足以还原课表。插件内部**直接读**
`ILessonsService`（课程状态）与 `IProfileService`（档案课表）最准。
与后端之间用「**上报即拉取**」：每次上报的返回值里顺带带一条待弹出的提醒 ——
插件因此**不需要 WebSocket 依赖**，故障面更小，而且**上报间隔本身就是心跳**。
提醒是**轮询取回**的（默认最多 10 秒延迟，设置页「提醒轮询间隔」可调到 5 秒）。
## 设备令牌
- 令牌是**设备级**的，不是用户级；
- 插件在本机保存明文，服务端只存 **sha256** 与一个前缀提示（`chci_xxxxxxxx`）用于人眼识别；
- 同一班级下按 `deviceKey`（机器码）唯一 —— 插件重装后带同一 `deviceKey` 会**自动重绑**到原记录，
不会在设备列表里堆重复项；
- 关闭设备的「启用」开关后，该设备的上报与下发一律 403。
## 提醒的排队规则
| 提醒类型 | 上课时段 | 下课 / 放学 |
| ------------------------------------------------------ | ---------------------------- | ----------- |
| 通知类（`kind=notification`：通知发布页 / 联动页下发） | **暂存不弹** | 自动补弹 |
| 主动通知：紧急提醒、**叫人**（`kind=call`） | **立刻弹**（老师正在等学生） | 立刻弹 |
插件侧的实现在 `ClassHelperNotificationProvider`（`_deferred` + `FlushDeferred`，订阅课程事件）；
客户端侧的实现在 `renderer/island/bridge.ts`。**改这条规则要两端一起改。**
暂存期间**不回执**，所以服务端会一直保留着待提醒；`ClassIslandPush.expiresAt` 到期后不再补发
（避免学生几天后突然弹出旧提醒）。
## 镜像：为什么必须带 `startTime` / `endTime`
ClassIsland 的 `ClassPlan.Classes[i]` **强制与时间表里第 i 个 `TimeType == 0`（上课）的时间点对齐**。
所以镜像下发时，每一条课目都要带上自己的 `startTime` / `endTime`。
> **少一个时间点，整份课表就会错位** —— 而且表现为"课表看着有内容、每节课都对不上"，
> 极难排查。这是插件契约里最容易踩的坑。
另外镜像进 ClassIsland 的课表还要**带课间**：每两节之间补一段（上一节下课 → 下一节上课），
**最后一节之后不补**（放学）。实现见 `ClassPlanWriter.BuildTimeLayout`（自己按课目时间算），
服务端合成节次时间表用的是同一口径。
## 上报课表：单向还是双向
**双向对齐**。插件每次全量上报时，服务端只清理「`source='classisland'` 且本次未再上报」的行：
- 老师在 ClassIsland 里删掉 / 挪动一节 → 小助手这边跟着同步；
- 老师在小助手这边手排的课 → **一律不删**。
merge 的去重键是「星期 + 开始时间 + 单双周」。导入时**不要覆盖 `weekStart` / `weekEnd`** ——
插件上报契约里没有周次范围，硬写"整学期"会把老师设的「第 1~10 周」抹掉。
## 单双周的映射
ClassIsland 的 `WeekCountDiv` / `WeekCountDivTotal` ⇄ 本项目的 `ALL / ODD / EVEN`，
走 `@classhelper/shared` 的 `weekParityFromDiv` / `weekDivFromParity` ——
**服务端与插件共用同一份语义**，两边不会各算各的。
## 代理：本地地址强制直连
`ClassHelperClient` 里有一个 `LocalAwareProxy`：对本地 / 内网地址**强制直连**，
不走系统代理。
原因：教室机器上如果开了系统代理，填好令牌后表现为"立刻 HTTP 404"（其实是代理返回的错误页）。
`pnpm verify:classisland-plugin` 有 4 项断言盯着这段逻辑，别删。
## 构建、打包与验收
```bash
pnpm build:classisland-plugin # 编译（.NET 8；缓存与临时目录自动指到仓库内 .cache/）
pnpm dist:classisland-plugin # 打包 .cipx 并归集到 releases/classisland-plugin/<版本>/
pnpm verify:classisland-plugin # 静态契约校验（不需要 .NET，不需要服务端）
```
`verify:classisland-plugin` 会逐项校验：清单一致性、注册完整性、
**C# DTO ↔ 服务端 zod 与路由的字段对齐**，以及已修复坑的护栏。
### 那个预期内的编译警告
全量编译会有 **1 个警告 `AVLN3001`**：设置页只有 DI 构造函数、没有公开无参构造。
本插件走的是编译期 XAML + ClassIsland 的 DI 实例化，**加个无参构造反而会把 DI 弄坏**。
别为了消警告去改它。
## 部署到教室机器
```powershell
# 1) 完全退出 ClassIsland（它会锁住 DLL）
Get-Process ClassIsland.Desktop | Stop-Process -Force
# 2) 覆盖插件 DLL（**不要覆盖 Settings.json**，那里存着服务器地址与设备令牌）
Copy-Item packages\classisland-plugin\bin\Release\ClassHelper.ClassIslandPlugin.dll `
D:\Classisland\data\Plugins\classhelper.classisland.bridge\ -Force
# 3) 重新启动
Start-Process D:\Classisland\ClassIsland.exe -WorkingDirectory D:\Classisland
```
改配置要在 **ClassIsland 退出时**改：运行中改会被内存里的副本随时回写覆盖。
### 读日志要用 GBK
.NET 的控制台输出是**系统 ANSI（GBK）**编码。用 UTF-8 读会变成乱码，
**中文关键字一条都搜不到**（只能搜到 ASCII 的类名）：
```powershell
[System.IO.File]::ReadAllLines($path, [System.Text.Encoding]::GetEncoding(936))
```
日志文件被运行中的进程占用时，先 `Copy-Item` 一份再读。
## 真机验收链路
`pnpm verify:classisland`（需要后端在跑）会真的走一遍：设备令牌 → 上报 → 提醒下发与回执 →
镜像契约 → 幽灵行清理。
> 这个脚本开头会先**抽干本班的历史积压提醒**。因为待提醒接口是「本班全部未确认提醒，
> 按时间升序取前 20 条」，而其他冒烟会真的往演示班发通知 —— 攒够 20 条之后，
> 本脚本刚发的提醒会被挤出窗口，表现为"待提醒里找不到刚发的那条"，跟代码对不对毫无关系。
> **别把那个 drain 删掉。**
docs/dev/data-model.md
+87
View File
@@ -0,0 +1,87 @@
---
title: 数据模型
description: 14 张表的职责、跨库通用约定、迁移历史与启动时自动迁移。
---
# 数据模型
模型定义只有一份：`packages/server/prisma/schema.prisma`。
## 跨库通用约定
- 默认是 **SQLite**（Prisma 7 的 libSQL driver adapter，数据文件 `packages/server/prisma/dev.db`）；
- 字段**只用** `String / Int / Float / Boolean / DateTime`，**不用 Prisma enum、不用 `@db.*` 原生类型**；
角色与优先级存字符串，在 API 层用 zod 校验 —— 这样 SQLite 与 MySQL 行为完全一致；
- 因此切库只需改 `provider` 与连接串（`pnpm db:switch:mysql` 就地改写它，没有第二份 schema）；
- 主键统一用 cuid 字符串，便于多端离线生成与合并。
## 14 张表
| 表 | 职责 | 值得注意的字段 |
| ------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
| `User` | 教师 / 管理员 / 学生统一存储 | `role`、`classId`；学生 `passwordHash` 是空串占位，不能登录 |
| `Class` | 班级 | `code` + `passwordHash`（班级账号）、`termWeeks`、`notificationChannel` |
| `ClassTeacher` | 教师-班级 分配关系（协作教师） | `@@unique([classId, teacherId])` |
| `Enrollment` | 学生-班级 归属记录 | 与 `User.classId` 同步，为将来多班预留 |
| `Course` | 课程（班级维度） | `@@unique([classId, name])` |
| `Schedule` | 课表条目 | `weekStart` / `weekEnd` / `weekParity`（单双周）/ `source`（manual｜classisland） |
| `Homework` | 作业 | `assignDate`（所属日期）、`attachmentUrl`；`dueAt` 是已下线的遗留列 |
| `HomeworkStatus` | 学生作业完成状态 | `@@unique([homeworkId, userId])` |
| `Notification` | 通知 | `priority` |
| `NotificationRead` | 已读记录 | `@@unique([notificationId, userId])` |
| `TimeLayout` | 节次时间配置（ClassIsland 同款 JSON 导入得到） | `items` 是 JSON 字符串：`[{ index, name, startTime, endTime, type, skipped }]` |
| `Grade` | 成绩 | `score` / `totalScore` / `examName` |
| `IntegrationDevice` | ClassIsland 联动设备 | `tokenHash`（只存 sha256）、`tokenHint`、两个开关、最后一次上报的快照字段 |
| `ClassIslandPush` | 下发给 ClassIsland 的提醒 | `kind`（notification｜call）、`ackedAt`、`expiresAt` |
### 三个容易忽略的设计
**`ClassIslandPush` 与 `IntegrationDevice`** —— 提醒是**落库**的，不是"发出去就算"。
设备离线时通知不丢：插件重连后拉取未确认的那条立即弹出，弹完回执（`ackedAt`）。
`expiresAt` 防止学生几天后突然弹出旧提醒。
**`Schedule.source`** —— 决定插件全量上报时能清理哪些行：只清 `classisland` 来源且本次未再上报的行。
**`source` 只在 create 时确定，update 一律保持原值**（否则手排的课会被"收养"后又被清掉）。
**`Homework.dueAt`** —— 截止时间功能已下线，UI 与接口都不再读写它。
保留列是为了**不对已安装的库做破坏性迁移**；新库里它恒为 `null`。
## 迁移历史（10 个）
```
init → add_time_layout → add_class_account → add_schedule_week_parity →
add_class_term_weeks → add_classisland_integration → add_class_notification_channel →
add_homework_assign_date → add_push_kind → add_schedule_source
```
### 启动时自动迁移
`src/lib/db-bootstrap.ts` 用一张账本表 `_ch_migrations` 记录已执行的迁移目录名：
| 情况 | 行为 |
| -------- | --------------------------------------------------- |
| 全新安装 | 依次执行全部迁移并创建初始管理员 |
| 覆盖安装 | 只补跑账本里没有的迁移（已存在的表 / 索引自动跳过） |
| 已是最新 | **不做任何写操作** |
日志会写明「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
用户因此**不需要手动执行 `prisma migrate deploy`**。
## 备份格式就是这份模型的拓扑序导出
「数据库管理」里的备份 / 导出导入 / 跨库迁移共用一种 JSON 快照：14 张表按拓扑序导出，
恢复时**临时关闭外键检查** —— 因为 `User.classId → Class` 与 `Class.teacherId → User`
**互相引用**，任何排序都会被其中一侧卡死。见[数据库管理](../management/database.md)。
## 开发时的模型改动
1. 改 `schema.prisma`；
2. 在 `prisma/migrations/` 下加一个迁移目录（本机用
`pnpm --filter @classhelper/server db:deploy` 应用，**别用 `pnpm db:migrate`** ——
它在 Windows 上不可靠）；
3. 改 schema 时先看**哪些外键指向 `User` 且是 Cascade**，再回来核对
`deleteTeacher` 的护栏清单（它必须覆盖 `Class.teacherId` / `Course.teacherId` /
`ClassTeacher.teacherId` / `Homework.createdBy` / `Notification.createdBy` 五项）。
模型总数与迁移个数会随版本增长，以 `schema.prisma` 与 `prisma/migrations/` 的实际内容为准；
本文里的数字标注的是当前版本（1.1.2）的状态。
docs/dev/index.md
+55
View File
@@ -0,0 +1,55 @@
---
title: 开发文档
description: 班级小助手的架构、接口、数据模型、权限、动效层，以及验收与发版流程。
---
# 开发文档
班级小助手是一个 **pnpm monorepo**，一份代码产出四个交付物：
| 交付物 | 位置 | 形态 |
| -------------------- | ----------------------------- | --------------------------------------------------------------- |
| 后端服务 | `packages/server` | Express 5 + Prisma 7 + Socket.IO，接口前缀 `/api` |
| Web 管理端 | `packages/web-admin` | Vue 3 + Vite + Element Plus（教师 / 管理员用，PWA 可安装） |
| 桌面客户端 | `packages/desktop-client` | Electron + Vue 3（学生端 / 教室机器，含灵动岛浮窗） |
| 共享契约 | `packages/shared` | 三端共用的类型 / 常量 / 权限 / 工具函数 |
| ClassIsland 联动插件 | `packages/classisland-plugin` | .NET 8 / C#（**独立于 pnpm workspace**，不参与 `pnpm install`） |
核心链路：
```
教师在 Web 端发布内容
│ REST API（JWT 鉴权）
▼
后端服务（Express + Prisma）
│ 写库 + 按班级房间广播
▼
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI（含灵动岛）
ClassIsland（教室机器）──► 联动插件 ──► /api/integrations/classisland/*（设备令牌鉴权）
▲ │
└──── 老师下发的提醒 ◄──────┘
```
## 这一章有什么
| 页面 | 内容 |
| -------------------------------------------- | ------------------------------------------------ |
| [架构总览](architecture.md) | 目录结构、技术栈、模块化设计、几条贯穿全局的约定 |
| [REST API](api.md) | 全部接口一览（方法 / 路径 / 权限） |
| [实时事件（Socket.IO）](realtime.md) | 事件清单、房间规则、新增事件要改哪三处 |
| [数据模型](data-model.md) | 14 张表、迁移历史、跨库约定 |
| [角色与权限](permissions.md) | 权限矩阵与实现位置 |
| [动效层与主题](motion.md) | beUI 令牌、CSS `linear()` 弹簧、深色主题 |
| [ClassIsland 插件](classisland-plugin.md) | 插件契约、镜像为什么要带 `startTime`、部署与调试 |
| [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token |
| [验收与测试](testing.md) | 五套验收脚本怎么跑、哪些用例是脆弱的 |
| [版本迭代与发布](release.md) | 改版本号、出安装包、发 Release 的完整流程 |
## 仓库里另外两份文档
- **[完整参考](../reference.md)** —— 产品说明书 + 验收对照表（原 README 全文），
功能行为的**权威来源**；仓库首页那份 README 是精简后的门面页，细节都在这里。
- **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
写给 AI 编码代理的工程约定与本机踩坑记录，**改代码前必读**。
里面每一条硬约定都对应一次真实的翻车，比代码注释更值得先看一遍。
docs/dev/motion.md
+140
View File
@@ -0,0 +1,140 @@
---
title: 动效层与主题
description: beUI 动效令牌、CSS linear() 弹簧、运行时注入，以及深色主题的实现边界。
---
# 动效层与主题
## 令牌的单一来源
两端的动画与过渡统一走一套自研的动效语言，**移植自 [beUI](https://beui.dev) 的 `lib/ease.ts`**。
beUI 的组件本身是 React（`motion/react` + Tailwind），用不到这里，**但它的动效语言与框架无关**。
令牌全部在 `packages/shared/src/motion.ts`：
| 常量 | 取值 | 用在哪 |
| --------------- | --------------------- | ------------------------------ |
| `EASE_OUT` | `[0.16, 1, 0.3, 1]` | 绝大多数进出场 |
| `EASE_IN_OUT` | `[0.77, 0, 0.175, 1]` | 对称的来回动（抽屉、内容互换） |
| `EASE_DRAWER` | `[0.32, 0.72, 0, 1]` | 侧向抽屉 |
| `SPRING_PRESS` | 500 / 30 / 0.6 | 按钮、可点表面 |
| `SPRING_SWAP` | 460 / 30 / 0.55 | 控件内的内容互换 |
| `SPRING_PANEL` | 420 / 40 / 0.5 | 弹窗、抽屉、气泡进场 |
| `SPRING_LAYOUT` | 360 / 32 / 0.6 | 共享布局滑动（指示器） |
| `SPRING_MOUSE` | 200 / 15 / 0.3 | 光标跟随类装饰动效 |
| `SPRING_GLIDE` | 700 / 50 / 0.5 | 拖拽滑块与填充（临界阻尼） |
弹簧语义与 `motion/react` 一致：`加速度 = (stiffness × 剩余距离 − damping × 当前速度) / mass`。
这六组里 PRESS / SWAP / MOUSE 是欠阻尼（有过冲），PANEL / LAYOUT / GLIDE 是过阻尼。
### 为什么这个文件必须"纯常量 + 纯函数"
`packages/shared` 会被后端（Express）一起消费，它的 tsconfig 是 `lib: ["ES2023"]`（**不含 DOM**）。
所以这里不碰 `document`、不碰 `window`、也不依赖 vue。
DOM 注入与 Vue 组合式函数在两端各自的 `composables/motion.ts` 里
（`useReducedMotion` / `useHoverCapable` / `useCountUp` / `useStaggerIn`）——
与 `ScoreBarChart.vue` 一样，两端各一份是这个仓库的既有做法。
## 弹簧怎么变成 CSS
不必给每个组件挂一个 rAF 循环：**用数值积分求出落定时间，再生成 CSS `linear()` 缓动字面量**，
弹簧就能纯 CSS 驱动。
几条实现约束：
| 约束 | 原因 |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 积分步长 1ms、`linear()` 取 60 个采样点 | 60 段肉眼已看不出折线，再密只是徒增样式表体积 |
| **落定时间不能用包络公式 `6/(ζ·ω0)`** | 它只对欠阻尼成立；过阻尼要用较慢的实极点 `ω0(ζ−√(ζ²−1))`，否则曲线会被截断在 0.87/0.95 上、元素永远差一截 |
| **`--ch-spring-X` 与 `--ch-spring-X-dur` 必须成对用** | `linear()` 是把 [0,1] 进度重映射，时长给短了等于把整条曲线等比压缩 —— 形状还在，但已经不是那组参数的手感了 |
| `linear()` 的进度值可以 >1（过冲） | 只能用在不越界无害的属性上。**别用在 `opacity`** |
### 运行时注入
两端的 `main.ts` 在 `app.mount()` **之前**把令牌写进 `:root` 的自定义属性
（`--ch-ease-*` / `--ch-spring-*` / `--ch-dur-*`）。CSS 里只引用变量，**不抄数值 —— 抄了必漂**。
> **灵动岛是另一个渲染进程**，不共享主窗口的 `:root`：令牌要在 `src/island/main.ts` 里**再注入一次**。
> 漏了的话 `var(--ch-ease-out)` 解析为空、**整条 `transition` 简写作废**，比不改还差（完全没有过渡）。
## 落地到界面上的效果
| 位置 | 动效 |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| Element Plus 全站过渡 | 时长 300/200ms → 200/140ms，缓动换成 `EASE_OUT`（改写 `--el-transition-*` 变量，不动组件源码） |
| 弹窗 / 抽屉 / 浮层 | 面板走 `SPRING_PANEL` / `SPRING_SWAP`；**退出一律比入场快** |
| 按钮 | 按下 90ms 直落（跟手）、抬起走 `SPRING_PRESS` 弹回 |
| 侧栏激活项 | 单个"底片"在菜单项之间滑过去（`SPRING_LAYOUT`） |
| 页面内容 | `.page > *` 按块错峰浮现（30ms 一档，封顶 180ms） |
| 统计数字 | 0 → 实际值滚动（`useCountUp`） |
| 主题切换（两端） | View Transition API：从点击位置扩散的圆整页换肤 |
| 灵动岛 | **刻意只有单调缓动，不用弹簧** |
### 灵动岛为什么不用弹簧
岛的形变由**主进程**缓动窗口尺寸，而冒烟断言「展开过程不震动」「收回过程不抖动」
是**逐帧采样岛体几何**并要求单调的 —— 任何带过冲的弹簧都会直接判红。
所以岛用 `--ch-ease-out` 这类单调曲线，壳的物理仍归它自己的 `src/island/spring.ts`（WinIsland 移植）。
**不要拿 beUI 的 `SPRING_*` 去换**。
另外岛的 `:hover` 规则必须关在 `@media (hover: hover) and (pointer: fine)` 里 ——
教室触摸屏的"幽灵 hover"会让点过「知道了」的按钮永远高亮。
## 四条硬约束
| 约束 | 后果 |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **路由层不要包 `<transition>`**，尤其不要 `mode="out-in"` | ① 点菜单后一小段时间页面上还是上一页；② 退场判定依赖 `animationend`，而**窗口被遮挡时 Chromium 冻结 CSS 动画**，事件永不触发 ⇒ 新页面永远不挂载，整个应用卡死在第一页 |
| **Vue 的 `<transition>` 一律显式给 `:duration`** | 同上，靠 `animationend` 判断的写法在窗口不可见时会永远停住 |
| **`position: fixed` 的整屏层、以及"自己量几何再据此设尺寸"的元素，不要叠位移类动画** | `getBoundingClientRect()` 包含 transform，而 `clientHeight` / `offsetHeight` 不含 —— 下移 6px 就可能溢出屏幕 |
| **弹窗面板的动画挂在 `.el-dialog` 上，不要挂在 `.el-overlay-dialog`** | Element Plus 的 `@opened` 按根元素（只有 200ms 淡入）的动画结束触发，而外层容器的弹簧要跑 463ms —— 在 `@opened` 里量尺寸会量到"还带着 `scale(0.97)` 的缩小版" |
页面切换的动效因此改成 `.page > *` 错峰入场 —— 那是随组件挂载**同步**触发的，不依赖动画事件。
## 降低动态效果
两端各有一个 `@media (prefers-reduced-motion: reduce)` 全局块，把动画压到 **1ms**。
**是压短而不是 `transition: none`** —— 后者会让依赖 `transitionend` 的逻辑失灵。
唯一的例外是**加载指示旋**：它改为放慢而不是停，停掉会让界面看起来像卡死。
## 主题
**两端机制完全一致**：在 `<html>` 上挂 `.dark` 类，由各自的样式表覆盖**语义色令牌**，
Element Plus 的 `theme-chalk/dark/css-vars.css` 提供 `--el-*` 的深色默认。
两端的 `main.ts` 都在挂载前落主题，深色用户首帧才不会看到"先白后黑"。
### 语义色令牌
| 令牌 | 用途 |
| ------------------------------------------------------ | -------- |
| `--ch-surface` / `-alt` / `-sunken` / `-hover` | 表面 |
| `--ch-text` / `-secondary` / `-muted` / `-placeholder` | 文字层级 |
组件里**一律引用这些，不要写死颜色**。自查命令：
```bash
grep -rn "rgba(255, 255, 255\|rgba(0, 0, 0\|#fff" packages/desktop-client/src/renderer
```
除了**明确固定深色**的区域（全屏作业看板、登录页渐变、启动过渡页、灵动岛自身、
以及 accent 渐变底上的白字）之外，都应该是变量。
### 两条纪律
**`html.dark` 只覆盖颜色，绝不覆盖圆角与动效令牌。** 两套主题的几何必须完全一致，
否则切换时会看到布局跳一下。
**改令牌时只改值，不要对样式表跑批量替换。** "把 `#303133` 全量替换成 `var(--ch-text)`"
会把令牌**定义本身**也换成 `--ch-text: var(--ch-text)` —— 自定义属性一旦自引用就整条失效、
`getPropertyValue` 返回空串，全站文字颜色静默回落成继承色（浅色下看着"还行"，深色下才露馅）。
Web 端还要一并同步 `<meta name="theme-color">` 与 `color-scheme` —— 后者管**原生控件**
（滚动条、日期选择器弹层、自动填充底色），只改 CSS 变量的话它们仍是浅色。
### 刻意固定深色的区域
登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、Web 管理端的侧边栏
（本来就是深色）、以及深色底上的白色文字。**改它们会被当成回归。**
docs/dev/permissions.md
+85
View File
@@ -0,0 +1,85 @@
---
title: 角色与权限
description: 权限矩阵、实现位置，以及"前端隐藏 ≠ 权限"这条纪律。
---
# 角色与权限
## 矩阵在哪
**唯一一份**在 `packages/shared/src/permissions.ts`：
- 后端 `lib/access.ts` 复用它做断言；
- 两端前端用它隐藏入口；
- 验收脚本按它逐条断言。
所以不存在"前端一套后端一套"。改权限就改这一个文件（改完记得 `pnpm build:shared`）。
## 角色判定
班级内的角色由「账号角色 + 与该班级的关系」共同决定：
| 角色 | 判定方式 | 可见范围 |
| ------------------ | ------------------------------ | -------------------------- |
| `ADMIN` 管理员 | `User.role = ADMIN` | 全部班级 |
| 班主任 `HEAD` | `Class.teacherId === 当前用户` | 本班 |
| 科任老师 `SUBJECT` | `ClassTeacher` 中存在当前用户 | 被分配的班级 |
| 学生 `STUDENT` | `User.classId` / 班级账号 | 自己的班级（只读业务数据） |
| `NONE` | 与这个班没有任何关系 | 什么都看不到 |
判定函数是 `resolveClassRole()`。
## 权限矩阵
| 操作 | 管理员 | 班主任 | 科任老师 |
| -------------------------------------------------- | :----: | :----------: | :------: |
| 班级创建 / 修改 / 删除 | ✅ | ❌ | ❌ |
| 分配班主任与科任老师 | ✅ | ❌ | ❌ |
| 学生名单管理（增删 / 导入） | ✅ | ❌ | ❌ |
| 教师录入（新建 / 导入名单 / 修改密码） | ✅ | ❌ | ❌ |
| 数据库管理（备份 / 导入导出 / 一键切换） | ✅ | ❌ | ❌ |
| 课表管理（增删改 / 时间配置导入） | ✅ | ✅（仅本班） | ❌ |
| 布置作业 | ✅ | ✅ | ✅ |
| 叫人 | ✅ | ✅ | ✅ |
| 发布通知 | ✅ | ✅ | ✅ |
| 成绩录入 / 修改 / 导入（仅本班） | ✅ | ✅（仅本班） | ❌ |
| 班级密码维护（`PATCH /classes/:id/class-account`） | ✅ | ❌ | ❌ |
## 实现要点
**路由级只做角色过滤**：`requireRole('ADMIN', 'TEACHER')`。
**班级维度的判断在服务层**：`src/lib/access.ts` 提供
```
assertCanManageClasses / assertCanAssignTeachers / assertCanManageRoster
assertCanManageSchedule / assertCanPublishContent / assertCanManageGrades
```
**列表数据用 `resolveClassScope()` 收敛**（`classId in [...]`），单条接口直接断言；
越权一律 403。
**鉴权中间件会回查数据库**（`middleware/auth.ts`）：JWT 校验之后重新读一次用户与班级关系，
所以改了班级 / 角色会**立即生效**，不用等令牌过期。班级会话则回查 `Class` 表。
## 前端隐藏 ≠ 权限
前端的隐藏只是"别让人看见入口"：
- 教师登录时侧边栏不显示「班级管理 / 学生管理 / 教师管理 / 数据库管理」；
- 课表页的增删改按钮只对「管理员或本班班主任」显示；
- 成绩页的录入 / 删除按钮同理。
但这些页面**直接输网址也进不去**（路由 `meta.roles` 会把非管理员挡回仪表盘），
而且**所有写入请求服务端都会再断言一次**。绕过菜单、绕过前端，一样 403。
> 新增视图时别忘了两处：路由的 `meta.roles` + 服务层对应 service 里的 `assertCanXxx`。
> 只做其中一个都等于没做。
## 学生账号的两个反向约束
1. **学生不能登录**。`/auth/login` 遇到 `role=STUDENT` 直接 403；
且**角色判定在密码校验之前** —— 否则"密码错(401) / 密码对但学生账号已停用(403)"的差异，
会把学生账号密码变成可离线验证的预言机。
2. **学生没有任何密码接口**。`POST /students/:id/reset-password` 已删除（调用返回 404），
新建学生也不设密码（`passwordHash` 是空串占位）。
docs/dev/realtime.md
+81
View File
@@ -0,0 +1,81 @@
---
title: 实时事件（Socket.IO）
description: 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。
---
# 实时事件（Socket.IO）
## 连接
```ts
io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
```
客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
（客户端在检测到服务器恢复时会触发 `onServerRecovered`）；**灵动岛的上课时段暂存通知**由服务端保留、
下课后补发，不依赖重连。
## 事件清单
事件名定义在 `@classhelper/shared` 的 `SOCKET_EVENTS` —— **不要手写字符串**。
| 事件 | 方向 | 载荷 |
| ------------------------------------- | --------------- | ------------------------------------------------ |
| `connected` | 服务端 → 客户端 | `{ userId, role, rooms }` |
| `notification:new` | 服务端 → 客户端 | `NotificationDto` |
| `homework:new` | 服务端 → 客户端 | `HomeworkDto` |
| `homework:updated` | 服务端 → 客户端 | `HomeworkDto & { deleted?: boolean }` |
| `homework:status` | 服务端 → 客户端 | `HomeworkStatusDto & { classId }` |
| `grade:updated` | 服务端 → 客户端 | `GradeDto` |
| `schedule:updated` | 服务端 → 客户端 | `{ classId, action, schedule? }` |
| `class:updated` | 服务端 → 客户端 | `{ classId, action }` |
| `call:new` | 服务端 → 客户端 | 叫人消息（定向到 `user:{studentId}` / 班级设备） |
| `classisland:state` | 服务端 → 客户端 | `ClassIslandStateEvent`（教室现在上什么课） |
| `classisland:notification` | 服务端 → 客户端 | `ClassIslandNotificationEvent`（提醒已下发） |
| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限） |
## 房间规则
房间名定义在 `SOCKET_ROOMS`：
| 房间 | 谁在里面 |
| --------------------- | --------------------------------- |
| `class:{classId}` | 这个班的所有在线端 |
| `user:{userId}` | 某个用户自己的连接 |
| `teacher:{teacherId}` | 某个教师 |
| `role:{role}` | 某一角色（`ADMIN` / `TEACHER` …） |
| `students` | 全部学生端连接 |
| `teachers` | 全部教师端连接 |
服务端通过 `realtime/bus.ts` 的 `emitToClass` / `emitToUser` 发事件 ——
**业务模块不直接依赖 Socket.IO 实例**，只依赖事件总线。
## 新增一个实时事件要改三处
```
① 服务端 shared/src/constants.ts 的 SOCKET_EVENTS 加常量
→ business service 调 bus.emitToXxx(...)
→ realtime/socket.ts 房间映射（如果需要新房间）
② Web 端 web-admin/src/stores/realtime.ts 订阅
③ 客户端 desktop-client/src/renderer/stores/realtime.ts 订阅
→ 灵动岛也依赖它（renderer/island/bridge.ts）
```
**只改服务端不会报错**，只是前端静静地不更新 —— 所以这三处必须一起改。
事件名一律取自共享常量，不要手写字符串（拼错一个字就是一个静默失效）。
## 事件到达之后发生什么
以通知为例：
```
服务端写库 → bus.emitToClass(classId, notification:new)
├─► Web 端 stores/realtime.ts → 通知列表刷新
└─► 客户端 stores/realtime.ts → 更新内存状态 + 写回 IndexedDB
└─► island/bridge.ts → pushNotificationToIsland()
└─► 主进程 IslandController 决定：隐藏 / 胶囊 / 详情
└─► 灵动岛渲染进程 IslandApp.vue
```
上课时段的取舍（隐藏还是立即展开）由主进程的 `IslandController` 按当前上课状态决定，
见[通知与提醒](../app/notifications.md)与[灵动岛](../app/island.md)。
docs/dev/release.md
+184
View File
@@ -0,0 +1,184 @@
---
title: 版本迭代与发布
description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
---
# 版本迭代与发布
## 一条总原则
> **版本号按「发布」迭代，不按「提交」迭代。**
日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
才走一次完整的版本迭代。理由很实际：安装包、`.cipx`、Docker 镜像 tag、文档站的版本徽标、
更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
| 算一次发布 | 不算 |
| --------------------------------------- | ---------------------------- |
| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
| 要给别人一份新安装包 | 只在自己机器上跑 |
| 插件单独发补丁（只动插件第 4 段版本号） | — |
## 版本号写在哪（10 处）
同一个版本号出现在 10 个文件里，**手工改必然漏一处**，而漏掉的那处不会报错：
| 文件 | 内容 |
| ---------------------------------------------------------------- | ------------------------------- |
| `package.json` | 单一来源（服务端运行时读它） |
| `packages/{shared,server,web-admin,desktop-client}/package.json` | 各包的版本 |
| `deploy/package.runtime.json` | 安装包 / 容器里的运行时依赖清单 |
| `deploy/docker-compose.yml`、`docker-compose.sqlite.yml` | 镜像 tag 的默认值 |
| `packages/classisland-plugin/manifest.yml` | 插件清单（四段：`x.y.z.0`） |
| `packages/classisland-plugin/src/Services/BridgeService.cs` | 插件上报的 `PluginVersion` 常量 |
所以**改版本号的唯一入口是脚本**：
```bash
pnpm version:check # 逐处列出并比对，不一致 exit 1
pnpm version:bump patch # 1.1.2 → 1.1.3
pnpm version:bump minor # 1.1.2 → 1.2.0
pnpm version:bump major # 1.1.2 → 2.0.0
pnpm version:check # 再确认一次
```
脚本按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，不做"尽力而为"的部分改写。
> 插件版本是 **四段** `x.y.z.0`：前三段跟产品版本走，第 4 段留给"只改插件、不动产品版本"的补丁发布。
> `--bump` / `--set` 会把第 4 段归零；要单独发插件补丁就手工改那两处（清单 + `BridgeService.cs`）。
## 一次完整的发布
下面这一串命令就是全部流程，逐条照抄即可。
### 1. 改版本号
```bash
pnpm version:check
pnpm version:bump patch
```
### 2. 本地体检
```bash
pnpm lint
pnpm typecheck
pnpm check:icons
pnpm docs:check # 文档站构建（警告即失败）
```
### 3. 跑验收
```bash
pnpm dev:server # 另开一个终端跑着
pnpm verify:e2e
pnpm verify:classisland
pnpm verify:classisland-plugin
pnpm build:desktop && pnpm verify:desktop
pnpm build && pnpm verify:web
```
哪一项红了先看[验收与测试](testing.md)的「失败时先别改代码」——
里面列了几个已知脆弱的用例，它们红不代表代码坏了。
### 4. 打安装包
```bash
pnpm dist:all # = dist:server + dist:win + dist:classisland-plugin
```
产物落在 `releases/<组件>/<版本>/`：`安装包/`、`免安装/`、`构建中间/`。
打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
```bash
pnpm verify:packaged --exe "releases/client/<版本>/免安装/班级小助手.exe"
```
> Linux 包**只能在 Linux 上构建**（依赖是平台相关的），所以不在这条命令里 ——
> 它由 GitHub Actions 出，见第 7 步。
### 5. 生成跨组件哈希清单
`releases/SHA256SUMS-<版本>.txt` 是**人读的**（表头 + 体积 + 说明），由发布流程维护，
本地只写 Windows 与插件那几行：
```bash
cd releases/client/<版本>/安装包 && sha256sum *.exe > ../../../SHA256SUMS-<版本>.txt # 按实际文件名整理
```
（Linux 那一行由 CI 在第 7 步里**合并**进去，不要手工写。）
### 6. 提交并推上去
```bash
git add -A
git commit -m "chore(release): 1.1.3"
git push origin master
```
提交信息用 Conventional Commits + 模块 scope，描述写中文，可多 scope，例如
`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`。
### 7. 开 Release
```bash
gh release create v1.1.3 --title "v1.1.3" --generate-notes
gh release upload v1.1.3 \
releases/client/<版本>/安装包/*.exe \
releases/classisland-plugin/<版本>/安装包/*.cipx \
releases/server/<版本>/安装包/*.exe \
releases/SHA256SUMS-<版本>.txt --clobber
```
`gh release create` 会**创建 tag 并推送**，这一步会自动触发
[`release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
构建 Linux 包（ubuntu runner）。它跑完之后会：
1. 把 `classhelper-server-linux-x64-<版本>.tar.gz` 与 `.sha256` 挂到 Release 上；
2. **把 Linux 那一行合并进** `SHA256SUMS-<版本>.txt`（保留 Windows / 插件那几行）。
> **顺序很重要**：Linux workflow 是在最后一步才去合并 SHA256SUMS 的，
> 所以第 5 步那份清单必须**先上传**。万一手速反了（workflow 先跑完、你后上传），
> 重新跑一次 `gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true` 就能把那一行补回来。
想手动触发（比如只需要重出 Linux 包）：
```bash
gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
```
### 8. 文档站
**不用做任何事。** 推送 master 时只要 `docs/**` 或 docs 的 workflow 变过，
[`docs.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/docs.yml)
会自动用 docfx 构建并部署到 GitHub Pages。
文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了。
### 9. 检查
- [ ] Release 页面上四个组件都在，`SHA256SUMS-<版本>.txt` 里 Windows / 插件 / Linux 三种行齐全；
- [ ] 文档站能打开，顶栏版本号是新版；
- [ ] 装一台机器试一遍（或至少跑 `pnpm verify:packaged`）。
## 回滚
发布出去之后发现严重问题：
| 情形 | 做法 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 只是文档 / Release 说明写错 | 直接改 Release 说明或重发文档站（`gh workflow run docs.yml`） |
| 二进制有问题 | 删掉 Release 与 tag（`gh release delete v1.1.3 --cleanup-tag`），修完重新发；**不要**拿同一个版本号发第二次内容不同的包 |
| 用户已经装了 | 发一个**新版本号**（`pnpm version:bump patch`）修复，不要原地改 |
> 已经发出去的版本号**不要复用**：客户端把它记进「忽略此版本」，服务端与 Web 端各有 30 分钟缓存，
> 同号换内容会让"检查更新"永久失灵。
## 相关
- 文档站本身怎么写的 → [架构总览的目录结构](architecture.md)
- 验收脚本与脆弱用例 → [验收与测试](testing.md)
- 各形态升级的**用户侧**步骤 → [更新与升级](../management/upgrade.md)
docs/dev/testing.md
+99
View File
@@ -0,0 +1,99 @@
---
title: 验收与测试
description: 五套验收脚本怎么跑、覆盖什么、哪些用例是脆弱的，以及怎么判断失败是不是真回归。
---
# 验收与测试
这个仓库的验收方式是**跑真东西**：真的起后端、真的开 Electron 窗口、真的点击菜单、
真的发一条通知。不是单元测试，是端到端回归。
## 五套脚本
| 命令 | 覆盖 | 需要什么 |
| -------------------------------- | -------------------------------------------------------------------------------- | --------------------------- |
| `pnpm verify:e2e` | 后端 + 实时推送 + RBAC 越权 + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查 | **后端已启动** |
| `pnpm verify:web` | Web 管理端真实点击回归（Electron 驱动） | 后端已启动 + Web 产物已构建 |
| `pnpm verify:desktop` | 客户端冒烟（Electron，无人工点击） | 已构建的客户端产物 |
| `pnpm verify:packaged` | 对**打包后 / 已安装**的客户端 EXE 复跑同一套冒烟（`--exe` 指定路径） | 打包产物 |
| `pnpm verify:classisland` | 设备令牌 / 上报 / 提醒下发与回执 / 镜像契约 / 幽灵行清理 | 后端已启动 |
| `pnpm verify:classisland-plugin` | 插件静态契约（清单一致性 / 注册完整性 / C# DTO ↔ 服务端 zod 与路由） | 不需要 .NET，也不需要后端 |
条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`），**文档里不写死容易过期的总数** ——
每次跑完看脚本输出。
另外三套是"门禁"而不是验收：`pnpm typecheck`、`pnpm lint`、`pnpm check:icons`。
### 一次完整的交付前检查
```bash
pnpm lint # ESLint，0 error 是底线
pnpm typecheck # 全仓库类型检查（含 vue-tsc）
pnpm dev:server # 另开一个终端
pnpm verify:e2e
pnpm verify:classisland
pnpm verify:classisland-plugin
pnpm build:desktop && pnpm verify:desktop
pnpm build && pnpm verify:web
```
改动涉及打包/交付形态时，再加 `pnpm dist:all` 与
`pnpm verify:packaged --exe "<客户端路径>"`（**开发产物通过不等于用户机器上的副本通过**）。
## 失败时先别改代码
下面这些用例**不是回归**，遇到时先看条件。完整清单在 `AGENTS.md` 的「已知脆弱用例」表。
| 用例 | 触发条件 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `verify:desktop`「真实通知链路」「灵动岛标为已读」等 3 项 | 要求**当前不在上课时段**。种子课表恰有课正在进行时，客户端会**正确地**把普通通知暂存到下课 —— 这三项就会红（日志里会写 `客户端判定上课中=true`） |
| `verify:e2e`「上课状态接口（at=周一 08:10）」 | 种子把周一第 1 节限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`.env` 的 `TERM_START_DATE` 对齐即可全绿 |
| `verify:web`「课表科目为全校统一目录」 | 种子给每个班建满了全部科目，下拉里就没有可自动建课的「统一科目」分组 |
| `verify:desktop`「课表今天时间轴」 | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤 |
| `verify:desktop`「作业看板全屏自适应」 | 演示数据某天有 6 条长作业、而冒烟窗口只有约 543px 高时，缩放被下限 0.45 钳住 → 必然溢出 |
| 岛交互 / 岛动画 / 岛截图留档 | **AI 会话里会间歇性失败**：置顶透明小窗的 rAF 被限流、形变采样抓不到帧。**先原样重跑一次再动手改** |
## 大面积报「登录失败 / 401」时
先核对本机 `teacher1` 的密码 —— 本机实测可能被改成了 `123456`，不是种子默认的 `teacher123`
（原因是「修改密码」弹窗留空会落到默认初始密码）。**处理方式是用环境变量传实际凭据，不要去改数据。**
两个演示账号的口令**不一定一起漂**，所以不能简单地全局替换。
| 脚本 | 覆盖凭据的方式 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `verify:desktop` | `set "ELECTRON_SMOKE_USER=teacher1" && set "ELECTRON_SMOKE_PASSWORD=123456" && pnpm verify:desktop` |
| `verify:packaged` | 同上（`ELECTRON_SMOKE_*`） |
| `verify:web` | `set "UI_SMOKE_USER=teacher1" && set "UI_SMOKE_PASS=123456" && pnpm verify:web`（另有 `UI_SMOKE_ADMIN*`） |
| `verify:e2e` | **不支持环境变量**，需用临时副本替换（且副本必须放在 `packages/server/scripts/` 里，否则 `import 'socket.io-client'` 会失败） |
## 冒烟会真的动你的屏幕
`verify:web` / `verify:desktop` / `verify:packaged` 会**真的弹窗口**、真的发通知、真的移动鼠标：
- 跑的时候别动键鼠；
- 验证实例的灵动岛是**洋红主题色**（`#e91e8c`），一眼可以与你自己客户端那个区分开。
两条反馈里的"屏幕上出现了第二个灵动岛""点它反应不对"都源于这个叠影；
- 冒烟会往演示班发几条「张老师 · _自检_」通知，用完即删；中途被 kill 会留下残条。
## 截图留档
回归测试顺手把截图存到 `docs/screenshots/`（island / client / web-mobile / classisland 四组），
文档站里用的就是这些图。要重新采集：
```bash
pnpm dev:server
ISLAND_SHOTS_DIR=F:/ClassHelper/.cache/island-shots \
ELECTRON_CLIENT_SHOTS_DIR=F:/ClassHelper/.cache/client-shots \
ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
ELECTRON_SMOKE_USER=teacher1 ELECTRON_SMOKE_PASSWORD=123456 \
node packages/desktop-client/scripts/smoke.mjs
```
官网的实机图则用 `website/tools/capture-shots.mjs`（采集步骤见 `README.md` §7）。
> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。
docs/dev/toc.yml
+22
View File
@@ -0,0 +1,22 @@
- name: 开发文档
href: index.md
- name: 架构总览
href: architecture.md
- name: REST API
href: api.md
- name: 实时事件（Socket.IO）
href: realtime.md
- name: 数据模型
href: data-model.md
- name: 角色与权限
href: permissions.md
- name: 动效层与主题
href: motion.md
- name: ClassIsland 插件
href: classisland-plugin.md
- name: 灵动岛设计令牌
href: winisland-design-tokens.md
- name: 验收与测试
href: testing.md
- name: 版本迭代与发布
href: release.md