fix(dist): Linux 包打不出 tar.gz —— 交付目录不再由 staging 顺带创建

1.3.0 把服务端组装中间物从 `releases/server/<版本>/linux-x64/classhelper-server-linux-x64/`
挪进 `.cache/server-staging/` 之后，`releases/server/<版本>/linux-x64/` 就再没有谁创建它了 ——
`tar -czf <那里>/classhelper-server-linux-x64-<版本>.tar.gz` 直接以
`tar (child): ...tar.gz: Cannot open: No such file or directory` 退出码 2 失败。

Windows 侧不受影响（`buildInstaller()` 里有 `mkdirSync(INSTALLER_DIR)`），
所以本地 `pnpm dist:server` 永远踩不到；`release-linux-server.yml` 在 v1.3.0 的 tag 上一跑就红
（run 38109984623 挂在「构建 Linux 安装包」）。补救是幂等的：目录已存在就什么也不做。

`packLinuxTarball()` 的 tar 调用与 1.2.0 逐字节相同，而 1.2.0 的 CI（run 37458412997）是绿的
—— 唯一的差异就是那句隐式创建没了。

.github/workflows/pages.yml

@@ -0,0 +1,93 @@
+name: 发布官网与文档站
+
+# 把一个 GitHub Pages 站点发出去：
+#
+#   /                产品官网（website/，纯静态、无构建步骤）
+#   /docs/           文档站（docfx 构建 docs/ 得到）
+#
+# 为什么要拼成一个站点：**一个仓库在 GitHub Pages 上只有一个站点**。两者发布节奏也不一样
+# （改个错别字就该上线，不该为此打个安装包），所以走 workflow 而不是塞进发布流程。
+#
+# 站点地址：https://lovechengke.github.io/ClassHelper/
+# 需要在仓库 Settings → Pages 里把 Source 选成「GitHub Actions」（只需做一次）。
+#
+# 本地预览：pnpm dev:site（官网在 :5180，文档站挂在同一个端口的 /docs/ 下）
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'website/**'
+      - 'docs/**'
+      - 'scripts/build-pages.mjs'
+      - '.github/workflows/pages.yml'
+      # 两个页面上的版本号都取自根 package.json
+      # （官网是手写的徽章，文档站由 docs/build.mjs 用 --metadata 注入），
+      # 所以版本号变了也要重新发一次
+      - 'package.json'
+  workflow_dispatch:
+
+# Pages 部署需要的三件套：读代码、写 Pages、用 OIDC 拿部署令牌
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 同一时间只跑一个部署；已经在跑的那次不取消（半途取消会留下一个坏掉的站点）
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 安装 .NET SDK 8
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: 安装 docfx
+        # docfx 是 .NET 全局工具，装完在 ~/.dotnet/tools 下；setup-dotnet 会把它加进 PATH，
+        # 这里再显式补一次，免得换 runner 镜像后找不到命令。
+        run: |
+          dotnet tool install --global docfx
+          echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
+
+      - name: 构建文档站
+        # --check 把 docfx 的警告当错误：最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
+        # 那种页面会被构建出来但没有侧边栏 —— 属于必须修掉的疏漏，不该悄悄上线。
+        #
+        # DOCS_BASE 是给文档站那份 404 用的：项目页挂在 /<仓库名>/ 子路径下，而浏览器按
+        # **被请求的路径**解析 404 页里的相对链接，所以要把站点根钉成 <base>。
+        env:
+          DOCS_BASE: /${{ github.event.repository.name }}/docs/
+        run: node docs/build.mjs --check
+
+      - name: 组装站点（官网在根，文档站在 /docs/）
+        env:
+          SITE_BASE: /${{ github.event.repository.name }}/
+        run: node scripts/build-pages.mjs
+
+      - name: 配置 Pages
+        uses: actions/configure-pages@v5
+
+      - name: 上传构建产物
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .cache/pages
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: 部署到 GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release-linux-server.yml

@@ -9,7 +9,7 @@ name: 发布 Linux 服务端安装包
 #
 # 用法：
 #   1. 先在本地按惯例打出 Windows 包并发 Release（vX.Y.Z）；
-#   2. 到 Actions 页面手动运行本 workflow，填 tag（例如 v1.1.0）；
+#   2. 到 Actions 页面手动运行本 workflow，填 tag（例如 v1.1.2）；
 #   3. 跑完 Release 里会多出 Linux 包与更新后的 SHA256SUMS-<版本>.txt。
 #
 # 也可以只跑构建不挂 Release（attach=false），产物在 workflow 的 Artifacts 里。
@@ -18,7 +18,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: '要构建并挂载的 Release tag（例如 v1.1.0）'
+        description: '要构建并挂载的 Release tag（例如 v1.1.2）'
         required: true
         type: string
       attach:
@@ -69,19 +69,27 @@ jobs:
       - name: 安装依赖
         run: pnpm install --frozen-lockfile
 
+      - name: 生成 Prisma Client
+        # 必须显式生成：packages/server/src/generated/prisma 是 gitignored 的，CI 上全新检出没有它。
+        # 少了这一步，`tsc` 会因为 Prisma 类型解析不到而把回调参数全推成 any，报出一大片
+        # "TS7006 Parameter 'item' implicitly has an 'any' type" / "TS2339 Property 'id' does not exist
+        # on type '{}'" —— 看着像代码写错了，实际是缺生成物（本机因为早就生成过，永远踩不到）。
+        # deploy/Dockerfile 的构建阶段有同样的步骤与注释。
+        run: pnpm --filter @classhelper/server db:generate
+
       - name: 构建 Linux 安装包
         run: pnpm dist:server:linux
 
       - name: 展示产物
-        run: ls -la release-server/
+        run: ls -la releases/server/*/linux-x64/
 
       - name: 上传构建产物（Artifacts）
         uses: actions/upload-artifact@v4
         with:
           name: classhelper-server-linux-x64
           path: |
-            release-server/classhelper-server-linux-x64-*.tar.gz
+            releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz
-            release-server/classhelper-server-linux-x64-*.tar.gz.sha256
+            releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz.sha256
           if-no-files-found: error
           retention-days: 30
 
@@ -93,24 +101,32 @@ jobs:
         run: |
           set -euo pipefail
           VERSION="${TAG#v}"
-          TARBALL="release-server/classhelper-server-linux-x64-${VERSION}.tar.gz"
+          ARTIFACT_DIR="releases/server/${VERSION}/linux-x64"
-          SUMS="release-server/SHA256SUMS-${VERSION}.txt"
+          TARBALL="${ARTIFACT_DIR}/classhelper-server-linux-x64-${VERSION}.tar.gz"
+          SHAFILE="${TARBALL}.sha256"
+          SUMS="releases/SHA256SUMS-${VERSION}.txt"
 
           if [ ! -f "$TARBALL" ]; then
             echo "::error::没有找到 $TARBALL（tag 与 package.json 的版本号对得上吗？）"
             exit 1
           fi
+          # .sha256 必须跟着一起传：它是独立发布的资产，只更新 tar.gz 会让这个文件指向旧哈希，
+          # 拿它校验的人会得到 mismatch（classhelper upgrade 用的是 --sha256/这个文件，不是 SHA256SUMS）。
+          if [ ! -f "$SHAFILE" ]; then
+            sha256sum "$TARBALL" | sed "s#${ARTIFACT_DIR}/##" > "$SHAFILE"
+          fi
 
-          # 取回已有的校验清单（Windows 包那几行），把本次的 Linux 包追加/替换进去
+          # 取回已有的校验清单（Windows 包那几行），只替换/追加本包这一行，其余内容原样保留。
-          gh release download "$TAG" --pattern "SHA256SUMS-*.txt" --dir release-server --clobber || true
+          # 注意**不要**用 `sort -u` 去重：那份文件是人读的（表头 + 体积 + 说明），排序会把它们打散。
-          DOWNLOADED="$(ls release-server/SHA256SUMS-*.txt 2>/dev/null | head -n 1 || true)"
+          gh release download "$TAG" --pattern "SHA256SUMS-*.txt" --dir releases --clobber || true
+          DOWNLOADED="$(ls releases/SHA256SUMS-*.txt 2>/dev/null | head -n 1 || true)"
           if [ -n "$DOWNLOADED" ] && [ "$DOWNLOADED" != "$SUMS" ]; then mv "$DOWNLOADED" "$SUMS"; fi
-          grep -v "classhelper-server-linux-x64-${VERSION}.tar.gz" "$SUMS" 2>/dev/null > "${SUMS}.tmp" || true
+          touch "$SUMS"
-          cat "${SUMS}.tmp" > "$SUMS" 2>/dev/null || true
+          grep -v "^[0-9a-f]\{64\}  classhelper-server-linux-" "$SUMS" > "${SUMS}.new" || true
-          rm -f "${SUMS}.tmp"
+          printf '%s  %s\n' "$(sha256sum "$TARBALL" | awk '{print $1}')" "$(basename "$TARBALL")" >> "${SUMS}.new"
-          sha256sum "$TARBALL" | awk '{print $1"  "$2}' | sed "s#release-server/##" >> "$SUMS"
+          mv "${SUMS}.new" "$SUMS"
-          sort -u -k2 "$SUMS" -o "$SUMS"
 
-          gh release upload "$TAG" "$TARBALL" "$SUMS" --clobber
+          gh release upload "$TAG" "$TARBALL" "$SHAFILE" "$SUMS" --clobber
           echo "已上传："
+          cat "$SHAFILE"
           cat "$SUMS"

.gitignore

@@ -48,3 +48,6 @@ releases/
 .zcodeignore
 packages/server/prisma/backups/
 packages/server/prisma/database-settings.json
+
+# 鏂囨。绔欐瀯寤轰骇鐗╋紙pnpm docs:build 鐢熸垚锛岀敱 GitHub Pages 鍙戝竷锛涜� docs/锛�
+docs/_site/

.prettierignore

@@ -7,3 +7,4 @@ pnpm-lock.yaml
 .cache
 .pnpm-store
 .probe
+docs/_site

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md — 班级小助手（Class Helper）
+# AGENTS.md — ClassHelper（Class Helper）
 
 本文件写给在本仓库里干活的 AI 编码代理。先读这里，再动代码。
 文中「本机环境」「已知坑」两节按**实测**写成；若与本机现状不符，以本机实测为准并顺手改掉这里。
@@ -28,7 +28,7 @@
         ▼
  Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI
 
-ClassIsland（教室机器）──► 班级小助手联动插件 ──► /api/integrations/classisland/*（设备令牌鉴权）
+ClassIsland（教室机器）──► ClassHelper 联动插件 ──► /api/integrations/classisland/*（设备令牌鉴权）
                                    ▲                                  │
                                    └──── 老师下发的提醒（上报返回值里顺带带回）◄┘
 ```
@@ -47,15 +47,16 @@ pnpm-workspace.yaml          workspace + allowBuilds（pnpm 11 依赖构建白
 tsconfig.base.json           共享 TS 基础配置（ESM + NodeNext + strict）
 eslint.config.mjs            ESLint 扁平配置（TS + Vue）；ignores 含 releases/ / release-server/ / src/generated/
 .prettierrc.json             单引号 / printWidth 110 / trailingComma all / LF / 2 空格
-build/icon.{ico,png}         应用图标（由 pnpm icons 生成）
+build/classhelper.{png,ico}   图标源（**设计导出、手工放入**；`pnpm icons` 从它派生其余全部图标，见 §5 第 62 条）
 scripts/
   use-database.mjs           SQLite ⇄ MySQL 切换（**改写 schema.prisma 里的 provider**，没有第二份 schema）
-  generate-icons.mjs         Electron 渲染 SVG → PNG/ICO
+  generate-icons.mjs         启动 Electron 跑 icons/render.cjs（= `pnpm icons`）
-  icons/render.cjs           图标渲染（CommonJS）
+  icons/render.cjs           把 classhelper.png 重采样成各端图标（CommonJS，见 §5 第 62 条）
-  dist-server.mjs            服务端 + Web 管理端打包（产物落在 release-server/）
+  dist-server.mjs            服务端 + Web 管理端打包（产物落在 releases/server/<版本>/）
   nsis/server-installer.nsi  服务端 NSIS 安装脚本
   verify-packaged.mjs        对**打包后/已安装**的客户端 EXE 复跑冒烟
   check-icons.mjs            图标注册表静态门禁（漏注册会静默渲染空白，见 §5 第 53 条）
+  version.mjs                版本号单一来源的读写与一致性校验（= `pnpm version:*`，见 §4.4）
   ui-smoke/{run,main.cjs,live-probe.mjs}  Web 管理端真实点击回归（Electron 驱动）
   lib/{electron-env,node-runtime}.mjs     启动 Electron / 定位真实 node.exe
 deploy/                      Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf / package.runtime.json
@@ -65,19 +66,69 @@ deploy/                      Dockerfile / docker-compose{,.sqlite}.yml / nginx.c
                              profile.d/ logrotate.d/ systemd/（装到 /etc 的模板）
                              Dockerfile.linux-package（安装包内那份，--mode docker 用）
                              classhelper.service（systemd 模板，5 个占位符）/ .env{,.sqlite}.example
-docs/                        production.md（生产部署）/ linux-deploy.md（Linux 部署与运维）
+docs/                        **文档站**（docfx 项目；不进 pnpm workspace）
-                             mysql.md（MySQL 切换）/ winisland-design-tokens.md
+                             ⚠ 与官网（website/）共用**同一个** GitHub Pages 站点：官网在根、
-                             screenshots/{island,client,web-mobile,classisland}/
+                               文档站在 /docs/ 下。一个仓库在 Pages 上只有一个站点，
-packages/shared/src/         types.ts / constants.ts / permissions.ts / utils.ts / index.ts
+                               拼装由 scripts/build-pages.mjs 完成，见 §4.4「官网与文档站怎么发布」。
+                             docfx.json / toc.yml（顶栏）+ 各章节自己的 toc.yml（侧栏）
+                             get-started/ app/ management/ dev/（四章内容）
+                             management/{production,linux-deploy,mysql}.md（部署与换库）
+                             dev/winisland-design-tokens.md
+                             images/（**展示图**：文档站 / README / 官网共用的同一份，1× 逻辑像素）
+                             screenshots/（回归留档的截图：island / client / web-mobile / classisland，
+                                          页面不展示；两者分工见 docs/dev/testing.md「截图留档」）
+                             templates/classhelper/（模板覆盖：_master.tmpl + public/main.css + 图标）
+                             build.mjs（构建，注入版本号与 404 的 base）/ serve.mjs（本地预览 :5181）
+                             _site/（构建产物，gitignored）
+                             ⚠ 站点的顶栏版本徽标取自根 package.json（build.mjs 用 --metadata 注入），
+                               不要在文档里再写一份版本号。
+                             ⚠ 页面里的照片一律指向 images/ —— 它就是 README 与官网吃的那一份。
+                               别再往 screenshots/ 引图：那是冒烟脚本滚动的留档，随时被下一次验证覆盖。
+                             ⚠ 模板目录里的 logo.png / favicon.png 由 `pnpm icons` 派生（见 §5 第 62 条），
+                               别手工替换；改图标只改 build/classhelper.png 再跑 pnpm icons。
+                             ⚠ 文档站只发布 docs/ 这一棵树，页面里**不要**写指向 docs/ 之外的相对链接
+                               （如 ../AGENTS.md）—— 发布出去全是 404，要用 GitHub 的绝对 URL。
+website/                     产品官网（**纯静态、无构建步骤**，不进 pnpm workspace）
+                             index.html（门面）/ download.html（下载页，首页的「立即下载」跳到它）
+                             assets/{styles.css,motion.js,main.js,download.js,icon.png,shots/}
+                             serve.mjs（本地预览）/ tools/capture-shots.mjs（实机图采集）
+                             404.html（**站点根** 404，含 {{BASE}} 占位符，由 build-pages.mjs 注入）
+                             ⚠ serve.mjs 把 ../docs/_site 挂在 /docs/ 下，为的是让本地与线上同形 ——
+                               否则页脚那几个「文档站」链接在本地全是 404。文档站得先 pnpm docs:build。
+                             ⚠ 首屏标题第二行是 .reveal-grad：**它不参与逐字揭示**
+                               （main.js 会跳过它）。拆成 per-char 的 inline-block 后每个字各自建一层合成，
+                               祖先的 background-clip: text 就穿不过去，渐变会整行失效。
+                             ⚠ assets/motion.js 是动效层：曲线与弹簧 token 逐条取自 beUI
+                               （beui.dev/components/motion，见 docs/reference.md 的「官网」一节）。
+                               改官网动效请改 token 表，不要在组件里另写 duration / cubic-bezier。
+                             ⚠ assets/shots/ 里全是**跑起来截的**实机图，重采集步骤见
+                               docs/dev/testing.md 的「截图留档」；客户端那两张要配合冒烟的
+                               ELECTRON_CLIENT_SHOTS_DIR / ELECTRON_SMOKE_ISLAND_* 开关。
+                             ⚠ download.html 的版本清单是**当场**读 GitHub Releases 的
+                               （assets/download.js）：版本分段控件 → 一行状态 → 「装什么」分段控件
+                               （客户端 / 服务端 / 插件，**默认停在客户端**）→ 卡片。卡片是拉到数据之后
+                               才建的，建完会派发一次 ch:content，由 main.js 补挂按压反馈
+                               （新增动态内容照这个来）。两个分段控件共用同一套指示器实现。
+                               卡片排版照 ClassIsland 官网那页：图标 + 名称 + 系统要求 + 主按钮 + 变体下拉
+                               （<details>，点别处或 Esc 收起）；插件那张只有一个文件，不摆点不开的箭头。
+                               读不到时退回 <meta name="ch-version"> 并按发布命名约定拼直链 ——
+                               那个 meta 是 version.mjs 的落点之一，发版必须一起改。
+                               命名约定与 README「开始使用」表里那三个名字要对齐
+                               （ClassHelper-<版本>-x64-client-setup.exe / -client-portable.exe /
+                               -x64-server-setup.exe），它们是离线兜底链接的唯一依据。
+packages/shared/src/         types.ts / constants.ts / permissions.ts / motion.ts / utils.ts / index.ts
 packages/server/
-  prisma/schema.prisma       数据模型（14 个 model，无 enum、无 @db.*；连接串在 prisma.config.ts）
+  prisma/schema.prisma       数据模型（24 个 model，无 enum、无 @db.*；连接串在 prisma.config.ts）
-  prisma/migrations/         10 个迁移（init / time_layout / class_account / schedule_week_parity /
+  prisma/migrations/         17 个迁移（到 add_schedule_source 为止是旧模型；之后 6 个是
-                             class_term_weeks / classisland_integration / class_notification_channel /
+                             2026-10-06 的角色与权限重构：add_student_table / add_student_grade_query /
-                             homework_assign_date / push_kind / schedule_source）
+                             add_grade_level / add_classhelper_heartbeat / add_archives / add_term_weeks；
+                             最后 1 个是 2026-10-10 的 add_permission_groups_and_clients：
+                             权限组 3 表 + AppSetting + 客户端设备/命令/安装包 + AiAudit +
+                             Notification.assignDate + User.careMode）
   prisma/seed.ts             种子数据（会清空业务表后重建演示数据）
   prisma.config.ts           Prisma 7 配置：schema / migrations / seed / 连接串
-  scripts/verify-e2e.mjs     后端端到端验收（条数由脚本统计，2026-10-05 实测 190 项）
+  scripts/verify-e2e.mjs     后端端到端验收（条数由脚本统计，2026-10-06 实测 205 项）
-  scripts/verify-classisland.mjs        联动链路验收（实测 42 项）
+  scripts/verify-classisland.mjs        联动链路验收（实测 44 项）
   scripts/apply-column-migrations.cjs  旧库补列（手工覆盖 dist 部署时用）
   src/app.ts                 Express 装配（探针 → 限流 → 模块挂载 → 静态托管 → 兜底）
   src/index.ts               启动入口（自检 + HTTP + Socket.IO + 优雅退出）
@@ -86,17 +137,21 @@ packages/server/
                              password schemas session term version(读 package.json) web-static
   src/middleware/            auth validate error security
   src/realtime/              socket.ts（房间）+ bus.ts（事件总线）
-  src/modules/               15 个功能模块 + registry.ts + module.types.ts
+  src/modules/               21 个功能模块 + registry.ts + module.types.ts
-packages/web-admin/src/      api stores router layouts views(12) components(5) composables styles config.ts
+                             （含 archives 毕业归档、term 学期周次、permissions 权限组、
+                               clients 客户端心跳与远控、system 开发者模式/开机自启、ai 大模型助手）
+packages/web-admin/src/      api stores router layouts views(18) components(5) composables styles config.ts
+                             （含 ArchivesView 毕业归档、TermWeeksView 学期周次、PermissionsView 权限组、
+                               ClientsView 客户端设备、AssistantView/aiSettingsView 大模型助手）
 packages/desktop-client/
   src/main/                  主进程：index / config（含作业短语与看板偏好）/ ipc / island / tray / update / logger / smoke
   src/preload/               contextBridge 白名单桥（index.ts + island.ts，**不暴露 ipcRenderer 本体**）
   src/island/                灵动岛渲染进程：IslandApp.vue / spring.ts / squircle.ts / main.ts
-  src/renderer/              学生端渲染进程：api / cache(IndexedDB) / stores / views / island / router
+  src/renderer/              ClassHelper 班级端渲染进程：api / cache(IndexedDB) / stores / views / island / router
   src/types/desktop.d.ts     主进程 ↔ 渲染进程契约
   scripts/                   build-main / dev / smoke / dist-win
 packages/classisland-plugin/ .NET 8 插件（独立于 pnpm workspace，不参与 pnpm install）
-  manifest.yml               清单：id=classhelper.classisland.bridge / apiVersion=2.0.0.0 / version=1.1.0.0
+  manifest.yml               清单：id=classhelper.classisland.bridge / apiVersion=2.0.0.0 / version=1.2.0.0
   ClassHelper.ClassIslandPlugin.csproj（TargetFramework=net8.0）
   src/Plugin.cs              入口：读配置 → 注册提醒提供方 / 设置页 / BridgeService
   src/Models/PluginSettings.cs
@@ -104,7 +159,7 @@ packages/classisland-plugin/ .NET 8 插件（独立于 pnpm workspace，不参
                              ClassHelperNotificationProvider（把提醒显示到 ClassIsland 上）
   src/Views/BridgeSettingsPage.axaml(.cs)：Avalonia 设置页
   src/Interop/ClassHelperClient.cs：HTTP 客户端 + 与服务端逐个字段对齐的 DTO
-  scripts/                   build.mjs（编译 / 打包 .cipx）/ verify.mjs（静态契约校验，实测 68 项）
+  scripts/                   build.mjs（编译 / 打包 .cipx）/ verify.mjs（静态契约校验，实测 74 项）
 ```
 
 ---
@@ -113,8 +168,8 @@ packages/classisland-plugin/ .NET 8 插件（独立于 pnpm workspace，不参
 
 | 项               | 状态                                                                                                                                                                       |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Node             | **v24.19.0**（`D:\nodejs\node.exe`；要求 ≥ 20.19，Prisma 7 硬性要求）                                                                                                      |
+| Node             | **v22.15.0**（`D:\Node.js\node.exe`；根 `engines` 要求 ≥ 20.19，Prisma 7 的 engine 约束是 `^20.19 \|\| ^22.12 \|\| >=24.0`，v22.15 都满足）                                                  |
-| pnpm             | 11.8.0（`packageManager` 锁定 11.8.0），宿主就是上面这个 node                                                                                                              |
+| pnpm             | 11.8.0（`packageManager` 锁定 11.8.0）。本机可用的本体在 `C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs`；PATH 里那个 `pnpm.ps1` 是 DSH 桌面端的转发壳，**别绕它**（见下） |
 | npm registry     | `https://registry.npmjs.org/`（仓库内无 `.npmrc`，取全局配置）                                                                                                             |
 | 依赖             | 已装（707 包，`pnpm install` 实测 2m45s）                                                                                                                                  |
 | 后端 `.env`      | 已由 `.env.example` 生成（**gitignored**），`JWT_SECRET` 为本机随机值，`TERM_START_DATE=2026-09-07`                                                                        |
@@ -130,6 +185,43 @@ packages/classisland-plugin/ .NET 8 插件（独立于 pnpm workspace，不参
 > **旧文档里的 `F:\classisland` / `F:\data` 已失效**：本机只有 `C:` 与 `D:`，`F:` 盘不存在。
 > 另有一份旧副本在 `C:\Users\胡\Desktop\classisland`（数据在它自己的 `data/` 下，2026-09-18 用过），当前以 `D:\Classisland` 为准。
 
+#### AI 会话里跑 pnpm：别撞上 DSH 的转发壳（2026-10-11 实测）
+
+在 DSH 的 shell 工具里直接写 `pnpm xxx` 会拿到
+`pnpm.ps1 : Node.js runtime not found. Please run DeepSeek Harness Desktop to install it first.`，
+而同一台机器上人在普通终端里跑得好好的。原因与绕过办法：
+
+- PATH 里排在前面的是 **DSH 桌面端的转发壳** `C:\Users\hck16\AppData\Local\deepseek-harness\bin\pnpm.ps1`
+  （`.cmd` 同理）。它有两道会挡住的判据：① 认 `$env:DSH_NODE` / PATH 上的 `node`，
+  **但要求 `major ≥ 24` 或 `22.19+`**，本机的 `v22.15.0` 卡在门外；
+  ② 它自己的兜底 `%APPDATA%\dsh-tauri\runtime\node.exe` 与 bundled pnpm
+  `%APPDATA%\dsh-tauri\dependencies\pnpm\bin\pnpm.cjs` **本机都不存在**。
+- **正确解法是喂给这个壳两个环境变量**（它自己就认这两个覆盖开关，见 shim 第 10、52 行），
+  把 `node` 与 `pnpm` 都指到本机真实的那份，然后就**照常写 `pnpm xxx`**：
+
+  ```powershell
+  $env:DSH_NODE     = 'D:\Node.js\node.exe'
+  $env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs'
+  pnpm typecheck      # 与人在终端里跑完全等价
+  pnpm build:shared
+  ```
+
+  - `DSH_NODE` 必须是**绝对路径**：壳拿到它就不再走"发现 PATH 上的 node 再卡版本"那段。
+  - `DSH_PNPM_BIN` 是**本体 .cjs 的路径**（不是目录，也不是 `pnpm.ps1`）；壳会 `& $node $pnpmBin @args`
+    直接执行它。它同时替掉那条会失败的 `pnpmBin` 存在性检查。
+  - **`pnpm` 的嵌套调用**（`typecheck` = `build:shared && pnpm -r --no-bail typecheck`）靠这两个变量就够了：
+    子进程继承同一份环境，于是又落进同一个壳、又被同一对覆盖接住。
+  - **这三条都是踩过的坑**（同一个会话里依次试错，前两条各失败一次）：
+    - 不要用 `DSH_PNPM`，那是"用户 pnpm 的可执行路径"：壳转发给它时**仍然先过 ② 的版本门槛**，
+      而且**残留的 `DSH_PNPM` 会污染后面所有调用**——它与 `DSH_PNPM_BIN` 同时存在时壳会转发进
+      corepack 的 `pnpm.ps1`，那个壳又把它重置回不存在的 bundled 路径，于是原本能跑的
+      `typecheck` 报出 `[pnpm] pnpm not found`。要么别设，要么先 `Remove-Item Env:DSH_PNPM`。
+    - 也不要用 `node <pnpm.cjs> <script>` 绕开壳：只在**不带嵌套调用**的脚本上凑效
+      （`check:icons` / `lint` 能用），`typecheck` 这类内部还要再 `pnpm -r` 的会二次翻车。
+- 反过来说：本机 **Node v22.15.0 够用**（根 `engines` ≥ 20.19，Prisma 7 允许 `^22.12`），
+  不需要为了跑命令去装 v24；上面那条 `runtime not found` 纯粹是壳的版本门槛，不是环境不满足要求。
+
+
 ### 从零重建环境（本机实测可行的顺序）
 
 ```bash
@@ -157,13 +249,19 @@ pnpm build:classisland-plugin
 | -------------- | ------------------------------- | ------------ |
 | 管理员         | `admin`                         | `admin123`   |
 | 教师           | `teacher1` / `teacher2`         | `teacher123` |
-| 学生端班级账号 | 班级码 `G101` / `G102` / `G203` | `123456`     |
+| ClassHelper 班级端班级账号 | 班级码 `G101` / `G102` / `G203` | `123456`     |
 
 > 密码是**种子脚本里硬编码**的（`admin123` / `teacher123` / 班级 `123456`）；
 > `.env` 的 `DEFAULT_CLASS_PASSWORD` 只影响**新建**班级时的初始班级密码。
-> **学生没有个人账号**（2026-10-01 清理）：`student01…15` 只是名单记录（成绩/未交/叫人/已读按名单），
+>
-> `User.passwordHash` 为空串、不能登录，也没有任何密码接口；学生端统一用班级码 + 班级密码。
+> **学生不是账号**（2026-10-06 起由表结构保证）：`Student` 表里根本没有 `passwordHash` / `role`，
-> 班级码 `G203` 是「高二(3)班」，不是 `G103`。
+> 学号（`202601`…`202615`）只是名单记录与查询键。拿学号去 `/auth/login` 只会得到 401。
+> 教室机器统一用**班级码 + 班级密码**登录（会话主体是班级，角色 `CLASS_DEVICE`）。
+>
+> 演示数据布局：在读班级 `2026级1班`（码 `G101`）/ `2026级2班`（码 `G102`）/ `2025级3班`（码 `G203`），
+> 外加一个**已归档**的 `2023级1班`（3 名毕业生，用于验证「毕业归档」页）。
+> 任课关系刻意让**语文**由另一位老师任教，这样班主任在语文上没有编辑权 ——
+> 正好覆盖「班主任不自动拥有所有科目作业成绩编辑权」这条规则。
 
 ---
 
@@ -178,7 +276,7 @@ pnpm build:classisland-plugin
 | `pnpm build:shared`                                       | 只构建 shared（改完 `packages/shared` 必须跑）                                                        |
 | `pnpm build:desktop`                                      | 只构建客户端（esbuild 主进程/preload + Vite 渲染进程）                                                |
 | `pnpm build:classisland-plugin`                           | 构建 ClassIsland 联动插件（.NET 8；缓存/临时目录自动指到 `.cache/`）                                  |
-| `pnpm dist:classisland-plugin`                            | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/`                                            |
+| `pnpm dist:classisland-plugin`                            | 打包插件为 `.cipx` 并归集到 `releases/classisland-plugin/<版本>/`                                     |
 | `pnpm typecheck`                                          | 全仓库类型检查（含 `vue-tsc`）                                                                        |
 | `pnpm lint` / `pnpm lint:fix`                             | ESLint                                                                                                |
 | `pnpm check:icons`                                        | 图标注册表门禁（两端 build 已内联，这里可单独跑；见 §5 第 53 条）                                     |
@@ -188,16 +286,23 @@ pnpm build:classisland-plugin
 | `pnpm --filter @classhelper/server db:deploy`             | 应用已有迁移（**本机推荐**；根 scripts 里没有 `db:deploy`）                                           |
 | `pnpm db:seed` / `pnpm db:reset`                          | 写种子 / 重置并重播种子                                                                               |
 | `pnpm db:studio`                                          | Prisma Studio                                                                                         |
-| `pnpm db:switch:mysql` / `db:switch:sqlite`               | 改写 `schema.prisma` 的 provider（配合 `docs/mysql.md`）                                              |
+| `pnpm db:switch:mysql` / `db:switch:sqlite`               | 改写 `schema.prisma` 的 provider（配合 `docs/management/mysql.md`）                                              |
-| `pnpm verify:e2e`                                         | 后端端到端验收（**需后端已启动**；2026-10-05 实测 190 项全过）                                        |
+| `pnpm verify:e2e`                                         | 后端端到端验收（**需后端已启动**；2026-10-06 实测 205 项全过）                                        |
 | `pnpm verify:web`                                         | Web 管理端真实点击回归（Electron 驱动，需后端已启动且 Web 产物已构建）                                |
 | `pnpm verify:desktop`                                     | 客户端冒烟（Electron，无人工点击）                                                                    |
 | `pnpm verify:packaged`                                    | 对**打包后/已安装**的客户端 EXE 跑同一套冒烟（`--exe` 指定路径）                                      |
-| `pnpm verify:classisland`                                 | ClassIsland 联动链路（设备令牌 / 上报 / 提醒下发与回执 / 镜像契约 / 幽灵行清理；实测 42 项）          |
+| `pnpm verify:classisland`                                 | ClassIsland 联动链路（设备令牌 / 上报 / 提醒下发与回执 / 镜像契约 / 幽灵行清理；实测 44 项）          |
-| `pnpm verify:classisland-plugin`                          | 插件静态契约校验（清单一致性 / 注册完整性 / C# DTO ↔ 服务端 zod 与路由 / 已修复坑的护栏；实测 68 项） |
+| `pnpm verify:classisland-plugin`                          | 插件静态契约校验（清单一致性 / 注册完整性 / C# DTO ↔ 服务端 zod 与路由 / 已修复坑的护栏；实测 74 项） |
-| `pnpm dist:server` / `dist:win` / `dist:dir` / `dist:all` | 打包服务端安装程序 / 客户端安装包 / 免安装目录 / 全部                                                 |
+| `pnpm dist:server` / `dist:win` / `dist:all`              | 打包服务端安装程序 / 客户端安装包 / 全部                                                              |
 | `pnpm dist:server:linux`                                  | 打包 **Linux 服务端安装包**（`classhelper-server-linux-x64-<版本>.tar.gz` + `.sha256`）—— 见 §5 第 59 条 |
-| `pnpm icons`                                              | 生成应用图标（Electron 渲染 SVG → PNG/ICO）                                                           |
+| `pnpm icons`                                              | 从 `build/classhelper.png` 派生全部图标（PWA / favicon / 托盘 / 安装包 / 插件 / 官网 / 文档站 / 界面内品牌标） |
+| `pnpm version:check`                                      | 逐处列出并比对 14 个落点的版本号，不一致即 exit 1（见 §4.4「版本迭代」）                              |
+| `pnpm version:bump patch\|minor\|major`                   | **改版本号的唯一入口**：一次改写全部 14 处（含插件清单、C# 里的常量、官网上手写的三处，以及下载页的兜底值） |
+| `pnpm docs:build`                                         | 构建文档站到 `docs/_site`（需要 .NET SDK 8 + `dotnet tool install -g docfx`）                         |
+| `pnpm docs:serve`                                         | 构建文档站并起本地预览 → http://127.0.0.1:5181                                                        |
+| `pnpm docs:check`                                         | 构建文档站并把 docfx 的警告当错误（发布前用；最常见的警告是"某个 .md 没被任何 toc.yml 引用"）          |
+| `pnpm pages:build`                                        | 把官网（根）与文档站（/docs/）拼成一份 GitHub Pages 产物到 `.cache/pages`（CI 用；见 §4.4）           |
+| `pnpm dev:site`                                           | 构建文档站后起官网预览 → http://127.0.0.1:5180（文档站挂在同端口的 /docs/ 下，与线上同形）            |
 
 ### 端口
 
@@ -206,51 +311,229 @@ pnpm build:classisland-plugin
 | 4000 | 后端 REST + Socket.IO + （生产/构建后）Web 管理端静态托管 |
 | 5173 | Web 管理端开发服务器（`/api`、`/socket.io` 代理到 4000）  |
 | 5174 | 桌面客户端渲染进程开发服务器                              |
+| 5180 | 官网本地预览（`node website/serve.mjs`）                  |
+| 5181 | 文档站本地预览（`pnpm docs:serve`）                       |
 
 ### 交付产物归集
 
-打包脚本各自输出到固定目录，**归集到仓库根 `releases/` 是本仓库的人工约定**（该目录 gitignore + eslint ignore）：
+**三个打包脚本都直接输出到仓库根 `releases/<组件>/<版本>/`，没有中间输出目录**
+（该目录 gitignore + eslint ignore），人工归集这一步已经取消：
 
 ```
-release-server/                      pnpm dist:server 的输出（免安装目录 + NSIS 安装程序）
+releases/
-                                     pnpm dist:server:linux 的输出（classhelper-server-linux-x64-<版本>.tar.gz + .sha256）
+  client/<版本>/
-packages/desktop-client/release/     pnpm dist:win / dist:dir 的输出（win-unpacked + setup.exe + portable.exe）
+    安装包/      ClassHelper-<版本>-x64-setup.exe / -portable.exe（+ .blockmap）
-releases/                            本仓库约定的归集处（把上面的产物拷进 client/ server/ classisland-plugin/）
+    构建中间/    builder-*.yml、*.nsis.7z
+  server/<版本>/
+    安装包/      ClassHelper 服务端-<版本>-x64-setup.exe
+    linux-x64/   classhelper-server-linux-x64-<版本>.tar.gz + .sha256
+    构建中间/    server-installer.generated.nsi
+  classisland-plugin/<版本>/
+    安装包/      ClassHelper.ClassIslandPlugin.cipx
+    checksums.md
+  SHA256SUMS-<版本>.txt    跨组件哈希清单（人读，由发布流程维护）
 ```
 
+**`releases/` 里只放交付物，不放"解包出来的那一份"。** 这条是硬约定，2026-10-11 统一过一遍：
+
+| 曾经有的目录 | 它是什么 | 现在 |
+| --- | --- | --- |
+| `client/<版本>/免安装/` | electron-builder 的 `win-unpacked`（约 323MB） | 只在打包过程中存在，生成两个 exe 后由 `tidyArtifacts()` 删除 |
+| `server/<版本>/免安装/` | `pnpm dist:server` 组装的运行时（约 335MB） | 组装到 `.cache/server-staging/<版本>/win/`，打完 NSIS 即删 |
+| `server/<版本>/linux-x64/classhelper-server-linux-x64/` | tar.gz 的解包留档（约 265MB） | 打完 tar.gz 即删（内容与 tar 完全一样） |
+| `classisland-plugin/<版本>/免安装/` | `.cipx` 的解压副本 | 不再产出（`.cipx` 本身就是 zip，解压即用） |
+
+理由：这些都是 300MB 量级的**中间物**，而且长得跟交付物一样像"该拷走的东西" ——
+五个客户端版本 + 七个服务端版本堆下来就是 4.8GB，其中 3.4GB 是重复的中间物。
+`-portable.exe` 是自解压单文件，服务端安装程序内置 Node，**用户侧一个解包目录都不需要**。
+需要临时看一眼解包内容时，直接解压 portable，或按下面那张表的路径去 `.cache/` 找。
+（三个脚本仍会把 `构建中间/` 留在版本目录里 —— `builder-*.yml`、`*.nsis.7z`、
+`server-installer.generated.nsi`，那是每个版本几 KB 的打包脚本与元数据，**保留**。
+实测 8 个版本目录合计约 50 KB。）
+
+**Linux 包同理**：`.tar.gz` 旁边的同名解包目录（约 265MB）已不再保留，需要看内容就
+`tar -xzf` 一份到 `.cache/` 里（见 §5 第 59 条 ④ 的命名约定）。
+
+版本号取自根 `package.json`（插件用 `manifest.yml` 的前三段，与产品版本对齐）；
+重新打包只清**当前版本目录**里的产物，历史版本原样保留 —— 所以同版本多次构建留下的
+不同产物要自己改名归档（例如 `1.0.0-重构建20261005/`），别把上一次的覆盖掉。
+
 ```bash
-# 客户端：electron-builder 支持指定输出目录（dist-win.mjs 会把额外参数透传）
+pnpm dist:server          # 服务端 Windows（首次会跑一次 npm install；重试可加 --reuse-deps 跳过）
-node packages/desktop-client/scripts/dist-win.mjs -c.directories.output=<绝对路径>\releases\client
-
-# 服务端：输出路径写死在 release-server/，打完自行移进 releases/server/
-pnpm dist:server          # 首次会跑一次 npm install；重试可加 --reuse-deps 跳过
 pnpm dist:server:linux    # Linux 安装包（**必须在 Linux 上跑**，见 §5 第 59 条 ④）
-
+pnpm dist:win             # 客户端：安装包 + 便携版
-# ClassIsland 插件：构建脚本自己归集到 releases/classisland-plugin/
 pnpm dist:classisland-plugin
 ```
 
+`dist-win.mjs` 用 `--config.directories.output` 覆盖 electron-builder 自己的输出目录，打包成功后
+再把原始布局整理成上面的分层（`*.exe` → `安装包/`、`*.yml` → `构建中间/`），**最后删掉 `win-unpacked/`**；
+显式传 `-c.directories.output=<路径>` 时不再覆盖，整理以传入路径为准。
+两条别动的顺序约束：
+- **删 `win-unpacked` 必须排在整理之后**：portable 目标就是拿这份解包结果做自解压包，
+  提前删会让 `-portable.exe` 直接失败。
+- **输出目录的完整性标签要在打包前压回 Low**：上一轮收尾把它标成 Medium 之后，7za（自身带 Low）
+  读不动那些目录，pack 时报 `cannot open file ... Access is denied`（实测踩过）。
+
+**交付物的完整性标签修正（§7 第 7 条）挂在收尾链路上，别把 `tidyArtifacts` 之后的
+`normalizeIntegrityLabel(destDir)` 拆掉。**
+
+### 版本迭代（每一次 releases，不是每一次提交）
+
+> **版本号按「发布」迭代，不按「提交」迭代。** 日常的 `feat` / `fix` 提交不动版本号；
+> 只有要产出一批安装包、在 GitHub 上开一个 Release 时才走一次。
+> 理由很实际：安装包名、`.cipx`、Docker 镜像 tag、文档站顶栏的版本徽标、更新检查接口
+> 全都按版本号对齐 —— 每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
+>
+> 算一次发布：攒够一批功能 / 修好一个用户能感知的 bug / 要给别人一份新安装包。
+> 不算：改注释、改文档、重构、加测试。
+
+**同一个版本号写在 14 处（12 个文件）里**（5 份 `package.json`、`deploy/package.runtime.json`、
+两个 `docker-compose*.yml` 的镜像 tag、插件 `manifest.yml`、插件 C# 里的 `PluginVersion` 常量、
+官网首页上三处手写值，以及下载页 `<meta name="ch-version">` 那个兜底值）。
+手工改必然漏一处，而漏掉的那处**不会报错** —— 只会在某个不常走的分支上表现为"版本号对不上"
+（官网那三处的后果是首页一直挂着旧版本号；下载页那一处的后果是离线访客点到一串不存在的直链）。
+所以**改版本号的唯一入口是脚本**：
+
+```bash
+pnpm version:check              # 逐处列出并比对，不一致 exit 1（默认就是检查模式）
+pnpm version:bump patch         # 1.1.2 → 1.1.3（另有 minor / major）
+pnpm version:check              # 再确认一次
+```
+
+`scripts/version.mjs` 按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，
+不做"尽力而为"的部分改写。
+
+插件版本是**四段** `x.y.z.0`：前三段跟产品版本走，第 4 段留给"只改插件、不动产品版本"的补丁发布。
+`--bump` / `--set` 会把第 4 段归零；要单独发插件补丁就手工改清单与 `BridgeService.cs` 那两处。
+
+#### 一次完整发布的命令序列
+
+```bash
+# ① 改版本号
+pnpm version:check && pnpm version:bump patch
+
+# ② 本地体检
+pnpm lint && pnpm typecheck && pnpm check:icons && pnpm docs:check
+
+# ③ 跑验收（另开一个终端跑着 pnpm dev:server）
+pnpm verify:e2e
+pnpm verify:classisland
+pnpm verify:classisland-plugin
+pnpm build:desktop && pnpm verify:desktop
+pnpm build && pnpm verify:web
+
+# ④ 打安装包（产物落在 releases/<组件>/<版本>/）
+pnpm dist:all
+# 对**打包后的副本**复验：便携版就是自解压单文件，直接拿它当被测副本最省事
+pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe"
+
+# ⑤ 整理跨组件哈希清单 releases/SHA256SUMS-<版本>.txt（人读；Linux 那一行由 CI 合并进来）
+# ⑥ 提交并推上去
+git add -A && git commit -m "chore(release): <版本>" && git push origin master
+
+# ⑦ 开 Release（gh release create 会创建并推送 tag，从而触发 Linux 包的 CI；见下）
+gh release create v<版本> --title "v<版本>" --generate-notes
+gh release upload v<版本> \
+  releases/client/<版本>/安装包/*.exe \
+  releases/classisland-plugin/<版本>/安装包/*.cipx \
+  releases/server/<版本>/安装包/*.exe \
+  releases/SHA256SUMS-<版本>.txt --clobber
+```
+
+> **上传前把三个 EXE 改成 ASCII 名。** 构建产物是中文名（客户端 `ClassHelper-<版本>-x64-setup.exe`
+> / `-x64-portable.exe`，服务端 `ClassHelper 服务端-<版本>-x64-setup.exe`），而 Release 上的名字
+> 是给别人看、要贴进脚本的 —— 一律用 ASCII 形式，与构建产物一一对应（内容相同、sha256 相同）：
+>
+> | 构建产物                    | Release 上的名字                            |
+> | --------------------------- | ------------------------------------------- |
+> | `<客户端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-client-setup.exe`    |
+> | `<客户端>-x64-portable.exe` | `ClassHelper-<版本>-x64-client-portable.exe` |
+> | `<服务端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-server-setup.exe`    |
+>
+> **这三个名字是外部契约**：README 的「开始使用」表、官网下载页的离线兜底直链都按它们拼 ——
+> 改名要三处一起改。上传前改名比上传后 `gh release edit` 省事：
+>
+> ```bash
+> V=<版本>
+> mkdir -p .cache/release-staging
+> cp "releases/client/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-client-setup.exe"
+> cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/ClassHelper-$V-x64-client-portable.exe"
+> cp "releases/server/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe"
+> cp "releases/classisland-plugin/$V/安装包/ClassHelper.ClassIslandPlugin.cipx" .cache/release-staging/
+> gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber
+> ```
+
+**第 ⑦ 步的顺序有讲究**：`.github/workflows/release-linux-server.yml` 由 tag 推送触发，
+它在**最后一步**才把自己的那一行**合并进** Release 上已有的 `SHA256SUMS-<版本>.txt`
+（`grep -v` 掉旧的 linux 行再追加，Windows / 插件那几行原样保留）。
+所以本地那份清单必须**先上传**；万一手速反了，重跑一次就能补回来：
+
+```bash
+gh workflow run release-linux-server.yml -f tag=v<版本> -f attach=true
+```
+
+**Linux 包只能在 Linux 上构建**（`@libsql/linux-x64-gnu` 这类依赖是平台相关的），
+所以 `pnpm dist:all` 里没有它，必须走 CI（见 §5 第 59 条）。
+
+**已发布的版本号不要复用**：客户端把它记进「忽略此版本」，两端各有 30 分钟缓存 ——
+同号换内容会让「检查更新」永久失灵。要修就 `pnpm version:bump patch` 发新号。
+
+#### 官网与文档站怎么发布
+
+**不用做任何事。** 推 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
+`package.json` 变过，`.github/workflows/pages.yml` 就会构建并部署到 GitHub Pages：
+
+```
+https://lovechengke.github.io/ClassHelper/          ← 官网（website/，纯静态无构建）
+https://lovechengke.github.io/ClassHelper/download.html   ← 下载页（同一棵树里的一个页面）
+https://lovechengke.github.io/ClassHelper/docs/     ← 文档站（docfx 构建 docs/）
+```
+
+> **一个仓库在 GitHub Pages 上只有一个站点**，所以两者是拼在一起发的
+> （`scripts/build-pages.mjs` 把 `website/` 放到根、`docs/_site/` 放到 `docs/` 下）。
+> 官网在根是因为产品页的地址最短最好分享；文档站多一层路径没有代价。
+> 改这个布局要同时动三处：`scripts/build-pages.mjs`、本 workflow 里的 `DOCS_BASE`，
+> 以及文档站模板 `docs/templates/classhelper/layout/_master.tmpl` 里那个 `{{_rel}}../` 的「官网」入口。
+
+- 顶栏的版本徽标取自根 `package.json`（`docs/build.mjs` 用 `--metadata _chVersion=…` 注入），
+  **不要在文档里再写一份版本号**；官网首页那排芯片里的 `v1.1.2` 与下载页的
+  `<meta name="ch-version">` 是手写的，发版时要一起改（都在 `pnpm version:bump` 的 14 个落点里）；
+- 下载页的版本清单**不在站点里存副本**：每次打开都由 `assets/download.js` 当场读
+  GitHub Releases（匿名接口 60 次/小时/IP），读不到才退回上面那个 meta 按发布命名约定拼直链。
+  所以发完 Release 不用重新部署这一页，但**兜底值必须跟着发版改**；
+- 首次启用需要在仓库 Settings → Pages 把 Source 选成「GitHub Actions」（只需一次）；
+- 404 页的 `<base>` 由 `scripts/build-pages.mjs`（本地 `./`）与 workflow（CI 传 `/<仓库名>/`）注入 ——
+  项目页挂在 `/<仓库名>/` 子路径下，而浏览器是按**被请求的路径**解析 404 页里的相对链接的；
+- 本地预览：`pnpm dev:site`（官网在 http://127.0.0.1:5180，文档站挂在同一个端口的 `/docs/` 下，
+  与线上同形）；只想单独看文档站用 `pnpm docs:serve`。
+
 ---
 
 ## 5. 架构硬约定（改代码前必须知道）
 
 1. **模块注册表是唯一入口。** 服务端每个功能是 `src/modules/<name>/`（`*.module.ts` 路由、
-   `*.schemas.ts` zod 校验、`*.service.ts` 业务）。当前 15 个：`auth / classes / courses / schedules /
+   `*.schemas.ts` zod 校验、`*.service.ts` 业务）。当前 21 个：`auth / classes / courses / schedules /
-homeworks / notifications / calls / imports / integrations / grades / students / teachers / dashboard /
+homeworks / notifications / calls / imports / integrations / grades / students / teachers / archives /
-database / update`。
+term / dashboard / database / update / permissions / clients / system`。
    新增/下线功能**只改 `src/modules/registry.ts`**（加一行 / 改 `enabled: false`），不要动 `app.ts`。
 2. **统一响应与校验。** 用 `src/lib/http.ts` 的 `sendOk / sendCreated / …` 返回，用
    `middleware/validate.ts` 挂 zod schema；错误交给 `middleware/error.ts`，不要各写一套。
 3. **鉴权 = JWT + RBAC + 班级内角色。** 路由级用 `requireRole('ADMIN', 'TEACHER')`；班级维度用
-   `@classhelper/shared` 的 `resolveClassRole` → `ADMIN / HEAD（班主任）/ SUBJECT（科任）/ STUDENT / NONE`，
+   `@classhelper/shared` 的 `resolveClassRole` → `ADMIN / HEAD（班主任）/ SUBJECT（科任）/
-   权限判 `canManageSchedule` / `canPublishContent` / `canManageRoster` / `canManageGrades` 等
+   CLASS_DEVICE（班级端）/ NONE`，权限判 `canManageSchedule` / `canPublishNotification` /
-   （人类可读矩阵是 `PERMISSION_MATRIX`，README 直接引用它），**不要在页面里另写一套规则**。
+   `canManageRoster` / `canManageGrades` / `canManageSubjectContent` 等
-4. **学生端主体是「班级账号」。** 班级码 + 班级密码登录后，`classId` 即身份；该设备的「已读 / 完成」
+   （人类可读矩阵是 `PERMISSION_MATRIX`），**不要在页面里另写一套规则**。
-   代全班操作，个人学生登录已停用。API 里对此有专门分支，别按个人账号语义改。
+4. **学生不是账号 —— 这是表结构保证的，别在代码里"兼容"学生账号。**
-5. **实时推送只走房间。** 服务端 `src/realtime/`（`SOCKET_ROOMS`：`class:{classId}`、`user:{id}`、
+   `Student` 表没有 `passwordHash` / `role`，学生不能登录、没有任何密码接口；
-   `teacher:{id}`、`role:{role}`、`students`、`teachers`；`bus.ts` 事件总线），客户端
+   学号（`Student.studentNo`）是学生的唯一标识与查询键（名单 / 成绩 / 作业提交 / 导入导出全用它）。
-   `renderer/stores/realtime.ts` 订阅。**新增实时事件要同时改三处**：服务端 bus/socket、Web 端订阅、
+   曾经那套"`User.role='STUDENT'` + 空串密码占位 + 登录前判 role 再 403"的写法在 2026-10-06
-   客户端订阅（灵动岛也依赖它）。事件名一律取自共享常量 `SOCKET_EVENTS`，不要手写字符串。
+   整体删除，**不要再加回来**：任何 `role === 'STUDENT'` 的分支都是回归。
+5. **任课关系的唯一来源是 `Course`（班级 + 科目 + 教师）。** 没有第二张任课表
+   （历史上那张无科目的 `ClassTeacher` 已删除）。作业与成绩的写权限必须走
+   **`assertCanManageSubjectContent(user, classId, courseId, action, { allowClassDevice })`**：
+   挂了科目就只能由该科的任课老师改，没挂科目则归班主任 / 管理员；
+   班级端只有**作业**可以写（成绩不给）。**新增"发布内容"类入口必须复用它**，否则又会出现
+   "某个页面能改别人的科目"。
 6. **共享契约只在 `packages/shared`。** 三端都 `import ... from '@classhelper/shared'`；它产出 `dist`，
    改完要 `pnpm build:shared`（或跑着 `pnpm dev` 的 watch）。类型/常量**不要在两端各写一份**。
 7. **数据模型跨库通用。** `schema.prisma` 只用 String / Int / Float / Boolean / DateTime，不用 Prisma enum、
@@ -528,6 +811,17 @@ database / update`。
     主题状态在 `stores/ui.ts`（持久化到主进程配置 `theme`），主窗口 `backgroundColor` 也按主题设置
     （深色下若仍用浅色底会"先白后黑"闪一下）。
 
+    **两端都有深色主题，机制一致**（Web 管理端 2026-10-06 补齐）：`html.dark` + element-plus 的
+    `dark/css-vars.css` + 两端各自的 `stores/ui.ts`。语义色令牌是
+    `--ch-surface` / `--ch-surface-alt` / `--ch-surface-sunken` / `--ch-surface-hover` 与
+    `--ch-text` / `-secondary` / `-muted` / `-placeholder`；**`html.dark` 只覆盖颜色，
+    绝不覆盖圆角与动效令牌** —— 两套主题的几何必须完全一致，否则切换时会看到布局跳一下。
+    Web 端还要一并同步 `<meta name="theme-color">` 与 `color-scheme`（后者管原生控件：
+    滚动条、日期选择器弹层 —— 只改 CSS 变量的话它们仍是浅色）。
+    默认**跟随系统**（`prefers-color-scheme`，系统改了就跟着变）；用户手动点过之后以用户为准。
+    切换入口两端都在顶栏，都走 `useThemeReveal()`（见第 61 条）。
+    改令牌时只改值 —— **不要对样式表跑批量 sed**，理由见第 61 条末尾。
+
 47. **数据库管理模块（`/api/database/*`，仅 ADMIN）——改它之前必须知道的四件事**：
     ① **一切都建立在 `lib/snapshot.ts` 的 JSON 快照上**（备份 / 导入导出 / 跨库迁移共用一种格式，
     14 张表按拓扑序导出、恢复时临时关外键检查、分批 `createMany`）。恢复时**必须**先关外键检查：
@@ -742,7 +1036,20 @@ database / update`。
     schema engine，CLI 运行期按平台扫 `@prisma/engines/schema-engine-debian-openssl-3.0.x` 这类路径，
     而交叉包里只有 `schema-engine-windows.exe`。交叉构建会写入 `.cross-built` 标记，
     `classhelper doctor` 据此提示（别改成静默），`upgrade` 替换程序文件时会按新包有无该标记来增删。
-    正式产物仍走 CI。
+    正式产物仍走 CI。**交叉构建时 `tar` 还有两个 Windows 专有坑**（`packLinuxTarball()`）：
+    `-f F:\...tar.gz` 里的**盘符冒号**会被 GNU tar 当成 `主机:路径` 的远程归档写法，报
+    `tar (child): Cannot connect to F: resolve failed`、退出码 2 —— 现象很误导：包已经整套铺好、
+    就差最后打 tar 那一步失败。反斜杠还会被当成转义符。所以那一步把路径统一转成**正斜杠**
+    并加 `--force-local`。该选项在 Linux 上无害（本地路径本来就该走本地分支），因此无条件加上、
+    不做平台分支 —— **Linux 上路径没有盘符，这个坑在 CI 与真机上永远复现不了**，只在交叉构建时现形。
+
+    还有一条**两边都会踩**的：**交付目录必须自己 `mkdir`，别指望谁来顺带创建它。**
+    `releases/server/<版本>/linux-x64/` 曾经是 staging（`linux-x64/classhelper-server-linux-x64/`）的父目录，
+    2026-10-11 把 staging 挪进 `.cache/server-staging/` 之后它就没有创建者了，`tar -czf <那里>/…`
+    直接报 `tar (child): …tar.gz: Cannot open: No such file or directory`、退出码 2 ——
+    **Windows 侧踩不到**（`buildInstaller()` 里有 `mkdirSync(INSTALLER_DIR)`），本地 `pnpm dist:server`
+    永远绿的，只有 CI 上那一次 `pnpm dist:server:linux` 才会红（v1.3.0 实测，run 38109984623）。
+    现在 `packLinuxTarball()` 开头显式建目录，别再把这句删掉。
 
     ⑤ **密码永远走 stdin，命令行一律不接受密码；调用服务端模块的工具必须压掉它的 stdout 噪声。**
     `classhelper password` 用 `read -s` 优先读 `/dev/tty`、无 tty 回退 stdin（这样既能交互，
@@ -766,8 +1073,240 @@ database / update`。
     `STAGE_DIR` 而不是 `echo` 返回路径）这两类是实打实的 bug；`die` 要先 `trap - ERR` 再退出，
     免得 ERR 钩子再补一句误导的"第 N 行执行失败"。
 
+60. **安全响应头里的 `upgrade-insecure-requests` 与 HSTS 只能在 HTTPS 请求下下发**（`middleware/security.ts`
+    的 `buildHelmet(httpsRequest)`，按 `req.secure` 二选一；TRUST_PROXY 开启时 `req.secure` 已含
+    `x-forwarded-proto` 判断）。helmet 的默认 CSP **自带 `upgrade-insecure-requests`**，而安装器的
+    默认形态是 `http://IP:端口` 直连（无 TLS）：这条指令会把页面**子资源**请求全部改写成 https 发出去，
+    服务器没有 TLS 监听，全部连接失败 —— 表现为「管理端一片空白、标签页标题正常」
+    （2026-10-05 用户在 98.142.241.144 实测踩到；`/healthz`、登录 API 都正常，纯浏览器侧的资产全灭）。
+    HSTS 在明文响应里按规范会被浏览器忽略，但 CSP 指令没有这层豁免，所以两者都要跟着 https 走。
+    开发时一直用 localhost（浏览器视为安全上下文、不做改写），所以这个坑在本地永远不复现，
+    只有真机 http 直连部署才炸 —— 别因为"本地好好的"就把条件判断摘掉。
+
+61. **动效层：令牌在 `packages/shared/src/motion.ts`，两端各一份组合式函数。**
+    移植自 [beUI](https://beui.dev) 的 `lib/ease.ts`（它的组件是 React，用不了；动效语言与框架无关）。
+    三组缓动 + 六组具名弹簧（`SPRING_PRESS/SWAP/PANEL/LAYOUT/MOUSE/GLIDE`）。
+
+    - **令牌必须是纯常量**：`packages/shared` 被后端一起消费，它的 tsconfig 是 `lib: ["ES2023"]`
+      （不含 DOM），所以 `motion.ts` 里不碰 `document` / `window` / vue。DOM 注入与 Vue 组合式函数
+      在两端各自的 `composables/motion.ts`（两端各一份，与 `ScoreBarChart.vue` 同一做法）。
+    - **CSS 变量在 `app.mount()` 之前由 JS 注入 `:root`**（两端 `main.ts` 调 `applyMotionTokens()`）。
+      CSS 里只引用 `var(--ch-spring-*)`，**不要抄数值** —— 抄了必漂。
+    - **弹簧靠数值积分生成 CSS `linear()`**，于是弹簧可以纯 CSS 驱动，不需要每组件一个 rAF 循环。
+      算落定时间**不能用包络公式 `6/(ζ·ω0)`**：它只对欠阻尼成立，过阻尼要用较慢的实极点
+      `ω0(ζ−√(ζ²−1))`，否则曲线会被截断在 0.87/0.95 上、元素永远差一截没到位（实测踩过）。
+    - **`--ch-spring-X` 与 `--ch-spring-X-dur` 必须成对用**：`linear()` 是把 [0,1] 进度重映射，
+      时长给短了等于把整条曲线等比压缩 —— 形状还在，但已经不是那组参数的手感了。
+    - `linear()` 的进度值可以 >1（过冲）：只能用在不越界无害的属性上。**别用在 `opacity`**。
+
+    **四条硬约束（都对应实测过的坑）**：
+
+    - **路由层不要包 `<transition>`，尤其不要 `mode="out-in"`。** 它把"旧组件卸载、新组件挂载"推迟到
+      退场动画结束（90ms 起），后果有两个：① 点菜单后有一小段时间页面上还是上一页，`ui-smoke` 的多条
+      用例（"pathname 一变就找新页面的元素"）会整片判红 —— 实测一次掉 9 项；② 退场判定依赖
+      `animationend`，**窗口被遮挡时 Chromium 冻结 CSS 动画**（实测 `document.timeline` 1.2 秒推进 0ms），
+      事件永不触发 ⇒ 新页面永远不挂载，整个应用卡死在第一页。页面切换的动效改用 `.page > *` 错峰入场，
+      那是随组件挂载**同步**触发的。
+    - **Vue 的 `<transition>` 一律显式给 `:duration`。** 同上，靠 `animationend` 判断的写法在窗口不可见时
+      会永远停住（`UrgentClassWarning` 那块铺满全屏的遮罩尤其致命：不卸载就再也点不动）。
+    - **`position: fixed` 的整屏层、以及"自己量几何再据此设尺寸"的元素，不要叠位移类动画。**
+      `.page > *` 错峰入场排除了 `.el-overlay`（Element Plus 的 `el-dialog` 默认 `append-to-body=false`，
+      声明在视图里的弹窗其遮罩就是 `.page` 的直接子元素）、`.el-loading-mask`、`.board-host`
+      （客户端的作业看板按"刚好铺满"算 `transform: scale()`，下移 6px 就溢出屏幕）。
+      判定方法是 `getBoundingClientRect()` **包含** transform，而 `clientHeight` / `offsetHeight` 不含。
+    - **弹窗面板的动画要挂在 `.el-dialog` 上，不要挂在 `.el-overlay-dialog`（居中容器）上。**
+      Element Plus 的 `@opened` 按**根元素**（`.el-overlay`，只有 200ms 淡入）的动画结束触发，
+      而外层容器上的弹簧要跑 463ms —— 任何在 `@opened` 里量容器尺寸做自适应的弹窗都会量到
+      "还带着 `scale(0.97)` 的缩小版"，被 `minScale` 兜住后反而超出屏幕（作业看板实测 +7px）。
+      挂 `.el-dialog` 还有个好处：全屏弹窗能用 `is-fullscreen` 精确豁免（全屏表面本来也不该缩放入场）。
+
+    **两条容易踩的实现细节**：
+    - 客户端的 `--nav-ease` **刻意保留** Material 的 `cubic-bezier(.4, 0, .2, 1)`，没有统一成 EASE_OUT。
+      EASE_OUT 起步极快，宽度掉到 80px 以下时动画才走了约 35%，而 `layoutChromeSelfTest` 一到读宽度
+      判据就往下走、立刻量图标中心，此刻内边距还在动 ⇒ 6 个分组子项偏 2.3px 判红。想换曲线得连那条断言
+      一起重新商量。（该断言的宽度判据已从 `≤80` 收紧到 `≤65`，即"真正收拢到稳态"再量 —— 折叠目标宽度是 64px。）
+    - **Vue 的 scoped `<style>` 可以引用全局 `@keyframes`**（只有同一个 scoped 块里**定义**的才会被改名）。
+      实测：`.login-card` 的 `animation: ch-panel-in …` 原样输出且生效。但 `mode="out-in"` 之类的
+      transition 类名仍在 scoped 块里写、元素也带 `data-v`，能正常命中。
+    - `el-aside` / `el-menu` 这些是**组件**不是原生标签：模板 ref 拿到的是组件实例，
+      `.querySelector` 不是函数（会被 `app.config.errorHandler` 吞成一行中文异常，界面看着毫无异样）。
+      用 `$el`，或直接 `document.querySelector`（客户端的主侧栏只有一个，后者更直白）。
+    - 降低动态效果：两端 `styles/index.css` 各有一个 `@media (prefers-reduced-motion: reduce)` 全局块，
+      把动画压到 1ms（不是删掉，`transition: none` 会让依赖 transitionend 的逻辑失灵）。
+      **加载指示旋要豁免**（改为放慢而非停）—— 停掉会让界面看起来像卡死。
+
+    **灵动岛：只移植曲线，不移植弹簧。**
+    岛的形变由主进程缓动窗口尺寸（`src/main/island.ts`），而冒烟断言「展开过程不震动」
+    「收回过程不抖动」**逐帧采样岛体几何**并要求单调 —— 任何带过冲的弹簧都会直接判红。
+    所以岛用 `--ch-ease-out` 这类单调曲线，壳的物理仍归它自己的 `island/spring.ts`（WinIsland 移植），
+    不要拿 beUI 的 `SPRING_*` 去换。
+    `IslandApp.vue` 是**另一个渲染进程**，不共享主窗口的 `:root`：令牌要在
+    `src/island/main.ts` 里**再注入一次**（`applyMotionTokens()`）。漏了的话 `var(--ch-ease-out)`
+    解析为空、**整条 `transition` 简写作废**，反而比改造前更差（完全没有过渡）。
+    另外岛的 `:hover` 规则必须关在 `@media (hover: hover) and (pointer: fine)` 里 ——
+    教室触摸屏的"幽灵 hover"会让点过「知道了」的按钮永远高亮。
+
+    **深色主题的语义色令牌：只改值，不要对样式表跑批量 sed。**
+    `--ch-text: #303133` 被"把 #303133 换成 var(--ch-text)"的批量替换一过，就变成
+    `--ch-text: var(--ch-text)` —— **自引用**会让整条自定义属性失效，`getPropertyValue` 返回空串，
+    全站文字颜色静默回落成继承色（浅色下看着"还行"，深色下就露馅）。实测踩过。
+
+62. **图标：全项目只有一个图形源 `build/classhelper.{png,ico}`，其余一律由 `pnpm icons` 派生。**
+    这两个文件是**设计导出、手工放入**的，`pnpm icons` 只读不写 —— 要换图标就换这两个文件，
+    别去改脚本。派生清单写在 `scripts/icons/render.cjs` 顶部的注释里，覆盖：Web 端 PWA 三件套
+    （`icon-192` / `icon-512` / `apple-touch-icon`）、`favicon`（png + svg 各一份）、
+    ClassIsland 插件 `icon.png`、客户端 `build/{classhelper,icon}.{png,ico}`、
+    托盘 `public/tray.png`、官网 `assets/icon.png`，以及**两端界面内的品牌标** `public/logo.png`。
+
+    **四条硬约束（都对应实测踩过的坑）**：
+
+    - **ICO 原样透传，不要重新生成。** `classhelper.ico` 里 9 个尺寸
+      （16/24/32/48/64/72/96/128/256）是设计工具**逐尺寸栅格化**的，比把那张 345×339 的位图
+      缩下去干净得多；脚本只解析它的目录项做日志与校验，然后把整份复制给客户端与 electron-builder。
+    - **`packages/desktop-client/build/icon.{png,ico}` 别删。** 它们是与 `classhelper.*` 同步的副本，
+      而名字是 **electron-builder 的兜底约定**：`convertIcon()` 的候选表是
+      `['<win.icon>', 'icon.ico', 'icons', 'icon', 'icon.png', 'icon.svg', 'icon.icns']`，
+      依次在 `[buildResources, projectDir]` 两个根下 stat，**第一个命中的就赢**。
+      `win.icon` 现在显式写着 `build/classhelper.ico`（实测 `isFallback = false`，
+      解析到 `packages/desktop-client/build/classhelper.ico`），但那条配置一旦被拿掉，
+      就会**静默**回落到 `icon.ico` —— 副本同步着，回落也还是新图标。
+    - **界面内的品牌标用 `<img>`，且两端 URL 的写法必须不同。** Web 端写根绝对路径 `/logo.png`
+      （永远从源站根提供服务；前端是 history 路由，相对路径在 `/classes/1` 这类嵌套路由下会解析错）。
+      客户端**必须经 `BRAND_LOGO_URL`（`src/renderer/config.ts`）绑定给 `:src`** ——
+      字面量的相对 `src` 会被 Vite 当成模块导入去解析
+      （`Rolldown failed to resolve import "logo.png" from "LoginView.vue"`，构建直接失败），
+      而根绝对路径在 `file://` 加载的打包形态下会解析到**盘符根目录**。
+    - **`School` 字形在两端 `icons.ts` 里的注册不要删**：它仍是「班级管理」菜单项与
+      「班级码」输入框前缀的字段图标，只是不再是品牌标。品牌标换成真图标后，
+      `.brand-logo` 的 `background` / `color` / `border-radius` / `overflow` 都要撤掉 ——
+      圆角与透明边角本来就在图里，再叠一层会出现双重圆角。
+
+    跑完 `pnpm icons` 记得把**生成出来的那些图**一起提交（脚本会比对内容，没变动的不会重写）。
+    源图 345×339 不是正方形，脚本按等比缩放居中补透明（补边约 1.7%，肉眼不可见）；
+    512 那两档是**放大**，会略软 —— 那是源图分辨率的上限，要更清晰只能换更大的设计导出。
+
 ---
 
+63. **实时推送只走房间，而且没有"学生房间"。** 服务端 `src/realtime/`（`SOCKET_ROOMS`：
+    `class:{classId}`、**`session:{id}`**、`teacher:{id}`、`role:{role}`、`students`、`teachers`；
+    `bus.ts` 事件总线），客户端 `renderer/stores/realtime.ts` 订阅。
+    `session:{id}` 里的 id 是**会话主体**：教师/管理员是自己的账号 id，
+    ClassHelper 班级端是**班级 id**（见 `socket.ts` 的握手逻辑）—— 「叫人」这类定向消息就发到它。
+    **2026-10-06 起把 `user:{id}` 改名成了 `session:{id}` 并且不再有学生房间**：学生不是账号，
+    没有任何客户端会订阅它。**新增实时事件要同时改三处**：服务端 bus/socket、Web 端订阅、
+    客户端订阅（灵动岛也依赖它）。事件名一律取自共享常量 `SOCKET_EVENTS`，不要手写字符串。
+
+64. **ClassHelper 班级端主体是「班级」，`classId` 即身份。** 班级码 + 班级密码登录后角色是
+    `CLASS_DEVICE`，该设备的「作业完成 / 通知已读」由 `lib/session.ts` 的 `resolvePersonalIds()`
+    展开成**全班学生 id** 后再写（所以教师端的"完成人数 / 已读人数"统计依然准确）。
+    写 `createdBy` 之类的字段前要把它换成该班班主任 —— 班级端的 `sub` 是**班级 id**，
+    直接写会撞 `User` 外键（见 §5 第 20 条「教室机器能录入作业」）。
+    班级端的成绩查询受 `Class.studentGradeQueryEnabled` 这个**按班开关**控制（默认开启）。
+
+65. **课表同步的主方向是「服务端 → 教室」，教室不再自动回传。**
+    `IntegrationDevice.mirrorScheduleToClassIsland` 默认 **true**（服务端改完课表自动下发），
+    `syncScheduleToServer` 默认 **false**。要取教室的课表走
+    `POST /integrations/devices/:id/request-schedule` —— 它只置一个待办
+    （`requestScheduleReport`），插件在下一次心跳看到就把课表推上来并清除标记。
+    Web 端点击前**必须弹警告**（会覆盖 / 合并本班课表）。
+    插件侧对应 `ReportSettingsDto.scheduleRequested` + `ReportAsync(..., forceSchedule: true)`，
+    且补发发生在**镜像之前**（顺序反了会把刚拿到的课表盖掉）——
+    `verify:classisland-plugin` 有 6 条护栏盯着这段契约，别删。
+
+66. **学期周次可以逐周配，别再用"开学日期 + 每周七天"硬推。**
+    `TermWeek`（`classId = ''` 表示全校默认）存每一周的 `startDate`/`endDate`；
+    `lib/term.ts` 的 `loadTermContext(classId)` 负责把"班级覆盖 → 全校默认 → 纯线性"三级回落算出来，
+    `resolveCurrentWeek(now, context)` 优先按区间判定。
+    **调休 / 周末补课 / 错峰开学会让线性推算整体错位一周以上**，而课表、作业、成绩都按周次组织。
+    改周次（`PUT /api/term`、`POST /api/term/auto`）之后要 `notifyScheduleChanged()`，
+    让变更随课表下发给教室的 ClassHelper 班级端。
+    联网拉取调休建议（`GET /api/term/holidays`）**只给建议、不改数据**，且
+    **机房无外网时 `ok:false` 是正常结果**，失败结果同样进缓存（否则断网点一次要白等一个超时）。
+
+67. **功能级准入看「权限键」，角色只是默认模板（2026-10 权限组重构）。**
+    路由上挂 `requirePermission('…')`（AND）/ `requireAnyPermission(…)`，键目录在
+    `packages/shared/src/permissions.ts`（`PERMISSION_KEYS` 39 键 / `PERMISSION_LABELS` /
+    `PERMISSION_CATEGORIES` / `PERMISSION_DEFAULT_ROLES` / `ROLE_DEFAULT_PERMISSIONS`）。
+    有效权限由 `packages/server/src/lib/permissions.ts` 的 `loadEffectivePermissions()` 算：
+    ADMIN=全集且 `permission:manage`/`system:manage` 不可剥夺；CLASS_DEVICE=空集（不受分组影响）；
+    有分组=并集（**可以比角色默认更少**，这就是"能收权"）；无分组=角色默认模板。
+    它**每请求实时查库**（不缓存），所以改完分组立刻生效。
+    **不可松的边界**：权限组只管功能/路由级；班级维度的科目规则（`assertCanManageSubjectContent`）
+    故意不可被权限组覆盖，否则「班主任布置别人科目作业」的老 bug 会从新路长回来。
+    Web 端门控是「`meta.roles` 粗筛 + `meta.permission` 细筛」（`beforeEach` 里
+    `await auth.ensurePermissions()` 再 `auth.can(key)`，不通过 fail-closed），
+    权限矩阵与生效规则见 `docs/dev/permissions.md`。
+
+68. **客户端设备身份是 `deviceKey`，它不接受外部改写。** 客户端配置里的 `deviceKey` 是首次启动生成的
+    UUID，服务端按它 upsert `ClientDevice`；`saveConfig()` **拒绝**渲染进程改写它（改了就等于换一台机器），
+    退出登录走 `clearConfig()` 时也**保留**它（连同 `autoLaunch`/`autoUpdate`/`developerMode`/`careMode`
+    与待安装的更新记录）。上报走「客户端定时拉」而不是服务端推：
+    `POST /api/clients/heartbeat`（30 秒一次，首报延迟 3 秒），响应里带回「目标版本 + 一条待执行命令」；
+    在线判定窗口 `CLIENT_ONLINE_WINDOW_MS`=90 秒。三条边界：**没有 token 就不上报**（未登录静默跳过）、
+    **401/403 退避 5 分钟**、**冒烟默认不上报**（要验这条链路才设 `ELECTRON_SMOKE_CLIENT_AGENT=1`）。
+
+69. **远控命令要两端各确认一次，而且客户端**必须**回执。** 服务端 `POST /api/clients/commands` 只对
+    `remote:control`（默认仅 ADMIN）开放，动作限 `shutdown`/`restart`/`logoff`/`lock`，有效期
+    `CLIENT_COMMAND_EXPIRE_MS`=10 分钟；客户端收到后弹**默认选中「取消」**的对话框（60 秒未确认按取消处理），
+    执行只支持 Windows（`shutdown.exe /s|/r /t 0`、`/l`、`rundll32 user32.dll,LockWorkStation`），
+    然后 `POST /api/clients/commands/:id/ack`（body 带 `deviceKey`，服务端据此校验归属，重复回执幂等）。
+    同一台机器上**同一条命令只弹一次**（内存去重），回执失败只暂存重试、不重复弹窗。
+
+70. **客户端安装包由服务端下载并缓存，教室机不直连 GitHub。** 原因有两条：Web 端 CSP
+    （`connect-src 'self' ws wss …`）不允许浏览器直连 GitHub，而教室机常常根本没有外网。
+    所以 `POST /api/update/client/fetch` 由**服务端**下载到 `<serverRoot>/../data/client-releases/<版本>/`
+    并登记 sha256+size，`GET /api/update/client/download/:version` **故意不挂权限键**（班级端要能下载）。
+    版本号一律先用 `^[0-9A-Za-z._-]+$` 校验（防路径穿越）。客户端自动安装的三条护栏：
+    **没有 sha256 就拒收**、**必须等到"非上课 + 主窗口隐藏满 `CLIENT_UPDATE_IDLE_MS`（5 分钟）"**、
+    冒烟模式**永不安装**。
+
+71. **通知与作业一样按「所属日期」归档，批量发布在服务端做。** `Notification.assignDate` 与
+    `Homework.assignDate` 同口径（`dayKeyLocal()`，禁止 UTC 切片）；列表支持 `date`/`from`/`to`/`createdBy`，
+    另有 `GET /notifications/days` 与 `/notifications/creators` 供"按天/按发布人归档"的界面用。
+    批量走 `POST /notifications/bulk` 与 `POST /homeworks/bulk`：**单班失败不影响整批**
+    （逐班返回 `BulkPublishClassResult`），作业的 `subjectName` 跨班**按名匹配**已有课程，
+    **找不到就整班记失败，绝不自动建课**（自动建课会把创建者写成任课老师，等于越权改任教关系）。
+
+72. **大模型助手只解析、不落库。** `POST /api/ai/interpret` 返回的是**待确认**的结构化动作
+    （`create_homework` / `create_notification` / `call_student` / `unknown` + `params` + `preview`），
+    真正落库由前端确认后调**既有**端点 —— 于是权限断言、上课时段紧急通知保护、ClassIsland 推送全部自动复用。
+    模型给的 `params` **必须用与手动入口同一份 zod 再校验一次**（模型输出不可信）。
+    API Key 用 `packages/server/src/lib/secrets.ts` 的 AES-256-GCM（密钥由 `JWT_SECRET` 经 scrypt 派生）
+    加密后存 `AppSetting`，**只进不出**（GET 只回 `hasApiKey` 与尾 4 位）。
+    `provider='mock'` 是离线确定性解析，**自动化验收一律用它**（§5 第 52 条：不许访问外网）；
+    每次解析写一条 `AiAudit`（不含密钥）。
+
+73. **开发者模式是服务端的一个内存缓存开关。** 真值存在 `AppSetting`（键 `system.developerMode`），
+    但热路径（错误中间件）不可能每请求查库，所以 `packages/server/src/lib/settings.ts` 用
+    `isDeveloperMode()` / `refreshDeveloperMode()` 缓存它：**启动时刷一次、管理员改设置时更新**。
+    开启后只多做一件事：500 的 `ApiError` 在 `details` 里附 `error.stack`（见 `middleware/error.ts`）。
+    `GET /api/system/diagnostics` **绝不回传任何密钥**。开关与诊断接口都要求 `system:manage`。
+
+74. **开机自启动必须"可选择 + 运行期可改"。** 安装器只负责**默认值**：
+    Windows 在 `scripts/nsis/server-installer.nsi` 里是**组件页上一个独立的 Section**（默认勾选），
+    Linux 在 `deploy/install.sh`；装完之后一律走 `GET/PUT /api/system/autostart`
+    （Windows 改 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`，
+    Linux `systemctl enable/disable classhelper`）。**非安装形态（开发机 / 免安装目录 / 容器）必须返回
+    `supported:false` 并说明原因** —— 别往开发机的注册表里写自启项。
+
+75. **服务端菜单回缩与关怀模式：折叠只用 CSS，放大只动字号。** 侧栏折叠**不要用 `el-menu` 的
+    `:collapse`**（它会重建 DOM，与桌面客户端侧栏踩过的坑同源），而是 CSS 收拢宽度 + 折叠态文字
+    「既无宽度又不透明」；覆盖 Element Plus 缩进时要**照抄它自己的选择器形状**（0-5-0/0-6-0），
+    写低特异度的选择器会静默失效。关怀模式（`html.care-mode` + `--ch-font-scale`）只放大**正文字号与控件**，
+    **不动任何几何令牌**（圆角/阴影/侧栏宽），否则桌面客户端侧栏导轨的折叠几何断言会红。
+
+76. **客户端上线补弹离线期间收到的消息只做一次。** 起点（`localStorage` 的
+    `classhelper.offlineSince`）**只在"可达 → 不可达"的边界写**（不在每次失败上覆盖，否则窗口被无限推迟），
+    恢复时按起点筛未读通知、取**最近 5 条**并按时间升序推给灵动岛，推完清起点（同一次离线只弹一次）。
+    **冒烟模式直接跳过**：冒烟会反复断开/恢复网络，补弹会与注入的合成通知互相打乱队列，
+    把既有的条数/顺序/列表高度断言变成随机红。
+
+77. **客户端崩溃自愈只在"没在上课、没人看着"时才重启进程。** `render-process-gone` 与
+    `unresponsive`（超 10 秒）先**静默重建主窗口**（10 分钟内最多 3 次），
+    `uncaughtException`/`unhandledRejection` 也只在 `isIdle()`（非上课 + 无可见窗口）时才
+    `app.relaunch()`；**冒烟模式绝不重启**（会杀掉验证实例）。
+    自愈模块在 `packages/desktop-client/src/main/crash-guard.ts`，限流与 `isIdle` 判据别放宽。
+
 ## 6. 代码风格
 
 - **TypeScript ESM + NodeNext**：`package.json` 全是 `"type": "module"`，相对导入**必须带 `.js` 后缀**
@@ -789,7 +1328,9 @@ database / update`。
   折线图是 `viewBox="0 0 100 100" + preserveAspectRatio="none"` 的 SVG（数据点用 HTML 绝对定位，
   免得非等比拉伸把圆点压成椭圆）。两者都是响应式的，**不要给它们加重算尺寸的 resize 监听**。
   新增图表请沿用这个做法，不要重新引入图表库。
-- **改动交付形态 / 新增功能后**，同步更新 `README.md`（它兼作产品说明书与验收对照表）。
+- **改动交付形态 / 新增功能后**，同步更新 `docs/reference.md`（完整参考 = 产品说明书 + 验收对照表）。
+  仓库根的 `README.md` 是**展示页**（门面：简介、功能清单、截图、怎么装），不承载细节。改动交付形态、
+  新增功能、或**重采了展示图**之后，两边都要看一眼 —— 不要在 README 里堆实现细节。
 
 ---
 
@@ -843,12 +1384,17 @@ database / update`。
    判据与修法（都是实测过的）：
 
    ```bash
-   # 判据：看交付物（以及 node_modules/electron/dist）有没有 Low 标签
+   # 判据：看交付物（以及 node_modules/electron/dist）有没有 Low 标签。
-   icacls packages\desktop-client\release\win-unpacked\班级小助手.exe | findstr Mandatory
+   #   **正常状态是"没有 Mandatory Label 这一行"**（= 默认 Medium）；出现
+   #   `Mandatory Label\Low Mandatory Level` 才是坏的那个。所以别去找"是不是 Medium"。
+   #   目标就是下面这两个 exe —— 中间物 win-unpacked 打完就删了（§4「交付产物归集」）。
+   icacls "releases\client\<版本>\安装包\ClassHelper-<版本>-x64-setup.exe" | findstr Mandatory
+   icacls "releases\client\<版本>\安装包\ClassHelper-<版本>-x64-portable.exe" | findstr Mandatory
    # 修法：把交付物改成 Medium。dist-win.mjs 收尾会自动做，手工补救用：
-   icacls packages\desktop-client\release /setintegritylevel Medium /T /C
+   icacls "releases\client\<版本>" /setintegritylevel Medium /T /C
    # 目录自身要还原成继承，否则下次构建时自带 Low 标签的 7za / makensis 写不进去
-   icacls packages\desktop-client\release /setintegritylevel "(OI)(CI)Low"
+   #（这一步 dist-win.mjs 现在在**打包前**就做了，见 §4）
+   icacls "releases\client\<版本>" /setintegritylevel "(OI)(CI)Low"
    ```
 
    连带的三条经验：**归档内部的载荷标签无所谓**（装到仓库外得到的是默认 Medium 文件），
@@ -885,10 +1431,12 @@ database / update`。
     （`packages/classisland-plugin/.gitignore` 是本仓库里唯一能正常编辑的 .gitignore。）
 11. **`releases/`（复数）必须在 ESLint 忽略列表里**：本地跑过 `pnpm dist:*` 之后，
     这个目录里是构建后的压缩 JS，不忽略的话 `pnpm lint` 会报出几千条与源码无关的 error
-    （`eslint.config.mjs` 里已补 `**/releases/**`，别再删掉；`release-server/` 同理）。
+    （`eslint.config.mjs` 里已补 `**/releases/**`，别再删掉；旧的 `release-server/` 条目留作兜底）。
     **它一度只在 ESLint 里被忽略、`.gitignore` 里漏了**（后者只有单数的 `release/` 和 `release-server/`）：
     归集一次客户端产物就有 225MB 的 EXE 变成未跟踪文件，`git add -A` 会直接把安装包提交入库。
     2026-09-30 已在 `.gitignore` 末尾补上 `releases/`。
+    （2026-10-05 起 `release-server/`、`packages/desktop-client/release/` 这两个中间输出目录已取消，
+    三个打包脚本都直接输出到 `releases/`，见 §4；那两条 ignore 保留作兜底。）
 12. **ClassIsland 的数据根是 `D:\Classisland\data`**（**不是**旧文档写的 `F:\data`，F 盘已不存在）：
     - 插件 DLL 覆盖到 `D:\Classisland\data\Plugins\classhelper.classisland.bridge\`（**ClassIsland 运行时会锁住
       DLL，必须先退出它再覆盖**：`Get-Process ClassIsland.Desktop | Stop-Process -Force`）；
@@ -909,11 +1457,13 @@ database / update`。
     同一个排查动作 —— 先把 `TEMP` 指到仓库内一个**真实存在的 Windows 绝对路径**再重试：
     - `pnpm dist:server` 报 `Internal compiler error #12345: error creating mmap the size of N`：模板用了
       `SetCompressor /SOLID lzma`，makensis 会在 **`%TEMP%` 所在的盘**建一个上百 MB 的 mmap 临时文件，盘紧就失败
-      （免安装目录其实已生成好，只是最后一步打不出安装包）。加 `--reuse-deps` 还能跳过依赖安装。
+      （组装出来的运行时其实已经落在 `.cache/server-staging/<版本>/win/`，只是最后一步打不出安装包）。
+      加 `--reuse-deps` 还能跳过依赖安装。
     - `pnpm dist:win` 报 `!tempfile: Unable to create temporary file!` / `Error in macro _Switch`：**不是空间不足**，
       而是 Git Bash 里 `TEMP=TMP=/tmp` —— makensis 是原生程序，把 `/tmp` 当成「当前盘根下的 tmp」解析成
       `D:\tmp`，该目录不存在。`/c` 有 79G、`/d` 有 124G 也会照样失败（2026-09-30 实测）。
-      `win-unpacked` 与 `release/*.nsis.7z` 此时都已生成，**只需重跑 electron-builder，不必重建前端**：
+      `win-unpacked` 与 `*.nsis.7z` 此时都已生成（整理进 `安装包/`、删 `win-unpacked/` 的那一步在打包
+      成功之后才跑，失败时还没执行），**只需重跑，不必重建前端**：
 
       ```bash
       mkdir -p .cache/tmp
@@ -941,8 +1491,8 @@ database / update`。
     同理，断言岛体尺寸别写死"胶囊尺寸 + 留白"：那一刻是胶囊还是卡片取决于前面用例留下的状态，
     应改成**与形态无关的不变量**（如"窗口 = 卡片实测尺寸 + 2×阴影留白"）。
 
-23. **客户端安装包有硬底：`班级小助手.exe` 单独压缩后就有 85~90MB，"压到 60MB"做不到 —— 别再为这个反复折腾。**
+23. **客户端安装包有硬底：`ClassHelper.exe` 单独压缩后就有 85~90MB，"压到 60MB"做不到 —— 别再为这个反复折腾。**
-    实测（2026-10-05，Electron 44.3.0）：`win-unpacked` 372MB，其中 `班级小助手.exe`（就是 electron.exe，
+    实测（2026-10-05，Electron 44.3.0）：`win-unpacked` 372MB，其中 `ClassHelper.exe`（就是 electron.exe，
     rcedit 只加了 74KB）**234.7MB**；brotli-9 抽样压缩后估算它单独就有 85~90MB。也就是说把渲染产物
     从 3.2MB 压到 2.1MB、把图标从 293 个减到 42 个，对安装包只影响约 1MB。
     剩下能动的只有这些（合计约 12MB，风险不成比例，**当前一律不做**）：
@@ -966,6 +1516,7 @@ database / update`。
 | `verify:e2e`「上课状态接口（at=周一 08:10）」 | 种子把「周一第 1 节」限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`TERM_START_DATE` 对齐到 `2026-09-07` 即全绿（本机 `.env` 已这样配；`.env.example` 仍是 `2026-02-23`，重置 `.env` 时记得改回来）                                                           |
 | `verify:desktop`「课表今天时间轴」            | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤，`已结束=false` 判定失败                                                                                                                                                                             |
 | `verify:web`「课表科目为全校统一目录」        | 种子给每个班建满了全部科目，下拉里没有可自动建课的「统一科目」分组                                                                                                                                                                                              |
+| `verify:desktop`「作业看板全屏自适应」        | 演示数据里某天有 6 条长作业、而冒烟窗口只有 ~543px 高时，`computeScale` 算出的缩放低于下限 0.45 被 `Math.max(minScale, …)` **钳住**，于是必然溢出（实测 565 > 543）。判据用的是 `host.clientHeight` / `inner.offsetHeight`，**这两个是布局属性、transform 不影响**，所以与动效层无关；数据在冒烟里建了又删，每次跑出来的高度还会差几十像素 |
 | 岛交互 / 岛动画 / 岛截图留档这几个用例        | **AI 会话里会间歇性失败**：同一份产物连跑两次，失败项会在「点击展开 / 紧急展开动画 / 各状态截图留档」之间跳（2026-09-30 实测三轮结果各不相同）。根因是置顶透明小窗的 rAF 被限流、形变采样抓不到帧，属时序敏感；**先原样重跑一次再动手改代码**，别把偶发当成回归 |
 
 ---
@@ -977,9 +1528,9 @@ pnpm lint                # ESLint（0 error 为底线）
 pnpm typecheck           # 全仓库类型检查
 
 pnpm dev:server          # 另开终端
-pnpm verify:e2e          # 后端端到端（2026-10-05 实测 190 项全过）
+pnpm verify:e2e          # 后端端到端（2026-10-06 实测 205 项全过）
-pnpm verify:classisland  # ClassIsland 联动链路（实测 42 项）
+pnpm verify:classisland  # ClassIsland 联动链路（实测 44 项）
-pnpm verify:classisland-plugin          # 插件静态契约（不需要后端，实测 68 项）
+pnpm verify:classisland-plugin          # 插件静态契约（不需要后端，实测 74 项）
 pnpm build:desktop && pnpm verify:desktop   # 客户端冒烟（AI 会话可跑，先看 §7 第 7 条）
 pnpm build && pnpm verify:web               # Web 端真实点击回归（同上）
 ```
@@ -995,7 +1546,7 @@ bash -n deploy/install.sh deploy/classhelper deploy/verify-linux.sh deploy/insta
 pnpm dist:server:linux      # 只能在 Linux 上跑；开发机是 Windows 时到服务器/CI 上验证
 
 # 真机（任意一台能 SSH 的 Linux，容器也行但 systemd 用例会跳过）
-scp release-server/classhelper-server-linux-x64-*.tar.gz deploy/{install.sh,verify-linux.sh} root@<主机>:/tmp/
+scp releases/server/<版本>/linux-x64/classhelper-server-linux-x64-*.tar.gz deploy/{install.sh,verify-linux.sh} root@<主机>:/tmp/
 ssh root@<主机> 'bash /tmp/install.sh --check'
 ssh root@<主机> "printf '%s\n' '<密码>' | bash /tmp/install.sh --yes --admin-password-stdin --package /tmp/classhelper-server-linux-x64-*.tar.gz"
 ssh root@<主机> "bash /tmp/verify-linux.sh --admin-password-stdin" < <(printf '%s\n' '<密码>')
@@ -1025,12 +1576,15 @@ Start-Process D:\Classisland\ClassIsland.exe -WorkingDirectory D:\Classisland
 并用 `pnpm verify:packaged --exe "<客户端路径>"` 对**打包后的副本**复验 ——
 开发产物通过不等于用户机器上的副本通过。
 
-**改过 `pruneRuntime()`（§5 第 55 条）时，还要对免安装目录本身跑一遍**（开发形态跑通不代表裁剪后跑通）。
+**改过 `pruneRuntime()`（§5 第 55 条）时，还要对裁剪后的产物本身跑一遍**（开发形态跑通不代表裁剪后跑通）。
-从 `release-server/classhelper-server/` 起，用**自带的 node.exe**：
+产物有两处现成的，**都带裁剪**：装好的服务端 `%LOCALAPPDATA%\Programs\ClassHelperServer`，
+或打包过程中的组装目录 `.cache/server-staging/<版本>/win/`（`dist-server.mjs` 在成功收尾时会删掉它，
+所以要么在打包失败时留用、要么临时注掉那一步 `fs.rmSync(staging, ...)`）。
+从那一层起，用**自带的 node.exe**：
 
 ```bash
 # ① 起服务：探针通 + 能真实查表（AUTO_MIGRATE 会建库；PORT 用环境变量避开开发端口）
-cd release-server/classhelper-server && PORT=4100 ./node.exe server/dist/index.js
+cd %LOCALAPPDATA%\Programs\ClassHelperServer && set PORT=4100 && node.exe server/dist/index.js
 curl.exe -s --noproxy '*' http://127.0.0.1:4100/healthz
 curl.exe -s --noproxy '*' -X POST http://127.0.0.1:4100/api/auth/login \
   -H "content-type: application/json" -d '{"username":"admin","password":"admin123"}'
@@ -1050,3 +1604,48 @@ DATABASE_PROVIDER=sqlite DATABASE_URL="file:./prune-test.db" \
 这里的目标是脚本刚建出来的空临时库，不是真实数据。）
 
 自测本地接口记得绕过代理（见 §7 第 1 条）。
+
+---
+
+## 9. 工作区维护（2026-10-11 整理留档）
+
+工作区会随着每次发版慢慢长胖，而且长得**很像正经产物**。这一节记录清理的结论与边界，
+下次觉得"盘要满了"直接照这里做，不要临场发挥。
+
+### 这次删了什么、留了什么
+
+| | 内容 | 量 |
+| --- | --- | --- |
+| 删 | `releases/**/免安装/`（客户端 4 版 + 服务端 4 版 + 插件 4 版） | 2.57 GB |
+| 删 | `releases/server/{0.1.0,1.0.0,1.0.0-重构建20261005}`（旧产品名"班级小助手"时期的孤立目录） | 204 MB |
+| 删 | `releases/server/{1.1.0,1.1.2}/linux-x64/classhelper-server-linux-x64/`（tar.gz 的解包留档） | 530 MB |
+| 删 | `releases/server/1.1.2/安装包/班级小助手服务端-1.1.2-x64-setup.exe`（改名前的重复包） | 62 MB |
+| 删 | `.cache/` 里的草稿：smoke 日志与 JSON、`ui-smoke-profile`、`pages`、`tmp`、截图目录、`ci-*.html/css`、`beui-*`、`release-notes-*`、一次性脚本、`dev.db.bak-*` | 276 MB |
+| 删 | 根目录 `ClassHelper video.cachedbg3.log`（0 字节）、`.acl-recovery/`（沙箱 ACL 修复的一次性备份） | ~0 |
+| 删 | `packages/classisland-plugin/{bin,obj,cipx}`（构建产物，gitignored，重跑即生成） | 1.1 MB |
+| **留** | `.cache/{nuget,npm-cache,dotnet-home,mingit}`（工具缓存，按用户要求一个都不删） | 2.4 GB |
+
+合计释放 **约 3.7 GB**，`releases/` 从 4.8 GB 降到 1.4 GB，其余是安装包本体。
+
+### 边界（别删过界）
+
+- **`releases/` 里的安装包本体与 `SHA256SUMS-*.txt` 一律留着**：每个都在 GitHub Release 上有对应资产
+  （v1.0.0 无 Linux 包，v1.1.0/v1.2.0 有），删了要重新下载才能对齐哈希。
+- **`.cache/{nuget,npm-cache,dotnet-home,mingit}` 不删** —— 它们是工具缓存，删了要重新下载；
+  `dotnet-home` 里还有 docfx（`pnpm docs:build` 依赖）。
+- **`packages/*/dist` 与 `packages/server/src/generated` 不删**：删了要重跑构建 + `db:generate`，
+  而且 `verify:*` 全部要重新准备前置产物。
+- **`.cache/dev.db.bak-*` 这类"带日期的备份"删之前想一下**：本次删掉的是 2026-10-06 的
+  `dev.db` 快照，演示数据可用 `pnpm db:reset` 重建，所以算草稿。别把 `packages/server/prisma/` 下的库当草稿。
+- **`.zcode/plans/` 与 `.claude/`** 是历史工具目录，内容已过时但不占空间，留着即可。
+
+### 怎么不重新长回来
+
+产出侧已经改成"只留交付物"（§4「交付产物归集」的硬约定）。另外接手时要清楚：
+
+- **别把 `--reuse-deps` 的复用目录当成产物找回**：服务端的组装中间物现在在
+  `.cache/server-staging/<版本>/`，打完 `dist-server.mjs` 就会删掉它；想留一份能直接跑的副本，
+  就在打包过程中拷出来（或直接跑 `pnpm --filter @classhelper/server start`）。
+- **别在 `releases/` 下留"临时跑一下"的东西**：需要看解包内容就解压 `-portable.exe` 到 `%TEMP%`。
+- 判断某个目录能不能删，就问一句：**"它能不能用仓库里的脚本一条命令重建？"** 能就删。
+

deploy/.env.example

@@ -7,7 +7,7 @@
 SERVER_PORT=4000
 
 # 应用版本（镜像标签）
-APP_VERSION=1.1.0
+APP_VERSION=1.1.2
 
 # MySQL 配置
 MYSQL_ROOT_PASSWORD=请改成强密码_root

deploy/.env.sqlite.example

@@ -8,7 +8,7 @@
 SERVER_PORT=4000
 
 # 应用版本（镜像标签）
-APP_VERSION=1.1.0
+APP_VERSION=1.1.2
 
 # JWT 签名密钥（必填，必须 ≥32 位；不能包含 secret / change-me 等示例词）
 # 生成：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

deploy/Dockerfile

@@ -1,4 +1,4 @@
-# 班级小助手服务端 · 生产镜像
+# ClassHelper 服务端 · 生产镜像
 #
 # 两阶段构建：
 #   build   —— 安装依赖并编译 shared / server / web-admin

deploy/classhelper

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · 运维命令（Linux）
+# ClassHelper · 运维命令（Linux）
 #
 # 安装位置：<安装目录>/bin/classhelper，并在 /usr/local/bin/classhelper 建软链，
 #           因此任何用户在任何目录都能直接敲 `classhelper`。
@@ -30,7 +30,8 @@ DEFAULT_LOG_DIR="/var/log/classhelper"
 DEFAULT_BACKUP_DIR="/var/backups/classhelper"
 REPO_SLUG="LoveChengke/ClassHelper"
 GITHUB_API="https://api.github.com/repos/${REPO_SLUG}"
-GITHUB_RELEASES_PAGE="https://github.com/${REPO_SLUG}/releases"
+GITHUB_REPO_URL="https://github.com/${REPO_SLUG}"
+GITHUB_RELEASES_PAGE="${GITHUB_REPO_URL}/releases"
 # GitHub 对没有 User-Agent 的请求直接 403
 HTTP_UA="ClassHelper-Ops"
 CURL_OPTS=(-fsSL --max-time 20 -H "User-Agent: ${HTTP_UA}")
@@ -48,6 +49,23 @@ fi
 log()  { printf '%s[classhelper]%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
 info() { printf '%s[classhelper]%s %s\n' "$C_CYAN" "$C_RESET" "$*"; }
 warn() { printf '%s[classhelper]%s %s\n' "$C_YELLOW" "$C_RESET" "$*" >&2; }
+
+# 给"正在交互输入"的那几行提示用的输出口：
+# 优先直接写 /dev/tty —— 交互提示语是往 fd 3（/dev/tty）写的，警告也从同一个设备出去，
+# 才能保证"警告紧挨着它对应的那次输入"、不会被 stdout/stderr 的缓冲或分流弄丢/错位
+# （read_secret 结束时会把 fd 3 关掉，所以这里不用 fd 3，而是重新开 /dev/tty 写）。
+# 没有终端时退回 stderr。整句包在 if 条件里，写失败也不会因 set -e 打断命令。
+warn_user() {
+  # `{ …; } 2>/dev/null` 这个形状是必需的：/dev/tty 打不开时（没有控制终端）bash 会先自己打一句
+  # "bash: /dev/tty: No such device or address"，而 `… >/dev/tty 2>/dev/null` 这种写法压不住它
+  # —— 重定向是从左往右处理的，报错发生在 `2>/dev/null` 生效之前。把整句包进一个 stderr
+  # 已经被接管的组里，那行噪音才会被吃掉，调用方也仍然走得到下面的 stderr 回退。
+  if [ "${PROMPT_FD:-}" = "3" ] &&
+     { printf '%s[classhelper]%s %s\n' "$C_YELLOW" "$C_RESET" "$*" >/dev/tty; } 2>/dev/null; then
+    return 0
+  fi
+  warn "$*"
+}
 die()  { printf '%s[classhelper]%s %s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
 
 # ---------------------------------------------------------------- 2. 定位自身与安装元数据
@@ -650,7 +668,7 @@ EOF
     return 0
   fi
 
-  printf '%s班级小助手服务端%s v%s\n\n' "$C_BOLD" "$C_RESET" "$(current_version)"
+  printf '%sClassHelper 服务端%s v%s\n\n' "$C_BOLD" "$C_RESET" "$(current_version)"
   printf '  %-10s %s\n' "服务状态" "$([ "$active" = "active" ] && printf '%s运行中%s' "$C_GREEN" "$C_RESET" || printf '%s未运行%s' "$C_RED" "$C_RESET")（开机自启：${enabled}）"
   printf '  %-10s %s\n' "健康探针" "$([ "$healthy" = "yes" ] && printf '%s通过%s' "$C_GREEN" "$C_RESET" || printf '%s无响应%s' "$C_RED" "$C_RESET")"
   printf '  %-10s %s\n' "安装形态" "${MODE}"
@@ -747,8 +765,10 @@ cmd_doctor() {
       "这是交叉构建的包（$(tr -d '\n' <"${INSTALL_DIR}/.cross-built" 2>/dev/null)）：Web 端「数据库一键切换」可能失败，其余功能正常；正式部署请用 GitHub Actions 出的包"
   fi
 
-  local avail; avail="$(df -Pk "$INSTALL_DIR" 2>/dev/null | awk 'NR==2 {print $4}')"
+  local avail_kb; avail_kb="$(df -Pk "$INSTALL_DIR" 2>/dev/null | awk 'NR==2 {print $4}')"
-  doctor_check "磁盘剩余 ≥1GB（$(human_size "${avail:-0}")）" "$([ "${avail:-0}" -ge 1048576 ] && echo 0 || echo 1)" "清理旧备份：classhelper backup list"
+  case "$avail_kb" in ''|*[!0-9]*) avail_kb=0 ;; esac
+  # df -Pk 给的是 1K 块，human_size 收的是字节 —— 不乘 1024 会把 25 GB 显示成 25 MB
+  doctor_check "磁盘剩余 ≥1GB（$(human_size "$((avail_kb * 1024))")）" "$([ "$avail_kb" -ge 1048576 ] && echo 0 || echo 1)" "清理旧备份：classhelper backup list"
 
   local newest="" backup_ok=1
   newest="$(ls -1t "$BACKUP_DIR" 2>/dev/null | grep -E '^[0-9]{8}-[0-9]{6}' | head -1)"
@@ -778,23 +798,32 @@ cmd_doctor() {
 # 也不进 shell history。
 open_tty() {
   [ "${CLASSHELPER_NO_TTY:-0}" = "1" ] && return 1
-  exec 3</dev/tty 2>/dev/null
+  # 必须用 `<>`（读写）：read_secret 既要往 fd 3 写提示语、又要从它读输入，
+  # 而只读打开的 fd 一写就 EBADF（"write error: Bad file descriptor"）——
+  # 在 set -e 下会让整个命令当场退出。install.sh 里踩过同一个坑（见那边的注释）。
+  exec 3<>/dev/tty 2>/dev/null
 }
 
 read_secret() { # $1=提示语 $2=目标变量名；读到 EOF 时把 READ_SECRET_EOF 置 1
   local prompt="$1" var="$2" value=''
   READ_SECRET_EOF=0
   if open_tty; then
-    printf '%s' "$prompt" >&3
+    # 提示语写不进去（fd 3 不可写）时按"读不到输入"处理，交给调用方报错退出；
+    # 千万别让这行失败把命令打死 —— set -e 下它会让 `classhelper password` 毫无提示地退出。
+    if printf '%s' "$prompt" >&3 2>/dev/null; then
       if ! IFS= read -r -s value <&3; then READ_SECRET_EOF=1; fi
-    printf '\n' >&3
+      printf '\n' >&3 2>/dev/null || true
-    exec 3<&- || true
+    else
+      READ_SECRET_EOF=1
+    fi
+    exec 3<&- 2>/dev/null || true
   else
     printf '%s' "$prompt" >&2
     if ! IFS= read -r -s value; then READ_SECRET_EOF=1; fi
     printf '\n' >&2
   fi
   printf -v "$var" '%s' "$value"
+  return 0
 }
 
 # 与服务端 tools/admin-cli.mjs 同一套强度规则（两处口径必须一致）
@@ -860,36 +889,43 @@ cmd_password() {
   fi
 
   printf '%s现在修改 %s 的密码%s\n' "$C_BOLD" "$label" "$C_RESET"
-  printf '%s提示：输入不回显；密码不会出现在命令行、进程列表或日志里。%s\n\n' "$C_DIM" "$C_RESET"
+  # 要求提前说清楚：原来是"先让人撞墙、再看报错才知道规则"，用户得失败一两次才明白
+  # （而且 read -s 不回显，屏幕上什么都没有，更容易以为卡住了）
+  printf '%s密码要求：至少 8 位；小写字母 / 大写字母 / 数字 / 符号 中至少包含 3 类；不能与用户名相同；\n' "$C_DIM"
+  printf '          也不要用 admin / 123456 / password 这类开头（例如 RainYun-2026 就合规）。%s\n' "$C_RESET"
+  printf '%s提示：输入不回显 —— 敲键盘时屏幕上不会出现任何字符（连星号都没有），这是正常的，输完直接回车。%s\n\n' "$C_DIM" "$C_RESET"
 
   # 有界循环：每次尝试都计数，且 stdin 读完（EOF）立刻退出 ——
   # 否则管道喂入不合规的密码时会一直重读空值，表现为"卡住不动"。
   local pw1='' pw2='' problems='' tries=0 accepted=0
   while [ "$tries" -lt 3 ] && [ "$accepted" = "0" ]; do
     tries=$((tries + 1))
-    read_secret "新密码：" pw1
+    read_secret "新密码（第 ${tries}/3 次）：" pw1
     if [ -z "$pw1" ]; then
       if [ "${READ_SECRET_EOF:-0}" = "1" ]; then
-        die "读不到输入（标准输入已结束）。自动化请用管道：printf '%s\\n%s\\n' \"\$PW\" \"\$PW\" | classhelper password ${key}"
+        die "读不到输入（标准输入已结束）。自动化请用管道：
+  printf '%s\\n%s\\n' \"\$PW\" \"\$PW\" | CLASSHELPER_NO_TTY=1 classhelper password ${key}"
       fi
-      warn "密码不能为空，请重试"
+      warn_user "密码不能为空，请重试"
       continue
     fi
     problems="$(password_problems "$pw1" "${target:-admin}")"
     if [ -n "$problems" ]; then
-      warn "密码不合规：${problems}"
+      warn_user "密码不合规：${problems}"
       continue
     fi
     read_secret "再输入一次确认：" pw2
     if [ "$pw1" != "$pw2" ]; then
-      warn "两次输入不一致，请重来"
+      warn_user "两次输入不一致，请重来"
       continue
     fi
     accepted=1
   done
   if [ "$accepted" != "1" ]; then
     audit password "$key" rejected
-    die "连续 3 次输入不合规，已退出（密码未改动）"
+    warn_user "连续 3 次都没通过校验，已退出（密码未改动）"
+    die "如需非交互改密，用：
+  read -r -s -p '新密码: ' PW; echo; printf '%s\\n%s\\n' \"\$PW\" \"\$PW\" | CLASSHELPER_NO_TTY=1 classhelper password ${key}; unset PW"
   fi
 
   # 改前备份原哈希：失败或复核不过时按这份文件回滚（只含用户名 + bcrypt 哈希，权限 600）。
@@ -1104,8 +1140,10 @@ resolve_download() { # $1=版本(可空) $2=url(可空)；输出下载地址
   if [ -n "$want" ]; then tag="v${want#v}"; else tag="$(github_latest_tag)" || true; fi
   [ -n "$tag" ] || return 1
   ver="${tag#v}"
+  # 用 GITHUB_REPO_URL（不含 /releases）拼接：GITHUB_RELEASES_PAGE 已以 /releases 结尾，
+  # 拼错就成了 .../releases/releases/download/... 必然 404（install.sh 里踩过同一个坑）。
   printf '%s/releases/download/%s/classhelper-server-linux-%s-%s.tar.gz' \
-    "$GITHUB_RELEASES_PAGE" "$tag" "$(asset_arch)" "$ver"
+    "$GITHUB_REPO_URL" "$tag" "$(asset_arch)" "$ver"
 }
 
 download_to() { # $1=url $2=目标文件
@@ -1484,7 +1522,7 @@ EOF
 
 cmd_help() {
   cat <<EOF
-${C_BOLD}班级小助手 · 运维命令${C_RESET}
+${C_BOLD}ClassHelper · 运维命令${C_RESET}
 
 用法：classhelper <子命令> [参数]
 
@@ -1496,7 +1534,7 @@ ${C_BOLD}查看与诊断${C_RESET}
 ${C_BOLD}账号${C_RESET}
   password [用户名]              修改密码（默认 admin）；交互输入、不回显、不进历史
   password --list                列出可登录账号与班级账号（含是否已设密码）
-  password --class <班级码>      修改班级密码（学生端用「班级码 + 班级密码」登录）
+  password --class <班级码>      修改班级密码（ClassHelper 班级端用「班级码 + 班级密码」登录）
 
 ${C_BOLD}备份与恢复${C_RESET}
   backup [--note 说明] [--keep N]    备份配置 + 数据库到 ${BACKUP_DIR}

deploy/docker-compose.sqlite.yml

@@ -1,4 +1,4 @@
-# 班级小助手 · Docker 单容器部署（SQLite + 数据卷）
+# ClassHelper · Docker 单容器部署（SQLite + 数据卷）
 #
 # 适用：云服务器 / 与别的服务共用一台机器。相比 deploy/docker-compose.yml（MySQL 变体）
 #      少跑一个数据库容器，内存占用小很多；数据落在 Docker 卷 classhelper-data 里。
@@ -23,7 +23,7 @@ services:
       context: ..
       dockerfile: deploy/Dockerfile
       target: runtime
-    image: classhelper-server:${APP_VERSION:-1.1.0}
+    image: classhelper-server:${APP_VERSION:-1.3.0}
     restart: unless-stopped
     environment:
       NODE_ENV: production

deploy/docker-compose.yml

@@ -1,4 +1,4 @@
-# 班级小助手 · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
+# ClassHelper · 生产部署（MySQL + 服务端 + 可选 HTTPS 反代）
 #
 # 使用：
 #   1) 复制环境变量模板并填写密钥：cp deploy/.env.example deploy/.env
@@ -45,7 +45,7 @@ services:
     environment:
       DATABASE_PROVIDER: mysql
       DATABASE_URL: mysql://${MYSQL_USER:-classhelper}:${MYSQL_PASSWORD}@db:3306/${MYSQL_DATABASE:-classhelper}
-      # MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/mysql.md 安装）
+      # MySQL 需要 mariadb 驱动适配器（切换数据库时按 docs/management/mysql.md 安装）
       NODE_ENV: production
     command: >
       sh -c "pnpm --filter @classhelper/server add @prisma/adapter-mariadb &&
@@ -60,7 +60,7 @@ services:
       context: ..
       dockerfile: deploy/Dockerfile
       target: runtime
-    image: classhelper-server:${APP_VERSION:-1.1.0}
+    image: classhelper-server:${APP_VERSION:-1.3.0}
     restart: unless-stopped
     environment:
       NODE_ENV: production

deploy/install.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · 服务端 Linux 一键安装器
+# ClassHelper · 服务端 Linux 一键安装器
 #
 # 支持：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+
 #       （自动识别 apt / yum / dnf；直接安装形态要求 systemd）
@@ -9,7 +9,23 @@
 #   native（默认）—— 装成 systemd 服务，自带 Node 运行时，SQLite 或 MySQL
 #   docker        —— 用随包的 Dockerfile 构建镜像 + compose 起容器（需要 docker）
 #
-# 用法：
+# 用法（一行安装，推荐给最终用户）：
+#   curl -fsSL -o /tmp/classhelper-install.sh \
+#     https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh \
+#     && sudo bash /tmp/classhelper-install.sh
+#
+#   脚本会自动从 GitHub Release 取**最新版**服务端安装包，并取发布页上同名的 .sha256 做校验，
+#   所以整条链路只需要这一行。要加参数就接在最后：`sudo bash /tmp/classhelper-install.sh --check`
+#     --check             只体检、不安装（不需要 root）      --yes            全部默认、不交互
+#     --version 1.1.2     装指定版本                         --port 8080      自定义端口
+#     --admin-password-stdin                                从 stdin 读初始管理员密码
+#
+#   ⚠ 别写成 `bash -c "$(curl …)" --check`：`bash -c '代码' 第一个参数` 里那个参数会变成 **$0**、
+#     不是 $1，脚本根本收不到它（实测踩到：想着体检、结果走进交互式安装）。先落盘再执行没这个坑。
+#   内网/离线：把 tar.gz 与 install.sh 一起拷进去，再
+#     sudo bash install.sh --package /path/to/classhelper-server-linux-x64-<版本>.tar.gz
+#
+# 本地已有的脚本用法：
 #   sudo bash install.sh                      # 交互式（TUI 菜单 + 问答）
 #   sudo bash install.sh --check              # 只体检（不需要 root，不改动任何东西）
 #   sudo bash install.sh --uninstall          # 卸载（会问保留什么）
@@ -28,6 +44,7 @@
 #     --node-tarball <url|路径>    直接用指定的 Node 压缩包（内网离线场景）
 #     --with-nginx                 顺带放一份 Nginx 反代配置（不自动申请证书）
 #     --open-firewall              按检测到的防火墙放行端口
+#     --no-autostart               不设开机自启（默认设为自启；装完仍可 systemctl enable 改回来）
 #     --yes                        全部用默认值，不再交互（CI / 验收用）
 #
 # 幂等：重复执行 = 覆盖安装。已有 config.env（含 JWT_SECRET）与 data/ 一律保留，不重置密钥。
@@ -37,7 +54,7 @@ set -euo pipefail
 
 # ---------------------------------------------------------------- 集中变量
 
-PRODUCT="班级小助手"
+PRODUCT="ClassHelper"
 SERVICE_NAME="classhelper"
 
 INSTALL_DIR="/opt/classhelper"
@@ -59,7 +76,8 @@ MYSQL_PASSWORD=""
 
 # 服务端安装包（默认取 GitHub Release 上的 Linux 资产）
 REPO_SLUG="LoveChengke/ClassHelper"
-GITHUB_RELEASES_PAGE="https://github.com/${REPO_SLUG}/releases"
+GITHUB_REPO_URL="https://github.com/${REPO_SLUG}"
+GITHUB_RELEASES_PAGE="${GITHUB_REPO_URL}/releases"
 PACKAGE_URL=""
 PACKAGE_SHA256=""
 VERSION=""
@@ -74,6 +92,10 @@ NODE_DIR_NAME="runtime/node"
 
 WITH_NGINX=0
 OPEN_FIREWALL=0
+# 是否设为开机自启（systemd enable）。需求：「支持选择开机自启动」——
+# 安装器只负责**默认值**，装完之后随时可以用 `systemctl disable/enable classhelper` 改
+# （Windows 侧对应 Web 管理端「系统设置」里的开关，见 PUT /api/system/autostart）。
+AUTOSTART=1
 ASSUME_YES=0
 CHECK_ONLY=0
 UNINSTALL=0
@@ -83,8 +105,20 @@ INSTALL_DOCKER=0
 FORCE=0
 
 LOG_FILE="${LOG_DIR}/install.log"
-SCRIPT_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+
+# 脚本自身路径。两种"一行脚本安装"方式下这里会不一样，必须都能活：
+#   bash -c "$(curl -fsSL .../install.sh)"   → 没有脚本文件（BASH_SOURCE 为空）
+#   curl -fsSL .../install.sh | bash         → 脚本内容是 stdin，同样没有文件
+# SCRIPT_DIR 只用来找与脚本同目录的模板（classhelper.service / nginx.conf），
+# 从远端执行时找不到也不要紧 —— 安装包里带了同样的模板（见 place_program_files）。
+SELF_PATH="${BASH_SOURCE[0]:-}"
+if [ -n "$SELF_PATH" ] && [ -f "$SELF_PATH" ]; then
+  SCRIPT_PATH="$(cd "$(dirname "$SELF_PATH")" && pwd)/$(basename "$SELF_PATH")"
   SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+else
+  SCRIPT_PATH=""
+  SCRIPT_DIR=""
+fi
 
 # ---------------------------------------------------------------- 输出
 
@@ -99,12 +133,29 @@ log()  { printf '%s[classhelper]%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
 info() { printf '%s[classhelper]%s %s\n' "$C_CYAN" "$C_RESET" "$*"; }
 step() { printf '\n%s▶ %s%s\n' "$C_MAGENTA" "$*" "$C_RESET"; }
 warn() { printf '%s[classhelper]%s %s\n' "$C_YELLOW" "$C_RESET" "$*" >&2; }
-die()  { trap - ERR; printf '%s[classhelper]%s %s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
+
+# 真正的 stderr 先留一份到 fd 9。main() 里会用 `exec > >(tee -a 安装日志)` 接管 stdout/stderr，
+# 而脚本退出时那个进程替换的子进程**可能来不及把最后几行写出去** —— 后果是致命错误被彻底吞掉，
+# 用户只看到脚本默默退回 shell、一条提示都没有（2026-10-05 实测踩到，排查成本很高）。
+# 所以 die / on_error 绕开 tee：直接写 fd 9 + 直接追加日志文件。
+exec 9>&2
+
+fail_print() { # $1=要同时显示到终端与日志的错误文本
+  printf '%s\n' "$1" >&9 2>/dev/null || printf '%s\n' "$1" >&2
+  # 日志目录还没建起来时（比如卡在 root 检查）不要去追加，否则 bash 会额外吐一句
+  # "install.log: No such file or directory"，把真正的原因淹掉
+  if [ -n "${LOG_FILE:-}" ] && [ -d "$(dirname "$LOG_FILE")" ]; then
+    printf '[%s] %s\n' "$(date '+%F %T')" "$1" >>"$LOG_FILE" 2>/dev/null || true
+  fi
+  return 0
+}
+
+die() { trap - ERR; fail_print "$(printf '%s[classhelper]%s %s' "$C_RED" "$C_RESET" "$*")"; exit 1; }
 
 on_error() {
   local code=$?
-  printf '\n%s[classhelper]%s 安装中断（第 %s 行，退出码 %s）\n' "$C_RED" "$C_RESET" "$1" "$code" >&2
+  fail_print "$(printf '\n%s[classhelper]%s 安装中断（第 %s 行，退出码 %s）' "$C_RED" "$C_RESET" "$1" "$code")"
-  if [ -f "$LOG_FILE" ]; then printf '完整日志：%s\n' "$LOG_FILE" >&2; fi
+  [ -f "${LOG_FILE:-}" ] && fail_print "完整日志：${LOG_FILE}"
   exit "$code"
 }
 trap 'on_error "$LINENO"' ERR
@@ -123,11 +174,39 @@ ASCII
   printf '%s  一键安装 + classhelper 运维命令（status / password / upgrade / backup …）%s\n\n' "$C_DIM" "$C_RESET"
 }
 
-# 打印文件头部注释里的用法（第一个分隔线之后、第二个分隔线之前）
+# 用法：能读到脚本文件时直接打印文件头部注释（唯一真身，不会漂）；从远端执行时没有文件可读，
+# 退化成下面这份精简参数表。
 usage() {
+  if [ -n "$SCRIPT_PATH" ] && [ -r "$SCRIPT_PATH" ]; then
     awk 'NR == 1 { next }
          /^# -{10,}/ { seen++; if (seen == 2) exit; next }
          seen == 1 { sub(/^# ?/, ""); print }' "$SCRIPT_PATH"
+    return 0
+  fi
+  cat <<'USAGE'
+ClassHelper · 服务端 Linux 安装器
+
+（本次是从远端直接执行的，没有本地脚本文件可读，这里只列常用参数；
+  完整说明见 https://github.com/LoveChengke/ClassHelper/blob/master/docs/management/linux-deploy.md ）
+
+  --mode native|docker         安装形态（默认 native：systemd + 内置 Node）
+  --dir /opt/classhelper       安装目录        --port 4000        服务端口
+  --database sqlite|mysql      数据库（默认 sqlite）
+  --mysql-host/-port/-db/-user/-password-stdin                 MySQL 连接信息
+  --admin-password-stdin       从 stdin 读一行作为初始管理员密码
+  --package <url|file://路径>  服务端安装包（默认从 GitHub Release 取最新版）
+  --sha256 <哈希>              安装包校验值（不给时自动取发布页上的同名 .sha256）
+  --version <X.Y.Z>            指定安装的版本
+  --node-source bundled|system|tarball    Node 运行时来源（默认 bundled）
+  --node-mirror <url> / --node-tarball <url|路径>               Node 下载镜像 / 离线包
+  --with-nginx                 顺带放一份 Nginx 反代配置
+  --open-firewall              按检测到的防火墙放行端口
+  --install-docker             Docker 形态缺少 docker 时自动安装
+  --yes                        全部用默认值，不再交互（CI / 验收用）
+  --force                      覆盖已有配置；无 systemd 时只铺文件不装服务
+  --check                      只体检（不需要 root，不改动系统）
+  --uninstall                  卸载
+USAGE
 }
 
 # ---------------------------------------------------------------- 参数解析
@@ -157,6 +236,8 @@ parse_args() {
       --node-tarball) NODE_TARBALL="${2:-}"; NODE_SOURCE="tarball"; shift 2 ;;
       --with-nginx) WITH_NGINX=1; shift ;;
       --open-firewall) OPEN_FIREWALL=1; shift ;;
+      --autostart) AUTOSTART=1; shift ;;
+      --no-autostart) AUTOSTART=0; shift ;;
       --install-docker) INSTALL_DOCKER=1; shift ;;
       --yes|-y) ASSUME_YES=1; shift ;;
       --force) FORCE=1; shift ;;
@@ -181,6 +262,10 @@ parse_args() {
 
 OS_ID=""; OS_VER=""; OS_NAME=""; PKG=""
 detect_os() {
+  # /etc/os-release 里也有 VERSION（Ubuntu 是 "24.04.1 LTS (Noble Numbat)"），直接 source 会盖掉
+  # 安装包版本号：.installed.json 会记成发行版名，而且不带 --package 时 resolve_package_url
+  # 会拿它当 Release tag 去拼下载地址（必然 404）。
+  local keep_version="${VERSION:-}"
   if [ -r /etc/os-release ]; then
     # shellcheck disable=SC1091
     . /etc/os-release
@@ -190,6 +275,7 @@ detect_os() {
   else
     OS_NAME="$(uname -s) $(uname -r)"
   fi
+  VERSION="$keep_version"
   if command -v apt-get >/dev/null 2>&1; then PKG="apt"
   elif command -v dnf >/dev/null 2>&1; then PKG="dnf"
   elif command -v yum >/dev/null 2>&1; then PKG="yum"
@@ -258,16 +344,66 @@ config_value() { # $1=KEY：从已有配置里读一项（覆盖安装时沿用
 
 # ---------------------------------------------------------------- 交互问答
 
+# 交互输入的统一出口。
+#
+# 为什么不能直接用 `read`：一行脚本安装的两种写法里，stdin 未必是终端 ——
+#   curl -fsSL .../install.sh | bash        → **stdin 就是脚本内容本身**，read 会把脚本的下一行吃掉，
+#                                            表现为"问题全被跳过 + 后续脚本乱套"
+#   bash -c "$(curl -fsSL .../install.sh)"  → stdin 仍是终端，正常
+# 所以统一优先读 /dev/tty，退回 stdin；两者都不行（CI、定时任务）才按"非交互"处理。
+PROMPT_FD=""
+
+open_prompt_fd() {
+  if [ -n "$PROMPT_FD" ]; then return 0; fi
+  if [ "${CLASSHELPER_NO_TTY:-0}" = "1" ]; then return 1; fi
+  # 必须用 `<>`（读写）打开，不能只用 `<`（只读）：下面 read_prompt 要往 fd 3 **写**提示语，
+  # 而往只读 fd 写会 EBADF（"printf: write error: Bad file descriptor"），在 set -e 下
+  # 直接把安装脚本打死 —— 现象是"菜单打印完就默默退回 shell"，错误还被 tee 吞掉，极难查。
+  # 2026-10-05 在 Ubuntu 24.04 上实测踩到并定位。
+  if exec 3<>/dev/tty 2>/dev/null; then PROMPT_FD=3; return 0; fi
+  return 1
+}
+
+# $1=提示语 $2=目标变量名 $3=1 表示隐藏输入（密码）
+#
+# 注意：**这个函数永远返回 0**。它一旦返回非 0，在 `set -e` 下会把整个安装脚本当场终止，
+# 而调用处（`read_prompt "…" choice`）是独立命令、不会去接这个返回值 —— 实测后果是
+# "菜单打印完就默默退回 shell，一条错误信息都没有"，极难排查。
+# 读不到终端时就把变量留空，由调用方按默认值走。
+read_prompt() {
+  local prompt="$1" var="$2" hidden="${3:-0}" value=""
+  printf -v "$var" ''
+  if open_prompt_fd; then
+    # 提示语写不进去时**不能让它把脚本打死**：退化成"这一项用默认值"，并且把这件事说出来
+    if printf '%s' "$prompt" >&3 2>/dev/null; then
+      if [ "$hidden" = "1" ]; then IFS= read -r -s value <&3 || true; else IFS= read -r value <&3 || true; fi
+      printf '\n' >&3 2>/dev/null || true
+    else
+      fail_print "$(printf '%s[classhelper]%s 写不进终端（fd 3 不可写），这一项按默认值处理' "$C_YELLOW" "$C_RESET")"
+    fi
+  fi
+  # 刻意**不**退回 stdin：`curl … | bash` 时 stdin 就是脚本内容本身，
+  # 从 stdin 读会把脚本的下一行当成用户输入吃掉，表现为"脚本后半段莫名其妙乱套"。
+  printf -v "$var" '%s' "$value"
+  return 0
+}
+
+# 能不能问用户：--yes 不问；没有终端可读也不问（这时一律用默认值）
+can_prompt() {
+  [ "$ASSUME_YES" = "1" ] && return 1
+  open_prompt_fd
+}
+
 ask() { # $1=提示 $2=默认值 $3=目标变量
   local prompt="$1" default="$2" var="$3" answer=""
-  if [ "$ASSUME_YES" = "1" ] || [ ! -t 0 ]; then
+  if ! can_prompt; then
     printf -v "$var" '%s' "$default"
     return 0
   fi
   if [ -n "$default" ]; then
-    read -r -p "$(printf '%s[?]%s %s [%s]: ' "$C_CYAN" "$C_RESET" "$prompt" "$default")" answer || true
+    read_prompt "$(printf '%s[?]%s %s [%s]: ' "$C_CYAN" "$C_RESET" "$prompt" "$default")" answer
   else
-    read -r -p "$(printf '%s[?]%s %s: ' "$C_CYAN" "$C_RESET" "$prompt")" answer || true
+    read_prompt "$(printf '%s[?]%s %s: ' "$C_CYAN" "$C_RESET" "$prompt")" answer
   fi
   printf -v "$var" '%s' "${answer:-$default}"
 }
@@ -275,24 +411,33 @@ ask() { # $1=提示 $2=默认值 $3=目标变量
 ask_secret() { # $1=提示 $2=目标变量（不回显）
   local prompt="$1" var="$2" value=""
   printf -v "$var" ''
-  if [ "$ASSUME_YES" = "1" ] || [ ! -t 0 ]; then return 0; fi
+  if ! can_prompt; then return 0; fi
-  read -r -s -p "$(printf '%s[?]%s %s' "$C_CYAN" "$C_RESET" "$prompt")" value || true
+  read_prompt "$(printf '%s[?]%s %s' "$C_CYAN" "$C_RESET" "$prompt")" value 1
-  printf '\n'
   printf -v "$var" '%s' "$value"
 }
 
 ask_yes_no() { # $1=提示 $2=默认 y/n；返回 0=是
   local prompt="$1" default="$2" answer=""
-  if [ "$ASSUME_YES" = "1" ] || [ ! -t 0 ]; then
+  if ! can_prompt; then
     [ "$default" = "y" ]
     return
   fi
-  read -r -p "$(printf '%s[?]%s %s [%s]: ' "$C_CYAN" "$C_RESET" "$prompt" "$default")" answer || true
+  read_prompt "$(printf '%s[?]%s %s [%s]: ' "$C_CYAN" "$C_RESET" "$prompt" "$default")" answer
   case "${answer:-$default}" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac
 }
 
 choose_mode_interactive() {
-  if [ "$ASSUME_YES" = "1" ] || [ ! -t 0 ]; then return 0; fi
+  if [ "$ASSUME_YES" = "1" ]; then return 0; fi
+  # 交互式安装却读不到终端时**明确报错**，而不是默默按默认值装下去：
+  # 后者会让用户以为自己在选，其实一个都没问到（实测踩到过）。
+  if ! can_prompt; then
+    die "读不到终端（/dev/tty 打不开），没法交互式选择安装形态。
+   · 确实想非交互安装：加 --yes（默认 native + SQLite + ${INSTALL_DIR} + 端口 ${PORT}）
+   · 或者先把脚本存成文件，再在同一终端里执行：
+       curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh
+       sudo bash /tmp/classhelper-install.sh
+   · 只想先体检（不需要终端、也不需要 root）：加 --check"
+  fi
   printf '%s请选择：%s\n' "$C_BOLD" "$C_RESET"
   printf '  1) 直接安装（systemd 服务 + 内置 Node 运行时，默认 SQLite）%s  ← 推荐%s\n' "$C_GREEN" "$C_RESET"
   printf '  2) 直接安装 + MySQL\n'
@@ -300,7 +445,7 @@ choose_mode_interactive() {
   printf '  4) 只体检（--check，不改动系统）\n'
   printf '  5) 卸载\n'
   local choice=""
-  read -r -p "$(printf '%s[?]%s 输入序号 [1]: ' "$C_CYAN" "$C_RESET")" choice || true
+  read_prompt "$(printf '%s[?]%s 输入序号 [1]: ' "$C_CYAN" "$C_RESET")" choice
   case "${choice:-1}" in
     1) MODE="native"; DB_KIND="sqlite" ;;
     2) MODE="native"; DB_KIND="mysql" ;;
@@ -339,6 +484,7 @@ collect_answers() {
   fi
   if ask_yes_no "顺带放一份 Nginx 反向代理配置到 ${CONFIG_DIR}/nginx.conf？" "n"; then WITH_NGINX=1; fi
   if ask_yes_no "按检测到的防火墙放行端口 ${PORT}？" "n"; then OPEN_FIREWALL=1; fi
+  if ask_yes_no "设为开机自启（systemctl enable ${SERVICE_NAME}）？" "y"; then AUTOSTART=1; else AUTOSTART=0; fi
 }
 
 # ---------------------------------------------------------------- 用户与目录
@@ -391,12 +537,14 @@ resolve_package_url() {
     tag="$(github_latest_tag)" || true
     if [ -z "$tag" ]; then
       die "取不到 GitHub 最新版本（本机可能没有外网）。请用 --package 指定安装包，例如：
-    sudo bash install.sh --package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz"
+    sudo bash install.sh --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz"
     fi
   fi
   ver="${tag#v}"
+  # 注意这里用 GITHUB_REPO_URL 而不是 GITHUB_RELEASES_PAGE：后者本身已经以 /releases 结尾，
+  # 再拼一次就变成 .../releases/releases/download/... （必然 404，实测踩到）。
   printf '%s/releases/download/%s/classhelper-server-linux-%s-%s.tar.gz' \
-    "$GITHUB_RELEASES_PAGE" "$tag" "$(asset_arch)" "$ver"
+    "$GITHUB_REPO_URL" "$tag" "$(asset_arch)" "$ver"
 }
 
 # 下载 + 校验 + 解压；结果放进全局 STAGE_DIR（不用命令替换取，否则会把日志一起捕获）
@@ -414,13 +562,30 @@ fetch_package() {
   esac
   [ -s "$pkg" ] || die "安装包为空：${url}"
 
+  # 没给 --sha256 时，把发布页上同名的 .sha256 取回来自己校验。
+  # 这一步是一行脚本安装下的**唯一**校验机会：用户不会自己去核哈希，
+  # 而少了它，"校验"就只是把算出来的哈希记进日志而已。
+  if [ -z "$PACKAGE_SHA256" ]; then
+    local sum_file="${tmp}/expected.sha256"
+    case "$url" in
+      file://*|/*|./*|../*) [ -f "${url#file://}.sha256" ] && cp -f "${url#file://}.sha256" "$sum_file" ;;
+      *) curl -fsSL --max-time 60 -H 'User-Agent: ClassHelper-Installer' -o "$sum_file" "${url}.sha256" 2>/dev/null ;;
+    esac
+    if [ -s "$sum_file" ]; then
+      PACKAGE_SHA256="$(awk '{print $1; exit}' "$sum_file")"
+      [ -n "$PACKAGE_SHA256" ] && info "已从发布页取到 sha256，安装包会做校验"
+    fi
+  fi
+
   local got; got="$(sha256sum "$pkg" | awk '{print $1}')"
   if [ -n "$PACKAGE_SHA256" ]; then
-    [ "$got" = "$PACKAGE_SHA256" ] || die "sha256 校验失败：期望 ${PACKAGE_SHA256}，实际 ${got}"
+    [ "$got" = "$PACKAGE_SHA256" ] || die "sha256 校验失败：期望 ${PACKAGE_SHA256}，实际 ${got}
+安装包可能在传输中损坏或被篡改，已中止（什么也没改）。可用 --sha256 <正确的哈希> 重试。"
     log "sha256 校验通过"
   else
     PACKAGE_SHA256="$got"
-    info "sha256（未提供校验值，仅记录）：${got}"
+    warn "取不到发布页的 .sha256，本次只记录实际哈希、不做校验：${got}"
+    warn "（内网分发时请自带 --sha256；或手工核对上面这串哈希）"
   fi
 
   STAGE_DIR="${tmp}/pkg"
@@ -636,7 +801,7 @@ write_config() {
 
   cat >"$CONFIG_FILE" <<EOF
 # ---------------------------------------------------------------------------
-# 班级小助手服务端配置（由 install.sh 生成于 $(date '+%F %T')）
+# ClassHelper 服务端配置（由 install.sh 生成于 $(date '+%F %T')）
 #
 # 这是**唯一的配置真身**：安装目录里的 .env 是指向本文件的软链，
 # systemd 通过 EnvironmentFile 读本文件；改完执行 classhelper restart 生效。
@@ -673,7 +838,7 @@ BCRYPT_ROUNDS=10
 INITIAL_ADMIN_USERNAME=admin
 ${admin_line}
 
-# 新建班级 / 重置教师账号时的默认密码（学生端用「班级码 + 班级密码」登录）
+# 新建班级 / 重置教师账号时的默认密码（ClassHelper 班级端用「班级码 + 班级密码」登录）
 DEFAULT_CLASS_PASSWORD=123456
 DEFAULT_TEACHER_PASSWORD=123456
 
@@ -687,7 +852,7 @@ EOF
 
 link_env_file() {
   # Web 端「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是 config.env；
-  # 用软链把两者收成一份真身，否则切换看起来成功、重启后又连回旧库（详见 docs/linux-deploy.md）
+  # 用软链把两者收成一份真身，否则切换看起来成功、重启后又连回旧库（详见 docs/management/linux-deploy.md）
   local link="${INSTALL_DIR}/.env"
   if [ -e "$link" ] && [ ! -L "$link" ]; then
     warn "安装目录里存在真实文件 .env，已改名保留为 .env.bak.$(date +%s) 再建立软链"
@@ -744,8 +909,12 @@ EOF
   fi
   chmod 644 "/etc/systemd/system/${SERVICE_NAME}.service"
   systemctl daemon-reload
+  if [ "${AUTOSTART}" = "1" ]; then
     systemctl enable "$SERVICE_NAME" >/dev/null
     log "已安装 /etc/systemd/system/${SERVICE_NAME}.service 并设为开机自启"
+  else
+    log "已安装 /etc/systemd/system/${SERVICE_NAME}.service（**未**设为开机自启；需要时执行 systemctl enable ${SERVICE_NAME}）"
+  fi
 }
 
 install_aux_files() {
@@ -816,7 +985,7 @@ install_docker_engine() {
 write_compose() {
   local compose="${CONFIG_DIR}/compose.yml"
   cat >"$compose" <<EOF
-# 班级小助手 · 由 install.sh 生成的 compose 文件（${MODE} 形态）
+# ClassHelper · 由 install.sh 生成的 compose 文件（${MODE} 形态）
 # 配置见 ${CONFIG_FILE}（改完执行 classhelper restart 重建容器）
 # 数据在 Docker 卷 classhelper-data 里；备份用 classhelper backup
 #
@@ -868,7 +1037,7 @@ setup_nginx() {
     install -m 600 "${INSTALL_DIR}/nginx.conf" "$target"
   else
     cat >"$target" <<EOF
-# 班级小助手 · Nginx 反向代理（替换 server_name 与证书路径后启用）
+# ClassHelper · Nginx 反向代理（替换 server_name 与证书路径后启用）
 server {
     listen 80;
     server_name class.example.com;
@@ -991,7 +1160,7 @@ print_result() {
   printf '  1. 改掉默认密码：%sclasshelper password admin%s\n' "$C_CYAN" "$C_RESET"
   printf '  2. 公网访问请上 HTTPS：改好 %s/nginx.conf 的域名与证书，并把 CORS_ORIGIN\n' "$CONFIG_DIR"
   printf '     收敛到你的域名（classhelper config set CORS_ORIGIN https://your.domain）\n'
-  printf '  3. 学生端「服务器地址」填 http://%s:%s 或你的域名\n' "$ip" "$PORT"
+  printf '  3. ClassHelper 班级端「服务器地址」填 http://%s:%s 或你的域名\n' "$ip" "$PORT"
   printf '%s────────────────────────────────────────────────────────────%s\n' "$C_GREEN" "$C_RESET"
 }
 
@@ -1000,15 +1169,34 @@ print_result() {
 main() {
   parse_args "$@"
 
+  # `--check` 与菜单里的"4) 只体检"是同一条路：都不需要 root、都不改动系统。
+  # 菜单必须出现在 root 检查**之前** —— 否则非 root 用户连菜单都看不到，只能靠 --check。
   if [ "$CHECK_ONLY" = "1" ]; then
     banner
     check_only
     exit $?
   fi
 
-  [ "$(id -u)" = "0" ] || die "请用 root 执行：sudo bash install.sh（只体检不需要 root：bash install.sh --check）"
-
   banner
+  detect_os
+  info "系统：${OS_NAME:-未知}｜包管理器：${PKG:-未知}｜架构：$(uname -m)"
+  choose_mode_interactive
+
+  # 菜单里选了 4：到这里才分流。
+  # （原来这段判断写在菜单**之前**，从菜单选 4 时 CHECK_ONLY 设了也没人看 —— 实测踩到：
+  #   用户选"只体检"，脚本却直接开始安装。）
+  if [ "$CHECK_ONLY" = "1" ]; then
+    check_only
+    exit $?
+  fi
+
+  if [ "$(id -u)" != "0" ]; then
+    if [ -n "$SCRIPT_PATH" ]; then
+      die "请用 root 执行：sudo bash ${SCRIPT_PATH}（只体检不需要 root：加 --check）"
+    fi
+    die "请用 root 执行：在刚才那条命令前面加 sudo（只体检不需要 root：末尾加 --check）"
+  fi
+
   mkdir -p "$LOG_DIR" && chmod 700 "$LOG_DIR"
   {
     printf '\n===== %s 安装开始 =====\n' "$(date '+%F %T')"
@@ -1017,11 +1205,9 @@ main() {
   # 后续输出同时进日志（tee 不占 stdin，交互问答照常）
   exec > >(tee -a "$LOG_FILE") 2>&1
 
-  detect_os
-  info "系统：${OS_NAME:-未知}｜包管理器：${PKG:-未知}｜架构：$(uname -m)"
-
-  choose_mode_interactive
   collect_answers
+  # 把最终生效的选择打出来：非交互（--yes）或问答被跳过时，这一行是唯一能看出"到底按什么装的"地方
+  info "本次安装：形态 ${MODE}｜目录 ${INSTALL_DIR}｜端口 ${PORT}｜数据库 ${DB_KIND}｜Node ${NODE_SOURCE}"
 
   if [ "$UNINSTALL" = "1" ]; then
     do_uninstall --yes

deploy/logrotate.d/classhelper

@@ -1,5 +1,5 @@
 # ---------------------------------------------------------------------------
-# 班级小助手 · 日志轮转
+# ClassHelper · 日志轮转
 # 由 deploy/install.sh 安装到 /etc/logrotate.d/classhelper
 #
 # copytruncate 而不是 create+信号：安装器与 classhelper 都是"追加写完就关"

deploy/package.runtime.json

@@ -1,9 +1,9 @@
 {
   "name": "classhelper-server-runtime",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": true,
   "type": "module",
-  "description": "班级小助手服务端运行时（安装包 / 容器内置）",
+  "description": "ClassHelper 服务端运行时（安装包 / 容器内置）",
   "dependencies": {
     "@libsql/client": "^0.17.0",
     "@prisma/adapter-libsql": "7.10.0",

deploy/profile.d/classhelper.sh

@@ -1,5 +1,5 @@
 # ---------------------------------------------------------------------------
-# 班级小助手 · 登录 shell 环境变量
+# ClassHelper · 登录 shell 环境变量
 #
 # 由 deploy/install.sh 安装到 /etc/profile.d/classhelper.sh（占位符替换成真实路径）。
 # 生效方式：重新登录，或 `source /etc/profile.d/classhelper.sh`。

deploy/tools/admin-cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * 班级小助手 · 离线账号工具（随 Linux 包发布，安装在 ${INSTALL_DIR}/tools/admin-cli.mjs）
+ * ClassHelper · 离线账号工具（随 Linux 包发布，安装在 ${INSTALL_DIR}/tools/admin-cli.mjs）
  *
  * 为什么不用 HTTP API 改密码：`classhelper password` 要能在**服务停机**时救急，
  * 而调 API 必须先有一个能登录的账号 —— 管理员忘了密码时就是死锁。
@@ -88,7 +88,7 @@ async function loadServerModules() {
   return { env: env.env, prisma: db.prisma, disconnectPrisma: db.disconnectPrisma, ...password };
 }
 
-/** 目标账号：普通用户按 username，班级账号按 Class.code（学生端登录用的是班级码） */
+/** 目标账号：普通用户按 username，班级账号按 Class.code（ClassHelper 班级端登录用的是班级码） */
 async function resolveTarget(prisma, key) {
   if (key.startsWith('class:')) {
     const code = key.slice('class:'.length).toUpperCase();
@@ -100,7 +100,7 @@ async function resolveTarget(prisma, key) {
   if (!user) return { error: `用户名不存在：${key}`, code: EXIT.NOT_FOUND };
   if (user.role === 'STUDENT') {
     return {
-      error: `学生没有个人账号（${key} 只是名单记录），学生端用「班级码 + 班级密码」登录，请用 --class 改班级密码`,
+      error: `学生没有个人账号（${key} 只是名单记录），ClassHelper 班级端用「班级码 + 班级密码」登录，请用 --class 改班级密码`,
       code: EXIT.NOT_FOUND,
     };
   }
@@ -174,7 +174,7 @@ async function cmdList(modules, asJson) {
   for (const user of users) {
     process.stdout.write(`  ${user.role.padEnd(8)} ${user.username.padEnd(16)} ${user.name}\n`);
   }
-  process.stdout.write('\n班级账号（学生端用「班级码 + 班级密码」登录）：\n');
+  process.stdout.write('\n班级账号（ClassHelper 班级端用「班级码 + 班级密码」登录）：\n');
   for (const item of classes) {
     const state = item.passwordHash ? '已设置' : '⚠ 未设置密码（该班当前无法登录）';
     process.stdout.write(`  ${item.code.padEnd(8)} ${item.name.padEnd(16)} ${state}\n`);

deploy/verify-linux.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
+# ClassHelper · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
 #
 # 覆盖：安装结果 → 服务可用性 → API 登录 → 改密（含回滚与审计）→ 备份 →
 #       配置读写 → key rotate →（可选）升级 / 回滚 / 卸载
@@ -74,7 +74,7 @@ CURL=(curl -fsS --noproxy '*')
 
 if [ "$ADMIN_PASSWORD_FROM_STDIN" = "1" ]; then IFS= read -r ADMIN_PASSWORD || true; fi
 
-printf '%s班级小助手 · Linux 安装验收%s\n' "$B" "$N"
+printf '%sClassHelper · Linux 安装验收%s\n' "$B" "$N"
 note "安装目录 ${INSTALL_DIR}｜配置 ${CONFIG_FILE}｜端口 ${PORT}"
 
 # ---------------------------------------------------------------- 1. 安装结果
@@ -181,12 +181,14 @@ if [ -n "$TOKEN" ]; then
   check "审计日志里没有新密码明文" "$(grep -q -- "$GENERATED" "${LOG_DIR}/audit.log" 2>/dev/null && echo 1 || echo 0)"
   check "审计日志里没有原密码明文" "$(grep -q -- "$ADMIN_PASSWORD" "${LOG_DIR}/audit.log" 2>/dev/null && echo 1 || echo 0)"
 
-  check "弱密码被拒绝（长度/种数不足）" \
+  # 先把输出收进变量再 grep：`外部命令 | grep -q` 在 `set -o pipefail` 下，grep 命中即退出会让
-    "$(printf 'abc\nabc\n' | "$CLASSHELPER" password "$ADMIN_USER" 2>&1 | grep -q '不合规' && echo 0 || echo 1)"
+  # 写端收到 SIGPIPE（退出码 141），于是"匹配到了"被算成失败
+  weak_out="$(printf 'abc\nabc\n' | "$CLASSHELPER" password "$ADMIN_USER" 2>&1 || true)"
+  check "弱密码被拒绝（长度/种数不足）" "$(printf '%s' "$weak_out" | grep -q '不合规' && echo 0 || echo 1)"
   check "密码不合规时不会卡死（stdin 结束即退出）" \
     "$(printf 'abc\n' | timeout 20 "$CLASSHELPER" password "$ADMIN_USER" >/dev/null 2>&1; [ $? -ne 124 ] && echo 0 || echo 1)"
-  check "password --list 能列出账号" \
+  list_out="$("$CLASSHELPER" password --list 2>&1 || true)"
-    "$("$CLASSHELPER" password --list 2>&1 | grep -q "$ADMIN_USER" && echo 0 || echo 1)"
+  check "password --list 能列出账号" "$(printf '%s' "$list_out" | grep -q "$ADMIN_USER" && echo 0 || echo 1)"
 
   # 用改密前保存的哈希把账号恢复原样：比再改一次密码更可靠
   # （原密码若是 admin123 这类弱口令，改回去会被强度校验挡下 —— 那是产品的正确行为）
@@ -223,7 +225,8 @@ if [ -n "$latest" ]; then
   fi
   check "备份目录权限 700" "$([ "$(stat -c '%a' "${latest%/}" 2>/dev/null)" = "700" ] && echo 0 || echo 1)"
 fi
-check "backup list 能列出备份" "$("$CLASSHELPER" backup list 2>&1 | grep -qE '^  [0-9]{8}-' && echo 0 || echo 1)"
+backup_list_out="$("$CLASSHELPER" backup list 2>&1 || true)"
+check "backup list 能列出备份" "$(printf '%s' "$backup_list_out" | grep -qE '^  [0-9]{8}-' && echo 0 || echo 1)"
 
 # ---------------------------------------------------------------- 6. 配置
 
@@ -248,8 +251,10 @@ if [ -n "$TOKEN" ]; then
     note "按环境变量跳过"
   else
     old_secret="$(read_cfg JWT_SECRET)"
-    # key rotate 会问一次确认；无 tty 时从 stdin 读，因此用管道喂 yes
+    # key rotate 无 tty 时会问两次（确认轮换、是否现在重启）；只喂一个 yes 的话第二次读到 EOF，
-    printf 'yes\n' | CLASSHELPER_NO_TTY=1 "$CLASSHELPER" key rotate >/dev/null 2>&1 || true
+    # 重启被跳过 —— 新密钥不生效，下面「旧 token 已失效」必然失败。
+    # 用 CLASSHELPER_ASSUME_YES=1 跳过问答并强制重启，语义才是"轮换后旧会话立即失效"。
+    CLASSHELPER_NO_TTY=1 CLASSHELPER_ASSUME_YES=1 "$CLASSHELPER" key rotate >/dev/null 2>&1 || true
     new_secret="$(read_cfg JWT_SECRET)"
     check "key rotate 改变了 JWT_SECRET" "$([ -n "$new_secret" ] && [ "$new_secret" != "$old_secret" ] && echo 0 || echo 1)"
     check "新密钥长度 ≥32" "$([ "${#new_secret}" -ge 32 ] && echo 0 || echo 1)"

docs/404.html

@@ -0,0 +1,147 @@
+<!doctype html>
+<!--
+  404 页 —— 不经过 docfx 模板（它只处理 .md/.yml），由 docs/build.mjs 把 {{BASE}} 换成站点根路径。
+
+  为什么要 <base>：GitHub Pages 的项目页挂在 /<仓库名>/ 子路径下，未知路径返回的是**站点根**的
+  404.html，而浏览器按**被请求的那个路径**解析页面里的相对链接。不钉住 base，访问
+  /classhelper/get-started/typo 时页面上所有链接都会指向 /classhelper/get-started/ 下面的东西。
+-->
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <base href="{{BASE}}" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex" />
+    <title>页面不存在 | ClassHelper文档</title>
+    <script>
+      // 与 docfx 主题选择同一套 key（theme 存 light / dark / auto），避免两边主题不一致
+      const theme = localStorage.getItem('theme') || 'auto';
+      document.documentElement.setAttribute(
+        'data-bs-theme',
+        theme === 'auto'
+          ? window.matchMedia('(prefers-color-scheme: dark)').matches
+            ? 'dark'
+            : 'light'
+          : theme,
+      );
+    </script>
+    <style>
+      :root {
+        --bg: #ffffff;
+        --fg: #1f2328;
+        --muted: #59636e;
+        --line: #d1d9e0;
+        --accent: #0f6cbd;
+      }
+
+      [data-bs-theme='dark'] {
+        --bg: #1b1f24;
+        --fg: #e6edf3;
+        --muted: #9198a1;
+        --line: #30363d;
+        --accent: #6cb8ff;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html {
+        color-scheme: light dark;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 32px;
+        background: var(--bg);
+        color: var(--fg);
+        font-family:
+          'Segoe UI Variable Text',
+          'Segoe UI',
+          'Microsoft YaHei UI',
+          'Microsoft YaHei',
+          -apple-system,
+          BlinkMacSystemFont,
+          'PingFang SC',
+          'Hiragino Sans GB',
+          sans-serif;
+        line-height: 1.7;
+      }
+
+      main {
+        max-width: 34em;
+      }
+
+      .code {
+        font-size: 4.5rem;
+        font-weight: 600;
+        line-height: 1;
+        letter-spacing: -0.02em;
+        color: var(--accent);
+      }
+
+      h1 {
+        margin: 16px 0 8px;
+        font-size: 1.5rem;
+        font-weight: 600;
+      }
+
+      p {
+        margin: 0 0 24px;
+        color: var(--muted);
+      }
+
+      .links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 10px;
+      }
+
+      a {
+        display: inline-block;
+        padding: 8px 16px;
+        border: 1px solid var(--line);
+        border-radius: 6px;
+        color: var(--fg);
+        text-decoration: none;
+        transition:
+          border-color 0.15s ease,
+          color 0.15s ease;
+      }
+
+      a:hover {
+        border-color: var(--accent);
+        color: var(--accent);
+      }
+
+      a.primary {
+        background: var(--accent);
+        border-color: var(--accent);
+        color: #fff;
+      }
+
+      a.primary:hover {
+        color: #fff;
+        filter: brightness(1.08);
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="code">404</div>
+      <h1>这里没有这一页</h1>
+      <p>链接可能过期了，或者这个页面已经被重写进了别的章节。从下面这两处开始找会快一些。</p>
+      <div class="links">
+        <a class="primary" href="index.html">回到首页</a>
+        <a href="get-started/index.html">快速上手</a>
+        <a href="app/index.html">应用帮助</a>
+        <a href="management/index.html">管理运维</a>
+        <a href="dev/index.html">开发文档</a>
+      </div>
+    </main>
+  </body>
+</html>

docs/app/appearance.md

@@ -0,0 +1,97 @@
+---
+title: 外观、主题与动效
+description: 深浅色主题、界面风格、设计令牌与动效语言，以及降低动态效果的降级行为。
+---
+
+# 外观、主题与动效
+
+## 深浅色主题
+
+**两端都有深色主题，机制完全一致**：在 `<html>` 上挂 `.dark` 类，由各自的样式表覆盖**语义色令牌**，
+Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts` 都在挂载之前就把主题落好，
+所以深色用户打开时不会"先白后黑"闪一下。
+
+| 行为         | 说明                                                     |
+| ------------ | -------------------------------------------------------- |
+| 默认         | **跟随系统**（`prefers-color-scheme`，系统改了就跟着变） |
+| 手动切换之后 | 以用户的选择为准（系统的偏好是默认值，不是命令）         |
+| 切换入口     | 客户端在顶栏（日月按钮），Web 管理端也在顶栏             |
+| 切换效果     | 从点击位置**扩散的圆**铺满整页换肤                       |
+
+**刻意不随主题的区域**：登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、
+Web 管理端的侧边栏（本来就是深色），以及深色底上的白色文字。
+
+Web 端还会同步 `<meta name="theme-color">`，并设 `color-scheme` 让**原生控件**
+（滚动条、日期选择器弹层、自动填充底色）也跟着走 —— 只改 CSS 变量的话它们会仍是浅色。
+
+## 语义色令牌
+
+组件里**一律引用令牌，不写死颜色**：
+
+| 令牌                                                   | 用途     |
+| ------------------------------------------------------ | -------- |
+| `--ch-surface` / `-alt` / `-sunken` / `-hover`         | 各种表面 |
+| `--ch-text` / `-secondary` / `-muted` / `-placeholder` | 文字层级 |
+| `--ch-radius-xl / lg / md / sm / pill`                 | 圆角     |
+| `--ch-shadow-sm` / `-md`                               | 投影     |
+
+`html.dark` **只覆盖颜色，绝不覆盖圆角与动效令牌** —— 两套主题的几何必须完全一致，
+否则切换时会看到布局跳一下。
+
+> 改令牌时**只改值**，不要对样式表跑批量替换。"把 `#303133` 全量替换成 `var(--ch-text)`"
+> 会把令牌**定义本身**也换掉，自定义属性一旦自引用就整条失效、解析成空串，
+> 全站文字颜色静默回落成继承色。
+
+## 界面风格
+
+- 浅色底 `#f3f3f3` + 半透明卡片（`rgba(255,255,255,.7)` + `backdrop-filter: blur(20px)`）；
+- 强调色 `#0F6CBD`（悬停 `#115EA3`）；选中的导航项 = 强调色淡底 + 左侧 3px 强调条；
+- 圆角统一：卡片 8px / 控件 4px；描边用半透明黑代替灰线；阴影极轻；
+- 字体 `Segoe UI Variable / 微软雅黑 UI`；Element Plus 的变量整体对齐这套规范。
+
+Web 管理端走的是另一套（1Panel 风格：深色侧边栏 + 白色圆角卡片），
+圆角与投影集中定义在它的 `:root` 令牌里。
+
+## 动效语言
+
+两端的动画与过渡统一走一套自研的动效语言，**移植自 [beUI](https://beui.dev) 的 `lib/ease.ts`**。
+beUI 的组件本身是 React，用不到这里，但它的动效语言与框架无关。
+
+- **令牌单一来源**：`packages/shared/src/motion.ts`。三组缓动曲线 + 六组具名弹簧；
+- **弹簧由数值积分算出落定时间**，再生成 CSS `linear()` 缓动字面量 ——
+  于是弹簧可以纯 CSS 驱动，不必给每个组件挂一个 rAF 循环；
+- **运行时注入**：两端在挂载前把令牌写进 `:root` 的自定义属性。CSS 里只引用变量，不抄数值。
+
+落地到界面上的效果：
+
+| 位置                  | 动效                                                               |
+| --------------------- | ------------------------------------------------------------------ |
+| Element Plus 全站过渡 | 时长收紧到 200 / 140ms，缓动换成 EASE_OUT                          |
+| 弹窗 / 抽屉 / 浮层    | 走弹簧；**退出一律比入场快**（用户已经决定关掉它了）               |
+| 按钮                  | 按下 90ms 直落（跟手）、抬起弹回                                   |
+| 侧栏激活项            | 单个"底片"在菜单项之间滑过去，取代"每项各画一块底色"               |
+| 页面内容              | 按块错峰浮现（30ms 一档，封顶 180ms）                              |
+| 统计数字              | 0 → 实际值滚动                                                     |
+| 灵动岛                | **刻意只有单调缓动，不用弹簧**（任何过冲都会让"开合"看起来在震动） |
+
+### 降低动态效果
+
+两端各有一个 `prefers-reduced-motion` 的全局降级块，把动画压到 1ms ——
+**是压短而不是删掉**（`transition: none` 会让依赖 `transitionend` 的逻辑失灵）。
+
+唯一的例外是**加载指示旋**：它是放慢而不是停，停掉会让界面看起来像卡死。
+
+## 客户端设置页
+
+「设置」是一个可展开的分组，六个子页各有自己的路由：
+
+| 子页   | 内容                                                                          |
+| ------ | ----------------------------------------------------------------------------- |
+| 通用   | 服务器连接、离线缓存、作业录入短语、使用引导                                  |
+| 外观   | 浅色 / 深色                                                                   |
+| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝（详见[灵动岛](island.md)） |
+| 提醒   | 通知显示在哪一端                                                              |
+| 账号   | 当前班级信息、退出登录                                                        |
+| 关于   | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢                   |
+
+`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**，重启后仍保留。

docs/app/calls.md

@@ -0,0 +1,57 @@
+---
+title: 叫人
+description: 老师点名让学生过来：普通与紧急两档、快捷短语、谁能叫谁，以及它在教室里的表现。
+---
+
+# 叫人
+
+「叫人」是老师点名让某位同学来一趟 —— 它**不是**一条普通通知，因为它有一个明确的收件人和一个明确的动作
+（学生会点「收到」）。
+
+## 在哪发
+
+| 入口            | 谁能用       |
+| --------------- | ------------ |
+| 通知发布 → 叫人 | 教师、管理员 |
+| 学生管理 → 叫人 | 管理员       |
+
+学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
+
+## 两档
+
+| 级别         | 落库级别 | ClassHelper 班级端行为                                                                                            |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------- |
+| **普通叫人** | `HIGH`   | 课间先显示「叫人」胶囊，点击展开；**上课时段只进队列、不打断课堂**，下课后自动弹出详情（90 秒后收起） |
+| **紧急叫人** | `URGENT` | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开                                        |
+
+两档的卡片都是「请 XXX 同学找 XXX 老师」+ 具体事由，徽标是「叫人」，按钮是「收到」
+（复用通知的已读机制）。
+
+> **是否立即展开只由 `priority` 决定**，与普通通知共用同一条排队 / 隐藏 / 下课弹出路径。
+
+## 怎么说
+
+两种输入方式，**自定义消息优先于快捷短语**：
+
+- **快捷短语**（8 条，点击选中、再点取消）：请到办公室找我 / 请到讲台找我 / 请到实验室找我 /
+  请到门卫处找我 / 请带上作业本找我 / 请带上试卷找我 / 请到教室门口等我 / 请马上来一趟；
+- **自定义消息**：最长 200 字，例如「带上昨天的数学作业到办公室」。
+
+## 谁能叫谁
+
+| 角色   | 限制                                                       |
+| ------ | ---------------------------------------------------------- |
+| 学生   | 调用被拒（403）                                            |
+| 教师   | 只能叫**自己班级**的学生；跨班、或学生不在本班 → 400 / 403 |
+| 管理员 | 任意班级                                                   |
+
+## 服务端做了什么
+
+`POST /api/calls`（教师 / 管理员）→ `urgent: true` 落库成 `URGENT`，否则 `HIGH`，
+然后广播两个事件：
+
+- `notification:new` 到班级房间（通知中心与灵动岛都靠它）；
+- `call:new` 定向到被叫学生 / 班级设备。
+
+如果教室的「通知显示位置」不是"只在 ClassHelper"，这条叫人也会推给 ClassIsland，
+教室大屏一并播报。

docs/app/classes.md

@@ -0,0 +1,98 @@
+---
+title: 班级、学生与教师
+description: 班级账号、学生名单、班主任与各科任课老师，以及"谁能看什么、谁能改什么"。
+---
+
+# 班级、学生与教师
+
+## 班级账号：ClassHelper 班级端的身份
+
+学生**没有个人账号**。一台教室机器用一个**班级账号**登录：
+
+```
+班级码（例如 G203） + 班级密码  →  这台机器代表"高二(3)班"
+```
+
+登录之后，这台机器上的「已读 / 完成 / 未交」都是**代全班**操作的；它看到的是本班的数据。
+
+班级码是管理员在「班级管理」里设的（新建时自动生成，可以改成好记的）。
+校验时会统一按大写比对（码存大写）。
+
+> 班级密码在新建班级时由 `.env` 的 `DEFAULT_CLASS_PASSWORD` 决定初始值，
+> 之后由管理员在「班级管理 → 修改班级账号」维护。
+>
+> **客户端没有改密码入口**，这是刻意移除的：教室机器上误改班级密码会让别的机器登录不了。
+> 教师 / 管理员本人改密码在 Web 端顶栏头像菜单里。
+
+## 学生
+
+**学生管理**（仅管理员）→ 新建 / 导入名单。
+
+学生记录**只是名单**：成绩、未交名单、叫人、已读记录都按名单记录，所以名单不全这几项就不准。
+
+| 项目     | 说明                                                                                 |
+| -------- | ------------------------------------------------------------------------------------ |
+| 用户名   | `^[A-Za-z0-9_.-]{3,32}$`；单个新建时自动生成                                         |
+| 密码     | **没有密码概念**。学生的 `passwordHash` 是空串占位，不能登录，也没有任何重置密码接口 |
+| 所属班级 | 一个学生属于一个主班级                                                               |
+
+> 学生**不是账号**（`Student` 表里没有密码、没有角色），拿学号去登录只会得到 401 ——
+> 否则"密码错(401)"和"密码对但学生账号已停用(403)"的差异会把学生账号密码变成可离线验证的预言机。
+
+## 教师
+
+| 能力                 | 在哪                                             | 谁能做        |
+| -------------------- | ------------------------------------------------ | ------------- |
+| 新建 / 编辑 / 删除   | 「教师管理」                                     | **仅管理员**  |
+| 导入名单（xlsx/csv） | 「教师管理 → 导入名单」                          | **仅管理员**  |
+| 重置密码             | 「教师管理」（可指定新密码，留空用默认初始密码） | **仅管理员**  |
+| 加进某个班           | 班级详情 → 任课老师（班级 + 科目 + 教师）        | 管理员        |
+| 换班主任             | 班级详情顶部「更换班主任」                       | **仅管理员**  |
+
+> **教师录入只有管理员能做**：`/api/teachers` 整组接口都是 `requireRole('ADMIN')`，教师调用返回 403。
+> 前端也只在管理员登录时显示这个菜单项。
+
+### 删除教师有护栏
+
+下面四种情况一律拒绝（409），因为删账号会级联删掉他在各班发过的内容：
+
+1. 他还是某个班的**班主任**；
+2. 名下有**课程**；
+3. 有**任课关系**（`Course.teacherId === 他`）；
+4. **发布过作业或通知**。
+
+（后两项曾经漏检，会静默删掉该教师发过的作业与通知。）
+
+## 角色与可见范围
+
+班级内的角色由「账号角色 + 与该班级的关系」共同决定：
+
+| 角色               | 怎么判定                       | 可见范围                   |
+| ------------------ | ------------------------------ | -------------------------- |
+| `ADMIN` 管理员     | `User.role = ADMIN`            | 全部班级                   |
+| 班主任 `HEAD`      | `Class.teacherId === 当前用户` | 本班                       |
+| 科任老师 `SUBJECT` | 该班 `Course.teacherId` 有当前用户 | 被任课的班级            |
+| 学生 `STUDENT`     | `User.classId` / 班级账号      | 自己的班级（只读业务数据） |
+
+### 权限矩阵（摘要）
+
+| 操作                                 | 管理员 |    班主任    | 科任老师 |
+| ------------------------------------ | :----: | :----------: | :------: |
+| 班级创建 / 修改 / 删除               |   ✅   |      ❌      |    ❌    |
+| 分配班主任与科任老师                 |   ✅   |      ❌      |    ❌    |
+| 学生名单管理（增删 / 导入）          |   ✅   |      ❌      |    ❌    |
+| 教师录入（新建 / 导入 / 改密码）     |   ✅   |      ❌      |    ❌    |
+| 数据库管理（备份 / 导入导出 / 切换） |   ✅   |      ❌      |    ❌    |
+| 课表管理（增删改 / 导入）            |   ✅   | ✅（仅本班） |    ❌    |
+| 布置作业                             |   ✅   |      ✅      |    ✅    |
+| 叫人                                 |   ✅   |      ✅      |    ✅    |
+| 发布通知                             |   ✅   |      ✅      |    ✅    |
+| 成绩录入 / 修改 / 导入（仅本班）     |   ✅   | ✅（仅本班） |    ❌    |
+| 维护班级密码                         |   ✅   |      ❌      |    ❌    |
+
+完整矩阵与实现见[角色与权限](../dev/permissions.md)。
+
+## 学期周数
+
+每个班有自己的学期周数（`Class.termWeeks`，默认 20，上限 30），**只有管理员**能改。
+它决定"现在是第几教学周"，见[课表](schedules.md)。

docs/app/grades.md

@@ -0,0 +1,56 @@
+---
+title: 成绩
+description: 成绩录入与导入、等级与得分率、ClassHelper 班级端看到的全班总览。
+---
+
+# 成绩
+
+## 三种录入方式
+
+Web 管理端「成绩录入」页：
+
+| 方式     | 适合                              | 说明                                                             |
+| -------- | --------------------------------- | ---------------------------------------------------------------- |
+| 单条录入 | 个别缺漏补录                      | 选学生、科目、考试名称、分数、总分                               |
+| 批量录入 | 一次录一个班的某一科              | 一屏列出全班学生，逐个填分                                       |
+| 导入表格 | 已经有 Excel 的（期中期末最常见） | 支持列名同义词映射、先预览再提交，见[表格与课表导入](imports.md) |
+
+**科目**下拉是全校统一的 18 科目录；选中一个该班还没有的科目时，前端会自动为该班建同名课程，
+不用先去把科目建一遍。
+
+## 谁能录
+
+| 角色            | 权限                                   |
+| --------------- | -------------------------------------- |
+| 管理员          | ✅ 全部班级                            |
+| **本班班主任**  | ✅ 仅本班（录入 / 修改 / 删除 / 导入） |
+| 科任老师        | ❌ 403                                 |
+| 学生 / 班级账号 | ❌ 只能看                              |
+
+权限在**服务层**兜底，前端只是按同一份矩阵隐藏按钮。
+
+## 学生看到的是什么
+
+ClassHelper 班级端（教室机器）用的是**班级账号**，所以它看到的不是"我的成绩"，而是**全班成绩总览**：
+
+- 表格：分数 / **得分率** / **等级**；
+- 柱状图；
+- 等级分布；
+- 最近更新。
+
+图表是自研的轻量组件（柱状图是纯 HTML/CSS，折线图是 SVG），项目里**不引图表库**。
+
+> 学生没有个人账号，所以系统里不存在"某个学生登录后看自己的成绩"这条路径。
+> 成绩记录本身是按学生名单存的（`Grade.userId`），只是入口统一在班级账号上。
+
+## 接口
+
+| 方法           | 路径                                           | 权限                        |
+| -------------- | ---------------------------------------------- | --------------------------- |
+| GET            | `/grades/my`                                   | 登录（班级会话 → 全班总览） |
+| GET            | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员               |
+| GET            | `/grades/stats?classId=&courseId=&examName=`   | 教师 / 管理员               |
+| POST           | `/grades`、`/grades/bulk`                      | 班主任 / 管理员             |
+| PATCH / DELETE | `/grades/:id`                                  | 班主任 / 管理员             |
+
+写入后会广播 `grade:updated`，客户端立刻刷新。

docs/app/homeworks.md

@@ -0,0 +1,92 @@
+---
+title: 作业
+description: 作业按所属日期归类、看板与全屏看板、教室机器录入作业、未交名单与附件。
+---
+
+# 作业
+
+## 按「所属日期」归类，不是按录入时间
+
+每份作业有一个**所属日期**（`Homework.assignDate`，形如 `2026-10-06` 的本地日期，不带时区）。
+按天查看、日期高亮、客户端的「只看今天」都看它。
+
+> 用录入时间（`createdAt`）当"哪一天的作业"是错的：它是 UTC，晚上 8 点留的作业会被算到第二天。
+> 系统里统一用「本地日期」，新增按天查询的接口也一样走 `?date=YYYY-MM-DD`。
+
+所以老师可以给今天、明天、甚至补录上周某一天 —— 客户端按日期查得到。
+
+## 两端各自能做什么
+
+| 能力               | Web 管理端（老师）                       | 桌面客户端（教室机器）                          |
+| ------------------ | ---------------------------------------- | ----------------------------------------------- |
+| 按天查看           | 工具栏日期选择器；有作业的日期下面带圆点 | 日期选择器 + 前 / 后一天，支持 `?date=` 深链    |
+| 发布 / 编辑 / 删除 | ✅（教师 / 管理员）                      | ✅ **录入**（班级账号也能发，归属到该班班主任） |
+| 看板模式           | —                                        | ✅ 默认视图                                     |
+| 全屏看板           | —                                        | ✅                                              |
+| 完成情况           | ✅ 按名单统计完成人数                    | ❌ **客户端不显示"已完成 / 待完成"**            |
+| 未交名单           | ✅ 作业详情抽屉里可看可改                | ✅                                              |
+
+> 客户端刻意不显示完成状态：完成与否是**老师端与通知中心**的概念；
+> 教室机器上只做"看作业 + 录作业"两件事。服务端的完成数据与统计接口都还在，Web 端照旧可用。
+
+## 看板模式
+
+客户端作业页默认按**科目**分卡片，每张卡列出该科的所有作业。工具栏可以：
+
+- **看板 / 列表** 切换视图（列表模式有一列"作业要求"全文）；
+- **只看今天** 开关（默认开）；
+- **显示时间** 开关；
+- **字号**滑块（11–28px 即时生效）。
+
+这些偏好存在客户端配置里，重启后仍生效。
+
+卡片里同时渲染**标题 + 作业要求全文**（不截断）。
+
+### 全屏看板
+
+点卡片或「全屏看板」进入。全屏下的排版不是简单地放大：
+
+1. 按"可用宽 × 可用高"枚举 1..N 列，取**单卡面积最大、宽高比最接近 1.15** 的方案；
+2. 再按「内容高度 / 可用高度」整体 `transform: scale()` 缩到刚好铺满 —— 所以**不用上下翻页**；
+3. 标题栏中间绝对居中显示当天日期时间（受「显示时间」开关控制，每分钟刷新）。
+
+> 字号仍由工具栏的滑块决定，缩放只负责"放得下"。工具栏上会显示当前缩放比例。
+
+## 教室机器录入作业
+
+教室里那台机器用**班级账号**登录，可以直接发作业。两个细节：
+
+- 服务端拿到的是班级账号的会话（`sub` 是班级 id），写 `createdBy` 前会换成该班班主任，
+  否则会撞外键。
+- **本机刚录入的那条不会弹到灵动岛上**——自己通知自己没意义。这条判断是在发请求**之前**
+  按内容登记指纹做的（服务端是先广播后回响应，等拿到 id 再登记就晚了）。
+
+录入时可以点**快捷短语**（默认 `P` / `大本` / `小本` / `卷子` / `背诵` / `默写` / `听写` / `预习` /
+`订正` / `读书`），点一下追加到标题或内容。短语可以在客户端「设置 → 通用」里增删，存在本机。
+
+## 未交名单
+
+在作业列表或详情里点「未交名单」→ 勾选**没交作业**的同学 → 保存。
+
+其余同学会被自动标记为已完成（接口是 `PATCH /api/homeworks/:id/submissions`）。
+Web 端作业详情抽屉里同样可看可改。
+
+> 名单来自班级的学生名单 —— 名单不全，这项就不准。见[班级、学生与教师](classes.md)。
+
+## 附件
+
+作业可以带一个附件链接。**只接受 `http(s)://` 或站内相对路径**，其他 scheme（`javascript:`、
+`data:text/html` 等）服务端会直接拒；Web 端渲染前还会再兜一层。
+放行这些 scheme 等于给了一条存储型 XSS。
+
+## 实时推送
+
+发布 / 修改 / 删除作业会分别广播：
+
+| 事件               | 客户端反应                            |
+| ------------------ | ------------------------------------- |
+| `homework:new`     | 作业列表刷新 + 灵动岛弹「新作业」胶囊 |
+| `homework:updated` | 刷新；带 `deleted: true` 表示删除     |
+| `homework:status`  | 完成状态变化时刷新统计                |
+
+课表、作业、通知、成绩都是同一个套路：写库 → 按班级房间广播 → 客户端更新内存状态并写回 IndexedDB。

docs/app/imports.md

@@ -0,0 +1,115 @@
+---
+title: 表格与课表导入
+description: 成绩、学生名单、教师名单的表格导入，以及从 ClassIsland 档案导入节次时间与课表。
+---
+
+# 表格与课表导入
+
+五条导入链路**都在服务端完成解析、校验与去重**，前端只负责收集文件与展示结果。
+所以 Web 端、客户端与直接调接口拿到的结果是同一套规则、同一份统计。
+
+## 通用流程
+
+表格类导入都是三段式（成绩 / 学生 / 教师都一样）：
+
+1. **下载模板** —— `GET /imports/template?kind=grades&format=xlsx|csv`。
+   CSV 带 BOM，Excel 直接双击打开不乱码。
+2. **上传预览** —— 服务端返回列名、前 20 行、总行数与**建议的字段映射**，以及校验问题。
+   列名按同义词自动映射（「用户名→学号」「得分→分数」「满分→总分」「课程→科目」……），也可以手动改。
+   **缺必填列不会静默通过**，会直接给出「缺少必填列「…」」。
+3. **确认导入** —— 按映射与写入模式提交：
+
+   | 模式     | 已存在的记录 |
+   | -------- | ------------ |
+   | `upsert` | 更新（默认） |
+   | `append` | 跳过         |
+
+   返回 `{ total, inserted, updated, skipped, failed, errors[], warnings[] }`。
+   `errors[].row` 是 **Excel 视角的行号（含表头）**，方便老师改完再导。
+
+**体积限制**：文件上限 **8MB**，请求体上限 12MB（文件以 base64 放进 JSON，约 4/3 倍）。
+超限返回 413 `IMPORT_TOO_LARGE` 与中文提示 —— 如果你看到一句英文的「request entity too large」，
+那说明这个异常没被映射，属于 bug。
+
+## 1. 成绩表格导入
+
+- 入口：成绩录入 → 「导入表格」
+- 模板列：`学生学号 / 学生姓名 / 考试名称 / 分数 / 总分 / 科目 / 等级`
+- 支持 `.xlsx / .xls / .csv / .tsv`（自动识别分隔符）
+- **重复判定**：同班级 + 同学生 + 同考试 + 同课程
+- 学生按「用户名」优先、「姓名」兜底匹配
+
+## 2. 学生名单导入
+
+- 入口：学生管理 → 「导入名单」（仅管理员）
+- 模板列：`学号 / 姓名 / 班级 / 性别 / 家长手机号` —— 学生**不是账号**，没有密码列
+- 用户名必须匹配 `^[A-Za-z0-9_.-]{3,32}$`
+- 用户名已经被某个教师 / 管理员账号占用时，**这一行进错误列表**，不会覆盖他人账号
+
+## 3. 教师名单导入
+
+- 入口：教师管理 → 「导入名单」（仅管理员）
+- 模板列：`工号 / 姓名 / 手机号 / 初始密码 / 角色`
+- 角色取 `ADMIN` / `TEACHER`，留空按 `TEACHER`
+- 与新建教师同一套校验，导入完可以直接登录
+
+## 4. 从 ClassIsland 导入课程表
+
+**这是最省事的一条路**：如果教室里已经在用 ClassIsland，直接导入它的档案 JSON，
+课表、节次时间、单双周会一起进来，不用排两遍。
+
+- 入口：课表管理 → 「导入 ClassIsland 课程表」
+- 输入：同一份档案 JSON（`ClassPlans` / `TimeLayouts` / `Subjects` 三个字典），
+  粘贴或选择 `.json` 文件
+
+### 真实档案的形态
+
+ClassIsland 2.x 的档案在 `Profiles/<档案名>.json`，字段是 PascalCase：
+
+```jsonc
+{
+  "TimeLayouts": {
+    "<guid>": { "Name": "…", "Layouts": [{ "StartTime": "08:00:00", "EndTime": "08:45:00", "TimeType": 0 }] },
+  },
+  "ClassPlans": { "<guid>": { "Name": "…", "Classes": [/* 与上课时间点逐位对齐 */] } },
+  "Subjects": { "<guid>": { "Name": "语文" } },
+}
+```
+
+解析器同时兼容顶层数组、`{ TimeLayouts: [...] }`、`{ items | Items | Layouts | TimeLayout: [...] }`
+与单个时间表对象。
+
+| 细节         | 说明                                                                                                                    |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| 时间字段     | `StartTime` / `EndTime`（`"08:00:00"`）；旧版 `StartSecond` / `EndSecond`（ISO 字符串或秒数）；`"8:0"` / `"08:00"` 都认 |
+| `TimeType`   | `0=上课`、`1=课间`、`2=分割线`、`3=行动`，与 ClassIsland 一致                                                           |
+| **节次对齐** | `ClassPlan.Classes[i]` 对应 `Layouts` 里**第 i 个 `TimeType === 0` 的时间点**（课间、分割线不占位）                     |
+| 单双周       | `TimeRule.WeekCountDiv`（`0=每周`、`1=单周`、`2=双周`）+ `WeekCountDivTotal`（默认 2）                                  |
+| 星期换算     | ClassIsland 是 `0=周日 … 6=周六`，导入时换算成 `1=周一 … 7=周日`                                                        |
+| 科目映射     | `Subjects[<guid>].Name`；该班还没有的科目**自动补建课程**（任课老师取该班班主任），预览里会提前列出                     |
+| 写入模式     | `replace` 清空该班课表后写入（事务内完成）/ `merge` 按「星期 + 开始时间 + 单双周」去重                                  |
+
+**解析出 `errors` 时返回 400 且数据库完全不写入**（`IMPORT_INVALID` / `IMPORT_EMPTY`）——
+先保证不写坏，再谈导入。
+
+时间重叠、分割线没有时间这类问题只作 `warnings`，不阻断导入。
+
+> **3 周及以上的轮换**没法用单双周表达，会给出 warning 并按"每周"处理。
+
+## 5. 只导入节次时间（旧入口）
+
+「导入时间配置」按钮**已经下线** —— 因为同一份档案 JSON 里的 `TimeLayouts` 已经跟着课表一起进来了。
+组件与接口（`/imports/time-layout/*`）仍然保留给旧脚本调用。
+
+它的写入模式也是 `replace`（整体替换该班同名配置）与 `merge`（以**开始时间**为槽位标识合并，
+同槽位被导入项覆盖，其它旧节次保留，不静默丢数据）。
+
+## 相关接口
+
+| 路径                                                   | 说明                                       |
+| ------------------------------------------------------ | ------------------------------------------ |
+| `/imports/template?kind=&format=`                      | 下载模板（`csv` 走 JSON，`xlsx` 走二进制） |
+| `/imports/table/preview`                               | 上传解析预览（base64）                     |
+| `/imports/table/commit`                                | 按映射与模式导入                           |
+| `/imports/class-plan/preview`、`/imports/class-plan`   | ClassIsland 课程表预览 / 导入              |
+| `/imports/time-layout/preview`、`/imports/time-layout` | 时间配置预览 / 导入（旧入口）              |

docs/app/index.md

@@ -0,0 +1,49 @@
+---
+title: 应用帮助
+description: ClassHelper每一项功能怎么用：课表、作业、通知、叫人、成绩、班级、灵动岛、外观与导入。
+---
+
+# 应用帮助
+
+这一章按功能讲，重点是**行为上的约定**——什么时段会弹、谁看得见、什么情况下不动。
+很多"看起来像故障"的现象其实是设计行为，下面每一页都会点出来。
+
+| 页面                              | 讲什么                                                 |
+| --------------------------------- | ------------------------------------------------------ |
+| [课表](schedules.md)              | 周视图与「今天」时间轴、单双周、学期周数、课表来源     |
+| [作业](homeworks.md)              | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
+| [通知与提醒](notifications.md)    | 三档优先级、上课时段策略、二次确认、已读与红点         |
+| [叫人](calls.md)                  | 普通叫人与紧急叫人的差别、快捷短语、谁能叫谁           |
+| [成绩](grades.md)                 | 录入方式、导入、等级分布、学生看到的是什么             |
+| [班级、学生与教师](classes.md)    | 班级账号、名单、班主任与各科任课老师、谁看得见什么     |
+| [灵动岛](island.md)               | 胶囊与卡片、多条通知的竖排列表、停靠与外观、触摸屏     |
+| [外观、主题与动效](appearance.md) | 深浅色、设计令牌、动效语言、降低动态效果               |
+| [表格与课表导入](imports.md)      | 成绩 / 名单 / 教师表格导入与 ClassIsland 档案导入      |
+
+## 贯穿所有功能的三条规则
+
+**一、角色决定可见范围。** 同一个页面，管理员、班主任、科任老师看到的数据与能点的按钮都不一样。
+前端会按权限隐藏入口，但**真正拦人的是服务端**——直接调接口一样会被拒。完整矩阵在
+[角色与权限](../dev/permissions.md)。
+
+**二、上课时段不打扰课堂。** 「上课时段」由课表实时判定，普通通知与普通叫人只进队列、下课补弹；
+紧急通知与紧急叫人才会立刻打断。规则只有一份，客户端与 ClassIsland 都遵守它。
+细节见[通知与提醒](notifications.md)。
+
+**三、实时推送只走班级房间。** 老师一发内容，服务端写库后按班级房间广播，客户端立刻更新，
+不靠轮询。教室机器断线重连后会自动补上漏掉的数据，灵动岛也会把上课期间暂存的通知补弹出来。
+
+## 两端的差异
+
+同一件事在 Web 管理端和桌面客户端上不一定完全一样，这是有意的：
+
+| 事情       | Web 管理端（老师）              | 桌面客户端（教室机器）                                    |
+| ---------- | ------------------------------- | --------------------------------------------------------- |
+| 作业       | 发布 / 编辑 / 删除 / 看未交名单 | 看作业 + **录入作业** + 勾未交名单，不显示"完成 / 待完成" |
+| 成绩       | 录入 / 导入 / 改 / 删，带统计   | 只看全班总览                                              |
+| 课表       | 排课、导入、改                  | 只看（周视图 + 今天时间轴）                               |
+| 通知       | 发布 / 删除 / 看已读            | 看、标为已读                                              |
+| 班级与人员 | 管理员可管                      | 只能看本班                                                |
+
+> 客户端没有"修改密码"入口，是**刻意移除的**：防止教室机器上误改班级密码后，
+> 别的教室机器被锁在门外。班级密码由管理员在 Web 端维护。

docs/app/island.md

@@ -0,0 +1,121 @@
+---
+title: 灵动岛
+description: 桌面客户端的通知浮窗：胶囊与卡片、多条通知的竖排列表、停靠与外观、触摸屏下的行为。
+---
+
+# 灵动岛
+
+灵动岛是桌面客户端上那个独立于主窗口的浮窗：无边框、透明、置顶、不占任务栏。
+它是「消息到达的第一现场」—— 老师发的内容先在岛上出现，学生点开才进主界面。
+
+视觉参照 [WinIsland](https://github.com/WinIslandProject/WinIsland)：
+连续圆角（超椭圆）而不是 `border-radius`、纯黑 / 毛玻璃 / 主题色三种底、Apple 系统色强调色、
+6 个停靠位、可选的「空闲细缝」。逐项设计令牌见[灵动岛设计令牌](../dev/winisland-design-tokens.md)。
+
+## 各形态长什么样
+
+| 形态                   | 截图                                                  | 说明                                              |
+| ---------------------- | ----------------------------------------------------- | ------------------------------------------------- |
+| 非上课时段的「新消息」 | ![新消息胶囊](../images/island-4-pill.png)            | 268×44，直接出现（无入场动画），点击后展开        |
+| 点开后的详情卡         | ![点击后展开](../images/island-5-clicked.png)         | 标题 / 内容 / 时间 + 打开应用 / 标为已读 / 知道了 |
+| 下课后自动弹出         | ![下课后自动弹出](../images/island-2-after-class.png) | 上课期间暂存的通知，下课后自动弹出                |
+| 上课期间的紧急通知     | ![紧急通知立即展开](../images/island-3-urgent.png)    | 卡片**内部**红色光晕 + 紧急角标，无需点击         |
+| 新作业                 | ![新作业](../images/island-7-homework.png)            | 青蓝描边 + 书本图标                               |
+| 叫人                   | ![叫人](../images/island-8-call.png)                  | 琥珀金卡片 + 「叫人」徽标 + 「收到」按钮          |
+
+## 什么时候弹、弹成什么样
+
+| 场景                              | 灵动岛行为                                                                                    |
+| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| 收到通知（非上课时段）            | 直接出现胶囊：`新消息 · 共 N 条` + 发送人 + `点击查看`                                        |
+| 多条未处理消息                    | 胶囊标题汇总类型：`新消息：叫人/作业/通知（共 3 条）`，右侧带类型小标签                       |
+| 点击胶囊（只有一条）              | 展开为**详情卡**：标题、内容、时间 + 三个按钮                                                 |
+| **点击胶囊（多条）**              | 展开为**竖排列表**，按重要程度排序（紧急 > 重要 > 普通 > 低，同级按时间新的在前）             |
+| **点「展开更多」**                | 把放得下的都铺出来；铺到工作区下沿还放不下时改成「更多请前往应用内操作」                      |
+| **多条时的「知道了 / 标为已读」** | 都是**整批**操作                                                                              |
+| 上课时段的**普通叫人**            | **不自动展开**（不打断课堂），但保留胶囊并**允许学生主动点开**；下课自动展开                  |
+| **紧急叫人**                      | 上课时段也立即展开，卡片是琥珀金 + 「叫人」徽标，按钮为「收到」                               |
+| 上课时段的普通通知                | **完全不显示**（窗口隐藏）并进队列；下课自动弹出详情 → 收起为胶囊                             |
+| 上课时段的紧急通知                | **无论是否上课立刻展开**，45 秒后收起                                                         |
+| 点击卡片空白处 / 屏幕任意位置     | 回缩为**胶囊**（不直接消失，仍可再次点开）                                                    |
+| **收起后胶囊常驻**                | 只要还有未处理通知，胶囊就不会消失；彻底消失只在「知道了 / 标为已读」、队列清空或进入上课时段 |
+
+> **本机刚录入的作业不会上岛** —— 自己通知自己没意义。
+
+## 多条通知时的排版
+
+这是最容易出问题的地方：卡片要长高，还得刚好放得下。规则是**主进程与渲染进程各算一次同一个数**
+（`islandListLayout()`，在 `@classhelper/shared` 里）：
+
+- 默认只显示前 `defaultVisibleRows`（3）条，下面是「展开更多（还有 N 条）」；
+- 点开后铺到 `maxCardHeight` 为止，仍放不下的改成「更多请前往应用内操作」；
+- `maxCardHeight` 是主进程按工作区 / 任务栏算出的**可用高度**，随状态下发。
+
+窗口的包围盒会**在卡片形变之前**先长高（这一步用户看不到），否则底部的按钮会被裁掉。
+
+## 外观设置
+
+客户端「设置 → 灵动岛」：
+
+| 设置项          | 区间 / 取值                            | 默认                      |
+| --------------- | -------------------------------------- | ------------------------- |
+| 高度            | 36–72px                                | 44                        |
+| 宽度            | 220–420px                              | 268                       |
+| 圆角            | 8–32px                                 | 20                        |
+| 不透明度        | 40%–100%                               | 100%                      |
+| **字号**        | 11–20px                                | 13                        |
+| 动画速度        | 0.5×–2×                                | 1×                        |
+| 主题色          | 取色器                                 | `#0a84ff`（Apple 系统蓝） |
+| **视觉风格**    | 纯黑 / 毛玻璃 / 主题色渐变             | 纯黑                      |
+| **显示位置**    | 顶部 / 底部 × 左 / 中 / 右（6 个锚点） | 顶部居中                  |
+| 左右 / 上下边距 | 0–200px / 0–160px                      | 都是 8px                  |
+| 跟随鼠标屏幕    | 开 / 关                                | 关                        |
+| 动画开关        | 开 / 关                                | 开                        |
+| 始终置顶        | 开 / 关                                | 开                        |
+| **空闲细缝**    | 开 / 关                                | 关                        |
+
+几个容易困惑的点：
+
+- **字号是"基础字号"**：岛内所有文本 = 基础字号 × 各自的排版系数（标题 1.08 / 正文 0.95 / 次要 0.78 /
+  徽标 0.76 / 胶囊标题 0.92 ……），所以调一个滑块就能整体放大，比例不会乱。
+- **左右边距只在「左 / 右停靠」时生效**：默认是「顶部居中」，水平锚点就是屏幕中线，
+  这时调左右边距不会有任何变化 —— 设置页会把那个滑块置灰并写明原因。
+- **「毛玻璃」不是窗口材质**，是 CSS 半透明深色卡。用系统级背景材质（`setBackgroundMaterial`）
+  会在卡片外那一圈垫出一块浅色"白底面板"，而且**调用过一次就再也回不去逐像素透明**。
+- **「预览效果」**会本地推一条通知，立刻看到当前尺寸 / 配色 / 动画。预览是专用通道：
+  直接展开、失焦不收起、30 秒后自行消失。
+
+越界的值在**主进程**统一夹紧，配置填坏了也不会让布局错乱。
+
+## 触摸屏（希沃白板等）
+
+触摸屏上灵动岛走的是**另一条命中链路**。
+
+原因：常规的命中判定有两条路径 ——渲染进程转发鼠标移动、主进程读系统光标位置 ——
+**两条都以"鼠标指针移动"为前提**。而手指触摸既不产生 `mousemove`、也不移动系统光标，
+窗口就会永远停在"穿透"状态，**手指点不开岛**。
+
+修法是：客户端检测到 `navigator.maxTouchPoints > 0` 后进入触摸模式，
+把窗口**贴合岛体**并**始终接收输入**（Windows 上 Electron 没有窗口区域能力，这是唯一可行的办法）。
+
+触摸模式下有三条额外的护栏，都是为了不闪、不裁：
+
+- **窗口可见期间只缩不放**（需要变小一律等窗口隐藏之后再做）；
+- 命中矩形按**窗口实际尺寸**算偏移；
+- 失焦宽限期放宽到 1200ms（触摸没有光标，"假失焦"会让刚展开的岛被缩回胶囊）。
+
+非触摸屏的机器**完全不走这条路**。
+
+## 鼠标穿透
+
+窗口是按最大形态创建的固定包围盒，比卡片大一圈。默认整块穿透，渲染层做命中测试，
+只在指针进入岛体时打开命中 —— 所以这个"大窗口"不会吞掉桌面上的点击。
+另有一层保险：主进程每 120ms 用系统光标位置校正一次命中。
+
+## 排查"闪一下"
+
+- **开合时底座闪一下**：卡片投影是常驻的 CSS `filter`，形态切换只改参数。
+  给元素增删 `filter` 会让 Chromium 重建渲染表面，首帧可能被当成空内容画出去。
+- **收回一瞬间闪一下**：多半是**自动化验证实例的叠影**，不是产品的问题 ——
+  冒烟会真的在屏幕上放一个灵动岛，如果它和你自己的客户端叠在一起，你看到的是两个窗口。
+  （验证实例的岛是洋红主题色，一眼可辨。）

docs/app/notifications.md

@@ -0,0 +1,91 @@
+---
+title: 通知与提醒
+description: 通知的三档优先级、上课时段策略、紧急通知的二次确认、提醒弹在哪个端、已读与红点。
+---
+
+# 通知与提醒
+
+通知是这套系统里规则最多的一项 —— 因为它要在"老师想说"和"别打断上课"之间做取舍。
+这一页把规则一次讲清楚。
+
+## 三档优先级
+
+| 优先级 | ClassHelper 班级端表现                                                                                   |
+| ------ | -------------------------------------------------------------------------------------------- |
+| 普通   | 课间弹「新消息」胶囊，点击展开详情；**上课时段完全不显示**（窗口隐藏）并进队列，下课自动补弹 |
+| 重要   | 同上，卡片上有优先级标签                                                                     |
+| 紧急   | **无论是否上课都立即展开**，卡片内部红色呼吸光晕 + 「紧急」角标，无需点击，45 秒后收起       |
+
+紧急通知的光晕画在**卡片内部**（`inset` 阴影），因为窗口比卡片只大 2~4px，向外的阴影会被裁成硬边。
+
+## 上课时段策略
+
+「上课时段」由课表实时判定（见[课表](schedules.md)）。判定之后：
+
+| ClassHelper 班级端行为 | 上课时段                                 | 课间 / 放学 |
+| ---------- | ---------------------------------------- | ----------- |
+| 普通通知   | 收着不弹（窗口隐藏），进待发队列         | 直接弹      |
+| 紧急通知   | **立刻弹**                               | 立刻弹      |
+| 任何点击   | 一律不响应（不会展开、也不会回缩出胶囊） | 正常        |
+
+ClassIsland 那一端遵守同一套规则，否则会出现"学生在客户端看不到、却在教室大屏上被打断"。
+
+## 紧急通知的二次确认
+
+上课时段发紧急通知，**服务端会拦一次**（`409 URGENT_DURING_CLASS`）：
+
+```
+POST /api/notifications { classId, title, content, priority: "URGENT" }
+  → 409 URGENT_DURING_CLASS（响应体里带着正在上的那节课）
+
+POST /api/notifications { …, priority: "URGENT", confirmDuringClass: true }
+  → 201 发出去
+```
+
+Web 端在提交前会先查一次上课状态，命中就弹一个**全屏二次确认**：全屏遮罩 + 强警示配色，
+文案是"现在为上课时间段……" + 正在上的课时段 + 待发布的标题。确认按钮带 **3 秒倒计时**
+（圆环进度），倒计时结束前点不动，防误触。
+
+**这个拦截在服务端，不是前端提醒。** 绕过界面直接调接口一样会被拦 —— 这是产品行为，不是可以关掉的提示。
+
+## 提醒弹在哪个端
+
+教室机器上的客户端「设置 → 提醒」里选，选择会同步到班级记录：
+
+| 选择                                      | ClassHelper 客户端             | ClassIsland |
+| ----------------------------------------- | ------------------------------ | ----------- |
+| `ClassHelper 与 ClassIsland 都弹`（默认） | 弹窗 + 灵动岛                  | 全屏提醒    |
+| `只在 ClassHelper 客户端弹`               | 弹窗 + 灵动岛                  | 不推送      |
+| `只在 ClassIsland 上弹`                   | 只进通知中心（不弹窗、不上岛） | 全屏提醒    |
+
+这条规则**任何入口都遵守**，包括 ClassIsland 联动页的「下发提醒」——
+那种情况下会回一句"该班教室已设置为只在 ClassHelper 客户端显示"。
+
+管理员与教师也可以用 `PATCH /api/classes/:id/notification-channel` 改，但默认由教室机器自己定。
+
+## 已读、红点与删除
+
+| 能力     | 说明                                                                           |
+| -------- | ------------------------------------------------------------------------------ |
+| 未读红点 | 客户端侧边栏「通知」项右上角的徽标；数字来自 `GET /notifications/unread-count` |
+| 标为已读 | 点开通知自动标为已读；也有「全部已读」                                         |
+| 班级设备 | 教室机器的"已读"是**代全班**操作的（它用的是班级账号）                         |
+| 删除     | 只有教师 / 管理员能删                                                          |
+
+## 发布入口只有一个实现
+
+「通知发布」页、叫人、ClassIsland 联动页的「下发提醒」三个入口，
+**共用同一份 ClassIsland 推送实现**。所以不存在"某个页面发的通知不联动"这种事 ——
+以前有过，现在是硬约定：新增发通知的入口必须复用同一份代码。
+
+## 接口
+
+| 方法   | 路径                                                     | 说明                            |
+| ------ | -------------------------------------------------------- | ------------------------------- |
+| GET    | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 列表（带已读状态）              |
+| GET    | `/notifications/unread-count`                            | 未读数                          |
+| POST   | `/notifications`                                         | 发布（广播 `notification:new`） |
+| POST   | `/notifications/:id/read`、`/notifications/read-all`     | 标记已读                        |
+| DELETE | `/notifications/:id`                                     | 删除                            |
+
+完整清单见 [REST API](../dev/api.md)。

docs/app/schedules.md

@@ -0,0 +1,82 @@
+---
+title: 课表
+description: 周课表与「今天」时间轴、单双周、学期周数、课表来源，以及上课时段是怎么判定的。
+---
+
+# 课表
+
+课表不只是"给学生们看看"的表格 —— **「上课时段」的判定完全基于它**。
+课表排错，提醒就会在该弹的时候不弹。所以这一页值得读完。
+
+## 两个视图
+
+| 视图           | 在哪                                      | 内容                                                     |
+| -------------- | ----------------------------------------- | -------------------------------------------------------- |
+| **周视图**     | Web 端「课表管理」、客户端「课表 → 本周」 | 节次 × 星期 的 7 列表格                                  |
+| **今天时间轴** | 客户端「课表 → 今天」                     | 大时钟 + 当前状态卡 + 时间轴（已结束 / 正在上 / 下一节） |
+
+「今天」时间轴是客户端默认打开的那一屏：
+
+- **大时钟**：时:分（大字）+ 秒（小字），下面一行是日期 / 星期 / 第 N 教学周。
+- **当前状态卡**：「正在上 XXX」+ 时段地点 + **距下课 X 分钟**；没课时显示"今天的课都上完了"或"今天没有课程安排"。
+- **时间轴**：左侧时间栏（开始 / 结束）+ 竖向轨道与节点 + 右侧课卡。已结束的置灰、
+  正在上的用强调色实底 + 进度条 + 距下课倒计时、下一节用橙色标记 + "还有多久开始"。
+
+## 单双周
+
+一门课可以设成**每周**（默认）、**单周**或**双周**。判定口径是 **第 1 周 = 单周**。
+
+从 ClassIsland 导入时，`WeekCountDiv`（`0=每周 / 1=单周 / 2=双周`）会换算成这套 `ALL / ODD / EVEN`。
+**3 周及以上的轮换没法用单双周表达**，导入时会给出 warning 并按"每周"处理 ——
+如果学校里真的是三周轮换，目前只能用两份课表 + 手工切换的方式绕过。
+
+## 学期周数
+
+每个班有自己的**学期周数**（`Class.termWeeks`，默认 20，**上限 30**），只有管理员能改。
+
+它决定三件事：课表的周次下拉能选到第几周、`weekEnd` 的默认值、以及"现在是第几教学周"。
+周次换算的起点是服务端 `.env` 里的 `TERM_START_DATE`（当学期第 1 教学周的周一）。
+
+> **`TERM_START_DATE` 设错，整套周次都错。** 它不在界面上改，要改 `.env` 后重启服务端。
+> 上限三处必须一致（`MAX_TERM_WEEK`、周次校验、班级设置），曾经出现过"班级能设到 40 周、
+> 而课表只到 30 周"的错位。
+
+## 上课时段是怎么判定的
+
+服务端有一个接口专门回答"这个班现在是不是在上课"：
+
+```
+GET /api/schedules/current?classId=<班级 id>[&at=<ISO 时间>]
+```
+
+返回 `{ inClass, current, next, week, serverTime }`。`at` 参数可以覆盖判定时刻，用来联调与测试。
+
+判定结果被用在四处，规则完全一致：
+
+1. 客户端灵动岛：上课时段普通通知**不显示**（窗口直接隐藏）并进队列，下课自动补弹；
+2. ClassIsland 插件：同样暂存，下课后补弹；
+3. 服务端发布接口：上课时段发紧急通知会被拦（`409 URGENT_DURING_CLASS`），确认后放行；
+4. Web 端：提交紧急通知前先查一次状态，命中就弹全屏二次确认。
+
+## 课表的"来源"字段
+
+每一行课表都记着它是从哪来的：
+
+| 来源          | 什么时候产生                                   | 会被自动清理吗               |
+| ------------- | ---------------------------------------------- | ---------------------------- |
+| `manual`      | Web 端手工录入、从 ClassIsland JSON 一次性导入 | **不会**，永远保留           |
+| `classisland` | 教室插件上报同步过来的                         | 会——本次没再上报的行会被删掉 |
+
+这条规则解决了"老师在 ClassIsland 里删掉一节，小助手这边却永远留着"的幽灵课问题，
+同时保证老师在小助手这边手排的课不会被插件覆盖掉。
+
+> 去重键是「星期 + 开始时间 + 单双周」。如果老师手排的某一节恰好和上报的同一时间槽重合，
+> 那一行会被上报"收养"（保留原本的 `manual` 来源），下一次清理不会删它。
+
+## 排课 / 改课 / 导入
+
+- 手工排课在 **课表管理**（管理员 / 本班班主任）。科目下拉是全校统一的 18 科目录，
+  选中一个该班还没有的科目会自动建课。
+- 从 ClassIsland 档案导入最省事，课表、节次时间、单双周会一起进来，
+  见[表格与课表导入](imports.md)。
+- 课表变更后会广播 `schedule:updated`，客户端与灵动岛立刻刷新。

docs/app/toc.yml

@@ -0,0 +1,20 @@
+- name: 应用帮助
+  href: index.md
+- name: 课表
+  href: schedules.md
+- name: 作业
+  href: homeworks.md
+- name: 通知与提醒
+  href: notifications.md
+- name: 叫人
+  href: calls.md
+- name: 成绩
+  href: grades.md
+- name: 班级、学生与教师
+  href: classes.md
+- name: 灵动岛
+  href: island.md
+- name: 外观、主题与动效
+  href: appearance.md
+- name: 表格与课表导入
+  href: imports.md

docs/build.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * 文档站构建脚本 —— `pnpm docs:build`。
+ *
+ * 为什么不用直接跑 `docfx docs/docfx.json`：
+ *   1) 站点版本号取自根 package.json（单一来源），DocFX 的配置文件是静态 JSON、读不了文件，
+ *      只能用 CLI 的 `--metadata` 传进去（模板里以 `{{_chVersion}}` 引用）；
+ *   2) GitHub Pages 的项目页挂在 /<仓库名>/ 子路径下，404 页里的相对链接必须相对**站点根**
+ *      而不是相对被请求的那个不存在的路径，因此 404 页的 `<base>` 由这里注入（DOCS_BASE 控制）。
+ *
+ * 用法：
+ *   node docs/build.mjs                 # 构建到 docs/_site
+ *   DOCS_BASE=/classhelper/ node docs/build.mjs
+ *   node docs/build.mjs --check         # 构建并把 docfx 的警告当成错误（CI / 交付前用）
+ *   node docs/build.mjs --serve         # 构建完起本地预览（等价于再跑 docs/serve.mjs）
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const siteDir = path.join(here, '_site');
+
+/** 站点根路径。CI 里按仓库名传进来；本地预览用 './'。 */
+const BASE = process.env.DOCS_BASE ?? './';
+
+function readVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+/** 找不到 docfx 时给出可照抄的安装命令，而不是一句 spawn ENOENT */
+function ensureDocfx() {
+  const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' });
+  if (probe.status === 0) return probe.stdout.trim();
+
+  console.error('[docs] 找不到 docfx。docfx 是 .NET 工具，安装方式：');
+  console.error('');
+  console.error('  dotnet tool install --global docfx');
+  console.error('');
+  console.error('  需要 .NET SDK 8（判据是 `dotnet --list-sdks` 有输出）。');
+  console.error('  想把工具装进仓库内（不污染全局）：');
+  console.error('    DOTNET_CLI_HOME=./.cache/dotnet-home NUGET_PACKAGES=./.cache/nuget \\');
+  console.error('      dotnet tool install --global docfx');
+  process.exit(2);
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32', ...options });
+    child.on('error', reject);
+    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`))));
+  });
+}
+
+/**
+ * 清空上一轮的产物。docfx 不负责清理，旧文件（改过名 / 删掉的页面）会一直留着，
+ * 而 GitHub Pages 上传的是整个目录 —— 不清就会把已下线的页面继续挂在线上。
+ */
+function cleanSite() {
+  const sleep = (ms) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      /* 同步等待：这是构建脚本，不值得为几毫秒引入异步 */
+    }
+  };
+  for (let attempt = 1; attempt <= 5; attempt += 1) {
+    try {
+      fs.rmSync(siteDir, { recursive: true, force: true });
+      return;
+    } catch (error) {
+      if (attempt === 5) {
+        throw new Error(
+          `清不掉 ${path.relative(root, siteDir)}（${error.code ?? error.message}）。` +
+            ' 多半是预览服务或编辑器正占用它 —— 关掉再试。',
+        );
+      }
+      sleep(250 * attempt);
+    }
+  }
+}
+
+/**
+ * 生成 404 页。
+ * GitHub Pages 对项目页的未知路径返回站点根的 404.html，而浏览器是**按请求的路径**解析相对链接的，
+ * 所以页面里的 <base> 必须显式指向站点根，否则 /classhelper/get-started/typo 会去解析
+ * /classhelper/get-started/ 下的链接。本地预览时 BASE 为 './'，正好等价于同目录。
+ */
+function writeNotFound() {
+  const template = fs.readFileSync(path.join(here, '404.html'), 'utf8');
+  const html = template.replaceAll('{{BASE}}', BASE);
+  fs.writeFileSync(path.join(siteDir, '404.html'), html, 'utf8');
+  console.log(`[docs] 404.html（base = ${BASE}）`);
+}
+
+async function main() {
+  const version = readVersion();
+  const docfxVersion = ensureDocfx();
+  console.log(`[docs] docfx ${docfxVersion} · 站点版本 ${version}`);
+
+  // --check：把警告当错误。最常见的警告是"某个 .md 没被任何 toc.yml 引用"，
+  // 那种页面会被构建出来但没有侧边栏，属于必须修掉的疏漏。
+  const check = process.argv.includes('--check');
+  const args = ['build', 'docfx.json', '--metadata', `_chVersion=${version}`];
+  if (check) args.push('--warningsAsErrors');
+
+  // docfx 只覆盖、不清理：删掉或改名的页面会以旧文件的形式留在 _site 里，
+  // 而 GitHub Pages 上传的是整个目录 —— 不清理就会把已经下线的页面继续挂在线上。
+  // Windows 上目录偶尔会被瞬时占用（编辑器 / 索引 / 预览进程），所以重试几次再放弃。
+  cleanSite();
+
+  await run('docfx', args, { cwd: here });
+
+  writeNotFound();
+  console.log(`[docs] 完成：${path.relative(root, siteDir)}`);
+
+  if (process.argv.includes('--serve')) {
+    await run(process.execPath, [path.join(here, 'serve.mjs')]);
+  }
+}
+
+main().catch((error) => {
+  console.error('[docs] 失败：', error.message);
+  process.exit(1);
+});

docs/dev/api.md

@@ -0,0 +1,138 @@
+---
+title: REST API
+description: ClassHelper后端全部接口一览：方法、路径、权限与说明。
+---
+
+# 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`                                                 | 公开                         | 登录（教师 / 管理员的**工号** + 密码）；学生不是账号，拿学号登录只会得到 401   |
+| POST                        | `/auth/class-login`                                           | 公开                         | **班级账号登录**：班级码 + 班级密码 → 班级会话                                 |
+| GET                         | `/auth/me`                                                    | 登录                         | 当前用户（学生附带班级 / 年级）                                                |
+| PATCH                       | `/auth/password`                                              | 登录                         | 修改自己的密码（班级会话 → 班级密码）                                          |
+| POST                        | `/auth/logout`                                                | 登录                         | 退出（无状态，客户端丢弃 token）                                               |
+| GET                         | `/permissions/me`                                             | 登录                         | 当前账号的生效权限（**无权限键**；班级端会话返回空集）                         |
+| GET                         | `/permissions/catalog`                                        | `permission:manage`          | 权限键目录（权限页整棵勾选树的唯一来源）                                       |
+| GET / POST                  | `/permissions/groups`                                         | `permission:manage`          | 权限组列表 / 新建                                                              |
+| PATCH / DELETE              | `/permissions/groups/:id`                                     | `permission:manage`          | 改名 / 改描述 / 整体替换权限键；内置组不可删                                   |
+| GET                         | `/permissions/users`                                          | `permission:manage`          | 成员列表（所属权限组 + 生效权限数量）                                          |
+| PUT                         | `/permissions/users/:id/groups`                               | `permission:manage`          | 整体替换某账号的权限组（空数组 = 回落角色默认模板）                            |
+| 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                | 移出学生                                                                       |
+| PUT                         | `/classes/:id/subject-teachers`                               | ADMIN                        | 设置各科任课老师（班级 + 科目 + 教师）                                         |
+| 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`                                  | 登录                         | 未交名单：读名单 / 回写全班完成状态                                            |
+| POST                        | `/homeworks/bulk`                                             | `homework:write`             | 一次给多个班级布置同一份作业（`subjectName` 跨班按名匹配科目；逐班结果）       |
+| GET                         | `/notifications?classId=&priority=&unreadOnly=&keyword=`      | 登录                         | 通知列表（带已读状态；另支持 `date` / `from` / `to` / `createdBy`）            |
+| GET                         | `/notifications/unread-count`                                 | 登录                         | 未读数（红点）                                                                 |
+| POST                        | `/notifications`                                              | 教师 / 管理员                | 发布通知（广播 `notification:new`）；上课时段发紧急通知需 `confirmDuringClass` |
+| POST                        | `/notifications/:id/read`、`/notifications/read-all`          | 登录                         | 标记已读（班级设备会写全班）                                                   |
+| DELETE                      | `/notifications/:id`                                          | 教师 / 管理员                | 删除通知                                                                       |
+| GET                         | `/notifications/days?classId=&from=&to=&createdBy=`           | 登录                         | 通知按天归档（日期 + 条数，日期取 `assignDate`）                               |
+| GET                         | `/notifications/creators?classId=&from=&to=&date=`            | 登录                         | 通知按发布人归档                                                               |
+| POST                        | `/notifications/bulk`                                         | `notification:publish`       | 一次给多个班级发同一条通知（逐班结果，**单班失败不影响整批**）                 |
+| 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`                                            | **管理员**                   | 数据库状态（连接 / 版本 / 体积 / 23 张表行数 / 备份列表 / 定时配置）           |
+| 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` 绕过缓存仅管理员生效）    |
+| POST                        | `/clients/heartbeat`                                          | 登录                         | 客户端每 30 秒上报（**无权限键**）；返回更新目标 + 安装包信息 + 一条待执行命令 |
+| POST                        | `/clients/commands/:id/ack`                                   | 登录                         | 命令执行回执（**无权限键**，靠 body 的 `deviceKey` 校验归属，幂等）            |
+| POST                        | `/clients/commands`                                           | `remote:control`             | 下发远控命令（关机 / 重启 / 注销 / 锁屏；自动撤销该机更早的未回执命令）        |
+| GET                         | `/clients/devices?classId=`                                   | `client:manage`              | 客户端设备列表（版本 / 在线 / 待执行命令）                                     |
+| POST                        | `/clients/updates`                                            | `client:update-push`         | 统一下发客户端更新（按设备 / 班级 / 全部）                                     |
+| DELETE                      | `/clients/devices/:id`                                        | `client:manage`              | 移除设备记录（换机 / 旧机器清理）                                              |
+| GET                         | `/update/client/releases`                                     | `client:manage`              | 服务端已缓存了哪些客户端安装包                                                 |
+| POST                        | `/update/client/fetch`                                        | `client:update-push`         | 服务端代教室机器从 GitHub 下载安装包并登记 sha256 + size                        |
+| POST                        | `/update/client/releases`                                     | `client:update-push`         | 手工登记已放进磁盘的安装包（内网 / U 盘分发兜底）                              |
+| DELETE                      | `/update/client/releases/:version`                            | `client:update-push`         | 删除缓存的安装包（元数据 + 磁盘文件）                                          |
+| GET                         | `/update/client/download/:version`                            | 登录                         | 下载安装包（**故意不挂权限键**，班级端要能下；`res.download`）                 |
+| GET / PUT                   | `/ai/settings`                                                | `ai:manage`                  | 大模型设置（API Key 加密存储、**只进不出**，只回 `hasApiKey` / `keyHint`）     |
+| POST                        | `/ai/interpret`                                               | `ai:use`                     | 一句话解析（**只解析不落库**）；回 `action` / `params` / `preview` / `confidence` |
+| GET                         | `/ai/audit?limit=`                                            | `ai:manage`                  | 助手使用记录（每次解析写一条 `AiAudit`）                                       |
+| GET / PUT                   | `/system/settings`                                            | `system:manage`              | 系统设置（`developerMode`：开启后 500 响应带 `error.stack`）                   |
+| GET / PUT                   | `/system/autostart`                                           | `system:manage`              | 开机自启状态 / 开关（Windows 注册表 Run 项，Linux systemd 单元）               |
+| GET                         | `/system/diagnostics`                                         | `system:manage`              | 运行诊断（版本 / Node / 运行时长 / 数据目录 / 在线客户端数 / 已加载模块）      |
+| 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`                          |
+| **三个接口故意不挂权限键**                   | `/permissions/me`、`/clients/heartbeat`、`/update/client/download/:version` —— 前两者由班级端（`CLASS_DEVICE`，权限集为空）调用，下载接口要能装包；保护只有"已登录 + 限流" |
+| **查询参数校验失败是 422**                   | `middleware/validate.ts` 的 zod 解析错误由错误中间件映射成 422 `VALIDATION_ERROR`（不是 400）   |
+| **批量发布逐班判定、不整批回滚**             | `/notifications/bulk` 与 `/homeworks/bulk` 的单班失败（403 越权 / `URGENT_DURING_CLASS`）不影响其它班，成功班照常落库并实时推送 |
+| **`/ai/interpret` 只解析不落库**             | 助手只回结构化参数与中文预览；落库由前端确认后调既有端点 —— 权限与上课时段保护都在那条路径上    |
+
+## 相关
+
+- 实时事件见[实时事件（Socket.IO）](realtime.md)；
+- 权限矩阵见[角色与权限](permissions.md)；
+- 数据模型见[数据模型](data-model.md)。

docs/dev/architecture.md

@@ -0,0 +1,168 @@
+---
+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 + 图标）
+│   ├── images/                  # 展示图：文档站 / README / 官网共用的同一份（1× 逻辑像素）
+│   ├── 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 # 数据模型（24 个 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（当前 21 个模块）
+export const apiModules: ApiModule[] = [
+  authModule,
+  aiModule, // 大模型助手（只解析不落库，见 docs/dev/api.md）
+  classesModule,
+  coursesModule,
+  schedulesModule,
+  homeworksModule,
+  notificationsModule,
+  callsModule,
+  importsModule,
+  integrationsModule,
+  gradesModule,
+  studentsModule,
+  teachersModule,
+  archivesModule,
+  termModule,
+  dashboardModule,
+  databaseModule, // 数据库管理（仅管理员）
+  updateModule, // 更新检查 + 客户端安装包缓存与统一下发
+  permissionsModule, // 权限组管理
+  clientsModule, // 客户端设备心跳 / 远控命令
+  systemModule, // 开发者模式 / 开机自启 / 运行诊断
+].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` |
+| **功能级准入看权限键**       | 路由挂 `requirePermission('…')` / `requireAnyPermission(…)`，角色只是默认模板（`ROLE_DEFAULT_PERMISSIONS`）—— 见 `docs/dev/permissions.md` |
+| **权限判在服务层**           | 权限组只管功能级；班级维度与科目维度仍用 `lib/access.ts` 的断言（`assertCanManageSubjectContent` 等），**权限组不可覆盖** —— 前端隐藏 ≠ 权限 |
+| **周一为新一周的第一天**     | 周次口径唯一：`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

@@ -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

@@ -0,0 +1,155 @@
+---
+title: 数据模型
+description: 24 张表的职责、跨库通用约定、迁移历史与启动时自动迁移。
+---
+
+# 数据模型
+
+模型定义只有一份：`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 字符串，便于多端离线生成与合并。
+
+## 两条核心不变量
+
+这两条是 2026-10-06 那次重构立下的，后面所有表都围着它们转：
+
+**① 学生不是账号。** `Student` 是独立的一张表，只有学号 / 姓名 / 班级 / 性别 / 家长手机号 /
+状态，**没有 `passwordHash`、没有 `role`、没有登录字段** —— 「学生不能登录」由表结构保证，
+不再靠"登录前先判 role === 'STUDENT' 并 403"这类代码分支维持。
+`User` 因此收缩为**纯账号表**（管理员 / 教师 / ClassHelper 班级端）。
+
+**② 任课关系的唯一来源是 `Course`。** `Course(classId, name, teacherId)` 就是
+「班级 + 科目 + 教师」这条关系本身，作业与成绩都挂在它上面；班主任另由 `Class.teacherId` 表示
+（每班 1 人）。历史上那张**没有科目**的 `ClassTeacher` 协作表已删除 —— 两套关系并存必然漂移。
+同一位教师可以在同一个班同时是班主任和某科科任老师：两处指向同一个 `User`，不重复建号，
+权限在 `@classhelper/shared` 的 `resolveClassRole()` 里合并。
+
+## 24 张表
+
+| 表                     | 职责                                       | 值得注意的字段                                                                                        |
+| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `User`                 | **纯账号表**：管理员 / 教师 / ClassHelper 班级端 | `username`（教师即**工号**，班级端即班级码）、`role`、`phone`、`careMode`（关怀模式偏好，目前只由本机界面读写）；**学生不在这里** |
+| `Student`              | 学生名单记录（**没有账号**）               | `studentNo`（学号，唯一，唯一标识与查询键）、`classId`、`status`、`archivedYearId`                     |
+| `StudentClassTransfer` | 调班 / 转出历史                            | 班级 id 与班级名**都存快照且不建外键**（班级删了历史仍要能读）、`mode`（single｜batch｜transfer-out）  |
+| `ArchivedYear`         | 毕业归档的届别档案                         | `enrollmentYear`（届别，唯一）、`graduationYear`、归档时的统计快照                                     |
+| `Class`                | 班级                                       | `name`（**「2026级1班」**，由 `enrollmentYear` + `classIndex` 生成）、`code` + `passwordHash`（班级端账号）、`termWeeks`、`termStartDate`、`notificationChannel`、`studentGradeQueryEnabled`、`archivedYearId` |
+| `TermWeek`             | 学期逐周日期区间                           | `classId`（**空串 = 全校默认**）、`weekNumber`、`startDate` / `endDate`                                |
+| `Course`               | 课程 = **「班级 + 科目 + 教师」任课关系**   | `teacherId` 就是该班该科的任课老师；`@@unique([classId, name])`                                        |
+| `Schedule`             | 课表条目                                   | `weekStart` / `weekEnd` / `weekParity`（单双周）/ `source`（manual｜classisland）                      |
+| `Homework`             | 作业                                       | `assignDate`（所属日期）、`attachmentUrl`；`dueAt` 是已下线的遗留列                                    |
+| `HomeworkStatus`       | 学生作业完成状态                           | `@@unique([homeworkId, studentId])`                                                                    |
+| `Notification`         | 通知                                       | `priority`、`assignDate`（所属本地日期，禁止 UTC 切片）；`@@index([classId, assignDate])` 供按天归档 |
+| `NotificationRead`     | 已读记录                                   | `@@unique([notificationId, studentId])`                                                                |
+| `TimeLayout`           | 节次时间配置（ClassIsland 同款 JSON 导入得到） | `items` 是 JSON 字符串：`[{ index, name, startTime, endTime, type, skipped }]`                         |
+| `Grade`                | 成绩                                       | `studentId`、`score` / `totalScore`、`levelType`（percent｜letter｜custom）与 `level`                  |
+| `IntegrationDevice`    | ClassHelper 班级端 / ClassIsland 联动设备   | `tokenHash`（只存 sha256）、`lastHeartbeatAt`（在线判定）、`lastSeenAt`（最后一次带状态的上报）、三个方向开关 |
+| `ClassIslandPush`      | 下发给 ClassIsland 的提醒                   | `kind`（notification｜call）、`ackedAt`、`expiresAt`                                                   |
+| `PermissionGroup`      | 权限组（角色之上的**默认模板**）             | `name`（唯一）、`builtin`（内置组不可删）；生效集合见 [角色与权限](permissions.md)                      |
+| `PermissionGroupItem`  | 权限组里的一个权限键（一行一个键）           | `@@unique([groupId, key])`；键取值必须是 shared 的 `PERMISSION_KEYS` 之一                              |
+| `UserPermissionGroup`  | 账号 ←→ 权限组 的分配关系（可属多个组）      | `@@unique([userId, groupId])`；**没有任何行 = 回落角色默认模板**                                       |
+| `AppSetting`           | 全局键值设置（大模型配置 / 开发者模式）      | `key` 即主键、`value` 存字符串（复杂结构存 JSON）；密钥类值做 AES-256-GCM 加密后存这里（**只进不出**）  |
+| `ClientDevice`         | ClassHelper 客户端设备（教室 / 学生机）      | `deviceKey`（唯一，客户端生成）、`classId`、`clientVersion`、`updateTargetVersion`、`lastHeartbeatAt`（**在线判定看它**） |
+| `ClientCommand`        | 下发给客户端的远控指令                       | `kind`（shutdown｜restart｜logoff｜lock）、`expiresAt`（10 分钟）、`ackedAt` / `result`、`cancelledAt`  |
+| `ClientRelease`        | 服务端缓存的客户端安装包                     | `version`（唯一，白名单校验防路径穿越）、`fileName`、`sha256`、`size`；文件在 `data/client-releases/`  |
+| `AiAudit`              | 大模型指令审计（意图与结果，不记密钥）        | `userId`、`prompt`、`intent`、`status`（pending｜confirmed｜rejected｜failed）、`rawReply`             |
+
+### 几个容易忽略的设计
+
+**`ClassIslandPush` 与 `IntegrationDevice`** —— 提醒是**落库**的，不是"发出去就算"。
+设备离线时通知不丢：插件重连后拉取未确认的那条立即弹出，弹完回执（`ackedAt`）。
+`expiresAt` 防止学生几天后突然弹出旧提醒。
+
+**在线判定看 `lastHeartbeatAt`，不看 `lastSeenAt`** —— 同一台设备的上报其实有两种：
+心跳（每 60 秒一次，只表明"我还在线"）与带状态的上报（课表 / 上课状态）。
+合成一个字段后无法区分"在线但一直没新状态"和"整个失联"，所以拆开：
+`lastHeartbeatAt` 每次上报都刷（60 秒窗口判在线），`lastSeenAt` 只在带运行状态时刷。
+
+**课表同步方向：服务端 → 教室是主方向。**
+`IntegrationDevice.mirrorScheduleToClassIsland` 默认 **true**（服务端自动下发），
+`syncScheduleToServer` 默认 **false**（教室不再自动回传）。要取教室的课表，走
+`POST /integrations/devices/:id/request-schedule` 这个**人工动作**（前端点击前会弹警告）——
+自动回传会在老师手排课之后被教室的旧课表悄悄覆盖。
+
+**`Schedule.source`** —— 决定插件上报时能清理哪些行：只清 `classisland` 来源且本次未再上报的行。
+**`source` 只在 create 时确定，update 一律保持原值**（否则手排的课会被"收养"后又被清掉）。
+
+**`Homework.dueAt`** —— 截止时间功能已下线，UI 与接口都不再读写它。
+保留列是为了**不对已安装的库做破坏性迁移**；新库里它恒为 `null`。
+
+**`Notification.assignDate`** —— 与 `Homework.assignDate` 同口径：**本地日期**（`YYYY-MM-DD`），
+创建时用 `dayKeyLocal()` 写入，按天 / 区间归档都读它。**不要用 `createdAt` 切 UTC 当"哪一天"** ——
+晚上发的通知会被算到第二天。`@@index([classId, assignDate])` 是归档查询的支撑。
+
+**`User.careMode`** —— 关怀模式的账号级偏好列（放大正文与控件）。**目前服务端没有任何接口读写它**：
+Web 端存在 `localStorage`（`classhelper.admin.careMode` + `careScale`），客户端存在本机 `config.json`。
+列先建好是为了将来跨设备同步偏好时不必再迁移；别把它当成"已有服务端开关"。
+
+**`TermWeek.classId` 用空串而不是 null 表示"全校默认"** —— SQLite 与 MySQL 的唯一约束都把
+NULL 视作互不相同，`@@unique([classId, weekNumber])` 用 null 就形同虚设。
+
+## 迁移历史（17 个）
+
+```
+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 →
+add_student_table → add_student_grade_query → add_grade_level →
+add_classhelper_heartbeat → add_archives → add_term_weeks →
+add_permission_groups_and_clients
+```
+
+`add_student_table` 是一次真正的表重构（不是加列）：新建 `Student` / `StudentClassTransfer`、
+把 `User` 里 `role='STUDENT'` 的行**按 id 原样搬过去**、把 `Grade` / `HomeworkStatus` /
+`NotificationRead` 的外键从 `userId` 换到 `studentId`、删掉 `Enrollment` 与 `ClassTeacher`。
+因为学生行的 id 保持不变，三张个人数据表的 `userId` 可以直接当 `studentId` 用，历史一条不丢。
+
+`add_permission_groups_and_clients` 是纯加表 / 加列：新建 `PermissionGroup` /
+`PermissionGroupItem` / `UserPermissionGroup`（权限组）、`AppSetting`（全局键值设置）、
+`ClientDevice` / `ClientCommand`（客户端设备与远控）、`ClientRelease`（安装包缓存）、
+`AiAudit`（大模型审计），并给 `Notification` 加 `assignDate` + `[classId, assignDate]` 索引、
+给 `User` 加 `careMode`。没有数据搬运，旧库直接补跑即可。
+
+### 启动时自动迁移
+
+`src/lib/db-bootstrap.ts` 用一张账本表 `_ch_migrations` 记录已执行的迁移目录名：
+
+| 情况     | 行为                                                |
+| -------- | --------------------------------------------------- |
+| 全新安装 | 依次执行全部迁移并创建初始管理员                    |
+| 覆盖安装 | 只补跑账本里没有的迁移（已存在的表 / 索引自动跳过） |
+| 已是最新 | **不做任何写操作**                                  |
+
+日志会写明「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
+用户因此**不需要手动执行 `prisma migrate deploy`**。
+
+## 备份格式就是这份模型的拓扑序导出
+
+「数据库管理」里的备份 / 导出导入 / 跨库迁移共用一种 JSON 快照：**23 张表按拓扑序导出**
+（见 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES`，现在共 23 项，顺序为
+`User` → `PermissionGroup` → `PermissionGroupItem` → `UserPermissionGroup` → `AppSetting` →
+`ArchivedYear` → `Class` → `Student` → … → `AiAudit`），恢复时**临时关闭外键检查** ——
+因为 `Class.teacherId → User` 与 `Student.classId → Class` 是一条链、
+`Class/Student.archivedYearId → ArchivedYear` 又是一条，任何排序都会被其中一侧卡死。
+见[数据库管理](../management/database.md)。
+
+## 开发时的模型改动
+
+1. 改 `schema.prisma`；
+2. 在 `prisma/migrations/` 下加一个迁移目录（本机用
+   `pnpm --filter @classhelper/server db:deploy` 应用，**别用 `pnpm db:migrate`** ——
+   它在 Windows 上不可靠）。要改已有表结构而不只是加列时，可以先用
+   `pnpm exec prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script`
+   生成骨架，再手工补数据搬运语句；
+3. 改完核对 **`SNAPSHOT_TABLES`**（新增 / 删除表要同步）与 `deleteTeacher` 的护栏清单
+   （它必须覆盖 `Class.teacherId` / `Course.teacherId` / `Homework.createdBy` /
+   `Notification.createdBy` 四项；`ClassIslandPush.createdBy` 是裸列、无外键、不级联，不用加）；
+   再回到 `packages/server/scripts/apply-column-migrations.cjs` 补上可 `ALTER TABLE` 的简单列。
+
+模型总数与迁移个数会随版本增长，以 `schema.prisma` 与 `prisma/migrations/` 的实际内容为准；
+本文里的数字标注的是**当前代码库**的状态。

docs/dev/index.md

@@ -0,0 +1,55 @@
+---
+title: 开发文档
+description: ClassHelper的架构、接口、数据模型、权限、动效层，以及验收与发版流程。
+---
+
+# 开发文档
+
+ClassHelper是一个 **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（ClassHelper 班级端 / 教室机器，含灵动岛浮窗）             |
+| 共享契约             | `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)                    | 24 张表、迁移历史、跨库约定                      |
+| [角色与权限](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

@@ -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

@@ -0,0 +1,158 @@
+---
+title: 角色与权限
+description: 权限矩阵、科目维度的收口规则，以及"前端隐藏 ≠ 权限"这条纪律。
+---
+
+# 角色与权限
+
+## 矩阵在哪
+
+**唯一一份**在 `packages/shared/src/permissions.ts`：
+
+- 后端 `lib/access.ts` 复用它做断言；
+- 两端前端用它隐藏入口；
+- 验收脚本按它逐条断言。
+
+所以不存在"前端一套后端一套"。改权限就改这一个文件（改完记得 `pnpm build:shared`）。
+
+## 角色判定
+
+角色只有三种，**没有 `STUDENT`** —— 学生不是账号（见[数据模型](data-model.md)）。
+班级内的角色由「账号角色 + 与该班级的关系」共同决定：
+
+| 角色                        | 判定方式                                   | 可见范围                             |
+| --------------------------- | ------------------------------------------ | ------------------------------------ |
+| `ADMIN` 管理员              | `User.role = ADMIN`                        | 全部班级                             |
+| 班主任 `HEAD`               | `Class.teacherId === 当前用户`             | 本班                                 |
+| 科任老师 `SUBJECT`          | 该班存在 `Course.teacherId === 当前用户`   | 被任课的班级                         |
+| `CLASS_DEVICE` 班级端       | 班级码 + 班级密码登录（`classSession`）    | 本班（代全班读写个人数据）           |
+| `NONE`                      | 与这个班没有任何关系                       | 什么都看不到                         |
+
+判定函数是 `resolveClassRole()`。「科任」的判定源是 **`Course`**（班级 + 科目 + 教师），
+不是那张已经没有的 `ClassTeacher` 协作表。
+
+## 权限矩阵
+
+| 操作                                                     | 管理员 |    班主任    | 科任老师 | 班级端 |
+| -------------------------------------------------------- | :----: | :----------: | :------: | :----: |
+| 班级创建 / 修改 / 删除                                   |   ✅   |      ❌      |    ❌    |   ❌   |
+| 分配班主任与各科任课老师                                 |   ✅   |      ❌      |    ❌    |   ❌   |
+| 学生名单管理（增删 / 导入 / 调班 / 转出）                |   ✅   | ✅（仅本班） |    ❌    |   ❌   |
+| 教师录入（新建 / 导入名单 / 修改密码）                   |   ✅   |      ❌      |    ❌    |   ❌   |
+| 毕业归档 / 学年升级 / 学期周次                           |   ✅   |      ❌      |    ❌    |   ❌   |
+| 数据库管理（备份 / 导入导出 / 一键切换）                 |   ✅   |      ❌      |    ❌    |   ❌   |
+| 课表管理（增删改 / 时间配置导入）                        |   ✅   | ✅（仅本班） |    ❌    |   ❌   |
+| 布置作业（**自己任教的科目**）                           |   ✅   | ✅（本班）   |    ✅    |   ✅   |
+| 叫人 / 发布通知                                          |   ✅   |      ✅      |    ✅    |   ✅   |
+| 成绩录入 / 修改 / 导入（**自己任教的科目**）             |   ✅   | ✅（本班）   |    ✅    |   ❌   |
+| 查看本班成绩汇总                                         |   ✅   |      ✅      |    ✅    |   ✅   |
+| 按学号查询学生成绩明细                                   |   ✅   |      ✅      |    ✅    | 需班级开关 |
+| 查看 ClassHelper 班级端在线状态                          |   ✅   |      ✅      |    ✅    |   ❌   |
+| 班级密码 / 班级码维护（`PATCH /classes/:id/class-account`） |   ✅   |      ❌      |    ❌    |   ❌   |
+
+## 科目维度的收口（本次重构的核心规则）
+
+作业与成绩不是"凡是能进这个班就能改"，而是**再按科目收一道**：
+
+| 情形                                    | 谁可以写                                   |
+| --------------------------------------- | ------------------------------------------ |
+| 管理员                                  | 全部                                       |
+| 挂了科目（`courseId` 有值）             | **该科的任课老师**（`Course.teacherId`）   |
+| 没挂科目（`courseId` 为空）             | 本班**班主任**                             |
+| ClassHelper 班级端                      | 只有**作业**可以（老师在教室随手录一条）；**成绩不给** |
+
+于是：班主任若不教这一科，就改不了这一科的作业与成绩 —— 这正是需求
+「班主任不自动拥有所有科目作业成绩编辑权，只有同时是该科科任老师时才有该科权限」。
+
+实现在 `lib/access.ts` 的 **`assertCanManageSubjectContent(user, classId, courseId, action, { allowClassDevice })`**，
+作业 / 成绩 / 叫人三处写入统一走它。
+
+## 权限键与权限组（2026-10 起：权限组驱动，角色只是默认模板）
+
+从权限组重构开始，**功能级准入不再看角色，而看权限键**：键目录同样是
+`packages/shared/src/permissions.ts` 的 `PERMISSION_KEYS`（39 个，形如 `domain:action`，
+中文名在 `PERMISSION_LABELS`、分组在 `PERMISSION_CATEGORIES`）。路由上挂的是
+
+```ts
+requirePermission('notification:publish')      // 需要全部列出的键
+requireAnyPermission('grade:write', 'grade:import')  // 有任意一个即可
+```
+
+**生效规则（四句话）**：
+
+| 账号                                    | 有效权限                                                       |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `ADMIN`                                 | 全集；其中 `permission:manage` / `system:manage` **不可被剥夺** |
+| `CLASS_DEVICE`（班级端）                | 空集，**不受任何分组影响**（它的能力来自班级维度断言）          |
+| 被分配了权限分组                        | 分组键的**并集**（可以比角色默认更少 —— 这就是"能收权"）        |
+| 没有被分配任何分组                      | 回落到角色默认模板 `defaultPermissionsForRole(role)`            |
+
+默认模板逐条镜像重构前的 `requireRole`，所以"不动分组"= 行为与以前完全一致。
+实现见 `packages/server/src/lib/permissions.ts` 的 `loadEffectivePermissions()`：它**每个请求实时查库**
+（不缓存），因此管理员改完分组**立刻生效**，不需要等令牌过期 —— 与下面「鉴权中间件会回查数据库」是同一个理由。
+
+**管理接口**（`packages/server/src/modules/permissions/`）：
+
+| 方法与路径                        | 权限要求             | 说明                                                     |
+| --------------------------------- | -------------------- | -------------------------------------------------------- |
+| `GET /api/permissions/me`         | 登录即可             | 当前账号的有效权限与来源（前端据此显示/隐藏入口）        |
+| `GET /api/permissions/catalog`    | `permission:manage`  | 全部权限键（含中文名、分类、默认角色、不可移除标记）     |
+| `GET/POST /api/permissions/groups`、`PATCH/DELETE /groups/:id` | `permission:manage` | 分组 CRUD；内置分组（`builtin=true`）可改不可删 |
+| `GET /api/permissions/users`、`PUT /api/permissions/users/:id/groups` | `permission:manage` | 成员列表与「整组替换」式分配；拒绝给 ADMIN / CLASS_DEVICE 分配 |
+
+**一条不能松的边界**：权限组只管**功能/路由级**准入；**班级维度的科目规则不可被权限组覆盖**。
+换句话说，给某人授了 `homework:write` 只代表"他能进布置作业这条路由"，
+**具体到哪个班、哪个科目**仍然由 `assertCanManageSubjectContent` 判（下一节）。
+否则「班主任能布置别人科目的作业」这个老 bug 会从权限组这条新路重新长出来。
+
+## 实现要点
+
+**路由级只做权限过滤**：`requirePermission('…')`（需要列出的键全有）或
+`requireAnyPermission('…')`（任意一个即可）。改造前这里是 `requireRole('ADMIN','TEACHER')`，
+按键目录里的 `PERMISSION_DEFAULT_ROLES` 逐条映射过来，因此**默认行为没有变化**。
+403 的文案会直接点名缺哪个键：「当前账号缺少「X」权限，请联系管理员在「权限组」里分配」。
+
+**班级维度的判断在服务层**：`src/lib/access.ts` 提供
+
+```
+assertCanManageClasses    / assertCanAssignTeachers / assertCanManageRoster
+assertCanManageSchedule   / assertCanPublishNotification
+assertCanManageGrades     / assertCanManageSubjectContent
+```
+
+**列表数据用 `resolveClassScope()` 收敛**（`classId in [...]`），单条接口直接断言；
+越权一律 403。
+
+**鉴权中间件会回查数据库**（`middleware/auth.ts`）：JWT 校验之后重新读一次账号，
+所以改了角色 / 班级关系会**立即生效**，不用等令牌过期。班级端会话则回查 `Class` 表。
+
+**班级端的成绩查询开关**：`Class.studentGradeQueryEnabled`（默认开启）。
+关闭后班级端调 `GET /grades/student/:studentNo` 一律 403，教师端不受影响 ——
+这就是需求「是否允许学生通过班级端查看本人明细，由教师或管理员开关控制」。
+
+## 前端隐藏 ≠ 权限
+
+前端的隐藏只是"别让人看见入口"：
+
+- 教师登录时侧边栏不显示「班级管理 / 学生管理 / 教师管理 / 毕业归档 / 学期周次 / 数据库管理 / 权限组 / 客户端设备」；
+- 课表页的增删改按钮只对「管理员或本班班主任」显示；
+- 成绩页的录入 / 删除按钮对教师显示（科任也能用，**具体到某一条由后端按科目判定**）。
+
+**门控怎么写的**：路由 `meta.roles` 做粗筛（角色），`meta.permission` 做细筛（权限键）——
+`packages/web-admin/src/router/index.ts` 的 `beforeEach` 会 `await auth.ensurePermissions()`
+再问 `auth.can(key)`（管理员短路为 true），不通过就 **fail-closed** 回仪表盘；
+侧栏菜单项同理带 `permission` 字段（`AdminLayout.vue` 的 `visibleMenuItems`）。
+`auth.ensurePermissions()` 读的就是 `GET /api/permissions/me`。
+
+但这些页面**直接输网址也进不去**（路由 `meta.roles` 会把非管理员挡回仪表盘），
+而且**所有写入请求服务端都会再断言一次**。绕过菜单、绕过前端，一样 403。
+
+> 新增视图时别忘了两处：路由的 `meta.roles` + 服务层对应 service 里的 `assertCanXxx`。
+> 只做其中一个都等于没做。
+
+## 学生没有账号的两个反向约束
+
+1. **学生不能登录，而且根本不存在可以登录的学生账号**。`User` 表里没有学生行，
+   拿学号当账号登录只会得到 401（"工号或密码错误"），连"这个学号存在吗"都探测不出来。
+2. **学生没有任何密码接口**。`POST /students/:id/reset-password` 已删除（调用返回 404），
+   新建学生也不设密码 —— `Student` 表里压根没有那一列。

docs/dev/realtime.md

@@ -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`            | 全部 ClassHelper 班级端连接                    |
+| `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

@@ -0,0 +1,221 @@
+---
+title: 版本迭代与发布
+description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
+---
+
+# 版本迭代与发布
+
+## 一条总原则
+
+> **版本号按「发布」迭代，不按「提交」迭代。**
+
+日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
+才走一次完整的版本迭代。理由很实际：安装包、`.cipx`、Docker 镜像 tag、文档站的版本徽标、
+更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
+
+| 算一次发布                              | 不算                         |
+| --------------------------------------- | ---------------------------- |
+| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
+| 要给别人一份新安装包                    | 只在自己机器上跑             |
+| 插件单独发补丁（只动插件第 4 段版本号） | —                            |
+
+## 版本号写在哪（14 处 / 12 个文件）
+
+同一个版本号分散在 14 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错：
+
+| 文件                                                             | 内容                               |
+| ---------------------------------------------------------------- | ---------------------------------- |
+| `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` 常量    |
+| `website/index.html` × 3                                         | 官网顶栏徽标 / 首屏芯片 / 页脚     |
+| `website/download.html`（`<meta name="ch-version">`）            | 下载页读不到版本清单时的兜底版本号 |
+
+最后两行值得单独说：官网是**纯静态站、没有构建步骤**，没有哪段代码会去读 `package.json`，
+所以那几处只能靠脚本一起改 —— 漏了的话首页会一直挂着旧版本号（而那是别人看到的第一眼），
+下载页则会给离线访客一串指向**不存在版本**的直链。
+
+所以**改版本号的唯一入口是脚本**：
+
+```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/<组件>/<版本>/`：`安装包/`（交付物）、`构建中间/`（可重新生成）。
+**没有免安装目录** —— 组装/解包出来的那一份是中间物，打包脚本用完就删（见仓库根 `AGENTS.md` §4
+「交付产物归集」）。
+
+打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
+
+```bash
+# 默认指向装好的客户端；推荐直接拿刚打出来的便携版单文件当被测副本
+pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.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
+
+上传前先把产物改成 ASCII 名 —— 构建产物是中文名，Release 上的名字是给别人看、要贴进脚本的：
+
+```bash
+V=1.1.3
+mkdir -p .cache/release-staging
+cp "releases/client/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-client-setup.exe"
+cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/ClassHelper-$V-x64-client-portable.exe"
+cp "releases/server/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe"
+cp "releases/classisland-plugin/$V/安装包/ClassHelper.ClassIslandPlugin.cipx" .cache/release-staging/
+
+gh release create v$V --title "v$V" --generate-notes
+gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber
+```
+
+| 构建产物                    | Release 上的名字                             |
+| --------------------------- | -------------------------------------------- |
+| `<客户端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-client-setup.exe`    |
+| `<客户端>-x64-portable.exe` | `ClassHelper-<版本>-x64-client-portable.exe` |
+| `<服务端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-server-setup.exe`    |
+
+这三个名字是**外部契约**：README 的「开始使用」表、官网下载页读不到版本清单时拼的兜底直链，
+都按它们写；改名要三处一起改。
+
+`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 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
+`package.json` 变过，
+[`pages.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/pages.yml)
+就会把两者构建成**同一个** GitHub Pages 站点发出去：
+
+```
+https://lovechengke.github.io/ClassHelper/          ← 官网
+https://lovechengke.github.io/ClassHelper/docs/     ← 文档站
+```
+
+（一个仓库在 Pages 上只有一个站点，所以是拼在一起发的 —— 官网在根、文档站在 `/docs/` 下。）
+
+文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了；
+官网首屏那排芯片、顶栏徽标与页脚里的版本号，以及下载页那个兜底版本号，
+也都是**由 `pnpm version:bump` 一起改的**（它们是那 14 个落点里的四个）。
+
+> 官网的「立即下载」会跳到 `/download.html`，那一页的版本清单是**当场**从 GitHub Releases 读的
+> （读不到才退回上面那个兜底版本号），所以发完 Release 不用重新部署那一页 —— 但**兜底值要跟着发版一起改**，
+> 不然离线访客点到的就是旧版本的直链。
+
+### 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

@@ -0,0 +1,122 @@
+---
+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/images/`      | **文档站、README、官网用的是同一份图**，页面上展示的都是它  | `capture-shots.mjs`（Web / 手机）+ 客户端冒烟（客户端 / 灵动岛）      |
+| `docs/screenshots/` | 回归留档，页面不展示；`verify:*` 的像素级断言比对的就是它们 | 各冒烟脚本自动写入（island / client / web-mobile / classisland 四组） |
+
+**展示图重新采集**（保证文档站与 README、官网用的是同一份图）：
+
+```bash
+pnpm dev:server                                                                    # 后端同时托管 Web 管理端
+CAPTURE_OUT=docs/images,website/assets/shots node website/tools/capture-shots.mjs  # → web-*.jpg / mobile-*.jpg
+
+# 客户端与灵动岛走的是冒烟脚本。它除了正片，还会顺手落一份「岛外留白对照图」
+# （*-window.png / *-backdrop.png），所以先落到临时目录，再挑要用的拷进去。
+ISLAND_SHOTS_DIR="$PWD/.cache/shots" ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/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
+cp .cache/shots/{island-*,client-*}.png docs/images/
+rm -f docs/images/*-window.png docs/images/*-backdrop.png
+cp docs/images/{island-*,client-*}.png website/assets/shots/       # 官网那份保持同步
+```
+
+**回归留档重新采集**（同一套冒烟，把输出指到留档目录）：
+
+```bash
+pnpm dev:server
+ISLAND_SHOTS_DIR="$PWD/.cache/island-shots" \
+ELECTRON_CLIENT_SHOTS_DIR="$PWD/.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
+```
+
+> 展示图都是**逻辑像素 1×**（灵动岛的 268×44、424×230 就是这个数，不再乘 2），
+> 页面按原始尺寸显示即可 —— 换图时别顺手放大，否则整页的尺寸对不上。
+> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
+> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
+> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。

docs/dev/toc.yml

@@ -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

docs/dev/winisland-design-tokens.md

@@ -575,7 +575,7 @@ VISUALIZER_TITLE_OFFSET    = 4.0    // 视觉条中心 y = 曲名基线 - 4
 
 ---
 
-## 附：班级小助手实际采纳了哪些（本次重写对照表）
+## 附：ClassHelper实际采纳了哪些（本次重写对照表）
 
 | WinIsland 做法                                           | 出处                                                                                                 | 我们的落地                                                                                                                         | 验证                                            |
 | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |

docs/docfx.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
+  "build": {
+    "content": [
+      {
+        "files": ["**/*.{md,yml}"],
+        "exclude": ["_site/**", "obj/**", "templates/**", "node_modules/**", "404.html"]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["screenshots/**", "images/**"],
+        "exclude": ["**/*.md"]
+      }
+    ],
+    "output": "_site",
+    "template": ["default", "modern", "templates/classhelper"],
+    "globalMetadata": {
+      "_appName": "ClassHelper",
+      "_appTitle": "ClassHelper文档",
+      "_appLogoPath": "logo.png",
+      "_appLogoUrl": "",
+      "_appFaviconPath": "favicon.png",
+      "_enableSearch": true,
+      "_disableContribution": false,
+      "_gitContribute": {
+        "repo": "https://github.com/LoveChengke/classhelper",
+        "branch": "master"
+      },
+      "_appFooter": "<div class=\"ch-footer\"><span>ClassHelper（Class Helper）· 文档</span><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper\">GitHub 仓库</a><span class=\"ch-footer-sep\">·</span><a href=\"https://github.com/LoveChengke/classhelper/releases\">下载与更新日志</a><span class=\"ch-footer-sep\">·</span><span>构建于 docfx</span></div>"
+    },
+    "sitemap": {
+      "baseUrl": "https://lovechengke.github.io/ClassHelper/docs/",
+      "changefreq": "weekly",
+      "priority": 0.5
+    }
+  }
+}

docs/faq.md

@@ -0,0 +1,155 @@
+---
+title: 常见问题
+description: 装不上、连不上、改了不生效——最常被问到的那些问题。
+---
+
+# 常见问题
+
+## 安装与启动
+
+### 客户端装不上 / 便捷版双击没反应 / 应用一闪就没了
+
+**现象**：安装程序报「拒绝访问」，便捷版双击毫无反应，装上了也启动即退且不写日志
+（退出码 `0x80000003`）。
+
+**原因**：交付物被打了 **Low 完整性标签**。带 Low 标签的 exe 会被 Windows 降级运行：
+写不进 `%LOCALAPPDATA%` / `%TEMP%`；即使装上，Chromium 的子进程（完整性更低）也读不到这些文件而秒崩。
+
+**处置**：从 [Releases](https://github.com/LoveChengke/classhelper/releases) 下载的官方包不受影响
+（打包脚本收尾会自动修正标签）。自己构建时如果碰到，用：
+
+```cmd
+icacls <产物目录> /setintegritylevel Medium /T /C
+```
+
+判据是 `icacls <exe> | findstr Mandatory` 里出现 `Low`。
+另外**别把安装测试装进仓库目录里** —— 在那里又会继承 Low。
+
+### 双击客户端"点了没反应"
+
+**关窗只是隐藏到托盘，进程还在。** 再双击 EXE 会被单实例锁秒退（看起来像没反应），
+安装包也会因为"应用正在运行"装不上。先**从托盘右键退出**。
+
+### 安装包装不上，说应用正在运行
+
+同上。托盘 → 退出 ClassHelper。
+
+## 连接与登录
+
+### 后端明明在跑，`Invoke-WebRequest` 却返回别人的 404
+
+**系统代理拦住了 `127.0.0.1`**。自测请加 `-NoProxy`（`curl.exe` 用 `--noproxy '*'`）。
+项目内的 Node 脚本直连，不受影响。
+
+### 客户端连不上服务器
+
+1. 服务器地址要填**局域网 IP**（`http://192.168.1.10:4000`），不要写 `localhost`（那是客户端自己）；
+2. 服务器防火墙放行 **4000**；
+3. 服务器上如果开了系统代理，内网地址可能被代理接管 —— 浏览器与客户端**不会**自动绕过
+   （只有 ClassIsland 插件对本地 / 内网做了强制直连）；
+4. 在服务器本机 `curl.exe --noproxy '*' http://127.0.0.1:4000/healthz` 是不是 200？
+
+### 页面能打开，但接口全 401
+
+令牌过期，或者 `.env` 里的 `JWT_SECRET` 被换过（换过之后所有人的令牌都失效）。重新登录即可。
+
+### 提示「无法连接 GitHub」/ 检查更新查不到
+
+**这是设计内的结果**，不是错误。机房与教室机器常常只有内网，请求会超时；
+界面按"暂时查不到更新"呈现。失败结果同样进缓存，不会每点一次都白等一个超时。
+
+### 反向代理后面所有请求都被限流
+
+反向代理没设 `TRUST_PROXY=1`，导致所有请求都被算作代理那一个 IP。
+
+## 功能行为
+
+### 上课时段发的通知学生看不到
+
+**这是设计行为。** 上课时段普通通知只进队列、不打断课堂，**下课自动补弹**。
+紧急通知与叫人则立刻弹。规则见[通知与提醒](app/notifications.md)。
+
+### 老师说发了通知，教室机器上什么都没弹
+
+按顺序排查：
+
+1. 客户端顶栏的实时通道是不是"已连接"？
+2. 现在是上课时段吗？（同上，是设计行为）
+3. 教室客户端的「设置 → 提醒」是不是设成了"只在 ClassIsland 上弹"？那样客户端只进通知中心。
+4. 反向代理放行 `/socket.io/` 的 WebSocket 升级了吗？
+
+### 屏幕上出现了第二个灵动岛，点它反应不对
+
+那是**自动化验证实例**的岛 —— `pnpm verify:desktop` / `verify:packaged` 会真的在屏幕上放一个，
+而且它归脚本控制，会自己展开 / 收起 / 消失。验证实例的岛是**洋红主题色**，一眼可辨。
+
+### 灵动岛上的文字往右跳一下再缩回
+
+那是早期的布局问题（胶囊内容跟着卡片重排），已经修掉了。如果你的版本还有，
+说明用的是旧产物 —— 参考[更新与升级](management/upgrade.md)。
+
+### 灵动岛调"左右边距"没反应
+
+**左右边距只在「左 / 右停靠」时生效。** 默认是「顶部居中」，水平锚点就是屏幕中线，
+这时调它不会有任何变化 —— 设置页会把那个滑块置灰并写明原因。
+
+### 触摸屏上点不开灵动岛
+
+触摸屏（希沃白板等）会自动走「触摸模式」，正常情况不用手动开。
+如果确实点不开，到「设置 → 关于」看一眼诊断信息，并把客户端版本反馈出来。
+
+### 教室机器上刚录的作业又要弹一次？
+
+**本机录入的作业不会上岛**（自己通知自己没意义）。如果弹了，说明这条不是这台机器录的。
+
+### 学生登录不了
+
+**学生没有个人账号。** ClassHelper 班级端统一用**班级码 + 班级密码**登录（见[装 ClassHelper 班级端](get-started/client.md)）。
+用学生用户名去登录一定会失败，这是设计。
+
+### 客户端里找不到"修改密码"
+
+**是刻意移除的。** 防止教室机器上误改班级密码后，别的教室机器被锁在门外。
+班级密码由管理员在 Web 端「班级管理」维护；教师 / 管理员本人密码在 Web 端顶栏头像菜单里改。
+
+## 开发与运维
+
+### `pnpm db:seed` 报 `Cannot find module '.../@classhelper/shared/dist/index.js'`
+
+`packages/shared` 还没构建（它产出 `dist`，三端与 seed 都依赖）。先 `pnpm build:shared`。
+
+### 根目录跑 `pnpm db:deploy` 说不存在
+
+根 `package.json` 没有这个脚本。正确写法：
+
+```bash
+pnpm --filter @classhelper/server db:deploy
+```
+
+### 后端改了代码不生效
+
+`tsx src/index.ts` **不热载**。用 `pnpm dev:server`（watch），或重启服务端。
+**切换数据库之后必须重启**才会连上新库。
+
+### 上传表格报「服务器内部错误：request entity too large」
+
+表格导入的文件上限是 **8MB**（请求体 12MB），超限应返回 **413 `IMPORT_TOO_LARGE`** 与中文提示。
+如果你看到的是英文兜底错误，说明这个异常没被映射 —— 那是 bug，不是你的文件太大。
+
+### 切了 MySQL 之后重启又连回旧库
+
+服务端安装形态里，安装目录的 `.env` **必须是指向 `/etc/classhelper/config.env` 的软链**。
+两处不是同一个文件时，一键切换会"看起来成功、重启后又连回旧库"。
+Linux 上跑 `sudo classhelper doctor` 有专门一条断言盯着这个软链。
+
+### SQLite 报 `database is locked`
+
+同一个数据库文件只允许一个服务实例。确认没有重复启动；需要并发就换 MySQL。
+
+## 还没解决？
+
+- 开发环境的坑（命令、代理与 TLS、完整性标签、ClassIsland 路径与日志编码……）
+  都记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
+- 功能行为的权威说明在[完整参考](reference.md)；
+- 都不是的话，去 [Issues](https://github.com/LoveChengke/classhelper/issues) 提一个，
+  附上版本号（Web 端顶栏 / 客户端「设置 → 关于」里都有）和日志。

docs/get-started/classisland.md

@@ -0,0 +1,120 @@
+---
+title: 接入 ClassIsland
+description: 把教室里的 ClassIsland 接上 ClassHelper：下课表上报、大屏提醒下发、课表镜像三个方向。
+---
+
+# 接入 ClassIsland
+
+课堂里真正"知道现在第几节、在上什么课"的是 [ClassIsland](https://classisland.tech)。
+它跟 ClassHelper管的事情不重叠，接起来之后两边各拿各的好处：
+
+| 方向                            | 做什么                                                                              | 老师在哪看                               |
+| ------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- |
+| ClassIsland → ClassHelper        | 上报**课表 + 节次时间 + 上课状态**（现在上什么 / 下一节 / 本节起止），写进本班课表  | Web 端「ClassIsland 联动」的实时状态卡片 |
+| ClassHelper → ClassIsland        | 老师发一条**提醒** → 落库 → 教室插件取回 → ClassIsland 上**全屏弹出**（可语音朗读） | Web 端「ClassIsland 联动 → 下发提醒」    |
+| （可选）班级 → ClassIsland 镜像 | 把小助手这边排好的课表**镜像**回 ClassIsland，新建一份档案，不动老师原有的课表      | 同一页的「开镜像」开关                   |
+
+> 没接 ClassIsland 也能用 ClassHelper，只是教室里少一个大屏播报的出口。**这一步是可选的。**
+
+## 前置：ClassIsland 装好了
+
+本插件按 ClassIsland 插件 API 2.0 编写，ClassIsland 2.0.x 与 2.1.0.x 都能加载。
+先确认教室机器上 ClassIsland 本身能正常显示课表。
+
+## 第一步：在 Web 端签发设备令牌
+
+**ClassIsland 联动**页（管理员 / 本班班主任）→「接入新设备」→ 选班级 → 生成令牌。
+
+令牌形如 `chci_xxxxxxxx…`，**明文只显示这一次**：服务端只存它的 sha256 与一个前缀提示
+（`chci_80fa1c…`），用来在设备列表里人眼区分。丢了就重置一个。
+
+## 第二步：在教室机器上装插件并填令牌
+
+### 装插件
+
+从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取
+`ClassHelper.ClassIslandPlugin.cipx`：
+
+- **推荐**：在 ClassIsland 里直接安装这个 `.cipx`（插件页有「从文件安装」）。
+- 或者手工解压：把包里的 `ClassHelper.ClassIslandPlugin/` 目录整个丢进
+  `<ClassIsland 数据目录>\Plugins\`，然后重启 ClassIsland。
+
+> **ClassIsland 运行时会锁住 DLL**。要覆盖升级插件，必须先完全退出 ClassIsland 再覆盖，
+> 否则写入会被拒。插件配置在 `Config\Plugins\<插件 id>\Settings.json`，
+> 里面存着服务器地址与设备令牌 —— **升级时别覆盖这个文件**。
+> 另外改配置要在 ClassIsland 退出时改，运行中改会被内存里的副本回写覆盖。
+
+### 填令牌
+
+ClassIsland 的**设置 → ClassHelper 联动**里填：
+
+| 设置项                       | 说明                                                            |
+| ---------------------------- | --------------------------------------------------------------- |
+| 后端地址                     | `http://<服务器IP>:4000`                                        |
+| 设备令牌                     | 上一步生成的 `chci_…`                                           |
+| 上报课表到小助手             | 打开后才会把 ClassIsland 的课表同步过来                         |
+| 接收小助手提醒               | 关掉就收不到老师发的提醒                                        |
+| 提醒轮询间隔                 | 默认 10 秒（可调到 5 秒）。上报本身就是心跳，轮询只是顺带取提醒 |
+| 把班级课表镜像回 ClassIsland | 见下面「镜像」一节                                              |
+
+填完点**「立即上报」**。
+
+## 第三步：验证
+
+回到 Web 端的「ClassIsland 联动」页，应该出现设备卡片和「在线」标记，实时状态卡上会显示这台机器
+现在上什么课。到这一步链路就通了。
+
+如果一直离线：先看插件的日志，再看服务端能不能从教室机器访问到（**别让系统代理拦住内网地址** ——
+插件对本地 / 内网做了强制直连，但填错地址一样连不上）。
+
+## 提醒弹在哪个端：由教室客户端自己选
+
+教室机器的**客户端**「设置 → 提醒」里选，选择会同步到班级记录：
+
+| 选择                                      | ClassHelper 客户端             | ClassIsland |
+| ----------------------------------------- | ------------------------------ | ----------- |
+| `ClassHelper 与 ClassIsland 都弹`（默认） | 弹窗 + 灵动岛                  | 全屏提醒    |
+| `只在 ClassHelper 客户端弹`               | 弹窗 + 灵动岛                  | 不推送      |
+| `只在 ClassIsland 上弹`                   | 只进通知中心（不弹窗、不上岛） | 全屏提醒    |
+
+规则只有一条，**任何入口都遵守**：通知发布页、叫人、联动页的「下发提醒」三个入口共用同一份推送实现，
+不存在"某个页面发的通知不联动"。
+
+## 两个方向各需要哪些开关
+
+| 要同步的内容                     | 需要打开                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| 服务端 → ClassIsland（镜像课表） | ① 插件设置「把班级课表镜像回 ClassIsland」+ ② Web 端该设备的「镜像课表」        |
+| ClassIsland → 服务端（上报课表） | 插件设置「上报课表到 ClassHelper」                                                |
+| 提醒下发                         | ① 教室客户端的「通知显示位置」不是"只在 ClassHelper" + ② 插件「接收小助手提醒」 |
+
+## 上课时段：两边同一套规则
+
+老师在**上课时段**发通知时，教室里的两个端遵守同一条规则，否则会出现"学生在客户端看不到、
+却在 ClassIsland 上被打断"的怪事：
+
+| 提醒类型                                               | 上课时段                     | 下课 / 放学 |
+| ------------------------------------------------------ | ---------------------------- | ----------- |
+| 通知类（`kind=notification`：通知发布页 / 联动页下发） | **暂存不弹**（两边都先收着） | 自动补弹    |
+| 主动通知：**紧急提醒**、**叫人**（`kind=call`）        | **立刻弹**                   | 立刻弹      |
+
+ClassIsland 侧的暂存由插件实现：它订阅课程服务，下课后把暂存的提醒补弹出来；未弹出前不回执，
+所以服务端会一直保留着待提醒，教室机器断网也不丢。
+
+## 上报课表是"双向对齐"的
+
+插件每次全量上报时，服务端只清理**「来源是 ClassIsland 且这次没再上报」**的课表行。于是：
+
+- 老师在 ClassIsland 里删掉 / 挪动一节 → 小助手这边跟着同步；
+- 老师在小助手这边手排的课 → 一律不删。
+
+## 镜像：把小助手的课表写回 ClassIsland
+
+开启后，插件会新建一份名为 `ClassHelper-<班级名>` 的档案课表，**不动老师原有的课表**。
+
+镜像时会连节次时间一起带过去，并且**每两节之间补一段课间、最后一节之后不补**（放学）。
+这一步不做的话，ClassIsland 的课表会整体错位 —— 表现为"看着有内容、每节课都对不上"。
+
+细节与实现见[ClassIsland 插件](../dev/classisland-plugin.md)。
+
+下一步：[发布第一条内容](first-content.md)。

docs/get-started/client.md

@@ -0,0 +1,89 @@
+---
+title: 装 ClassHelper 班级端
+description: 在教室机器上安装 ClassHelper桌面客户端，用班级码登录，并第一次跑通实时通知。
+---
+
+# 装 ClassHelper 班级端
+
+桌面客户端装在**教室的那台机器**上（教室大屏、讲台电脑）。它是学生看课表作业的地方，
+也是「消息到达的第一现场」—— 灵动岛就长在这一端。
+
+## 1. 下载与安装
+
+从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：
+
+| 产物                                 | 用途                                       |
+| ------------------------------------ | ------------------------------------------ |
+| `ClassHelper-<版本>-x64-setup.exe`    | 安装包（约 98 MB），装到本机并建快捷方式   |
+| `ClassHelper-<版本>-x64-portable.exe` | 单文件便携版，双击即用，适合不改动机房机器 |
+
+要自己打：
+
+```bash
+pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的解包目录）
+```
+
+> **装不上 / 双击没反应 / 一闪就没**（报 `0x80000003`）通常不是产物坏了，而是交付物被打了
+> Low 完整性标签。打包脚本收尾已自动修正；从 Release 下载的包不受影响。
+> 另外：关窗是隐藏到托盘，进程还在，再双击会因单实例锁秒退 —— 先从托盘退出。
+
+## 2. 登录
+
+打开客户端 → 填三项：
+
+| 字段       | 填什么                                                        |
+| ---------- | ------------------------------------------------------------- |
+| 服务器地址 | `http://<服务器IP>:4000`（局域网用内网 IP，别用 `localhost`） |
+| 班级码     | 管理员在「班级管理」里给这个班设的码，例如 `G203`             |
+| 班级密码   | 建班级时设的密码                                              |
+
+旁边的「测试连接」可以先确认网络通。**已登录过但服务器暂时不可达时**，登录页会给一个「离线进入」——
+进去后看到的是上次缓存的课表 / 作业 / 通知（顶部会标「离线缓存」），网络恢复后自动刷新。
+
+> 客户端**没有改密码入口**，这是刻意的：教室机器上误改班级密码会把别的机器锁在门外。
+> 班级密码由管理员在 Web 端「班级管理 → 修改班级账号」维护。
+
+## 3. 首次启动的六步向导
+
+第一次启动会在登录页上自动弹一个向导：欢迎 → 连接服务器 → 登录班级 → 登录之后（主界面与离线缓存）→
+灵动岛提醒 → 完成。走完或跳过都会记为已完成，之后不再自动弹。
+
+想重看：登录页的**「查看使用引导」**，或进去之后 **设置 → 通用 → 使用引导**。
+
+## 4. 认一认主界面
+
+左侧是四个一级项（**课表 / 作业 / 通知 / 成绩**）加上一个可展开的**设置**分组，
+顶部汉堡按钮把整栏收成 64px 的图标导轨（折叠状态会记住）。「通知」项上有未读红点。
+
+| 页面 | 一句话                                                         |
+| ---- | -------------------------------------------------------------- |
+| 课表 | 周视图 + 「今天」时间轴（大时钟 / 正在上什么 / 下一节）        |
+| 作业 | 看板模式（按科目卡片、可全屏）/ 列表模式；教室机器还能录入作业 |
+| 通知 | 未读红点、优先级标签、点开自动标为已读                         |
+| 成绩 | 班级账号看到的是全班总览（表格 + 柱状图 + 等级分布）           |
+| 设置 | 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，六个子页            |
+
+细节见[应用帮助](../app/index.md)。
+
+## 5. 在教室机器上把它调成"能看"的样子
+
+教室大屏的观看距离和角度跟办公桌不一样，装完建议顺手做三件事：
+
+1. **开全屏作业看板** —— 作业页「全屏看板」，按屏幕尺寸自动排版，整个屏幕刚好放得下、不用滚动。
+2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
+   讲台机器上通常把字号调大一点、位置放到顶部居中。
+   触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
+3. **选提醒弹在哪端** —— 设置 → 提醒：`ClassHelper 与 ClassIsland 都弹` / 只在客户端 / 只在 ClassIsland。
+   这个选择会同步到班级记录，服务端据此决定要不要推 ClassIsland。
+
+## 6. 确认实时链路是通的
+
+在 Web 管理端给这个班发一条普通通知，教室机器上应该几秒内出现灵动岛胶囊。如果没有：
+
+- 客户端顶栏的实时通道状态是不是"已连接"？
+- 现在是上课时段吗？上课时段的普通通知**只进队列、下课才弹**，这是设计行为，不是故障。
+- 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？
+
+排查清单见[常见问题](../faq.md)。
+
+下一步（可选）：[接入 ClassIsland](classisland.md)。

docs/get-started/first-content.md

@@ -0,0 +1,78 @@
+---
+title: 发布第一条内容
+description: 发通知、布置作业、叫人、录成绩——把 ClassHelper真正用起来的第一轮操作。
+---
+
+# 发布第一条内容
+
+前面几步做完，系统就完整了。这一页走一遍四件最常用的事，每件都点出**它会不会弹、弹在哪个端**。
+
+## 发一条通知
+
+**通知发布** → 选班级 → 填标题和内容 → 选优先级 → 发布。
+
+| 优先级 | ClassHelper 班级端表现                                                                 |
+| ------ | -------------------------------------------------------------------------- |
+| 普通   | 课间弹胶囊，点击展开；**上课时段只进队列**，下课自动补弹                   |
+| 重要   | 同上，卡片上带优先级标签                                                   |
+| 紧急   | **无论是否上课都立即展开**（卡片内部红色呼吸光晕 + 紧急角标），45 秒后收起 |
+
+**上课时段发紧急通知会被拦一次。** 服务端返回 `409 URGENT_DURING_CLASS`，前端弹一个全屏二次确认，
+上面写着"现在为上课时间段……"、正在上的那节课，还有待发布的标题；确认按钮带 **3 秒倒计时**，
+倒计时结束前点不动。确认之后才真的发出去。
+
+这个拦截是**服务端做的**，绕过界面直接调接口一样会被拦 —— 它是产品行为，不是前端提醒。
+
+## 布置一份作业
+
+**作业发布** → 选班级 / 科目 → 填标题与要求 → 选**所属日期** → 发布。
+
+> 作业按**所属日期**归类，不是按录入时间。晚上 8 点留的作业算今天。
+> 老师可以给今天、明天甚至上周补录一份作业，客户端按日期查得到。
+
+附件支持站内相对路径或 `http(s)://` 链接（其他 scheme 服务端会拒，避免被当成脚本执行）。
+
+ClassHelper 班级端那边默认是**看板模式**：按科目分卡片、每条作业完整显示要求、整个看板缩放到刚好铺满屏幕；
+老师也可以在教室机器上直接**录入作业**、勾选**未交名单**（教室机器用的是班级账号）。
+
+## 叫一位同学
+
+**通知发布 → 叫人**（或管理员在**学生管理 → 叫人**）→ 选学生 → 点一个快捷短语或自己写一句 → 发送。
+
+| 级别     | ClassHelper 班级端                                                             |
+| -------- | ------------------------------------------------------------------ |
+| 普通叫人 | 课间显示「叫人」胶囊，点击展开；**上课时段只进队列**，下课自动弹出 |
+| 紧急叫人 | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开     |
+
+文案是「请 XXX 同学找 XXX 老师」，卡片上是「收到」按钮（复用通知的已读机制）。
+
+> 学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
+
+## 录一次成绩
+
+**成绩录入** → 选班级与考试名称 → 单条录入 / 批量录入 / 导入表格。
+
+- **科目**下拉同样是全校统一目录，选一个该班还没有的科目会自动建课。
+- 导入表格支持 `.xlsx / .xls / .csv / .tsv`，列名按同义词自动映射（「用户名→学号」「得分→分数」），
+  也可以手动改。**文件上限 8MB**，超了会返回明确的 413 而不是一句英文的内部错误。
+- 导入结果会给逐行的错误与警告，`errors[].row` 是 **Excel 视角的行号**（含表头），改完可以再导。
+
+ClassHelper 班级端看到的是**全班总览**：表格（分数 / 得分率 / 等级）+ 柱状图 + 等级分布 + 最近更新。
+
+## 在教室大屏上播一条提醒（需要 ClassIsland）
+
+**ClassIsland 联动 → 下发提醒** → 选班级、填标题内容、设置显示时长与语音朗读 → 下发。
+
+它会**落库**再推给教室。教室机器断网也不丢：插件重连后会拉取还没确认的那条，
+立刻弹出来，弹完回执，不会重复弹。
+
+如果教室客户端把「通知显示位置」设成了"只在 ClassHelper 客户端显示"，这一步会回一句
+「该班教室已设置为只在 ClassHelper 客户端显示」—— 那是设计行为，不是报错。
+
+---
+
+到这里你已经把整套系统跑通了。接下来：
+
+- 每一项功能的完整行为 → [应用帮助](../app/index.md)
+- 服务器怎么维护 → [管理运维](../management/index.md)
+- 遇到问题 → [常见问题](../faq.md)

docs/get-started/index.md

@@ -0,0 +1,40 @@
+---
+title: 快速上手
+description: 从零把 ClassHelper跑起来：装服务端、认管理端、建班级排课、装 ClassHelper 班级端、接 ClassIsland、发第一条内容。
+---
+
+# 快速上手
+
+ClassHelper不是一个单机软件，它由四部分组成，**必须先有服务端，其他三端才有内容可看**：
+
+| 组成部分                 | 装在哪                                  | 谁用                       | 必须先装？       |
+| ------------------------ | --------------------------------------- | -------------------------- | ---------------- |
+| **服务端**               | 一台能一直开着的机器（服务器/办公电脑） | —（它同时托管 Web 管理端） | ✅ 是            |
+| **Web 管理端**           | 不用装 —— 浏览器打开服务端地址即可      | 老师、班主任、管理员       | 跟着服务端一起有 |
+| **桌面客户端**           | 教室的电脑 / 教室大屏                   | 学生看课表作业、老师录作业 | 服务端就绪之后   |
+| **ClassIsland 联动插件** | 教室那台装了 ClassIsland 的机器         | 教室大屏播报               | 可选             |
+
+按顺序走下面这几页就行，全程大约半小时（不含下载时间）：
+
+1. [系统要求](requirements.md) —— 先确认机器和网络够用
+2. [安装服务端](server.md) —— Windows 安装包 / Linux 一键脚本 / Docker / 源码跑
+3. [认识 Web 管理端](web-admin.md) —— 登录进去，认一认界面
+4. [建班级、排课表](setup-class.md) —— 这是后面所有功能的前提
+5. [装 ClassHelper 班级端](client.md) —— 教室机器用班级码登录
+6. [接入 ClassIsland](classisland.md) —— 让教室大屏也会弹提醒（可选）
+7. [发布第一条内容](first-content.md) —— 通知 / 作业 / 叫人 / 成绩
+
+## 只想先看看它长什么样？
+
+不用装任何东西也能看出来它在干什么：
+
+- **看界面**：本页文档里各处嵌的都是实机截图，比如[灵动岛](../app/island.md)、[课表](../app/schedules.md)。
+- **本地跑一套演示数据**：装好 Node 20.19+ 与 pnpm 之后，
+  `pnpm install && pnpm build:shared && pnpm db:seed && pnpm dev` 会在本机拉起一套带演示班级的后端与
+  Web 管理端（详见[安装服务端](server.md#从源码跑开发模式)）。
+
+## 装完之后呢
+
+- 日常怎么用 → [应用帮助](../app/index.md)
+- 服务器怎么维护（备份、换库、升级） → [管理运维](../management/index.md)
+- 出问题了 → [常见问题](../faq.md)

docs/get-started/requirements.md

@@ -0,0 +1,76 @@
+---
+title: 系统要求
+description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环境与网络要求。
+---
+
+# 系统要求
+
+## 服务端
+
+服务端的安装包**自带 Node 运行时**，目标机器不需要另外装 Node.js，也不需要数据库软件
+（默认用内嵌的 SQLite）。
+
+| 项目     | 要求                                                                        |
+| -------- | --------------------------------------------------------------------------- |
+| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker   |
+| 内存     | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB）               |
+| 磁盘     | 程序约 340 MB（免安装目录）/ 安装后约 400 MB；数据按班级量增长，通常几十 MB |
+| CPU      | 任意 x64；不需要独显                                                        |
+
+**Linux 的 glibc 要求**：内置的 Node 官方 linux-x64 构建要求 glibc ≥ 2.28。
+CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
+判据：
+
+```bash
+ldd --version | head -1
+```
+
+**外网**：服务端只在「检查更新」时访问 GitHub，且失败是设计内的结果（返回"查不到"，不报错）。
+内网机器可以完全不连通外网。
+
+## Web 管理端
+
+不需要安装，用浏览器打开服务端地址即可。
+
+| 项目     | 要求                                                                        |
+| -------- | --------------------------------------------------------------------------- |
+| 浏览器   | Chrome / Edge 100+、Firefox 100+、Safari 15+（要支持 CSS 容器查询）         |
+| 屏幕     | 桌面 1280×720 以上；手机（≤768px）有一套独立的抽屉式布局，同样可用          |
+| 安装 PWA | 手机 / 桌面 Chrome 里「添加到主屏幕」可当 App 用（需要 HTTPS 或 localhost） |
+
+## 桌面客户端（ClassHelper 班级端 / 教室机器）
+
+| 项目     | 要求                                                                         |
+| -------- | ---------------------------------------------------------------------------- |
+| 操作系统 | Windows 10 / 11（x64）                                                       |
+| 内存     | 4 GB 以上（Electron 常驻约 250–400 MB）                                      |
+| 磁盘     | 安装后约 330 MB                                                              |
+| 显卡     | 有 D3D11 即可；希沃一体机、老显卡、虚拟机都做过兼容（没有裁剪 GPU 回退组件） |
+| 触摸屏   | 支持，会自动进入[触摸模式](../app/island.md)（希沃白板等）                   |
+
+> 客户端**只有 Windows 版**。Linux / macOS 上目前只能用 Web 管理端。
+
+## 网络
+
+三端的通信都指向服务端的 **HTTP 端口（默认 4000）**，其中：
+
+- REST 接口：`/api/*`
+- 实时推送（Socket.IO）：`/socket.io/`
+- Web 管理端静态资源：`/`（由服务端托管）
+
+| 场景                      | 要做什么                                                                                |
+| ------------------------- | --------------------------------------------------------------------------------------- |
+| 只在服务器本机用          | 什么都不用做，`http://127.0.0.1:4000`                                                   |
+| 教室机器 / 老师电脑也要用 | 客户端与管理端填服务器的**局域网 IP**（如 `http://192.168.1.10:4000`），防火墙放行 4000 |
+| 公网访问                  | 前面加 Nginx / Caddy 反代并启用 HTTPS，见[生产部署指南](../management/production.md)    |
+
+> **别用代理**。本机自测时用 `curl.exe --noproxy '*'`，PowerShell 用 `-NoProxy`；
+> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。插件里对本地 / 内网地址做了强制直连，
+> 但浏览器与客户端本身不会绕过。
+
+## 卸载 / 重置
+
+- 服务端：开始菜单 → 卸载。卸载会保留数据库（`data` 目录改名为 `data.backup`）。
+- 客户端：从托盘退出后卸载；重置配置删 `%APPDATA%\class-helper`（或客户端「关于」页显示的数据目录）。
+
+下一步：[安装服务端](server.md)。

docs/get-started/server.md

@@ -0,0 +1,142 @@
+---
+title: 安装服务端
+description: 用 Windows 安装包、Linux 一键脚本、Docker 或源码把 ClassHelper 服务端跑起来。
+---
+
+# 安装服务端
+
+服务端是整个系统的中心：它存数据、发实时推送，**并且顺带托管 Web 管理端**（所以老师那一端不用单独装东西）。
+
+四种装法按场景选，任选一种即可：
+
+| 方式                              | 适合                                   | 一句话                          |
+| --------------------------------- | -------------------------------------- | ------------------------------- |
+| [Windows 安装包](#windows-安装包) | 学校机房、教师办公电脑、单机即完整系统 | 双击 exe，装完自动启动          |
+| [Linux 一键安装](#linux-一键安装) | 学校已有 Linux 服务器                  | 一条命令，带 systemd 与运维命令 |
+| [Docker](#docker)                 | 云服务器、想跟别的服务共用一台机器     | `docker compose up -d`          |
+| [源码跑](#从源码跑开发模式)       | 想改代码、想先看看它长什么样           | `pnpm dev`                      |
+
+## Windows 安装包
+
+### 生成安装包
+
+安装包不入库（体积大），从 [Releases](https://github.com/LoveChengke/classhelper/releases) 直接下载
+`ClassHelper 服务端-<版本>-x64-setup.exe` 即可。要自己打：
+
+```bash
+pnpm dist:server                    # 首次会执行一次 npm install（约 2 分钟）
+pnpm dist:server -- --reuse-deps    # 迭代打包：复用已装依赖，跳过 npm install
+```
+
+产物：
+
+| 路径                                                                    | 说明                       |
+| ----------------------------------------------------------------------- | -------------------------- |
+| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
+
+> 交付产物只有安装程序。组装出来的那份运行时（内置 Node + 依赖 + 后端与 Web 产物，约 335 MB）
+> 只是打安装包的中间物，落在 `.cache/server-staging/<版本>/` 下，打完脚本就删掉了 ——
+> 想留一份可直接双击运行的副本，见本文末「不用安装程序的手动部署」。
+
+包内自带 Node 运行时、后端产物、Web 管理端产物、生产依赖、迁移 SQL、随机 `JWT_SECRET` 的 `.env`
+与启停脚本。目标机器**不需要预先安装 Node.js**。
+
+### 安装与启动
+
+双击安装程序即可，**不需要管理员权限**（当前用户级安装）。
+
+- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
+- 静默安装：`"ClassHelper 服务端-<版本>-x64-setup.exe" /S`
+- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
+- 自动加入当前用户开机自启
+
+装完服务会自动启动并完成首次初始化：数据库为空则执行随包迁移建表 → 创建管理员账号 →
+`http://127.0.0.1:4000/` 就是 Web 管理端。
+
+常用脚本（都在安装目录里）：
+
+```cmd
+start.cmd     :: 启动并等待就绪（已在运行则直接返回）
+stop.cmd      :: 按 PID 精确停止
+restart.cmd   :: 重启
+status.cmd    :: 查看状态与 HTTP 探针结果
+```
+
+机房主机这种无人值守的机器，建议以**管理员身份**跑一次 `install-service.cmd`，
+把服务注册成开机启动的计划任务（比注册表 Run 更稳）：
+
+```cmd
+install-service.cmd     :: schtasks /Create /SC ONSTART /RL HIGHEST
+uninstall-service.cmd   :: 删除计划任务
+```
+
+安装目录结构与配置见[生产部署指南](../management/production.md)；
+安装程序里的默认管理员口令**第一次登录后必须改掉**。
+
+## Linux 一键安装
+
+从 Release 下载 `classhelper-server-linux-x64-<版本>.tar.gz`（以及旁边的 `.sha256`），连同
+`install.sh` 一起拷到服务器：
+
+```bash
+scp releases/server/<版本>/linux-x64/classhelper-server-linux-x64-*.tar.gz \
+    install.sh verify-linux.sh root@<主机>:/tmp/
+
+ssh root@<主机> 'bash /tmp/install.sh --check'          # 先体检，不改任何东西
+ssh root@<主机> "printf '%s\n' '<管理员密码>' | bash /tmp/install.sh --yes --admin-password-stdin \
+    --package /tmp/classhelper-server-linux-x64-*.tar.gz"
+```
+
+安装器会装好内置 Node、把程序放到 `/opt/classhelper`、写好 systemd 单元、
+把 `classhelper` 运维命令软链到 `/usr/local/bin/`。之后：
+
+```bash
+classhelper status      # 服务状态
+classhelper doctor      # 一整套自检（配置软链、权限、依赖完整性…）
+classhelper backup      # 立即备份
+classhelper upgrade     # 升级到最新 Release（自动校验 sha256）
+```
+
+完整的目录布局、配置项、升级回滚、反向代理与故障排查见 [Linux 部署与运维](../management/linux-deploy.md)。
+
+## Docker
+
+```bash
+cd deploy
+cp .env.example .env          # 至少改 JWT_SECRET
+docker compose up -d          # 默认 SQLite 单容器，数据卷挂在本机
+```
+
+要 MySQL 就用 `docker-compose.yml`（带一个 MySQL 服务），只想要单容器 SQLite 用
+`docker-compose.sqlite.yml`。细节见[生产部署指南](../management/production.md)。
+
+## 从源码跑（开发模式）
+
+想改代码或只想先看看，用这条路。需要 **Node ≥ 20.19** 与 **pnpm 11**。
+
+```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                                                # 后端 4000 + Web 端 5173 一起起
+```
+
+演示账号见 [README 的「默认账号与种子数据」](https://github.com/LoveChengke/classhelper#readme)；
+**演示口令只用于本地开发，别带到真实环境**。
+
+| 端口 | 用途                                                     |
+| ---- | -------------------------------------------------------- |
+| 4000 | 后端 REST + Socket.IO + （构建后）Web 管理端静态托管     |
+| 5173 | Web 管理端开发服务器（`/api`、`/socket.io` 代理到 4000） |
+| 5174 | 桌面客户端渲染进程开发服务器                             |
+
+> 改动 `packages/shared` 之后必须 `pnpm build:shared`（或让它跑着 watch）——
+> 三端都从它的 `dist` 导入。
+
+## 装完之后
+
+打开 `http://<服务器地址>:4000/`，用管理员账号登录。下一页：
+[认识 Web 管理端](web-admin.md)。

docs/get-started/setup-class.md

@@ -0,0 +1,71 @@
+---
+title: 建班级、排课表
+description: 建第一个班级、配班级账号、加学生与老师、排课表——后面所有功能的前提。
+---
+
+# 建班级、排课表
+
+后面所有功能（发通知、布置作业、录成绩、接 ClassIsland）都挂在**班级**上，所以先把班级建出来。
+
+## 1. 建班级（仅管理员）
+
+Web 管理端 → **班级管理** → 「新建班级」：
+
+| 字段     | 说明                                                                    |
+| -------- | ----------------------------------------------------------------------- |
+| 班级名称 | 例如「高二(3)班」                                                       |
+| 年级     | 用于分组与统计                                                          |
+| 班主任   | 从教师账号里选，默认是自己；之后随时可在班级详情顶部「更换班主任」改    |
+| 学期周数 | 默认 20，**上限 30**。课表的周次选择与周次范围都以它为准                |
+| 班级码   | 保存时自动生成（字母数字 4–16 位，存大写），可以改成好记的，例如 `G203` |
+| 班级密码 | 新建班级时的初始密码就是它 —— 学生在教室机器上要用这个登录              |
+
+> **班级码 + 班级密码 = ClassHelper 班级端的登录凭据。** ClassHelper 班级端没有个人账号，一台教室机器用班级账号登录后，
+> 那台机器上的「已读 / 完成」是**代全班**操作的。
+>
+> 学期周数只有管理员能改：它决定"现在是第几教学周"，乱改会让课表的周次过滤和上课时段判定错位。
+
+## 2. 加学生（仅管理员）
+
+**学生管理** → 「新建」或「导入名单」：
+
+- **单个新建**：填姓名即可，登录名会自动生成。
+- **导入名单**：下载模板（列是 `学号 / 姓名 / 班级 / 性别 / 家长手机号`，学生**不是账号**，没有密码列），填好上传。
+  用户名要匹配 `^[A-Za-z0-9_.-]{3,32}$`；重复用户名在 `append` 模式下跳过、`upsert` 模式下更新姓名。
+  用户名已经属于某个教师 / 管理员账号时，这一行会进错误列表，不会覆盖别人的账号。
+
+学生的用途是：**成绩、未交名单、叫人、已读记录都按名单记录**。所以名单不全，这几项就不准。
+
+## 3. 加科任老师
+
+教师的**录入**只有管理员能做（**教师管理**页，支持单个录入与导入名单）。班级层面的**分配**在班级详情里：
+在「班级详情 → 任课老师」里给某位老师配一门课，他就能看到这个班，并**只能改自己任教科目**的作业与成绩。
+
+角色与可见范围见[班级、学生与教师](../app/classes.md)与[角色与权限](../dev/permissions.md)。
+
+## 4. 排课表
+
+**课表管理** → 选中班级 → 「新增课表」：
+
+- **科目**下拉直接列出全校统一的 18 科目录（语文 / 数学 / 英语 / 政治 / 历史 / 物理 / 化学 / 地理 /
+  生物 / 信息技术 / 体育 / 美术 / 音乐 / 班会 / 早读 / 晚读 / 通用技术 / 听力）。
+  选中一个该班还没有的科目时，前端会**自动为该班建同名课程**，不用先去把科目的建一遍。
+- 填星期、开始 / 结束时间、周次范围（第几周到第几周）、单双周（每周 / 单周 / 双周）。
+- 一节课**必须同时有开始时间和结束时间** —— 「上课时段」的判定就是拿这两个时间比对的。
+
+排完在**课表管理**里能看到周视图（7 列），客户端那边则多一个「今天」时间轴视图。
+
+### 从 ClassIsland 导入更省事
+
+如果教室里已经在用 ClassIsland，直接导入它的档案 JSON 就行：课表、节次时间、单双周都会一起进来，
+不用排两遍。见[表格与课表导入](../app/imports.md)。
+
+## 5. 确认「上课时段」判定是对的
+
+ClassHelper有一整套「上课时段策略」：普通通知在上课时段只进队列、下课自动补弹，紧急通知与叫人则立刻弹。
+这套判定完全基于课表，所以**课表排错，提醒就会在该弹的时候不弹**。
+
+排完课之后建议立刻验一下：在**通知发布**页选这个班，随便发一条普通通知，
+看客户端是不是在课间弹出来、上课时是不是安静地收着。规则详见[通知与提醒](../app/notifications.md)。
+
+下一步：[装 ClassHelper 班级端](client.md)。

docs/get-started/toc.yml

@@ -0,0 +1,16 @@
+- name: 快速上手
+  href: index.md
+- name: 系统要求
+  href: requirements.md
+- name: 安装服务端
+  href: server.md
+- name: 认识 Web 管理端
+  href: web-admin.md
+- name: 建班级、排课表
+  href: setup-class.md
+- name: 装 ClassHelper 班级端
+  href: client.md
+- name: 接入 ClassIsland
+  href: classisland.md
+- name: 发布第一条内容
+  href: first-content.md

docs/get-started/web-admin.md

@@ -0,0 +1,58 @@
+---
+title: 认识 Web 管理端
+description: 登录 ClassHelper Web 管理端，认一认 12 个页面、新手引导与手机端布局。
+---
+
+# 认识 Web 管理端
+
+Web 管理端不用装：服务端起来之后，浏览器打开 `http://<服务器地址>:4000/` 就是它。
+
+## 登录
+
+用**教师 / 管理员账号**登录（用户名 + 密码）。学生没有个人账号，学生那一端走
+[班级码 + 班级密码](client.md)，见[班级、学生与教师](../app/classes.md)。
+
+- 新装的服务端只有安装时创建的那一个管理员账号。**第一次登录后请立刻在顶栏头像菜单 → 修改密码里改掉它。**
+- 登录页**不含任何演示内容**（没有"点击填充示例账号"之类的按钮），也不会提示种子口令。
+- 连不上服务器时页面会直接失败，不会静默重试 —— 先确认服务端在跑、端口对、没走代理。
+
+## 界面
+
+布局沿用 1Panel 那一套：左边固定深色侧边栏，右边浅灰底 + 白色圆角卡片。
+
+| 页面             | 干什么                                         | 谁能进                 |
+| ---------------- | ---------------------------------------------- | ---------------------- |
+| 仪表盘           | 全校 / 本班的汇总数字与最近动态                | 所有登录用户           |
+| 课表管理         | 排课、导入 ClassIsland 课表、节次时间          | 管理员、本班班主任     |
+| 作业发布         | 发作业、按天查看、看未交名单                   | 教师、管理员、班级账号 |
+| 通知发布         | 发通知、发叫人                                 | 教师、管理员           |
+| 成绩录入         | 单条 / 批量录成绩、导入表格、看统计            | 管理员、本班班主任     |
+| ClassIsland 联动 | 接入教室设备、下发提醒、看实时状态、开镜像     | 管理员、教师           |
+| 班级管理         | 建班级、换班主任、改班级账号                   | **仅管理员**           |
+| 学生管理         | 学生名单增删、导入                             | **仅管理员**           |
+| 教师管理         | 教师账号增删改、导入名单、重置密码             | **仅管理员**           |
+| 数据库管理       | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员**           |
+| 检查更新         | 顶栏头像菜单里，查 GitHub 上有没有新版本       | 所有登录用户           |
+
+> **前端隐藏 ≠ 权限**。上面这张表只是"入口藏不藏"，每一条写入请求服务端都会再判一次
+> （见[角色与权限](../dev/permissions.md)）。直接输网址绕过菜单，一样会被挡回仪表盘。
+
+## 第一次登录的引导
+
+首次登录进入主布局后会自动弹一次聚焦式引导，依次指出：侧边菜单 → 实时通道状态 → 账号菜单 → 完成。
+走完或跳过（右上角 × 或 Esc）都记作"已看过"，之后不再自动弹。
+
+想重看：**右上角头像菜单 →「使用引导」**。
+
+## 手机 / 平板
+
+| 屏幕宽度  | 布局                                                   |
+| --------- | ------------------------------------------------------ |
+| > 992px   | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与实时事件计数 |
+| 769–992px | 保留侧边栏，内容区内边距压缩                           |
+| ≤ 768px   | 侧边栏收进抽屉，顶栏汉堡按钮唤出；表格在卡片内横向滚动 |
+
+手机上（与电脑同一局域网）用 `http://<主机IP>:4000` 打开，可以「添加到主屏幕」当 App 用（PWA）。
+做成 HTTPS 之后 PWA 才能完全离线化，见[生产部署指南](../management/production.md)。
+
+下一步：[建班级、排课表](setup-class.md)。

docs/index.md

@@ -0,0 +1,71 @@
+---
+title: 首页
+description: ClassHelper（Class Helper）的官方文档：安装部署、功能说明、运维手册与开发参考。
+---
+
+# ClassHelper文档
+
+ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统。**一份代码，四个交付物**：
+装在服务器上的后端、给老师用的 Web 管理端、装在教室机器的桌面客户端（ClassHelper 班级端 / 教室大屏），
+以及装在 [ClassIsland](https://classisland.tech) 上的联动插件。
+
+<p class="ch-tagline">
+老师发一条通知，教室那台机器上的灵动岛和 ClassIsland 会同时弹出来；学生打开客户端就能看到当天的课表和作业。
+</p>
+
+<div class="ch-cards">
+  <a class="ch-card" href="get-started/index.md">
+    <span class="ch-card-title">第一次装</span>
+    <span class="ch-card-desc">从零把服务端、管理端、ClassHelper 班级端和 ClassIsland 插件跑起来，大约半小时。</span>
+  </a>
+  <a class="ch-card" href="app/index.md">
+    <span class="ch-card-title">已经在用了</span>
+    <span class="ch-card-desc">课表、作业、通知、叫人、成绩、灵动岛，每一项具体怎么用。</span>
+  </a>
+  <a class="ch-card" href="management/index.md">
+    <span class="ch-card-title">负责运维</span>
+    <span class="ch-card-desc">部署形态怎么选、备份与恢复、换数据库、升级与回滚。</span>
+  </a>
+  <a class="ch-card" href="dev/index.md">
+    <span class="ch-card-title">要改代码</span>
+    <span class="ch-card-desc">架构、接口、数据模型、动效层，以及版本迭代与发布流程。</span>
+  </a>
+</div>
+
+## 它长什么样
+
+<div class="ch-shots">
+  <img src="images/client-schedule.png" alt="桌面客户端 · 课表「今天」时间轴" />
+  <img src="images/island-5-clicked.png" alt="灵动岛 · 点开通知后的详情卡" />
+  <img src="images/mobile-notifications.jpg" alt="Web 管理端 · 手机上的抽屉导航与通知发布页" />
+</div>
+
+> 这些图都是脚本把程序真的跑起来截的，不是示意图。采集方式见 [验收与测试](dev/testing.md)。
+
+## 目录
+
+| 章节                             | 里面有什么                                               | 谁看                 |
+| -------------------------------- | -------------------------------------------------------- | -------------------- |
+| [快速上手](get-started/index.md) | 系统要求、安装、第一次配置、发布第一条内容               | 第一次部署的人       |
+| [应用帮助](app/index.md)         | 逐个功能怎么用，以及行为上的约定（什么时段弹、谁看得见） | 老师、班主任、管理员 |
+| [管理运维](management/index.md)  | 部署形态、Linux 运维命令、备份、换库、升级               | 管服务器的人         |
+| [开发文档](dev/index.md)         | 架构、REST API、实时事件、数据模型、权限、发布流程       | 改代码的人           |
+| [常见问题](faq.md)               | 装不上、连不上、改了不生效……                             | 所有人               |
+
+## 这套系统的三件事
+
+**一、老师发，教室弹。** Web 端发布的内容通过 Socket.IO 按班级房间广播，客户端与灵动岛实时更新；
+落到 ClassIsland 上的那部分走设备令牌的独立通道，走 HTTP 上报，不依赖教室机器的网络环境有多好。
+
+**二、上课时段不打扰。** 「上课时段」由课表实时判定，普通通知只进队列、下课自动补弹，
+紧急通知和叫人则立刻弹出来 —— 服务端强制拦截，绕开界面直接调接口一样会被拦。
+
+**三、离线可用。** 客户端先写 IndexedDB，断网时回退缓存并在顶部提示；
+恢复连接后自动重新拉取，教室网络抖一下不会让大屏变白。
+
+## 关于本文档
+
+- 文档站的源码就在仓库里（`docs/`），用 [docfx](https://github.com/dotnet/docfx) 生成，发布在 GitHub Pages 上。
+  每页右下角有「在 GitHub 上编辑这一页」，发现写错或写漏可以直接改。
+- 版本号取自仓库根 `package.json`，显示在顶栏，与 [Releases](https://github.com/LoveChengke/classhelper/releases) 对齐。
+- 想在自己机器上预览：`pnpm docs:build --serve`。

docs/management/database.md

@@ -0,0 +1,78 @@
+---
+title: 数据库管理
+description: 备份与恢复、导出导入、定时备份，以及 Web 管理端里的「数据库管理」模块。
+---
+
+# 数据库管理
+
+Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可见**，后端同样 `requireRole('ADMIN')`），
+把过去要手工做的数据库运维都收进了界面。
+
+## 它能做什么
+
+| 能力         | 说明                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、23 张表的行数、连接串（MySQL 密码脱敏）                                                  |
+| 连接测试     | 对任意目标库试连（切换前的第一步）                                                                                                                     |
+| **一键切换** | SQLite ⇄ MySQL：自动「备份当前库 → 改写 schema provider → 生成客户端 / 建表 → 子进程迁移全部数据 → 改写 `.env`」，异步任务带步骤进度，**失败自动回滚** |
+| 备份 / 恢复  | gzip JSON 快照存在 `<数据目录>/backups/`；手动备份 / 从备份恢复（整库覆盖）/ 删除                                                                      |
+| 定时备份     | enabled + 间隔小时数 + 保留份数，配置存在 `data/database-settings.json`；服务端每 10 分钟检查一次到点任务（**进程不运行不补跑**）                      |
+| 快捷导入导出 | 下载快照 JSON（跨库通用）/ 下载数据库文件（仅 SQLite）/ 导入快照（整库覆盖，base64 上传）                                                              |
+
+## 关键设计：只有一种快照格式
+
+**备份、导入导出、跨库迁移共用同一种「JSON 快照」**：
+
+- 23 张表按**拓扑序**导出；
+- 恢复时临时**关闭外键检查** —— 因为 `User.classId → Class` 与 `Class.teacherId → User`
+  是**互相引用**的，任何排序都会被其中一侧卡死；
+- 分批 `createMany` 写入。
+
+因此**任意一份备份都能恢复回任意一种受支持的数据库**（SQLite 备份可以恢复进 MySQL，反之亦然）。
+
+MySQL 的连接测试 / 建表 / 写入依赖随包内置的 `@prisma/adapter-mariadb`，不需要额外安装。
+
+## 三条边界
+
+1. **主库只支持 SQLite 与 MySQL**。Redis 这类内存键值库 Prisma 不支持建表 / 迁移，
+   接口层直接 422 拒绝；PostgreSQL 暂未纳入。
+2. **切换完成后必须重启服务端**（安装版跑 `restart.cmd`，开发模式重跑 `pnpm dev:server`）才会连上新库。
+   切换失败会自动回滚 `schema.prisma`，`.env` 只在**数据全部迁移成功后**才改写。
+3. **目标库必须为空**（有表就拒绝）。
+
+> 安装包体积因此从约 34MB 涨到约 62MB：切换需要随包带上 prisma CLI 与 TypeScript 编译器
+> （Prisma 7 的生成器产出 `.ts` 源码，切换后要在目标机上编译进 `dist`）。
+
+## 命令行 / SSH 场景的备份
+
+Web 界面适合日常；服务器上更适合用命令。Linux 安装形态有一套现成的：
+
+```bash
+sudo classhelper backup                       # 备份配置 + 数据库
+sudo classhelper backup --note "升级前" --keep 7
+sudo classhelper backup list
+sudo classhelper backup restore 20261005-033000     # 用某个备份覆盖当前配置与数据（会先停服务）
+sudo classhelper backup schedule daily        # 每天 03:30 自动备份（systemd timer，保留 7 份）
+sudo classhelper backup schedule off
+```
+
+备份落在 `/var/backups/classhelper/<时间戳>[-说明]/`：`config.env` + `classhelper.db` + `meta.json`，
+目录权限 700、文件 600。
+
+- SQLite 用 `VACUUM INTO` 做**一致性快照** —— 服务在跑也安全，比直接 `cp` 可靠得多；
+- MySQL 用 `mysqldump --single-transaction`，密码经环境变量传给子进程，**不进 argv**；
+- `restore` 前会先自动备份现状；恢复的对象是**配置与数据**，不是程序。
+
+## 其它形态怎么备份
+
+| 形态              | 备份                                                   | 恢复                         |
+| ----------------- | ------------------------------------------------------ | ---------------------------- |
+| Windows 安装包    | 停服务后复制 `data\` 目录（里面有 `classhelper.db`）   | 替换后启动                   |
+| Linux             | `classhelper backup`（见上）                           | `classhelper backup restore` |
+| Docker            | 备份挂载出来的数据卷                                   | 还原数据卷                   |
+| MySQL（任意形态） | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql … < backup.sql`       |
+
+**建议**：每日自动备份 + 保留 7 份，并且**定期真的恢复一次**验证备份可用。
+
+> 变更 `JWT_SECRET` 会让所有用户重新登录，无必要时不要换。
+> Linux 上换用 `sudo classhelper key rotate`。

docs/management/index.md

@@ -0,0 +1,76 @@
+---
+title: 管理运维
+description: 部署形态怎么选、备份与恢复、换数据库、升级与回滚，以及上线前要逐项确认的清单。
+---
+
+# 管理运维
+
+这一章写给管服务器的人。如果你只是要用它，看[应用帮助](../app/index.md)就够了。
+
+## 先选部署形态
+
+| 形态                     | 适合                                     | 产物                                | 详细                                |
+| ------------------------ | ---------------------------------------- | ----------------------------------- | ----------------------------------- |
+| **Windows 安装包**       | 学校机房、教师办公电脑（单机即完整系统） | NSIS 安装程序，内置 Node 运行时     | [生产部署指南](production.md)       |
+| **Linux 原生 + systemd** | 学校已有 Linux 服务器                    | 一键安装器 + `classhelper` 运维命令 | [Linux 部署与运维](linux-deploy.md) |
+| **Docker**               | 云服务器、跟别的服务共用一台机器         | `deploy/docker-compose*.yml`        | [生产部署指南](production.md)       |
+| **手动部署**             | 已有 Node 环境、需要自定义               | 仓库源码（`pnpm build` 后直接跑）   | [生产部署指南](production.md)       |
+
+一句话的取舍：
+
+- **只有一台 Windows 机器** → 安装包形态，装完就能用，卸载也不留东西。
+- **有 Linux 服务器** → 一键安装器，之后所有维护都在 `classhelper` 这一条命令里。
+- **要对外提供服务** → Docker 或 Linux + Nginx 反代 + HTTPS（公网部署**必须**有 TLS）。
+
+## 数据库：默认 SQLite，可以换 MySQL
+
+默认用内嵌的 SQLite，**单校规模完全够用**，而且备份就是复制一个文件。
+多校区 / 高并发 / 需要多实例再换 MySQL：
+
+- 换法见[切换到 MySQL](mysql.md)（Web 端一键切换 / 命令行手工切换两条路）；
+- 备份、导出导入与跨库迁移共用同一种 JSON 快照格式，**任意备份能恢复回任意一种受支持的库**；
+- 见[数据库管理](database.md)。
+
+> 主库**只支持 SQLite 与 MySQL**。Redis 是内存键值库，Prisma 不支持它建表 / 迁移，接口层直接拒绝。
+
+## 升级
+
+不同形态的升级方式不一样，共同点是：**升级数据不会丢，但升级前一定先备份**。
+
+| 形态        | 升级方式                                                       |
+| ----------- | -------------------------------------------------------------- |
+| Windows     | 停服务 → 备份 `data` → 跑新版本安装程序（覆盖安装保留 `.env`） |
+| Linux       | `sudo classhelper upgrade`（自动下载、校验、快照、失败回滚）   |
+| Docker      | `docker compose pull && docker compose up -d`                  |
+| 手动 / 源码 | 替换程序目录，启动时自动补跑数据库迁移                         |
+
+完整流程、回滚与注意事项见[更新与升级](upgrade.md)。
+
+## 上线前逐项确认
+
+- [ ] 改掉 `admin` 与教师账号的默认密码；
+- [ ] `JWT_SECRET` 是随机值（≥ 48 字节）并妥善保管 —— **换它会让所有人重新登录**；
+- [ ] 公网访问走 HTTPS 反向代理（`deploy/nginx.conf` 可直接用）；
+- [ ] `CORS_ORIGIN` 收敛到具体域名，不要留 `*`；
+- [ ] `TRUST_PROXY=1` 并确认限流按真实 IP 生效（`/api` 响应头有 `RateLimit`）；
+- [ ] 反向代理**放行 `/socket.io/` 的 WebSocket 升级**（否则实时推送静默失效）；
+- [ ] 数据库账号用最小权限，只授权业务库；
+- [ ] 配好定时备份，并且**验证过能恢复**；
+- [ ] 关注 `/readyz` 与日志里的 5xx。
+
+## 监控与日志
+
+| 端点          | 用途                                     |
+| ------------- | ---------------------------------------- |
+| `/healthz`    | 存活探针：进程活着即 200                 |
+| `/readyz`     | 就绪探针：数据库可连才 200，否则 503     |
+| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长 |
+
+日志输出到 stdout/stderr；安装包形态由启停脚本重定向到 `logs/server.log`（UTF-8）。
+访问日志含方法、路径、状态码与耗时，5xx 记 error、4xx 记 warn。
+
+## 故障排查
+
+常见现象与排查方向列在[生产部署指南](production.md)的最后一节，
+以及[常见问题](../faq.md)。Linux 特有的问题（`systemctl` 启动即退出、`EACCES`、
+SQLite `database is locked`）在 [Linux 部署与运维](linux-deploy.md) 的故障排查一节。

docs/management/linux-deploy.md

@@ -3,10 +3,33 @@
 本文覆盖服务端在 Linux 上的**一键安装**与日常运维（`classhelper` 命令）。
 适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+（自动识别 apt / yum / dnf）。
 
-不想看长文的话，最短路径是这两条命令：
+不想看长文的话，最短路径就是这**一行**（在服务器上执行）：
 
 ```bash
-sudo bash install.sh --package /path/to/classhelper-server-linux-x64-1.1.0.tar.gz
+curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
+```
+
+它自己会把整套流程走完：识别发行版 → 补依赖 → 建系统用户 → **从 GitHub Release 取最新版服务端包
+并校验发布页上的 `.sha256`** → 下载内置 Node 运行时 → 建库建号 → 装成 systemd 服务。装完直接：
+
+```bash
+sudo classhelper status
+```
+
+参数接在最后即可，例如先只体检（不需要 root、不改动系统）：
+
+```bash
+curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && bash /tmp/classhelper-install.sh --check
+```
+
+> **别写成 `bash -c "$(curl …)" --check`**：`bash -c '代码' 第一个参数` 里那个参数会变成 `$0`，
+> 不是 `$1` —— 脚本收不到它（实测踩到：本意是体检，结果走进了交互式安装）。
+> 先落盘再执行没这个坑，也不会因为下载中断而执行到半个脚本。
+
+以下是"已有安装包 / 内网离线"的用法：
+
+```bash
+sudo bash install.sh --package /path/to/classhelper-server-linux-x64-1.1.2.tar.gz
 sudo classhelper status
 ```
 
@@ -38,10 +61,10 @@ classhelper-server-linux-x64-<版本>.tar.gz.sha256   ← 旁边那份校验值
 
 **为什么 Linux 包要单独出一个**：`@libsql/linux-x64-gnu`、`@prisma/adapter-libsql` 这些依赖是平台相关的，
 Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 Linux 跑不起来，因此 Linux 包必须在 Linux 上构建。
-仓库里的 [`.github/workflows/release-linux-server.yml`](../.github/workflows/release-linux-server.yml)
+仓库里的 [`.github/workflows/release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
 就是干这个的（拿 ubuntu runner 跑 `pnpm dist:server:linux`，再把产物挂到对应 Release 上）：
 
-1. 本地照惯例发 Windows 包的 Release（tag 形如 `v1.1.0`）；
+1. 本地照惯例发 Windows 包的 Release（tag 形如 `v1.1.2`）；
 2. GitHub → Actions → 「发布 Linux 服务端安装包」→ Run workflow → 填 tag → 运行；
 3. 跑完 Release 里会多出 Linux 包与更新后的 `SHA256SUMS-<版本>.txt`。
 
@@ -67,7 +90,7 @@ Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 Linux 跑不
 ```bash
 # 开发机（Windows 也可以）
 pnpm dist:server:linux
-# → release-server/classhelper-server-linux-x64-<版本>.tar.gz（+ .sha256）
+# → releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz（+ .sha256）
 #   重跑很快：node scripts/dist-server.mjs --platform linux --reuse-deps（复用已装的 node_modules）
 ```
 
@@ -88,17 +111,17 @@ TUI 会依次问：形态 → 安装目录 → 端口 → 数据库 → 初始
 
 ```bash
 # 全部默认：/opt/classhelper、4000 端口、SQLite、内置 Node
-sudo bash install.sh --yes --package ./classhelper-server-linux-x64-1.1.0.tar.gz
+sudo bash install.sh --yes --package ./classhelper-server-linux-x64-1.1.2.tar.gz
 
 # 指定目录与端口，从 stdin 传初始管理员密码（不进 argv / shell history）
 printf '%s\n' 'MyStrongPass!2026' | sudo bash install.sh --yes \
   --dir /srv/classhelper --port 8080 --admin-password-stdin \
-  --package ./classhelper-server-linux-x64-1.1.0.tar.gz
+  --package ./classhelper-server-linux-x64-1.1.2.tar.gz
 
 # MySQL 形态
 sudo bash install.sh --yes --database mysql --mysql-host 10.0.0.5 --mysql-db classhelper \
   --mysql-user classhelper --mysql-password-stdin \
-  --package ./classhelper-server-linux-x64-1.1.0.tar.gz <<< 'MySQL密码'
+  --package ./classhelper-server-linux-x64-1.1.2.tar.gz <<< 'MySQL密码'
 ```
 
 完整参数见 `bash install.sh --help`。要点：
@@ -262,7 +285,7 @@ classhelper logs --unit classhelper-backup     # 看定时备份的日志
 sudo classhelper password                 # 改 admin
 sudo classhelper password teacher1        # 改指定教师
 sudo classhelper password --list          # 列出可登录账号与班级账号（含是否已设密码）
-sudo classhelper password --class G101    # 改某个班的班级密码（学生端登录用）
+sudo classhelper password --class G101    # 改某个班的班级密码（ClassHelper 班级端登录用）
 ```
 
 安全约定（照要求逐条落实）：
@@ -366,7 +389,7 @@ sudo classhelper uninstall --purge    # 全删（含备份与数据），不可
 ## 6. 环境变量文件
 
 安装器会写 `/etc/profile.d/classhelper.sh`（内容见
-[`deploy/profile.d/classhelper.sh`](../deploy/profile.d/classhelper.sh)）：
+[`deploy/profile.d/classhelper.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/profile.d/classhelper.sh)）：
 
 ```sh
 export CLASSHELPER_HOME=/opt/classhelper
@@ -403,12 +426,13 @@ sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
 | --- | --- |
 | 服务起不来 | `classhelper doctor` → `classhelper logs -n 100`。常见：端口被占用、MySQL 连接串错、`data/` 权限 |
 | 装完打不开页面 | `classhelper status` 看探针与监听地址；云服务器还要在**安全组**放行端口 |
+| 页面能打开但是**空白** | 1.1.0 的服务端在 HTTP 直连访问时会下发 CSP `upgrade-insecure-requests`，浏览器把所有子资源改写成 https 加载而服务器没有 TLS，于是整页空白（HTML/接口都正常）。已修复的版本按请求协议条件下发；若暂不能升级，唯一正解是上 HTTPS 反代 |
 | 改了配置没生效 | 是否重启过（`classhelper config set` 会问）；`EnvironmentFile` 的值优先于文件里的同项 |
 | Web 端切库后还是连旧库 | `classhelper doctor` 看 `.env` 软链是否被破坏（`ln -sfn /etc/classhelper/config.env <安装目录>/.env`） |
 | 升级卡住/失败 | 失败会自动回滚；看 `classhelper logs -n 100`，确认磁盘余量 ≥1GB |
 | `classhelper` 命令找不到 | `ls -l /usr/local/bin/classhelper`；被删了就重装或 `ln -sfn <安装目录>/bin/classhelper /usr/local/bin/classhelper` |
 | 忘记管理员密码 | `sudo classhelper password admin`（直连数据库，不需要登录） |
-| 学生端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠 |
+| ClassHelper 班级端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠 |
 | CentOS 7 装完立刻退出 | glibc < 2.28，见下面的"已知限制" |
 
 ---
@@ -447,7 +471,7 @@ Node 官方的 linux-x64 二进制要求 **glibc ≥ 2.28**，而 CentOS 7 是 2
 ```bash
 # 在开发机：做出 Linux 包（或在 Actions 里下载）
 pnpm dist:server:linux
-scp release-server/classhelper-server-linux-x64-*.tar.gz root@<服务器>:/tmp/
+scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz root@<服务器>:/tmp/
 scp deploy/install.sh deploy/verify-linux.sh root@<服务器>:/tmp/
 ```
 
@@ -464,7 +488,7 @@ bash /tmp/install.sh --check
 
 ```bash
 sudo bash /tmp/install.sh --yes \
-  --package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz \
+  --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz \
   --admin-password-stdin <<< 'Verify-Pass-2026!'
 ```
 
@@ -503,7 +527,7 @@ sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x6
 
 ```bash
 # ① 浏览器打开 http://<IP>:4000/ ，用 admin 登录，改一次密码再登录
-# ② 学生端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
+# ② ClassHelper 班级端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
 # ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
 #    期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
 # ④ 卸载：sudo classhelper uninstall --yes

docs/management/production.md

@@ -4,10 +4,10 @@
 
 | 形态                  | 适用场景                                     | 产物                                                     | 本机验证情况                           |
 | --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
-| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `release-server/班级小助手服务端-<版本>-x64-setup.exe`   | ✅ 已完整实测（静默安装/启停/卸载/UI） |
+| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
 | **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`        | ⚠️ 文件已提供，本机无 Docker 未实测    |
-| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](../deploy/install.sh) + `classhelper` 运维命令             | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
+| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令             | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
-| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | `pnpm dist:server` 的免安装目录                          | ✅ 免安装目录已实测（163 项端到端）    |
+| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | 在仓库里构建后直接跑（见第四节）                          | ✅ 已实测（163 项端到端）    |
 
 ---
 
@@ -23,9 +23,12 @@ pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳
 产物：
 
 | 路径                                                                    | 说明                       |
-| ----------------------------------------------------- | ----------------------------------------------- |
+| ----------------------------------------------------------------------- | -------------------------- |
-| `release-server/classhelper-server/`                  | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
+| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
-| `release-server/班级小助手服务端-1.1.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS）                      |
+
+> 组装出来的运行时（内置 Node + 生产依赖 + 后端与 Web 产物，约 335 MB）是打安装包的中间物，
+> 落在 `.cache/server-staging/<版本>/`，脚本打完就删 —— 交付目录里只留安装程序。
+> 需要在有 Node 的机器上手动跑，见第四节。
 
 打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
 生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
@@ -35,10 +38,11 @@ pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳
 双击安装程序即可，**无需管理员权限**（当前用户级安装）：
 
 - 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
-- 静默安装：`"班级小助手服务端-1.1.0-x64-setup.exe" /S`
+- 静默安装：`"ClassHelper 服务端-1.2.0-x64-setup.exe" /S`
 - 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
-- 桌面：`班级小助手服务端.lnk`（打开管理端）
+- 桌面：`ClassHelper 服务端.lnk`（打开管理端）
-- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
+- **开机自启动可选**：安装向导的组件页里勾选（默认勾选），装完之后还能在管理端「系统设置」里随时开关
+  （`GET/PUT /api/system/autostart`）；勾选时写的是 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`
 - 卸载信息注册到「应用和功能」
 
 安装完成后服务会自动启动并完成首次初始化：
@@ -163,7 +167,7 @@ Linux 包由 GitHub Actions 在 ubuntu runner 上构建（平台相关的依赖
 ```bash
 # 开发机：做出 Linux 包并连同脚本一起拷到服务器
 pnpm dist:server:linux
-scp release-server/classhelper-server-linux-x64-*.tar.gz deploy/install.sh deploy/verify-linux.sh \
+scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz deploy/install.sh deploy/verify-linux.sh \
     root@<服务器>:/tmp/
 
 # 服务器上
@@ -176,7 +180,7 @@ sudo bash /tmp/install.sh               # 交互式：选形态 → 选目录
 ```bash
 printf '%s\n' 'StrongPass!2026' | sudo bash /tmp/install.sh --yes \
   --dir /srv/classhelper --port 8080 --admin-password-stdin \
-  --package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz
+  --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz
 ```
 
 安装器做的事：识别发行版与包管理器补依赖 → 建系统用户 `classhelper` → 下载包并校验 sha256 →
@@ -221,7 +225,7 @@ printf '%s\n' 'StrongPass!2026' | sudo bash /tmp/install.sh --yes \
 没有 systemd 的容器里可以用安装器的"只铺文件"模式，再自己托管进程：
 
 ```bash
-sudo bash /tmp/install.sh --yes --force --package /tmp/classhelper-server-linux-x64-1.1.0.tar.gz
+sudo bash /tmp/install.sh --yes --force --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz
 sudo -u classhelper /opt/classhelper/runtime/node/bin/node /opt/classhelper/server/dist/index.js
 ```
 
@@ -274,21 +278,27 @@ sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x6
 
 ## 四、手动部署（形态 D）
 
+目标机已有 Node.js（≥ 20.19）时，不需要任何安装包，直接在仓库里构建后跑：
+
 ```bash
 pnpm install
 pnpm build:shared
 pnpm --filter @classhelper/server build
 pnpm --filter @classhelper/web-admin build
-pnpm dist:server -- --reuse-deps      # 得到 release-server/classhelper-server 免安装目录
 ```
 
-把该目录拷贝到目标机，编辑 `.env`（端口、数据库、密钥、跨域），然后：
+按目标机的实际情况写好 `packages/server/.env`（端口、数据库、密钥、跨域），然后：
 
-```cmd
+```bash
-start.cmd      :: Windows
+pnpm --filter @classhelper/server start      # 或 node packages/server/dist/index.js
-# 或直接：node server/dist/index.js   （Linux/macOS 用系统 node，见上面的形态 C）
 ```
 
+> 想把这份构建结果整体拷到另一台机器，就自己带上这四样：
+> `packages/server/dist`、`packages/server/node_modules`（含 `src/generated/prisma`）、
+> `packages/web-admin/dist`（服务端按 `web/` 静态托管）、以及 `packages/shared/dist`。
+> `pnpm dist:server` 组装的正是这套东西，只是它现在把结果当中间物用、打完即删 ——
+> 需要留档时把 `.cache/server-staging/<版本>/win/` 在打包过程中拷出来即可。
+
 数据库初始化二选一：
 
 - 让服务自愈：`.env` 中 `AUTO_MIGRATE=true`（SQLite 首次启动自动建表 + 建管理员）
@@ -314,7 +324,7 @@ start.cmd      :: Windows
 | `PID_FILE`                                          | —                      | PID 文件路径（安装包启停脚本依赖），相对 `server` 根      |
 | `WEB_DIST_DIR`                                      | 自动探测               | Web 管理端产物目录（`../web-admin/dist` 或 `./web`）      |
 | `LOG_LEVEL`                                         | `info`                 | `debug` / `info` / `warn` / `error`                       |
-| `DEFAULT_CLASS_PASSWORD`                            | `123456`               | 新建班级时班级账号（学生端登录）的默认密码                |
+| `DEFAULT_CLASS_PASSWORD`                            | `123456`               | 新建班级时班级账号（ClassHelper 班级端登录）的默认密码                |
 | `DEFAULT_TEACHER_PASSWORD`                          | `123456`               | 新增/重置教师账号的默认密码（管理员录入教师用）           |
 | `TERM_START_DATE`                                   | —                      | 第 1 教学周的周一，用于"当前周次"与课表默认视图           |
 | `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123`   | 空库首启动创建的管理员                                    |

docs/management/toc.yml

@@ -0,0 +1,12 @@
+- name: 管理运维
+  href: index.md
+- name: 生产部署指南
+  href: production.md
+- name: Linux 部署与运维
+  href: linux-deploy.md
+- name: 数据库管理
+  href: database.md
+- name: 切换到 MySQL
+  href: mysql.md
+- name: 更新与升级
+  href: upgrade.md

docs/management/upgrade.md

@@ -0,0 +1,132 @@
+---
+title: 更新与升级
+description: 检查更新与各形态的升级步骤、Linux 的升级回滚链路，以及升级前必须做的准备。
+---
+
+# 更新与升级
+
+## 先知道版本是怎么回事
+
+三端**共用一套版本口径**：
+
+- 版本号的单一来源是仓库根 `package.json`。服务端在运行时读它（打包后读的是运行时清单），
+  不在代码里写死；
+- 比较逻辑放在 `@classhelper/shared` 的 `compareVersions` / `isNewerVersion`，三端共用 ——
+  避免出现"客户端说有新版、服务端说没有"；
+- 数字相同、只有后缀不同时，**带后缀的算更新**（对应 `v0.1.0-fix` 这种"同版本号的修复发布"）。
+
+## 检查更新
+
+| 端                  | 入口                                                            | 检查路径                                         |
+| ------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
+| 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」                                      | 浏览器 → 服务端 `GET /api/update/check` → GitHub |
+| 桌面客户端          | 启动后自动一次（延迟 5 秒）+「设置 → 关于」里的「检查更新」按钮 | 主进程 → GitHub（不经后端）                      |
+
+两端的路径不同是**被约束逼出来的**：
+
+- **Web 端不能直连 GitHub**。服务端下发的 CSP 里 `connect-src` 只放行 `'self'` 与 WebSocket，
+  浏览器发往 `api.github.com` 的请求会直接被拦掉。走服务端转发还有个好处：所有管理员共享同一份缓存
+  （GitHub 匿名限流是 60 次/小时/IP）。
+- **客户端在主进程做**。渲染进程的 CSP 与导航防线是安全模型里最要紧的一层，
+  不让它去连外部域名、解析外部 JSON。
+
+### "查不到"是设计内的结果
+
+机房服务器与教室机器常常只有内网，请求会超时或失败。这时接口返回 `ok: false` + 一句人话
+（「无法连接 GitHub，本机可能没有外网」），界面按"暂时查不到更新"呈现并给重试入口，
+**而不是弹红字报错**。
+
+失败结果同样进缓存 —— 否则断网时每点一次按钮都要白等一个超时。
+
+| 细节       | 说明                                                                                                  |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| 缓存       | 两端各缓存 30 分钟；`?force=1` 绕过服务端缓存，但**仅管理员生效**（否则任意登录用户都能刷爆匿名限流） |
+| 权限       | 任何已登录用户都能查（信息来自公开仓库）；`force` 除外                                                |
+| 只提示一次 | 客户端启动检查发现新版才推提示；点「忽略此版本」记进配置，同一版本不再提示                            |
+
+更新**只提示，不自动下载、不自动安装**。安装包仍由人从 [Releases](https://github.com/LoveChengke/classhelper/releases)
+页面取，可用 `SHA256SUMS-<版本>.txt` 核对。
+
+## 升级步骤
+
+### Windows 安装包
+
+1. `stop.cmd` 停止服务；
+2. **备份 `data` 目录**；
+3. 运行新版本安装程序 —— 覆盖安装会**保留原有 `.env`**，JWT 密钥与端口设置不变，
+   用户不需要重新登录；
+4. `start.cmd` 启动。数据库结构如有变更，会在首次启动时自动补跑迁移。
+
+如果升级后需要重新登录，说明 `.env` 被覆盖了（JWT 密钥变了），检查安装目录权限。
+
+### Linux
+
+```bash
+sudo classhelper upgrade --check            # 只检查有没有新版本
+sudo classhelper upgrade                    # 升到最新版
+sudo classhelper upgrade --version 1.2.0    # 升到指定版本
+sudo classhelper upgrade --url ./classhelper-server-linux-x64-1.0.1.tar.gz --sha256 <哈希>   # 内网离线
+sudo classhelper upgrade --url <包> --force # 强制重装同一版本
+
+sudo classhelper rollback --list            # 看有哪些程序快照
+sudo classhelper rollback                   # 回滚到最近一份（会问一次确认）
+```
+
+`upgrade` 的完整链路（**任一步失败都不改动程序文件**）：
+
+```
+解析目标版本 → 下载 → 校验 sha256 → 备份数据与配置 → 快照当前程序文件 →
+停服 → 替换程序文件（改名 + 就位，data/ 与配置原地不动）→ 起服 → 轮询 /healthz
+   ↘ 失败：自动用刚才的快照回滚并重新起服，再告诉你失败原因
+```
+
+两点必须知道：
+
+1. **升级不会回滚数据库结构**。如果新版执行过迁移，回滚程序前要确认旧版还能读新库，
+   必要时用 `classhelper backup restore` 连数据一起回退。
+2. 替换程序文件用的是"改名 + 就位"而不是删除重写：升级时**正在运行的就是 `bin/classhelper` 自己**，
+   必须先改名再放新文件，运行中的进程继续读旧 inode，否则 bash 会读到半个脚本。
+
+### Docker
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+数据库迁移在启动时自动补跑。
+
+### 手动 / 源码
+
+拉新代码（或覆盖安装新的服务端程序）→ 重启服务端。启动时 `db-bootstrap` 会用账本表 `_ch_migrations`
+对比已执行的迁移，只补跑缺的那些：
+
+- 全新安装：依次执行全部迁移并创建初始管理员；
+- 覆盖安装：只补跑账本里没有的迁移（已存在的表 / 索引自动跳过）；
+- 已是最新：**不做任何写操作**。
+
+日志里会明确写出「全新安装 / 升级安装」、应用了几个迁移、跳过了几个已存在对象。
+
+### 客户端（ClassHelper 班级端）
+
+从 Releases 取新的 `setup.exe` 覆盖安装即可，配置在 `%APPDATA%`，不受影响。
+
+> 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录，
+> 用户打开的还是旧的 `resources/app.asar` —— 表现为"改了但界面不生效"。
+> 覆盖升级时用 `robocopy ... /E` 推一遍，再对**那个副本**跑一次打包版冒烟确认。
+
+### ClassIsland 插件
+
+**必须先完全退出 ClassIsland**（它会锁住 DLL），再覆盖插件，然后重启。
+插件配置 `Config\Plugins\<插件 id>\Settings.json` 里存着服务器地址与设备令牌，**别覆盖它**。
+
+## 升级前的准备清单
+
+- [ ] 备份数据（`classhelper backup` / 复制 `data` 目录 / `mysqldump`）；
+- [ ] 记下当前版本号，必要时能回滚到它；
+- [ ] 挑一个没课的时间 —— 升级期间实时推送会中断；
+- [ ] 升级后确认 `/readyz` 是 200，并且客户端顶栏的实时通道显示"已连接"。
+
+## 给维护者
+
+打版本、出安装包、发 Release 的完整流程见[版本迭代与发布](../dev/release.md)。

docs/serve.mjs

@@ -0,0 +1,69 @@
+/**
+ * 文档站本地预览用的最小静态服务器（构建产物 docs/_site）。
+ * 正式发布走 GitHub Pages（.github/workflows/pages.yml：官网在根、文档站在 /docs/），不需要这个文件。
+ *
+ *   node docs/build.mjs --serve     → 构建后直接预览（推荐）
+ *   node docs/serve.mjs             → http://127.0.0.1:5181（要求已经构建过）
+ *   PORT=8080 node docs/serve.mjs
+ */
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(fileURLToPath(new URL('_site/', import.meta.url)));
+const PORT = Number(process.env.PORT ?? 5181);
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.map': 'application/json',
+};
+
+const server = createServer(async (request, response) => {
+  const url = new URL(request.url ?? '/', 'http://localhost');
+  const requested = decodeURIComponent(url.pathname);
+  const target = normalize(join(ROOT, requested === '/' ? 'index.html' : requested));
+
+  // 目录穿越防护：解析结果必须仍在 ROOT 里
+  if (target !== ROOT && !target.startsWith(ROOT + sep)) {
+    response.writeHead(403).end('Forbidden');
+    return;
+  }
+
+  try {
+    const info = await stat(target);
+    const file = info.isDirectory() ? join(target, 'index.html') : target;
+    const body = await readFile(file);
+    response.writeHead(200, {
+      'content-type': MIME[extname(file)] ?? 'application/octet-stream',
+      'cache-control': 'no-store',
+    });
+    response.end(body);
+  } catch {
+    // 与 GitHub Pages 行为对齐：未知路径给站点根的 404.html
+    const fallback = join(ROOT, '404.html');
+    if (existsSync(fallback)) {
+      response.writeHead(404, { 'content-type': MIME['.html'] }).end(await readFile(fallback));
+      return;
+    }
+    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('404');
+  }
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  if (!existsSync(ROOT)) {
+    console.warn('还没有构建产物，先跑 `node docs/build.mjs`');
+  }
+  console.log(`文档站预览：http://127.0.0.1:${PORT}`);
+});

docs/templates/classhelper/layout/_master.tmpl

@@ -0,0 +1,175 @@
+{{!班级小助手文档站的模板覆盖（只改必要的地方，其余保持 docfx modern 模板的行为）。}}
+{{!
+  覆盖的是 docfx modern 模板的 layout/_master.tmpl，改动只有四处：
+    1) lang 固定 zh-CN；loc: 开头的那些 meta 是给 docfx.min.js 用的 UI 文案（导航、目录、上一页/下一页、
+       主题菜单、复制按钮…），modern 模板只提供英文，这里全部换成中文；
+    2) 顶栏右侧补一个 GitHub 图标链接与一个版本徽标（版本号由 docs/build.mjs 通过 --metadata 传入，
+       单一来源是根 package.json，别在这里写死）；
+    3) 补 <meta name="theme-color"> 与 color-scheme，让手机浏览器地址栏跟着深浅色走；
+    4) 页脚换成项目自己的（_appFooter 在 docfx.json 里）。
+
+  下面三行 include 决定**模板目录里哪些文件会被拷进产物**：public/（本模板的 main.css）与两个图标。
+  别删 —— 删了图标与样式就进不了 _site。
+}}
+{{!include(/^public/.*/)}}
+{{!include(logo.png)}}
+{{!include(favicon.png)}}
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    {{#redirect_url}}
+    <meta http-equiv="refresh" content="0;URL='{{redirect_url}}'" />
+    {{/redirect_url}}
+    {{^redirect_url}}
+    <title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#1b1f24" media="(prefers-color-scheme: dark)" />
+    {{#_description}}<meta name="description" content="{{_description}}" />{{/_description}}
+    {{#description}}<meta name="description" content="{{description}}" />{{/description}}
+    <link rel="icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}" />
+    <link rel="stylesheet" href="{{_rel}}public/docfx.min.css" />
+    <link rel="stylesheet" href="{{_rel}}public/main.css" />
+    <meta name="docfx:navrel" content="{{_navRel}}" />
+    <meta name="docfx:tocrel" content="{{_tocRel}}" />
+    {{#_noindex}}<meta name="searchOption" content="noindex" />{{/_noindex}}
+    {{#_enableSearch}}<meta name="docfx:rel" content="{{_rel}}" />{{/_enableSearch}}
+    {{#_disableNewTab}}<meta name="docfx:disablenewtab" content="true" />{{/_disableNewTab}}
+    {{#_disableTocFilter}}<meta name="docfx:disabletocfilter" content="true" />{{/_disableTocFilter}}
+    {{#docurl}}<meta name="docfx:docurl" content="{{docurl}}" />{{/docurl}}
+    <meta name="loc:inThisArticle" content="本页内容" />
+    <meta name="loc:searchResultsCount" content="找到 {count} 条结果（{query}）" />
+    <meta name="loc:searchNoResults" content="没有找到「{query}」" />
+    <meta name="loc:tocFilter" content="按标题过滤" />
+    <meta name="loc:nextArticle" content="下一篇" />
+    <meta name="loc:prevArticle" content="上一篇" />
+    <meta name="loc:themeLight" content="浅色" />
+    <meta name="loc:themeDark" content="深色" />
+    <meta name="loc:themeAuto" content="跟随系统" />
+    <meta name="loc:changeTheme" content="切换主题" />
+    <meta name="loc:copy" content="复制" />
+    <meta name="loc:downloadPdf" content="下载 PDF" />
+
+    <script type="module" src="./{{_rel}}public/docfx.min.js"></script>
+
+    <script>
+      const theme = localStorage.getItem('theme') || 'auto';
+      document.documentElement.setAttribute(
+        'data-bs-theme',
+        theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme,
+      );
+    </script>
+
+    {{#_googleAnalyticsTagId}}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{_googleAnalyticsTagId}}"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag() {
+        dataLayer.push(arguments);
+      }
+      gtag('js', new Date());
+      gtag('config', '{{_googleAnalyticsTagId}}');
+    </script>
+    {{/_googleAnalyticsTagId}}
+    {{/redirect_url}}
+  </head>
+
+  {{^redirect_url}}
+  <body class="tex2jax_ignore" data-layout="{{_layout}}{{layout}}" data-yaml-mime="{{yamlmime}}">
+    <header class="bg-body border-bottom">
+      {{^_disableNavbar}}
+      <nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
+        <div class="container-xxl flex-nowrap">
+          <a class="navbar-brand" href="{{_appLogoUrl}}{{^_appLogoUrl}}{{_rel}}index.html{{/_appLogoUrl}}">
+            <img id="logo" class="svg" src="{{_rel}}{{{_appLogoPath}}}{{^_appLogoPath}}logo.svg{{/_appLogoPath}}" alt="{{_appName}}" />
+            {{_appName}}
+            {{#_chVersion}}<span class="ch-version">{{_chVersion}}</span>{{/_chVersion}}
+          </a>
+          <button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="展开导航">
+            <i class="bi bi-three-dots"></i>
+          </button>
+          <div class="collapse navbar-collapse" id="navpanel">
+            <div id="navbar">
+              {{#_enableSearch}}
+              <form class="search" role="search" id="search">
+                <i class="bi bi-search"></i>
+                <input class="form-control" id="search-query" type="search" disabled placeholder="搜索" autocomplete="off" aria-label="搜索" />
+              </form>
+              {{/_enableSearch}}
+            </div>
+            <!-- 官网入口。文档站被发布在官网下面一层（<站点根>/docs/），所以从任意一页
+                 回到官网就是「先退到文档站根（_rel），再退一层」。这个耦合与控制它的
+             .github/workflows/pages.yml 是同一件事，那边改布局这边要跟着改。 -->
+            <a class="ch-nav-site" href="{{_rel}}../" title="产品官网">官网</a>
+            <a class="ch-nav-github" href="https://github.com/LoveChengke/classhelper" target="_blank" rel="noopener noreferrer" title="GitHub 仓库" aria-label="GitHub 仓库">
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="18" height="18" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"/></svg>
+            </a>
+          </div>
+        </div>
+      </nav>
+      {{/_disableNavbar}}
+    </header>
+
+    <main class="container-xxl">
+      {{^_disableToc}}
+      <div class="toc-offcanvas">
+        <div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
+          <div class="offcanvas-header">
+            <h5 class="offcanvas-title" id="tocOffcanvasLabel">本页内容</h5>
+            <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="关闭"></button>
+          </div>
+          <div class="offcanvas-body">
+            <nav class="toc" id="toc"></nav>
+          </div>
+        </div>
+      </div>
+      {{/_disableToc}}
+
+      <div class="content">
+        <div class="actionbar">
+          {{^_disableToc}}
+          <button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="展开本页目录">
+            <i class="bi bi-list"></i>
+          </button>
+          {{/_disableToc}} {{^_disableBreadcrumb}}
+          <nav id="breadcrumb"></nav>
+          {{/_disableBreadcrumb}}
+        </div>
+
+        <article data-uid="{{uid}}">{{!body}}</article>
+
+        {{^_disableContribution}}
+        <div class="contribution d-print-none">
+          {{#sourceurl}}
+          <a href="{{sourceurl}}" class="edit-link">在 GitHub 上编辑这一页</a>
+          {{/sourceurl}}{{^sourceurl}}{{#docurl}}
+          <a href="{{docurl}}" class="edit-link">在 GitHub 上编辑这一页</a>
+          {{/docurl}}{{/sourceurl}}
+        </div>
+        {{/_disableContribution}} {{^_disableNextArticle}}
+        <div class="next-article d-print-none border-top" id="nextArticle"></div>
+        {{/_disableNextArticle}}
+      </div>
+
+      {{^_disableAffix}}
+      <div class="affix">
+        <nav id="affix"></nav>
+      </div>
+      {{/_disableAffix}}
+    </main>
+
+    {{#_enableSearch}}
+    <div class="container-xxl search-results" id="search-results"></div>
+    {{/_enableSearch}}
+
+    <footer class="border-top text-secondary">
+      <div class="container-xxl">
+        <div class="flex-fill">{{{_appFooter}}}{{^_appFooter}}<span>班级小助手文档</span>{{/_appFooter}}</div>
+      </div>
+    </footer>
+  </body>
+  {{/redirect_url}}
+</html>

docs/templates/classhelper/public/main.css

@@ -0,0 +1,649 @@
+/*
+ * ClassHelper文档站 —— docfx modern 模板的样式覆盖。
+ *
+ * docfx 按 `template` 数组的顺序合并模板，这个文件排在最后，因此覆盖掉 modern 模板自带的
+ * `public/main.css`（它本身是空的，被留作官方覆盖点）。docfx.min.css 在本文件之前加载，
+ * 所以同特异度的选择器这里写的会赢；Bootstrap 那类 0-2-0 的选择器要在下面用同等或更高的特异度压。
+ *
+ * 两条原则：
+ *   1) 只调版式与配色，不动 DOM 结构（结构改动都在 templates/classhelper/layout/_master.tmpl 里）；
+ *   2) 深色主题只覆盖**颜色**，几何与浅色完全一致 —— 切换主题时不该看到布局跳一下。
+ */
+
+/* ── 设计令牌 ─────────────────────────────────────────────────────────── */
+:root {
+  --ch-font-ui:
+    'Segoe UI Variable Text', 'Segoe UI', 'Microsoft YaHei UI', 'Microsoft YaHei', -apple-system,
+    BlinkMacSystemFont, 'PingFang SC', 'Hiragino Sans GB', sans-serif;
+  --ch-font-mono:
+    'Cascadia Mono', 'Cascadia Code', Consolas, 'JetBrains Mono', 'Sarasa Mono SC', ui-monospace,
+    SFMono-Regular, Menlo, monospace;
+  --ch-accent: #0f6cbd;
+  --ch-accent-soft: rgba(15, 108, 189, 0.08);
+  --ch-radius: 8px;
+  --ch-navbar-h: 60px;
+
+  --bs-body-bg: #ffffff;
+  --bs-body-color: #24292f;
+  --bs-secondary-color: #59636e;
+  --bs-tertiary-color: #7d8590;
+  --bs-border-color: #d8dee4;
+  --bs-link-color: var(--ch-accent);
+  --bs-link-hover-color: #115ea3;
+  --bs-link-color-rgb: 15, 108, 189;
+  --bs-code-color: #b1370f;
+  --bs-body-font-family: var(--ch-font-ui);
+  --bs-body-font-size: 16px;
+  --bs-body-line-height: 1.8;
+}
+
+[data-bs-theme='dark'] {
+  --ch-accent: #6cb8ff;
+  --ch-accent-soft: rgba(108, 184, 255, 0.12);
+
+  --bs-body-bg: #1b1f24;
+  --bs-body-color: #e6edf3;
+  --bs-secondary-color: #9198a1;
+  --bs-tertiary-color: #6e7681;
+  --bs-border-color: #30363d;
+  --bs-link-color: var(--ch-accent);
+  --bs-link-hover-color: #96ccff;
+  --bs-link-color-rgb: 108, 184, 255;
+  --bs-code-color: #ffa198;
+}
+
+/* ── 基础 ─────────────────────────────────────────────────────────────── */
+body {
+  font-family: var(--ch-font-ui);
+  font-size: 16px;
+  line-height: 1.8;
+  letter-spacing: 0.002em;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+body > main.container-xxl {
+  padding-top: 1.6rem;
+}
+
+:focus-visible {
+  outline: 2px solid var(--ch-accent);
+  outline-offset: 2px;
+  border-radius: 3px;
+}
+
+/* ── 顶栏 ─────────────────────────────────────────────────────────────── */
+header.bg-body {
+  backdrop-filter: saturate(180%) blur(12px);
+}
+
+.navbar {
+  min-height: var(--ch-navbar-h);
+}
+
+.navbar-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 17px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.navbar-brand #logo {
+  width: 28px;
+  height: 28px;
+  object-fit: contain;
+}
+
+/* 版本徽标：版本号由 docs/build.mjs 从根 package.json 注入，见 _master.tmpl 顶部注释 */
+.ch-version {
+  padding: 1px 7px;
+  border: 1px solid var(--bs-border-color);
+  border-radius: 999px;
+  font-family: var(--ch-font-mono);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1.6;
+  color: var(--bs-secondary-color);
+}
+
+/* 顶栏右侧那一组（官网链接 + GitHub 图标）。
+   `margin-left: auto` 只挂在组里的**第一个**元素上 —— 挂两个各推各的会散开。 */
+.ch-nav-site {
+  margin-left: auto;
+  padding: 6px 10px;
+  border-radius: 6px;
+  font-size: 14px;
+  color: var(--bs-secondary-color);
+  text-decoration: none;
+  white-space: nowrap;
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.ch-nav-site:hover {
+  color: var(--bs-body-color);
+  background: var(--ch-accent-soft);
+}
+
+.ch-nav-github {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 8px;
+  border-radius: 6px;
+  color: var(--bs-secondary-color);
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+.ch-nav-github:hover {
+  color: var(--bs-body-color);
+  background: var(--ch-accent-soft);
+}
+
+/* 顶栏一级导航（由 docfx.min.js 按 toc.yml 生成） */
+.navbar-collapse {
+  min-width: 0;
+}
+
+#navbar {
+  min-width: 0;
+  /* 章节有 7 个，窄屏上放不下就会换行成"首/页"这种两行标题 —— 改成横向滚动，
+     标题一律不折行（滚动条本身隐藏，触控板/滚轮照样能滚）。 */
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+#navbar::-webkit-scrollbar {
+  display: none;
+}
+
+#navbar .navbar-nav {
+  flex-wrap: nowrap;
+  gap: 2px;
+}
+
+#navbar .nav-link {
+  padding: 6px 12px;
+  border-radius: 6px;
+  font-size: 15px;
+  white-space: nowrap;
+  color: var(--bs-body-color);
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease;
+}
+
+#navbar .nav-link:hover {
+  color: var(--ch-accent);
+  background: var(--ch-accent-soft);
+}
+
+#navbar .nav-link.active,
+#navbar .nav-item.active > .nav-link {
+  color: var(--ch-accent);
+  font-weight: 600;
+}
+
+/* 搜索框：默认是 Bootstrap 的灰底，这里做成产品里那种浅色输入框 */
+form.search {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+form.search > i.bi-search {
+  position: absolute;
+  left: 10px;
+  font-size: 13px;
+  color: var(--bs-tertiary-color);
+  pointer-events: none;
+}
+
+form.search .form-control {
+  min-width: 190px;
+  padding-left: 30px;
+  border-radius: 6px;
+  background: var(--bs-tertiary-bg);
+}
+
+/* ── 左栏（章节导航）与右栏（本页内容） ───────────────────────────────── */
+.toc-offcanvas {
+  flex: 0 0 264px;
+  max-width: 264px;
+  padding-right: 8px;
+  border-right: 1px solid var(--bs-border-color);
+}
+
+.toc-offcanvas .offcanvas-header {
+  display: none;
+}
+
+#toc .nav,
+#affix .nav {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+
+#toc .nav-link,
+#affix .nav-link {
+  padding: 5px 10px;
+  border-left: 2px solid transparent;
+  border-radius: 0 6px 6px 0;
+  font-size: 14.5px;
+  line-height: 1.6;
+  color: var(--bs-secondary-color);
+  transition:
+    color 0.15s ease,
+    background-color 0.15s ease,
+    border-color 0.15s ease;
+}
+
+#toc .nav-link:hover,
+#affix .nav-link:hover {
+  color: var(--bs-body-color);
+  background: var(--ch-accent-soft);
+}
+
+#toc .nav-link.active,
+#affix .nav-link.active {
+  border-left-color: var(--ch-accent);
+  color: var(--ch-accent);
+  font-weight: 600;
+  background: var(--ch-accent-soft);
+}
+
+#toc .nav .nav,
+#affix .nav .nav {
+  margin-left: 10px;
+  padding-left: 6px;
+  border-left: 1px solid var(--bs-border-color);
+}
+
+#affix > .nav::before {
+  content: '本页内容';
+  display: block;
+  margin-bottom: 8px;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  color: var(--bs-tertiary-color);
+}
+
+.affix .toc-filter {
+  margin-bottom: 10px;
+}
+
+/* ── 正文 ─────────────────────────────────────────────────────────────── */
+article {
+  max-width: 46rem;
+  color: var(--bs-body-color);
+}
+
+article > h1 {
+  margin: 0 0 1.2rem;
+  padding-bottom: 0.6rem;
+  border-bottom: 1px solid var(--bs-border-color);
+  font-size: 2rem;
+  font-weight: 650;
+  line-height: 1.35;
+  letter-spacing: -0.01em;
+}
+
+article h2 {
+  margin: 2.6rem 0 0.9rem;
+  font-size: 1.4rem;
+  font-weight: 650;
+  line-height: 1.4;
+}
+
+article h3 {
+  margin: 1.9rem 0 0.6rem;
+  font-size: 1.13rem;
+  font-weight: 650;
+  line-height: 1.5;
+}
+
+article h4 {
+  margin: 1.5rem 0 0.5rem;
+  font-size: 1rem;
+  font-weight: 650;
+}
+
+article h1,
+article h2,
+article h3,
+article h4 {
+  scroll-margin-top: calc(var(--ch-navbar-h) + 16px);
+}
+
+article p,
+article li {
+  line-height: 1.85;
+}
+
+article a {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/* 文档里大量出现「代码 + 中文」混排，行内代码要能跟正文对齐 */
+article code {
+  padding: 0.15em 0.4em;
+  border-radius: 5px;
+  background: var(--bs-tertiary-bg);
+  font-family: var(--ch-font-mono);
+  font-size: 0.875em;
+  word-break: break-word;
+}
+
+article pre {
+  margin: 1.1rem 0;
+  padding: 14px 16px;
+  border: 1px solid var(--bs-border-color);
+  border-radius: var(--ch-radius);
+  background: var(--bs-tertiary-bg);
+  line-height: 1.65;
+  overflow-x: auto;
+}
+
+article pre code {
+  padding: 0;
+  background: none;
+  font-size: 13.5px;
+  color: inherit;
+  word-break: normal;
+}
+
+article blockquote {
+  margin: 1.2rem 0;
+  padding: 2px 0 2px 16px;
+  border-left: 3px solid var(--ch-accent);
+  color: var(--bs-secondary-color);
+}
+
+article blockquote p:last-child {
+  margin-bottom: 0;
+}
+
+article table {
+  display: table;
+  width: 100%;
+  margin: 1.2rem 0;
+  border: 1px solid var(--bs-border-color);
+  border-radius: var(--ch-radius);
+  border-collapse: separate;
+  border-spacing: 0;
+  overflow: hidden;
+  font-size: 14.5px;
+}
+
+article table thead th {
+  background: var(--bs-tertiary-bg);
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+article table th,
+article table td {
+  padding: 9px 13px;
+  border: 0;
+  border-bottom: 1px solid var(--bs-border-color);
+  border-right: 1px solid var(--bs-border-color);
+  vertical-align: top;
+  line-height: 1.7;
+}
+
+article table tr > *:last-child {
+  border-right: 0;
+}
+
+article table tbody tr:last-child > td {
+  border-bottom: 0;
+}
+
+article table img {
+  max-width: 100%;
+}
+
+article img {
+  max-width: 100%;
+  border-radius: var(--ch-radius);
+}
+
+article hr {
+  margin: 2.4rem 0;
+  border-top: 1px solid var(--bs-border-color);
+  opacity: 1;
+}
+
+/* 标题旁自动生成的锚点：默认常显会显得很吵，只在悬停/聚焦时露出来 */
+article a.anchor,
+article h1 > a.anchor,
+article h2 > a.anchor,
+article h3 > a.anchor {
+  float: none;
+  margin-left: 8px;
+  color: var(--bs-tertiary-color);
+  opacity: 0;
+  text-decoration: none;
+  transition: opacity 0.15s ease;
+}
+
+article h1:hover > a.anchor,
+article h2:hover > a.anchor,
+article h3:hover > a.anchor,
+article a.anchor:focus-visible {
+  opacity: 1;
+}
+
+/* ── 页脚区（上一页/下一页、编辑入口、站点页脚） ─────────────────────── */
+.contribution {
+  margin-top: 2.4rem;
+}
+
+.contribution .edit-link {
+  display: inline-block;
+  padding: 5px 12px;
+  border: 1px solid var(--bs-border-color);
+  border-radius: 6px;
+  font-size: 13.5px;
+  color: var(--bs-secondary-color);
+  text-decoration: none;
+  transition:
+    color 0.15s ease,
+    border-color 0.15s ease;
+}
+
+.contribution .edit-link:hover {
+  border-color: var(--ch-accent);
+  color: var(--ch-accent);
+}
+
+.next-article {
+  margin-top: 1.6rem;
+  padding-top: 1.2rem;
+}
+
+.next-article a {
+  display: inline-flex;
+  gap: 6px;
+  align-items: baseline;
+  max-width: 48%;
+  font-size: 14.5px;
+}
+
+footer.border-top {
+  margin-top: 2rem;
+  padding: 20px 0;
+  font-size: 13.5px;
+}
+
+.ch-footer {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+  justify-content: center;
+}
+
+.ch-footer a {
+  color: var(--bs-secondary-color);
+  text-decoration: none;
+}
+
+.ch-footer a:hover {
+  color: var(--ch-accent);
+}
+
+.ch-footer-sep {
+  color: var(--bs-tertiary-color);
+}
+
+/* ── 首页的入口卡片 ───────────────────────────────────────────────────────
+   首页（docs/index.md）里手写的一小块 HTML。只在首页用到，所以没做成通用组件。 */
+.ch-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  gap: 12px;
+  margin: 1.6rem 0 2rem;
+}
+
+.ch-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 16px 18px;
+  border: 1px solid var(--bs-border-color);
+  border-radius: 10px;
+  text-decoration: none;
+  transition:
+    border-color 0.15s ease,
+    box-shadow 0.15s ease,
+    transform 0.15s ease;
+}
+
+.ch-card:hover {
+  border-color: var(--ch-accent);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.07);
+  transform: translateY(-2px);
+}
+
+.ch-card-title {
+  font-size: 15.5px;
+  font-weight: 600;
+  color: var(--bs-body-color);
+}
+
+.ch-card-desc {
+  font-size: 13.5px;
+  line-height: 1.65;
+  color: var(--bs-secondary-color);
+}
+
+.ch-tagline {
+  margin: 0 0 1.6rem;
+  font-size: 17px;
+  color: var(--bs-secondary-color);
+}
+
+/* 首页的截图墙 */
+.ch-shots {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 16px;
+  margin: 1.4rem 0 2rem;
+}
+
+.ch-shots img {
+  width: 100%;
+  border: 1px solid var(--bs-border-color);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ch-card {
+    transition: border-color 0.15s ease;
+  }
+
+  .ch-card:hover {
+    transform: none;
+  }
+}
+
+/* ── 搜索结果页 ───────────────────────────────────────────────────────── */
+.search-results .search-list-item {
+  padding: 12px 0;
+  border-bottom: 1px solid var(--bs-border-color);
+}
+
+/* ── 小屏 ─────────────────────────────────────────────────────────────── */
+@media only screen and (max-width: 991px) {
+  .toc-offcanvas {
+    flex: 0 0 240px;
+    max-width: 240px;
+  }
+
+  article > h1 {
+    font-size: 1.7rem;
+  }
+}
+
+/* 中屏（约 1000–1200px）：顶栏放不下 7 个章节 + 搜索框，把每项收窄一档，
+   配合上面 #navbar 的横向滚动，标题不会被折成两行。 */
+@media only screen and (max-width: 1200px) {
+  #navbar .nav-link {
+    padding: 6px 8px;
+    font-size: 14px;
+  }
+
+  form.search .form-control {
+    min-width: 150px;
+  }
+}
+
+@media only screen and (max-width: 767px) {
+  body {
+    font-size: 15.5px;
+  }
+
+  .navbar-brand {
+    font-size: 16px;
+  }
+
+  .ch-version {
+    display: none;
+  }
+
+  article table {
+    display: block;
+    overflow-x: auto;
+    white-space: nowrap;
+  }
+
+  article > h1 {
+    font-size: 1.55rem;
+  }
+
+  .next-article a {
+    max-width: 100%;
+  }
+}
+
+/* ── 打印 ─────────────────────────────────────────────────────────────── */
+@media print {
+  .toc-offcanvas,
+  .affix,
+  header.bg-body,
+  .contribution,
+  .next-article {
+    display: none !important;
+  }
+
+  article {
+    max-width: none;
+  }
+}

docs/toc.yml

@@ -0,0 +1,14 @@
+- name: 首页
+  href: index.md
+- name: 快速上手
+  href: get-started/index.md
+- name: 应用帮助
+  href: app/index.md
+- name: 管理运维
+  href: management/index.md
+- name: 开发文档
+  href: dev/index.md
+- name: 常见问题
+  href: faq.md
+- name: 完整参考
+  href: reference.md

eslint.config.mjs

@@ -34,6 +34,8 @@ export default tseslint.config(
       '**/.cache/**',
       '**/.pnpm-store/**',
       '**/.probe/**',
+      // 文档站（docfx）的构建产物：里面是 docfx 模板自带的压缩 JS 与生成的 HTML
+      '**/docs/_site/**',
       '**/*.d.ts',
     ],
   },

package.json

@@ -1,8 +1,8 @@
 {
   "name": "class-helper",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": true,
-  "description": "班级小助手 - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
+  "description": "ClassHelper - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
   "packageManager": "pnpm@11.8.0",
   "engines": {
     "node": ">=20.19.0"
@@ -36,8 +36,14 @@
     "verify:classisland": "pnpm --filter @classhelper/server verify:classisland",
     "verify:classisland-plugin": "node packages/classisland-plugin/scripts/verify.mjs",
     "icons": "node scripts/generate-icons.mjs",
+    "version:check": "node scripts/version.mjs",
+    "version:bump": "node scripts/version.mjs --bump",
+    "docs:build": "node docs/build.mjs",
+    "docs:serve": "node docs/build.mjs --serve",
+    "pages:build": "node scripts/build-pages.mjs",
+    "dev:site": "pnpm docs:build && node website/serve.mjs",
+    "docs:check": "node docs/build.mjs --check",
     "dist:win": "pnpm --filter @classhelper/desktop-client dist:win",
-    "dist:dir": "pnpm --filter @classhelper/desktop-client dist:dir",
     "dist:server": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs",
     "dist:server:linux": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs --platform linux",
     "dist:classisland-plugin": "node packages/classisland-plugin/scripts/build.mjs --cipx",