fix(update): 修复云端安装交接并完善发布验收

修复隐藏缓存目录下载和响应收尾，使用原生助手校验安装包并确认交接。
补齐真实静默升级、便携版及中文路径验收，并按现行设备和科目授权契约更新回归。
服务端安装时生成独立密钥，覆盖升级保留既有配置；补齐安装包副本验证说明。

.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

@@ -0,0 +1,132 @@
+name: 发布 Linux 服务端安装包
+
+# 为什么单独有这个 workflow：
+#   Linux 包的依赖（@libsql/linux-x64-gnu、@prisma/adapter-libsql 等）是平台相关的，
+#   在 Windows 开发机上 npm install 出来的 node_modules 装到 Linux 跑不起来，
+#   所以 Linux 包必须在 Linux 上构建。这个 workflow 用 ubuntu runner 产出
+#   classhelper-server-linux-x64-<版本>.tar.gz 并挂到 GitHub Release 上，
+#   服务器上的 `classhelper upgrade` 就是从这里下载 + 校验 sha256 的。
+#
+# 用法：
+#   1. 先在本地按惯例打出 Windows 包并发 Release（vX.Y.Z）；
+#   2. 到 Actions 页面手动运行本 workflow，填 tag（例如 v1.1.2）；
+#   3. 跑完 Release 里会多出 Linux 包与更新后的 SHA256SUMS-<版本>.txt。
+#
+# 也可以只跑构建不挂 Release（attach=false），产物在 workflow 的 Artifacts 里。
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: '要构建并挂载的 Release tag（例如 v1.1.2）'
+        required: true
+        type: string
+      attach:
+        description: '构建后上传到该 Release'
+        required: false
+        default: true
+        type: boolean
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build-linux-package:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 40
+
+    steps:
+      - name: 确定 tag
+        id: ref
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
+            echo "attach=${{ inputs.attach }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            echo "attach=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: 检出代码
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.ref.outputs.tag }}
+
+      - name: 安装 Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: 安装 pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.8.0
+          run_install: false
+
+      - 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 releases/server/*/linux-x64/
+
+      - name: 上传构建产物（Artifacts）
+        uses: actions/upload-artifact@v4
+        with:
+          name: classhelper-server-linux-x64
+          path: |
+            releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz
+            releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz.sha256
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: 挂到 Release 并更新 SHA256SUMS
+        if: steps.ref.outputs.attach == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.ref.outputs.tag }}
+        run: |
+          set -euo pipefail
+          VERSION="${TAG#v}"
+          ARTIFACT_DIR="releases/server/${VERSION}/linux-x64"
+          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 包那几行），只替换/追加本包这一行，其余内容原样保留。
+          # 注意**不要**用 `sort -u` 去重：那份文件是人读的（表头 + 体积 + 说明），排序会把它们打散。
+          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
+          touch "$SUMS"
+          grep -v "^[0-9a-f]\{64\}  classhelper-server-linux-" "$SUMS" > "${SUMS}.new" || true
+          printf '%s  %s\n' "$(sha256sum "$TARBALL" | awk '{print $1}')" "$(basename "$TARBALL")" >> "${SUMS}.new"
+          mv "${SUMS}.new" "$SUMS"
+
+          gh release upload "$TAG" "$TARBALL" "$SHAFILE" "$SUMS" --clobber
+          echo "已上传："
+          cat "$SHAFILE"
+          cat "$SUMS"

.gitignore

@@ -38,3 +38,18 @@ eslint-report.json
 .idea/
 .DS_Store
 Thumbs.db
+
+# 设计参考压缩包（令牌见 docs/dev/winisland-design-tokens.md）
+WinIsland-master.zip
+releases/
+
+# AI 会话产物（ZCode 计划/配置，不属于产品代码）
+.zcode/
+.zcodeignore
+packages/server/prisma/backups/
+packages/server/prisma/database-settings.json
+
+# 文档站构建产物（pnpm docs:build 生成，由 GitHub Pages 发布；见 docs/）
+docs/_site/
+
+packages/data/courseware/

.prettierignore

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

AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md — ClassHelper（Class Helper）
+
+本文件供本仓库的 AI 编码代理使用。先读这里，再改代码。当前工作目录为 `F:\ClassHelper`。
+现行规则按工作区源码维护；产品说明见 `docs/app/`，开发契约见 `docs/dev/`，部署见 `docs/management/`。
+查证路径见 `docs/reference.md`。文档与代码冲突时，阅读实现及其校验规则后同步修正文档，不沿用历史报告中的结论。
+
+## 1. 项目与目录
+
+pnpm monorepo，根 `package.json` 是版本单一来源。文档、注释、界面文案及提交描述使用中文。
+远端为 `LoveChengke/ClassHelper`，默认分支 `master`。
+
+| 目录                       | 用途                                                      |
+| -------------------------- | --------------------------------------------------------- |
+| `packages/shared/src/`     | 三端共享类型、权限、常量、动效、岛方案与课件契约          |
+| `packages/server/`         | Express、Prisma、Socket.IO；API 前缀 `/api`               |
+| `packages/web-admin/`      | Vue Web 管理端，PWA                                       |
+| `packages/desktop-client/` | Electron 主进程、preload、主窗口与独立灵动岛渲染进程      |
+| `scripts/`                 | 版本、构建、验证、打包、图标与 Pages 脚本                 |
+| `deploy/`                  | Windows/Linux/Docker 部署与运维模板                       |
+| `docs/`                    | docfx 文档；`images/` 为展示图，`screenshots/` 为回归截图 |
+| `website/`                 | 纯静态官网与下载页                                        |
+| `releases/`                | 按组件和版本存放本地交付物，gitignored                    |
+
+不要在文档中手抄模块、表、权限键、测试用例的总数；分别查注册表、schema、共享目录与本次验证输出。
+
+## 2. 服务端与数据边界
+
+- 模块由 `packages/server/src/modules/registry.ts` 注册；新增或下线功能改注册表，不另改 `app.ts` 挂载。
+- 路由用 `middleware/validate.ts` 与 zod；响应复用 `lib/http.ts`，错误交给统一中间件。
+- 学生是 `Student` 名单记录，没有账号、角色或密码。教师/管理员存 `User`；班级登录读取 `Class.code/passwordHash`，会话角色 `CLASS_DEVICE`，主体 id 为班级 id。
+- 任课关系只在 `Course(classId, name, teacherId)`。班主任不自动获得别的科目的作业、成绩写权限，统一走 `lib/authz/assert.ts` 的 `assertContentWrite`。班级端可录作业，不可写成绩；员工还须对应功能权限。
+- 功能、范围、关系统一由 `lib/authz/` 判定，所有服务显式传权限键。ADMIN 固定全部能力；TEACHER 永久忽略管理员专用键；CLASS_DEVICE 为空集，接口明确允许并校验本班。权限管理仅 ADMIN。
+- 岗位模板只管能力与建议范围，生效范围存 `UserPermissionGroup.scope/scopeValue`，使用 TEACHING/HEAD/GRADE/DIVISION/ALL。无显式分配的教师使用默认模板与固定 TEACHING；空或未知年级拒绝。按键独立合并范围，无键查询为空集；班级账号/学期设置永远要求本班班主任，科目写检查原/目标科目。具体断言和迁移见 `docs/dev/permissions.md`。
+- 只有一份 `prisma/schema.prisma`，切库改 provider；保持 SQLite/MySQL 通用，不加 Prisma enum 或 `@db.*`。模型变动同步迁移、`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 与旧库兼容逻辑。
+- `deleteTeacher` 必须保护班主任、课程任课、发布的作业/通知和所属课件，避免级联删除业务内容。
+- 作业和通知按本地 `assignDate` 归类，使用 `dayKeyLocal/isDayKey/shiftDayKey`，不用 UTC 日期切片。
+- 批量通知/作业逐班返回结果；跨班作业按科目名匹配既有课程，找不到则该班失败，不自动把发布者设为任课老师。
+- 两个登录接口共用登录限流。附件链接校验 scheme；表格文件上限 8 MB、JSON 请求体 12 MB，超限映射 413。
+- AI 助手只解析待确认动作，前端确认后调既有发布接口；参数重新校验，Key 加密存储且不回传。自动化用 mock，不访问外网。
+
+## 3. 课表、周次、成绩与学年
+
+- 课表真值是 `ClassPlan/ClassPlanEntry/TimeLayoutItem`；旧 `Schedule` 与 `TimeLayout.items` 保留迁移审计用途，不双写或回读复活旧业务。
+- `/api/schedules/*` 是新模型兼容门面。启用解析统一走 `lib/class-plan.ts`，在线客户端不得另写启用优先级。
+- 时间点有上课、课间、分割线、行动四种；课程显式引用时间点外键。排序不能靠数组下标代替关联。
+- 支持 1–9 周轮换、群组、预定及临时层；完整档案导入走 `profile-import.service.ts`，不经过单双周有损格式。
+- 全校时间表写入仅管理员；班级时间表按存储 classId 校验 `schedule:write` 与班主任关系，引用班级也校验。日课表/名单在 TEACHING/HEAD 范围要求班主任，显式年级/部/全校分配可在范围内维护。离线整套课表导入可建立班级自有作息，不把 JSON 的 TeacherName 当授权。
+- 周次统一 `loadTermContext/resolveCurrentWeek`：班级逐周区间优先于全校区间，缺省再线性推算。开学日会参考班级设置、第 1 周区间、全校设置与环境兜底，详见 `lib/term.ts`。
+- 全校周数上限存 `term.maxWeeks`，默认 30、范围 1–60；服务端 `getMaxTermWeeks()`，shared 做归一化与离线兜底。班级周数不超全校上限。
+- 关闭个人成绩查询后，班级端仍可看服务端集体聚合；个人明细、原始全班成绩和排名拒绝读取。稀疏样本及补集抑制，不下发原始成绩后在客户端聚合。
+- 总分开关属于 `Exam`；排名同学生同科取最高分，并列排名为 1、2、2、4。客户端只展示，不能修改成绩查询或考试配置。
+- 年度升级由 `term.promotionAt` 配置，`PromotionRun.year` 保证幂等，升级前保存快照。运行期到点自动执行，启动漏跑先预览补跑；开发机启动不得擅自升级业务数据。
+- 高三归档，其余升一级；新班仅建骨架，不复制班主任/任课关系。转出过滤复用 `lib/students.ts`，学号不复用，归档页保留历史与撤回转出。
+
+## 4. 客户端、灵动岛与课件
+
+- preload 仅暴露 contextBridge 白名单，不暴露 ipcRenderer；跨桥接传纯数据，不传 Vue Proxy。契约写在 `src/types/desktop.d.ts`。
+- 保留 CSP、导航同源校验与弹窗限制。安装包不能含凭据，保留 `check-bundle-secrets` 构建门禁。
+- 离线缓存按服务端与班级隔离，缓存故障不应阻断在线读取。退出、切服务器时清理会话状态，设备 `deviceKey` 保持不变，渲染层不能改写它。
+- 设备维护只走 `/api/clients/*`，管理页 `ClientsView.vue`；心跳、进度、回执仅接受本班 CLASS_DEVICE，deviceKey 不可跨班迁移。心跳约 30 秒，90 秒窗口判在线；未登录不报，401/403 退避，切配置重置计时并隔离迟到响应。
+- 远控须 `remote:control`，只允许 shutdown/restart/logoff/lock，客户端立即执行、持久去重并回执。冒烟始终假执行，不得真关机/重启/注销/锁屏。
+- 安装包登记/删除为管理员 `client:update`；班级推送用 `client:update-push`；服务端缓存包并登记 SHA256，教室机从本服务下载；无哈希拒收，按立即/放学后/空闲策略执行，关闭自动更新不得强装。冒烟不运行安装器。
+- 灵动岛方案保存在本机 `config.json.islandLayout`，默认 `layout=fixed`；`custom` 当前即常驻模式，旧 `residentEnabled` 是兼容字段。新尺寸上报仅在 custom 模式执行。
+- `LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`，共用一个原生岛窗口；课件传输状态优先显示 `CoursewareTransfer.vue`。
+- 经典模式：普通通知/作业上课暂存；普通叫人保留可点击胶囊；紧急消息立即展开。自定义常驻模式：消息先提示铃铛数量，用户主动展开；上课也可主动查看。不要把两个模式规则混写。
+- 自定义方案的常态 `rows` 与无消息展开 `expandedRows` 分开编辑。课程、时钟、容器等使用 shared 组件契约；测量自然内容并按工作区约束适配。
+- 保留经典岛连续圆角、投影常驻、触摸输入、失焦宽限与固定窗口几何护栏。不要调用 `setBackgroundMaterial()` 破坏逐像素透明。左右边距仅左/右停靠生效。
+- 消息按 id 去重，通知/叫人双播不得重复；列表布局复用 shared 度量。崩溃恢复保持限流，冒烟不得自重启。
+- 课件权限和任课范围独立校验：拥有文件、文件可见范围与本人授课班级共同约束推送，岗位范围不代替任课授权。
+- 课件最大 512 MB，流式收发、临时文件、SHA256 校验；客户端不自动运行文件，每设备独立回执。JSON 快照只含元数据，完整备份另带文件目录。
+
+## 5. 实时、界面与资源
+
+- 事件名与房间名取 shared 常量。班级房间为 `class:{id}:{channel}`，教师按每域读键及范围订阅，班级端仅本班全部通道；握手回查数据库身份。业务用 `emitToClass/emitToSession`，由总线选择事件域。
+- 会话房间为 `session:{id}`；教师/管理员 id 为账号 id，班级端为班级 id。`students` 是班级端广播房间，不是个人学生账号房间。
+- 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。
+- Web 菜单分组在 `config/navigation.ts`，标题/图标/权限取路由；守卫与服务端都检查权限，前端隐藏不能代替鉴权。
+- 侧栏折叠用 CSS 保持 DOM，关怀模式放大字号/控件，不改变几何令牌。使用语义色，动效统一 shared 令牌；图标新增后检查注册表。
+- 图标源是 `build/classhelper.png` 与设计导出的 `.ico`，`pnpm icons` 派生其余资源。ICO 原样透传，客户端兜底 `build/icon.*` 同步保留。
+- Web 品牌图用 `/logo.png`，客户端用 `BRAND_LOGO_URL`，避免 file:// 绝对路径问题。
+- 官网和文档站共用一个 Pages 站点，`scripts/build-pages.mjs` 拼装根站与 `/docs/`；文档不写指向 docs 树外的相对链接，源码用 GitHub 绝对链接。
+- 展示图引用 `docs/images/`，回归图放 `docs/screenshots/`。官网 `.reveal-grad` 不拆逐字节点，动效改 token 表。
+- ClassIsland 联动插件、设备令牌、提醒渠道与镜像接口已退役；保留离线 JSON 导入和设计参考，不恢复在线联动依赖。
+
+## 6. 本机命令与验证
+
+脚本以根/各包 `package.json` 为准；端口：后端 4000，Web dev 5173，客户端 dev 5174，官网 5180，文档 5181。
+先构建 shared 再启动下游。新环境按需执行 install → db:generate → server db:deploy → build:shared；`db:seed/db:reset` 会清业务表，只用于明确选择的演示/隔离库。
+
+本机 Node 路径为 `D:\Node.js\node.exe`。受限终端的 pnpm 可能解析到运行时兜底版本，先看 `Get-Command pnpm` 与 `pnpm --version`。
+仓库锁定 pnpm 11.8.0，可用 `C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs`。
+经 DSH 转发壳时可设置：
+
+```powershell
+$env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH
+$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'
+Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue
+pnpm --version
+```
+
+受限 electron-builder 调 pnpm list 曾报 `ERR_SQLITE_ERROR`，这是进程访问限制，不据此认定依赖缺失。
+Prisma 使用 driver adapter；本机优先应用已有迁移，不用 `migrate dev` 排查 Windows 初始化问题。
+本地 HTTP 探测绕过代理；运行中数据库及 WAL/SHM 不按临时文件清理。
+
+| 命令                                                        | 范围                                                   |
+| ----------------------------------------------------------- | ------------------------------------------------------ |
+| `pnpm lint` / `pnpm typecheck` / `pnpm check:icons`         | 代码静态门禁；按改动范围执行                           |
+| `pnpm docs:check`                                           | 文档严格构建，警告即失败                               |
+| `pnpm verify:e2e`                                           | 自动创建临时 SQLite 和账号，无需先开开发服务，禁止外网 |
+| `pnpm verify:web:isolated`                                  | 构建 Web 后运行隔离服务和隐藏 UI 回归                  |
+| `pnpm verify:courseware` / `pnpm verify:v14`                | 课件/课表等隔离专项                                    |
+| `pnpm verify:desktop` / `pnpm verify:packaged --exe <路径>` | 默认后台快速检查，不创建可见岛或托盘                   |
+| `pnpm verify:desktop:online`                                | 显式联网，使用临时教师和班级                           |
+| `pnpm verify:desktop:visual` / packaged 的 `--visual`       | 显式视觉模式，动画、透明度、截图；会使用桌面           |
+
+禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。
+仅文档修改做格式、链接、构建检查，不为此反复占用桌面或重打安装包。
+Prettier 用 LF，只格式化本次改动；不要为旧基线批量格式化源码。
+改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证；改打包逻辑需打包后副本复验。
+
+## 7. 发布与工作区清理
+
+- 版本只由 `scripts/version.mjs` 修改；日常维护不涨版，指定固定版本重构建时保持该版本。发布流程见 `docs/dev/release.md`。
+- 本地 `pnpm dist:all` 产出 Windows 服务端和客户端；Linux 正式包由 `release-linux-server.yml` 在 Linux runner 构建，非 Linux 交叉构建仅供验证。
+- 本地文件名与 Release 的 ASCII 上传名不同，校验清单应明确映射；保留当前版本清单、更新日志及最新包。
+- `releases/` 只放交付物及少量构建信息，不留 win-unpacked、服务端 staging、解包副本；staging 在 `.cache/server-staging/`，成功后脚本删除。
+- 2026-10-18 按用户要求清除 1.4.0 旧重构建归档，只保留 `client/1.4.0`、`server/1.4.0` 与当前清单/说明。以后同号重构建可临时留回滚副本，最新包验证完成且用户要求清理时再删除。
+- 递归删除/移动前核实绝对路径在指定工作区，禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。
+- 不清理 `node_modules`、`.pnpm-store`、`.cache/{nuget,npm-cache,dotnet-home,mingit}`、`packages/*/dist`、生成的 Prisma Client，除非任务明确要求。
+- 保留已有未提交工作；提交前查看 diff，中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。

README.md

@@ -1,730 +1,234 @@
-# 班级小助手（Class Helper）
+<!--markdownlint-disable MD033 MD041-->
 
-班级信息管理系统，采用 pnpm monorepo，包含**后端服务**、**Web 管理端**（教师/管理员）与
+<div align="center">
-**桌面客户端**（学生）三端。核心链路：
 
-```
+# <img src="build/classhelper.png" width="30" height="30" alt="" /> ClassHelper
-教师在 Web 端发布内容
-        │  REST API（JWT 鉴权）
-        ▼
-   后端服务（Express + Prisma）
-        │  写入数据库 + 按班级房间广播
-        ▼
- Socket.IO  ──►  class:{classId} 房间  ──►  学生桌面客户端实时更新 UI
-```
 
-## 当前交付范围
+<img src="docs/images/web-dashboard.jpg" alt="ClassHelper · Web 管理端仪表盘" />
 
-| 阶段 | 内容                                                                                                       | 状态                                                       |
+[![正式版](https://img.shields.io/github/v/release/LoveChengke/ClassHelper?style=flat-square&color=%233fb950&label=正式版)](https://github.com/LoveChengke/ClassHelper/releases/latest)
-| ---- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+[![下载量](https://img.shields.io/github/downloads/LoveChengke/ClassHelper/total?style=social&label=下载量&logo=github)](https://github.com/LoveChengke/ClassHelper/releases)
-| 1    | pnpm monorepo 脚手架、TypeScript / ESLint / Prettier / 环境变量                                            | ✅ 已完成                                                  |
+[![Issues](https://img.shields.io/github/issues/LoveChengke/ClassHelper?style=flat-square&logo=github&label=Issues&color=%233fb950)](https://github.com/LoveChengke/ClassHelper/issues)
-| 2    | 后端：Prisma schema + 迁移 + 种子数据 + JWT 认证 + RBAC + 模块化 REST API + Socket.IO                      | ✅ 已完成                                                  |
+<br/>
-| 3    | Web 管理端：登录、主布局、仪表盘、班级/学生/课表/作业/通知/成绩页面、Axios 封装、实时提示                  | ✅ 已完成                                                  |
+![平台](https://img.shields.io/badge/%E5%B9%B3%E5%8F%B0-Windows%20%7C%20Linux-0078d4?style=flat-square)
-| 4    | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 27/27）                                |
+![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A5%2020.19-5fa04e?style=flat-square&logo=nodedotjs&logoColor=white)
-| 5    | 三端联调脚本、打包命令、完整 README                                                                        | ✅ 已完成（三套安装包 + 两套 UI 回归测试）                 |
+![Vue](https://img.shields.io/badge/Vue-3-4fc08d?style=flat-square&logo=vuedotjs&logoColor=white)
-| 6    | 测试账号与种子数据说明                                                                                     | ✅ 已完成（见下文）                                        |
+![Electron](https://img.shields.io/badge/Electron-44-47848f?style=flat-square&logo=electron&logoColor=white)
-| 7    | 生产化：服务端安装程序（内置 Node）、Web 端 PWA 可安装、Docker + Nginx 部署、生产加固与运维文档            | ✅ 已完成（见 [`docs/production.md`](docs/production.md)） |
+[![仓库大小](https://img.shields.io/github/repo-size/LoveChengke/ClassHelper?style=flat-square&color=3cb371)](https://github.com/LoveChengke/ClassHelper)
-| 8    | 客户端灵动岛（通知浮窗，上课隐藏 / 下课弹出 / 紧急立即展开）与上课时段紧急通知二次确认                     | ✅ 已完成（见"上课时段策略"）                              |
 
-> **与原始提示词的两处偏差（已与你确认）**
+ClassHelper是给中小学班级用的一套信息管理系统。<br/>
->
+**老师发一条通知，教室客户端与灵动岛会实时提醒**；<br/>
-> 1. 桌面客户端采用 **Electron + Vue 3**（而非 Avalonia/FluentAvalonia）：正文 90% 的要求
+学生打开客户端就能看到当天的课表和作业。
->    （Socket.IO Client、Pinia、IndexedDB 离线缓存、electron-builder）都基于 Electron，
->    且本机没有 .NET SDK。
-> 2. 数据库 **先用 SQLite（libSQL 内嵌）跑通 MVP，并预留 MySQL 切换**：本机没有可用 MySQL
->    实例；`docs/mysql.md` 给出云数据库切换的完整步骤，`deploy/` 提供 MySQL 版 Compose。
 
-## 三套交付产物
+#### [🚀 软件下载](https://github.com/LoveChengke/ClassHelper/releases/latest) | [📚 使用文档](docs/index.md) | [🧭 功能与源码索引](docs/reference.md) | [💬 反馈问题](https://github.com/LoveChengke/ClassHelper/issues)
 
-| 产物                            | 文件                                                                          | 用途                                                                                         |
+</div>
-| ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| **服务端 + Web 管理端安装程序** | `release-server/班级小助手服务端-0.1.0-x64-setup.exe`（34 MB）                | 装到教师电脑/校服务器即完整系统，**内置 Node 运行时**，双击安装、开机自启、自动建库建号      |
-| **学生客户端安装程序**          | `packages/desktop-client/release/班级小助手-0.1.0-x64-setup.exe`（107 MB）    | 学生机安装（NSIS 安装包）                                                                    |
-| **学生客户端单文件版**          | `packages/desktop-client/release/班级小助手-0.1.0-x64-portable.exe`（107 MB） | 免安装直接运行（U 盘分发）                                                                   |
-| Web 管理端（PWA）               | 由服务端在 `/` 直接托管                                                       | 浏览器打开即用，可在 Edge/Chrome 中「安装为应用」；**已适配手机小屏**（1Panel 风格抽屉导航） |
 
-生产部署（Windows 安装包 / Docker + MySQL / 手动部署）请看
+## 它由什么组成
-**[docs/production.md](docs/production.md)**。
 
-## 目录结构
+一份代码，三个交付物：
 
-```
+| 装在哪                  | 是什么                                                               | 谁在用               |
-class-helper/
+| ----------------------- | -------------------------------------------------------------------- | -------------------- |
-├── package.json                 # 根脚本（dev / build / db:* / verify:* / dist:* / icons）
+| 教师的电脑 / 学校服务器 | **服务端**（Express + Prisma + Socket.IO），同时托管 Web 管理端      | 管理端与客户端       |
-├── pnpm-workspace.yaml          # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
+| 浏览器（手机也行）      | **Web 管理端**（Vue 3 + Element Plus，PWA 可安装）                   | 老师、班主任、管理员 |
-├── tsconfig.base.json           # 共享 TS 基础配置
+| 教室那台机器 / 学生电脑 | **桌面客户端**（Electron + Vue 3），含「灵动岛」浮窗、托盘、离线缓存 | 教室大屏、学生       |
-├── eslint.config.mjs            # ESLint 扁平配置（TS + Vue）
-├── .dockerignore                # 容器构建上下文排除项
-├── build/icon.{ico,png}         # 应用图标（由 pnpm icons 生成）
-├── scripts/
-│   ├── use-database.mjs         # SQLite ⇄ MySQL provider 切换助手
-│   ├── generate-icons.mjs       # 用 Electron 渲染 SVG 生成 PNG/ICO 图标
-│   ├── dist-server.mjs          # 服务端 + Web 管理端 打包（免安装目录 + NSIS 安装程序）
-│   ├── lib/electron-env.mjs     # 启动 Electron 的公共处理（清理 RUN_AS_NODE + 定位可执行文件）
-│   ├── nsis/server-installer.nsi# 安装程序脚本模板
-│   └── ui-smoke/                # Web 管理端 UI 真实点击回归测试（Electron 驱动 + 上课时段探针）
-├── deploy/                      # 生产部署：Dockerfile / docker-compose.yml / nginx.conf
-├── docs/
-│   ├── production.md            # 生产部署指南（三种形态 + 运维 + 安全清单）
-│   └── mysql.md                 # MySQL 切换指南
-└── packages/
-    ├── shared/                  # 三端共享：类型契约、常量、工具函数
-    │   └── src/{types,constants,utils,index}.ts
-    ├── server/                  # 后端服务
-    │   ├── prisma/schema.prisma         # 数据模型
-    │   ├── prisma/migrations/           # 迁移历史（已生成并应用）
-    │   ├── prisma/seed.ts               # 种子数据
-    │   ├── prisma.config.ts             # Prisma 7 配置（迁移/种子/连接串）
-    │   ├── scripts/verify-e2e.mjs       # 后端端到端验收脚本（62 项）
-    │   └── src/
-    │       ├── app.ts                   # Express 装配（静态托管 + 探针 + 限流 + 模块挂载）
-    │       ├── index.ts                 # 启动入口（自检/初始化 + HTTP + Socket.IO + 优雅退出）
-    │       ├── config/env.ts            # 环境变量校验（zod）+ 生产配置自检
-    │       ├── lib/                     # db / db-bootstrap / web-static / http / jwt / access(RBAC) / mappers
-    │       ├── middleware/              # auth / error / validate / security(helmet+限流+耗时日志)
-    │       ├── realtime/                # socket.ts + bus.ts（事件总线）
-    │       └── modules/                 # 功能模块 + registry.ts
-    ├── web-admin/               # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
-    │   ├── public/                      # manifest / sw.js / 图标（由 pnpm icons 生成）
-    │   └── src/{api,stores,router,layouts,views,styles}
-    └── desktop-client/          # EXE 客户端（Electron + Vue 3）
-        ├── electron-builder.yml         # 打包配置（nsis 安装包 + portable 单文件）
-        ├── build/icon.ico               # 应用图标（electron-builder 自动使用）
-        ├── vite.config.mts              # 渲染进程构建（base: './'，hash 路由）
-        ├── scripts/{build-main,dev,smoke,dist-win}.mjs
-        └── src/
-            ├── main/                    # 主进程：窗口/单实例/配置持久化(IPC)/冒烟验证/灵动岛
-            ├── preload/                 # contextBridge 安全桥（不暴露 ipcRenderer 本体）
-            ├── island/                  # 灵动岛渲染进程（独立透明置顶窗口）
-            ├── types/desktop.d.ts       # 主进程 <-> 渲染进程契约
-            └── renderer/                # 渲染进程：api / stores / cache / router / layouts / views
-```
 
-## 技术栈
+老师在 Web 端发布内容 → 服务端落库并按班级房间广播 → 客户端与灵动岛实时更新。
 
-| 层         | 选型                                                                   | 版本                                                  |
+## 功能
-| ---------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
-| 包管理     | pnpm workspace                                                         | 11.8.0                                                |
-| 语言       | TypeScript                                                             | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x） |
-| 后端       | Node.js + Express                                                      | 24.18 / 5.2                                           |
-| ORM        | Prisma + driver adapter                                                | 7.10（+ `@prisma/adapter-libsql`）                    |
-| 实时       | Socket.IO                                                              | 4.8                                                   |
-| 认证       | jsonwebtoken + bcryptjs                                                | 9.0 / 3.0                                             |
-| 校验       | zod                                                                    | 4.6                                                   |
-| Web 端     | Vue 3 + Vite + Element Plus + Pinia + Vue Router + Axios + ECharts     | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20 / 6.1             |
-| EXE 客户端 | Electron + Vue 3 + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8                         |
-| 打包       | electron-builder（nsis / portable）                                    | 26.15                                                 |
 
-> 运行环境要求：**Node.js ≥ 20.19**（Prisma 7 硬性要求，推荐 22/24）。
+### Web 管理端（老师 / 管理员）
 
-## 快速开始
+- [x] 仪表盘：本班人数、课程、课表、作业、通知、成绩一屏概览
+- [x] 班级管理：建班自动生成班级码与班级密码，随时更换班主任、按科目配置各科任课老师
+- [x] 学生 / 教师管理：单个录入或导入名单（xlsx / xls / csv / tsv）
+- [x] 课表管理：日课表、共享作息、1–9 周轮换、群组与临时换课；支持完整 ClassIsland 档案离线导入
+- [x] 作业发布：按「所属日期」归类，支持附件与未交名单
+- [x] 通知发布：四档优先级；在**上课时段**发紧急通知会被拦下来并要求二次确认
+- [x] 叫人：点名某位同学到办公室，分「普通」与「紧急」两级
+- [x] 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计；单科排名自动出，可选「各科相加排总分榜」
+- [x] 客户端管理：查看设备在线状态与版本，远控关机、重启、注销与锁屏；推送更新可选立即、放学后或空闲时安装
+- [x] 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换
+- [x] 权限组：按功能键建组分配账号，支持岗位与年级范围 —— 默认组可自定义，没分组的按角色默认组生效，分组后只按组的并集算
+- [x] 大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库
+- [x] 通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级
+- [x] 系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态）
+- [x] 关怀模式：字号与控件整体放大
+- [x] 手机小屏适配，可「添加到主屏幕」当应用用
 
-```bash
+### 教室里的桌面客户端
-# 1. 安装依赖（Node >= 20.19，pnpm >= 10）
-pnpm install
 
-# 2. 准备环境变量（后端）
+- [x] 班级码登录 —— 学生没有个人账号，一台教室机器代表一个班
-cp packages/server/.env.example packages/server/.env
+- [x] 课表：「今天」时间轴（大时钟 + 正在上 / 下一节 + 距下课倒计时）与周视图
-#    → 至少修改 JWT_SECRET；本地开发可直接使用仓库内已有的 .env
+- [x] 作业看板：按科目分卡、可全屏铺满、字号可调，也能切回列表
-
+- [x] 通知中心：未读红点、优先级标签、点击自动标为已读
-# 3. 生成 Prisma Client 并建库、写入种子数据
+- [x] 成绩总览：开启个人查询时显示本班成绩与排名；关闭后仅展示服务端集体分析，保留隐私限制
-pnpm db:generate
+- [x] 教室机器可直接录入作业、勾选未交名单
-pnpm db:migrate
+- [x] 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
-pnpm db:seed
+- [x] 断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口
-
+- [x] 浅色 / 深色主题，跟随系统
-# 4. 启动（后端 4000 + Web 端 5173 一起启动）
-pnpm dev
-```
-
-启动后访问：
-
-| 服务                                       | 地址                             |
-| ------------------------------------------ | -------------------------------- |
-| Web 管理端（开发）                         | http://127.0.0.1:5173            |
-| 后端服务首页（浏览器可读，列出已挂载模块） | http://127.0.0.1:4000            |
-| 后端 API                                   | http://127.0.0.1:4000/api        |
-| 健康检查                                   | http://127.0.0.1:4000/api/health |
-
-> 后端只提供 REST API 与 WebSocket，没有业务网页界面。直接访问
-> `http://127.0.0.1:4000/` 会返回服务首页（带 `Accept: application/json` 时返回结构化信息）；
-> 其它未匹配路径统一返回 `{ "success": false, "code": "NOT_FOUND" }`。
-> Web 管理端地址是 **5173** 端口，请勿访问 80 端口（会连接被拒绝）。
-
-也可以分开启动：`pnpm dev:server`（仅后端）、`pnpm dev:web`（仅 Web 端）。
-
-### 启动 EXE 客户端（学生端）
-
-```bash
-# 开发模式：自动构建主进程 + 启动 Vite 渲染进程(5174) + 打开 Electron 窗口（支持热更新）
-pnpm dev:desktop
-
-# 已构建产物的冒烟验证（不弹窗，跑完自动退出）
-pnpm build:desktop
-pnpm verify:desktop
-```
-
-客户端首次启动会带上默认服务器地址 `http://127.0.0.1:4000`，可用学生账号 `student01 / student123` 登录。
-若要验证"断网可查看缓存"，登录并浏览过程序后关闭后端（`Ctrl+C` 停掉 `pnpm dev:server`），
-客户端会在顶部提示「当前处于离线状态」，页面继续显示本地缓存数据；重新启动后端后会自动同步。
-
-### 端到端验收脚本
-
-```bash
-# 另开一个终端先启动后端：pnpm dev:server
-pnpm verify:e2e          # 后端 + REST + Socket.IO + RBAC + 上课时段拦截：62 项
-pnpm verify:web          # Web 管理端真实点击（含手机小屏适配、上课时段紧急通知全屏警告）：15 项
-pnpm verify:desktop      # Electron 客户端（含灵动岛、真实通知链路与联网集成）：27 项
-```
-
-后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截**等 62 项，
-实测通知 37ms、作业 26ms、成绩 25ms 到达（要求 < 5 秒），紧急通知 409 拦截与二次确认后发布均通过；
-客户端脚本验证 preload 桥接、渲染进程、IndexedDB 读写、断网回退、**灵动岛四种状态切换**与联网集成
-（登录 + 四类数据 + Socket.IO），实测 27/27 通过。
-
-## 默认账号与种子数据
-
-`pnpm db:seed` 会清空业务表并写入一套完整演示数据（1 管理员 / 2 教师 / 3 班级 / 15 学生 /
-15 课程 / 90 条课表 / 15 份作业 / 12 条通知 / 90 条成绩）。
-
-| 角色   | 用户名                    | 密码         | 说明                                       |
-| ------ | ------------------------- | ------------ | ------------------------------------------ |
-| 管理员 | `admin`                   | `admin123`   | 可访问全部班级                             |
-| 教师   | `teacher1`                | `teacher123` | 张老师：高一(1)班、高二(3)班班主任         |
-| 教师   | `teacher2`                | `teacher123` | 李老师：高一(2)班班主任，高二(3)班协作教师 |
-| 学生   | `student01`               | `student123` | 高一(1)班                                  |
-| 学生   | `student02` … `student05` | `student123` | 高一(1)班                                  |
-| 学生   | `student06` … `student10` | `student123` | 高一(2)班                                  |
-| 学生   | `student11` … `student15` | `student123` | 高二(3)班                                  |
-
-- 学生初始密码可用 `DEFAULT_STUDENT_PASSWORD` 配置（默认 `123456`），
-  教师也可在「学生管理」里一键重置为默认密码。
-- 教学周由 `TERM_START_DATE`（第 1 教学周的周一）换算，当前周次用于课表默认视图。
-
-## 常用命令
-
-| 命令                                        | 说明                                                                                    |
-| ------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `pnpm dev`                                  | 并行启动 shared(tsc watch) + 后端 + Web 端                                              |
-| `pnpm dev:server` / `pnpm dev:web`          | 只启动后端 / 只启动 Web 端                                                              |
-| `pnpm dev:desktop`                          | 启动 EXE 客户端开发模式（Vite 5174 + Electron，热更新）                                 |
-| `pnpm build`                                | 构建 shared + 后端 + Web 端 + EXE 客户端                                                |
-| `pnpm build:desktop`                        | 仅构建 EXE 客户端（esbuild 主进程/preload + Vite 渲染进程）                             |
-| `pnpm icons`                                | 生成应用图标（PNG/ICO，用 Electron 渲染 SVG）                                           |
-| **`pnpm dist:server`**                      | **打包服务端 + Web 管理端**（免安装目录 + NSIS 安装程序，内置 Node）                    |
-| `pnpm dist:dir`                             | 打包客户端免安装目录 `release/win-unpacked`（含可执行文件，最快）                       |
-| `pnpm dist:win`                             | 打包客户端 nsis 安装包 + portable 单文件 EXE                                            |
-| `pnpm dist:all`                             | 服务端安装程序 + 客户端安装程序一起打                                                   |
-| `pnpm verify:e2e`                           | 后端端到端验收（62 项，需服务端已启动）                                                 |
-| `pnpm verify:web`                           | Web 管理端 UI 真实点击测试（Electron 驱动，15 项，含手机小屏适配）                      |
-| `pnpm verify:desktop`                       | EXE 客户端冒烟验证（27 项，含灵动岛行为/像素级截图/真实通知链路、侧边栏点击与离线回退） |
-| `pnpm typecheck`                            | 全仓库类型检查（含 `vue-tsc`）                                                          |
-| `pnpm lint` / `pnpm lint:fix`               | ESLint 检查 / 自动修复                                                                  |
-| `pnpm format` / `pnpm format:check`         | Prettier 格式化 / 检查                                                                  |
-| `pnpm db:generate`                          | 生成 Prisma Client（输出到 `packages/server/src/generated/prisma`）                     |
-| `pnpm db:migrate`                           | 创建并应用迁移                                                                          |
-| `pnpm db:seed`                              | 写入种子数据                                                                            |
-| `pnpm db:reset`                             | 重置数据库并重新执行 seed                                                               |
-| `pnpm db:studio`                            | 打开 Prisma Studio                                                                      |
-| `pnpm db:switch:mysql` / `db:switch:sqlite` | 切换数据库 provider                                                                     |
-
-## Web 管理端（含手机小屏适配）
-
-布局沿用 **1Panel 风格**：固定深色侧边栏（`#1f2d3d` + 蓝色圆角选中态）+ 白色顶栏（当前页标题/连接状态/用户菜单）+
-浅灰底 + 白色圆角卡片内容区。手机小屏下侧边栏收进抽屉，由顶栏汉堡按钮唤出。
-
-| 断点             | 布局行为                                                                                      |
-| ---------------- | --------------------------------------------------------------------------------------------- |
-| `> 992px` 桌面   | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与"已接收 N 条实时事件"                               |
-| `769–992px` 平板 | 保留侧边栏，内容区内边距压缩（14px）                                                          |
-| `<= 768px` 手机  | 侧边栏**不渲染**，顶栏汉堡按钮 → 240px 深色抽屉菜单；顶栏显示当前页标题；用户菜单收成头像图标 |
-
-手机端细节（1Panel 同款思路：控件纵向铺满、表格卡片内滚动、弹窗自适应）：
-
-| 位置        | 小屏行为                                                                      |
-| ----------- | ----------------------------------------------------------------------------- |
-| 抽屉菜单    | 点汉堡滑出、点菜单项自动收起；`aria-expanded` 标记状态；桌面端侧边栏视觉不变  |
-| 顶栏        | 只保留汉堡 + 当前页标题 + 连接状态圆点 + 头像；身份信息移入用户下拉菜单第一行 |
-| 页面工具栏  | 选择器/搜索框/按钮全部铺满整行（`width: 100%`），方便拇指点击                 |
-| 表格        | 卡片内横向滚动（`.table-card` + `overflow-x: auto`），页面本身不横向滚动      |
-| 弹窗/消息框 | 宽度 `calc(100vw - 24px)`、贴近整屏；表单标签与输入框自适应                   |
-| 详情抽屉    | 宽 86vw；`el-descriptions` 由 2~3 列自动降为单列，避免文字被压成竖排          |
-| 统计卡片    | `.stat-grid` 两列；登录页卡片自适应宽度并保留安全内边距                       |
-
-实拍（`pnpm verify:web` 自动留档到 `docs/screenshots/web-mobile/`）：
-
-| 场景                                      | 截图                                                                  |
-| ----------------------------------------- | --------------------------------------------------------------------- |
-| 手机抽屉菜单                              | ![手机抽屉菜单](docs/screenshots/web-mobile/mobile-1-drawer.png)      |
-| 手机通知页（工具栏铺满 + 表格卡片内滚动） | ![手机通知页](docs/screenshots/web-mobile/mobile-2-notifications.png) |
-| 手机弹窗自适应                            | ![手机弹窗](docs/screenshots/web-mobile/mobile-3-dialog.png)          |
-
-实现位置：`src/composables/useResponsive.ts`（断点 + resize 监听）、`src/layouts/AdminLayout.vue`（抽屉/顶栏）、
-`src/styles/index.css`（全局响应式规则）、各视图表格卡片加 `.table-card`。
-
-`pnpm verify:web` 的 15 项里，后 7 项专门验证手机端（Electron 真实点击 + 真实尺寸窗口）：
-
-| 校验项                                 | 实测结果                                                             |
-| -------------------------------------- | -------------------------------------------------------------------- |
-| 侧边栏收起、顶栏汉堡按钮出现           | ✅ `innerWidth=377` 汉堡=true 桌面侧边栏未渲染                       |
-| 点汉堡滑出抽屉菜单（菜单项完整）       | ✅ 7 项、`left=0`、`transform=none`、遮罩进入动画已结束              |
-| 抽屉里真实点击"通知发布"并自动收起抽屉 | ✅ `path=/notifications`、抽屉 `right=0`（已滑出屏幕）               |
-| 页面无横向溢出                         | ✅ `scrollWidth=377 = innerWidth`，越界元素=无（表格自身滚动不计入） |
-| 表格在卡片内横向滚动                   | ✅ 卡片可视 336px / 内容 576px / 表格 560px                          |
-| 工具栏控件铺满整行                     | ✅ 控件宽 338px（视口 377px）                                        |
-| 弹窗宽度自适应                         | ✅ 弹窗宽 353px、`left=12`（不超出视口且接近整屏）                   |
-
-> 踩坑记录：这套检查必须让窗口**真正可见**（`win.showInactive()`）。
-> Chromium 会冻结隐藏页面的 CSS transition，Vue 的 `<Transition>` 收不到 `transitionend`，
-> Element Plus 抽屉会一直停在 `enter-from`（表现为"点了没反应"）——冒烟里已按"等抽屉滑到位"断言，避免误判。
-
-> 手机访问：与电脑同一局域网时用 `http://<主机IP>:4000` 打开管理端；
-> 支持「添加到主屏幕」（PWA manifest + Service Worker）。
-
-## EXE 客户端（学生端）
-
-### 进程结构与安全设置
-
-| 进程     | 文件                                             | 职责                                                                                                           |
-| -------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| 主进程   | `src/main/*` → `dist/main/index.js`              | 窗口/单实例锁、配置持久化（`safeStorage` 加密 token）、IPC、冒烟验证                                           |
-| 预加载   | `src/preload/index.ts` → `dist/preload/index.js` | 通过 `contextBridge` 暴露最小 API（`getConfig/saveConfig/getAppInfo/openExternal`），不暴露 `ipcRenderer` 本体 |
-| 渲染进程 | `src/renderer/**` → `dist/renderer/*`            | Vue 3 界面、Axios 请求、Socket.IO 实时、IndexedDB 离线缓存                                                     |
-
-安全基线：`contextIsolation: true`、`nodeIntegration: false`、`sandbox: true`、`webSecurity: true`，
-外部链接一律交给系统浏览器打开，禁止应用内导航到非本地地址。
-
-### 功能页面
-
-| 页面 | 功能                                                                                      |
-| ---- | ----------------------------------------------------------------------------------------- |
-| 登录 | 服务器地址 + 用户名 + 密码，附带「测试连接」；已登录但服务器不可达时可「离线进入」        |
-| 课表 | 按周展示 7 列课表，支持上一周/下一周/下拉选择周次，高亮"今天"，显示周次范围与地点         |
-| 作业 | 列表（全部/未完成/已完成过滤）、详情抽屉、标记完成/取消完成、附件链接、逾期高亮           |
-| 通知 | 未读红点（侧边栏徽标）、优先级标签、点击自动标为已读、全部已读、未读过滤、详情抽屉        |
-| 成绩 | 表格（分数/得分率进度条/等级）+ ECharts 柱状图（各次考试平均得分率）+ 等级分布 + 最近更新 |
-| 设置 | 服务器地址（保存并测试）、账号信息、离线缓存条目统计与清空、客户端版本信息、退出登录      |
-
-> 通知到达时还会由**灵动岛**在桌面中上方浮出提醒（见上一节），上课时段自动隐藏、紧急通知立即展开。
 
 ### 灵动岛（桌面通知浮窗）
 
-客户端有一个独立于主窗口的**灵动岛**：一个无边框、透明、置顶、不占任务栏的窄条窗口，
+- [x] 通知、新作业、叫人都会上岛：经典模式使用胶囊与详情卡，自定义模式使用常驻内容与铃铛
-常驻桌面**中上方**（屏幕工作区顶部居中，`y = workArea.y + 8`）。它是"消息到达"的第一现场：
+- [x] 多条消息展开为竖排列表，按重要程度排序，放不下时提示去应用内看
+- [x] **经典模式上课时段不打扰**：普通通知暂存，普通叫人可点开胶囊，紧急消息立即展开；自定义模式点击铃铛查看
+- [x] 尺寸、圆角、字号、主题色、停靠位置（顶部 / 底部 × 左 / 中 / 右）都可以调
+- [x] 纯黑 / 毛玻璃 / 主题色渐变三种底
+- [x] 触摸屏（希沃白板这类一体机）也能点开
+- [x] 自定义常驻岛：分别编辑常态与无通知展开内容，收到消息显示铃铛，点击查看通知
 
-| 场景                       | 灵动岛行为                                                                                                 |
+### 部署与运维
-| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| 收到通知（非上课时段）     | **直接出现胶囊**（无"上岛"入场动画）：`新消息 · 共 N 条` + 发送人 + `点击查看`，15 秒后自动收起            |
-| 点击胶囊                   | 展开为**详情卡**（弹簧形变 + 内容弹入）：标题、内容、时间、`打开应用 / 标为已读 / 知道了`，20 秒后收起     |
-| 点击卡片空白处             | 回缩为**胶囊**（不直接消失，仍可再次点开）                                                                 |
-| 点击右上角收起按钮         | 同上：回缩为胶囊                                                                                           |
-| 上课时间段收到普通通知     | **完全不显示**（窗口直接隐藏，不打扰课堂）并进入待发队列；下课后自动弹出详情（14 秒）→ 收起为胶囊（25 秒） |
-| 上课时间段收到**紧急**通知 | **无论是否上课立刻展开**显示详情（带内部红色呼吸光晕与"紧急"角标，无需点击），45 秒后收起                  |
-| 上课时间段内的任何点击     | 一律不显示（不会展开、也不会回缩出胶囊），只有紧急通知能出现在屏幕上                                       |
-| 多条约谈                   | 队列按时间排序，紧急通知优先插播；卡片底部提示"还有 N 条通知"                                              |
-| 退出/断开                  | 主窗口退出时灵动岛一并关闭；上课状态来自 `GET /api/schedules/current`（10 秒心跳 + 下课时长定时器）        |
 
-- 动画：窗口尺寸用逐帧缓动实现"形变"（胶囊 → 详情/紧急为 340ms `easeOutBack` **弹簧回弹**，
+- [x] Windows 一键安装：内置 Node 运行时，双击安装、开机自启、自动建库建号
-  收起为 260ms `easeOutCubic`），胶囊出现**不做动画**直接显示；
+- [x] Linux 一键安装 + `classhelper` 运维命令（systemd 托管，升级 / 回滚 / 备份）
-  卡片内部用 `cubic-bezier(0.34, 1.56, 0.64, 1)` 弹簧缩放入场，未读点用 `dot-pulse`。
+- [x] Docker Compose（MySQL 版与 SQLite 版各一份）
-  尺寸与淡入使用**独立令牌**，互不打断（早前"淡入取消形变导致窗口卡在胶囊尺寸"的问题已修复）。
+- [x] SQLite 与 MySQL 一键切换，备份与跨库迁移共用同一份 JSON 快照
-- 光晕：紧急形态的红色呼吸光晕**只用 inset 阴影**画在卡片内部。
+- [x] 客户端批量更新不依赖外网：安装包由服务端下载缓存，教室机从服务端取，校验 sha256 后空闲时自动装
-  窗口只比卡片大 2~4px，任何向外的 box-shadow/光晕都会被窗口边界裁切，
-  在屏幕上表现为"卡片周围一圈奇怪的光晕硬边"——冒烟测试里有一条像素断言守着这一点
-  （截图最外圈偏红像素必须为 0）。
-- 事件流：`notification:new` → `renderer/stores/realtime.ts` → `pushNotificationToIsland()` →
-  主进程 `IslandController`（决定隐藏/胶囊/详情）→ 灵动岛渲染进程 `src/island/IslandApp.vue`。
-- 相关文件：`src/main/island.ts`（控制器 + IPC）、`src/preload/island.ts`、`src/island/IslandApp.vue`、
-  `src/renderer/island/bridge.ts`（上课状态轮询与通知转发）。
 
-各形态实拍（由 `pnpm verify:desktop` 自动截取并归档到 `docs/screenshots/island/`，并做像素级校验）：
+## 软件截图
 
-| 形态                   | 截图                                                                | 尺寸（逻辑 / 截图） | 说明                                      |
+> 下面这些图都是脚本把程序真的跑起来截的（`node website/tools/capture-shots.mjs` 与客户端冒烟），不是示意图。
-| ---------------------- | ------------------------------------------------------------------- | ------------------- | ----------------------------------------- |
-| 下课后自动弹出详情     | ![下课后自动弹出](docs/screenshots/island/island-2-after-class.png) | 404×316 / 808×632   | 上课期间暂存的通知，下课后自动弹出        |
-| 上课期间紧急通知       | ![紧急通知立即展开](docs/screenshots/island/island-3-urgent.png)    | 424×344 / 848×688   | 卡片**内部**红色光晕 + 紧急角标，无需点击 |
-| 非上课时段"新消息"胶囊 | ![新消息胶囊](docs/screenshots/island/island-4-pill.png)            | 268×44 / 536×88     | 直接出现（无入场动画），点击后展开        |
-| 点击胶囊后的详情       | ![点击后展开](docs/screenshots/island/island-5-clicked.png)         | 404×316 / 808×632   | 标题/内容/时间 + 打开应用/标为已读/知道了 |
 
-> 截图路径可用 `ISLAND_SHOTS_DIR` 覆盖（默认 `.cache/island-shots/`）；
+### Web 管理端
-> 归档目录里的图就是打包后 EXE 跑自动化验证时产出的同一份文件。
-> 不设置该变量时只做像素统计与断言、不落盘，验证同样通过。
 
-**灵动岛不出现时怎么排查**（客户端是 GUI，看不到控制台，因此提供两条自查通道）：
+<img src="docs/images/web-schedules.jpg" alt="Web 管理端 · 课表管理" />
 
-1. 客户端 → **设置 → 灵动岛（桌面通知浮窗）**：实时显示当前形态（隐藏 / 新消息胶囊 / 展开详情）、
+<details>
-   是否处于上课时段、待查看条数与原因说明，并提供「测试灵动岛」按钮——
+<summary>展开其余页面……</summary>
-   点击后本地推一条自检通知；能看到胶囊就说明灵动岛本身正常，问题在"没有通知到达"或"上课时段自动隐藏"。
-2. 客户端日志：`%APPDATA%\@classhelper\desktop-client\logs\client.log`（超过 1MB 轮转为 `client.log.1`），
-   按时间记录灵动岛的每次状态流转，例如 `灵动岛：进入上课时间段，自动隐藏`、
-   `灵动岛暂存通知（上课中，下课后弹出）`、`灵动岛：下课，弹出上课期间暂存的通知`。
 
-常见原因（按出现频率）：
+| 页面       | 截图                                                           |
+| ---------- | -------------------------------------------------------------- |
+| 仪表盘     | <img src="docs/images/web-dashboard.jpg" alt="仪表盘" />       |
+| 班级管理   | <img src="docs/images/web-classes.jpg" alt="班级管理" />       |
+| 学生管理   | <img src="docs/images/web-students.jpg" alt="学生管理" />      |
+| 教师管理   | <img src="docs/images/web-teachers.jpg" alt="教师管理" />      |
+| 课表管理   | <img src="docs/images/web-schedules.jpg" alt="课表管理" />     |
+| 作业发布   | <img src="docs/images/web-homeworks.jpg" alt="作业发布" />     |
+| 通知发布   | <img src="docs/images/web-notifications.jpg" alt="通知发布" /> |
+| 成绩录入   | <img src="docs/images/web-grades.jpg" alt="成绩录入" />        |
+| 数据库管理 | <img src="docs/images/web-database.jpg" alt="数据库管理" />    |
 
-| 现象                      | 原因与处理                                                                                                                                               |
+</details>
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 一整天都不出现            | 客户端判定为"上课中"（课表覆盖当前时刻）→ 普通通知按设计暂存，紧急通知才立刻展开；下课后自动弹出                                                         |
-| 登录页时就期待出现        | 未登录不启动灵动岛桥接（`auth.token` 为空），登录后才有                                                                                                  |
-| 点过「知道了」后消失      | 正常行为：该条已看过，队列为空时整体隐藏，下一条通知会再出现                                                                                             |
-| 换显示器 / 分辨率后看不到 | 已修复：显示器参数变化会自动重新定位到主屏顶部居中（此前会停留在旧坐标，可能跑到屏幕外）                                                                 |
-| 偶发"再也不出现"          | 已修复：Windows 上 `hide()`/`show()` 异步生效，原先用 `isVisible()` 判断存在竞态（刚 hide 完仍报 true）→ 只做动画不再 show；现改为控制器自己维护显示标记 |
-| 客户端在跑但服务端离线    | 实时通道断开时收不到新通知；恢复连接自动重连，历史未读仍可在"通知"页查看                                                                                 |
 
-### 离线缓存与自动同步
+### 教室里的客户端
 
-```
+<img src="docs/images/client-schedule.png" alt="桌面客户端 · 课表「今天」时间轴" />
-                     ┌────────────── 在线 ──────────────┐
-请求 → fetchWithCache(store, key, loader, fallback)
-                     └── 失败 → 读取 IndexedDB 缓存 → 返回旧数据（UI 标记"离线缓存"）
-实时推送(notification:new / grade:updated ...) → 更新内存状态 + 写回 IndexedDB
-服务器不可达 → 可达（health 轮询 20s 或任意请求成功）→ 触发 onServerRecovered → 各页自动重新拉取
-```
 
-- 缓存按业务域分为 6 个 object store：`profile` / `classes` / `schedules` / `homeworks` / `notifications` / `grades`。
+<details>
-- 缓存写入前统一做 JSON 纯化（Vue 响应式对象是 Proxy，直接写入 IndexedDB 会抛 `could not be cloned`）。
+<summary>展开其余页面……</summary>
-- 登录令牌由主进程用 Electron `safeStorage`（Windows 下为 DPAPI）加密后落盘，因此重启客户端可离线进入。
-- 令牌缺失/失效时保持缓存资料可见，恢复网络后自动刷新个人资料。
 
-### 打包 Windows EXE
+| 页面                    | 截图                                                                       |
+| ----------------------- | -------------------------------------------------------------------------- |
+| 作业看板                | <img src="docs/images/client-homeworks.png" alt="作业看板" />              |
+| 通知                    | <img src="docs/images/client-notifications.png" alt="通知" />              |
+| 成绩                    | <img src="docs/images/client-grades.png" alt="成绩" />                     |
+| 设置 · 灵动岛           | <img src="docs/images/client-settings-island.png" alt="设置 · 灵动岛" />   |
+| 设置 · 外观（深色主题） | <img src="docs/images/client-settings-appearance.png" alt="设置 · 外观" /> |
+
+</details>
+
+### 灵动岛
+
+| 形态               | 截图                                                                    | 说明                                            |
+| ------------------ | ----------------------------------------------------------------------- | ----------------------------------------------- |
+| 新消息胶囊         | <img src="docs/images/island-4-pill.png" alt="新消息胶囊" />            | 非上课时段直接出现，点一下展开                  |
+| 点开后的详情       | <img src="docs/images/island-5-clicked.png" alt="详情卡" />             | 标题、内容、时间 + 打开应用 / 标为已读 / 知道了 |
+| 多条消息列表       | <img src="docs/images/island-9-list.png" alt="多条消息列表" />          | 按重要程度排序，默认显示三条                    |
+| 上课期间的紧急通知 | <img src="docs/images/island-3-urgent.png" alt="紧急通知" />            | 卡片内部红色呼吸光晕，无需点击                  |
+| 下课后补弹         | <img src="docs/images/island-2-after-class.png" alt="下课后自动弹出" /> | 上课期间暂存的通知，下课后自动弹出来            |
+| 老师叫人           | <img src="docs/images/island-8-call.png" alt="叫人卡片" />              | 「请 XXX 同学找 XXX 老师」                      |
+| 新作业             | <img src="docs/images/island-7-homework.png" alt="新作业" />            | 教室机器自己录的那条不会弹给自己                |
+
+### 手机上
+
+<details>
+<summary>展开……</summary>
+
+| 场景     | 截图                                                                     |
+| -------- | ------------------------------------------------------------------------ |
+| 仪表盘   | <img src="docs/images/mobile-dashboard.jpg" alt="手机 · 仪表盘" />       |
+| 通知发布 | <img src="docs/images/mobile-notifications.jpg" alt="手机 · 通知发布" /> |
+
+</details>
+
+## 开始使用
+
+| 装在哪                  | 装什么                                      | 从 Releases 里拿                                                            |
+| ----------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
+| 教师的电脑 / 学校服务器 | **服务端**（内含 Web 管理端与 Node 运行时） | `ClassHelper-<版本>-x64-server-setup.exe`                                   |
+| 教室机器 / 学生电脑     | **学生客户端**                              | `ClassHelper-<版本>-x64-client-setup.exe`，或 `-client-portable.exe` 免安装 |
+
+也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑：
+选一个版本，四个包排成四张卡，文件名、体积与 SHA256 清单都在那儿 ——
+那一页的清单是**当场**读 GitHub Releases 的，显示什么就能下什么。
+
+服务端**装上就算跑起来了**：双击安装程序，建库、建号、开机自启都由它自己办，
+装完在浏览器打开 `http://<服务器地址>:4000` 就能登录。教师的电脑、学校的服务器、
+一台常年开机的机器都可以装。
+
+Linux 服务器有更省事的路子，一行命令装成 systemd 服务，并带上 `classhelper` 运维命令：
 
 ```bash
-pnpm dist:dir     # 免安装目录：packages/desktop-client/release/win-unpacked/班级小助手.exe
+curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/LoveChengke/ClassHelper/master/deploy/install.sh && sudo bash /tmp/classhelper-install.sh
-pnpm dist:win     # nsis 安装包 + portable 单文件（需联网下载 NSIS 工具，可用镜像）
 ```
 
-打包脚本 `packages/desktop-client/scripts/dist-win.mjs` 做了三件事，规避常见网络问题：
+先体检、不改动系统的话，在末尾加上 `--check`。也可以走 Docker Compose，
+完整步骤见[部署指南](docs/management/production.md)与 [Linux 运维手册](docs/management/linux-deploy.md)。
 
-1. **复用本地已解压的 Electron**：检测到 `node_modules/electron/dist/electron.exe` 时通过
+## 获取帮助
-   `--config.electronDist` 直接使用，不再重复下载 150MB+ 发行包；
-2. 默认走国内镜像（可用环境变量覆盖）：
-   `ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/`、
-   `ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/`；
-3. 构建缓存固定到仓库内 `.cache/`，不污染全局目录。
 
-产物说明：`release/win-unpacked/班级小助手.exe`（约 235MB，Electron 运行时）+ `resources/app.asar`
+- **使用文档**：[docs/](docs/index.md) —— 分四块：第一次装、已经在用了、负责运维、要改代码
-（约 2.7MB，仅含 `dist/` 与 `package.json`，运行时不需要 node_modules）。
+- **完整参考**：[docs/reference.md](docs/reference.md) —— 功能口径、REST API、权限矩阵、验收证据
-默认使用 Electron 内置图标（未提供 `build/icon.ico`）。
+- **遇到问题 / 想提需求**：[提交 Issue](https://github.com/LoveChengke/ClassHelper/issues/new/choose)
 
-### 客户端冒烟验证（无需人工点击）
+## 开发
 
-`pnpm verify:desktop` 以 `ELECTRON_SMOKE_TEST=1` 启动应用（不弹窗），主进程依次校验后自动退出：
+| 层         | 选型                                                                |
-
+| ---------- | ------------------------------------------------------------------- |
-| 校验项                                 | 实测结果                                                                                                                                                          |
+| 后端       | Node.js ≥ 20.19 + Express 5 + Prisma 7（SQLite / MySQL）+ Socket.IO |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Web 管理端 | Vue 3 + Vite + Element Plus + Pinia                                 |
-| 渲染进程挂载 + 窗口标题                | ✅ `children=1` / `title=班级小助手`                                                                                                                              |
+| 桌面客户端 | Electron 44 + Vue 3 + IndexedDB 离线缓存（含独立的灵动岛渲染进程）  |
-| 登录页渲染（三个输入框）               | ✅ 服务器地址 / 用户名 / 密码                                                                                                                                     |
+| 共享契约   | `packages/shared`：类型、常量、权限矩阵、动效令牌                   |
-| preload contextBridge 注入             | ✅ 9 个方法（含灵动岛 3 个）                                                                                                                                      |
-| IPC 往返（getAppInfo/saveConfig）      | ✅ Electron 44.3.0                                                                                                                                                |
-| 配置文件写入用户目录                   | ✅ `%APPDATA%\@classhelper\desktop-client\config.json`                                                                                                            |
-| IndexedDB 缓存读写                     | ✅ 读写/统计/删除 + 6 个 store                                                                                                                                    |
-| 断网时回退本地缓存                     | ✅ `fromCache=true`（请求不可达端口）                                                                                                                             |
-| 灵动岛窗口创建（置顶/透明/不占任务栏） | ✅ `ready=true`                                                                                                                                                   |
-| 上课期间普通通知自动隐藏               | ✅ `mode=hidden queued=1 visible=false`（窗口真的隐藏，不是只改状态）                                                                                             |
-| 上课期间点击不展开（严格不显示）       | ✅ `mode=hidden visible=false`                                                                                                                                    |
-| 下课后自动弹出暂存通知详情             | ✅ `mode=expanded reason=after-class`                                                                                                                             |
-| 上课期间紧急通知立即展开（无需点击）   | ✅ `mode=expanded reason=urgent`                                                                                                                                  |
-| **紧急通知带展开动画**                 | ✅ 16ms 采样 34 帧，出现 7 个中间尺寸，最终 `424x344`（窗口从胶囊尺寸弹簧展开）                                                                                   |
-| 上课期间收起不回缩成胶囊               | ✅ `mode=hidden visible=false`                                                                                                                                    |
-| **真实通知链路（Socket.IO → 灵动岛）** | ✅ 教师真实发布通知 → 客户端实时通道 → `mode=pill 可见=true 文案="新消息 张老师 · 点击查看"`（用后删除测试通知）                                                  |
-| **普通通知直接显示胶囊（无入场动画）** | ✅ 推送前已隐藏，60ms 内窗口即为 `268x44`、`mode=pill`（无"上岛"动画）                                                                                            |
-| 胶囊 → 点击 → 展开详情                 | ✅ `新消息 · 共 2 条` → `expanded`（含真实 DOM 断言与截图）                                                                                                       |
-| **点击卡片空白处回缩为胶囊**           | ✅ 真实点击 `.body` 空白区域 → `mode=pill`                                                                                                                        |
-| **点击右上角收起按钮回缩为胶囊**       | ✅ 真实点击 `.icon-btn` → `mode=pill`                                                                                                                             |
-| **灵动岛截图留档 + 像素级校验**        | ✅ 4 张（808×632 / 848×688 / 536×88 / 808×632）；宽高比与状态机配置偏差 **0.000**；形态尺寸递增 pill < expanded < urgent；紧急态偏红 **20584 px**（卡片内部光晕） |
-| **紧急红晕不外溢（窗口边缘无红光）**   | ✅ 截图最外圈（2px）偏红像素 = **0**（守住"卡片周围不出现光晕硬边"）                                                                                              |
-| 联网集成（`ELECTRON_SMOKE_ONLINE=1`）  | ✅ 登录王小明 / 1 班级 / 7 作业 / 20 通知 / 8 成绩 / 第1周30节课 / Socket.IO 已连接                                                                               |
-
-该验证对**开发产物与打包后的 EXE 都适用**（打包后用 `ELECTRON_SMOKE_RESULT=<file>` 写出 JSON 结果，
-已实测 `packaged: true`、23/23 通过、退出码 0）。灵动岛各状态的窗口截图会写到
-`ISLAND_SHOTS_DIR`（默认 `.cache/island-shots/`，仓库内留档目录 `docs/screenshots/island/`），
-并对尺寸、宽高比、绘制内容（不透明像素/颜色种类）、紧急态红色像素与外溢红光做断言。
-冒烟进程使用独立 userData（`ELECTRON_SMOKE_PROFILE`），因此**用户开着客户端也能跑验证**。
-
-## 上课时段策略（紧急通知二次确认）
-
-"上课时段"由课表实时判定：`GET /api/schedules/current?classId=` 返回
-`{ inClass, current, next, week, serverTime }`（`at` 参数可覆盖判定时刻，便于联调与测试）。
-
-**服务端强制拦截**（不是只靠前端提醒）：
-
-```
-POST /api/notifications  { classId, title, content, priority: "URGENT" }        → 409 URGENT_DURING_CLASS
-POST /api/notifications  { …, priority: "URGENT", confirmDuringClass: true }    → 201
-POST /api/notifications  { …, priority: "NORMAL" }（上课时段）                   → 201（不受限）
-```
-
-409 响应体携带 `details: { classId, current, next, week, serverTime }`，前端据此渲染"正在上的课"。
-这样即使有人绕过界面直接调接口，也一定会被拦下来。
-
-**Web 管理端**：教师在通知发布弹窗选择"紧急"并提交时，先查询班级上课状态，命中则弹出**全屏二次确认**
-（`packages/web-admin/src/components/UrgentClassWarning.vue`）：
-
-- 全屏遮罩 + 强警示配色，文案"现在为上课时间段……" + 正在上的课时段 + 待发布标题；
-- 确认按钮带 **3 秒倒计时**（圆环进度 + 每秒钟数提示），倒计时结束前不可点击，防止误触；
-- 取消则不发；确认后带 `confirmDuringClass: true` 重新提交并成功发布；
-- 兜底：并发场景（提交瞬间刚好打铃）仍会收到 409，此时同样弹出该警告。
-
-**EXE 客户端**：上课时段非紧急通知自动隐藏、下课后自动弹出；紧急通知无论是否上课都立即展开（见"灵动岛"一节）。
-
-回归测试：`verify:e2e` 覆盖 409 拦截 / 二次确认后 201 / 普通通知不受限（用 `at` 固定时刻，结果可复现）；
-`verify:web` 用真实点击构造"正在上课"场景并断言全屏警告文案、按钮禁用与倒计时时长（实测 ~2.96s）。
-
-## REST API 一览
-
-统一响应体：`{ "success": true, "data": {}, "message": "" }`（错误为 `success:false` + `code`）。
-所有接口前缀 `/api`，除登录外均需 `Authorization: Bearer <token>`。
-
-| 方法                        | 路径                                                     | 权限            | 说明                                                                             |
-| --------------------------- | -------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------- |
-| POST                        | `/auth/login`                                            | 公开            | 登录，返回 token + 用户信息                                                      |
-| GET                         | `/auth/me`                                               | 登录            | 当前用户（学生附带班级/年级）                                                    |
-| PATCH                       | `/auth/password`                                         | 登录            | 修改自己的密码                                                                   |
-| POST                        | `/auth/logout`                                           | 登录            | 退出（无状态，客户端丢弃 token）                                                 |
-| GET                         | `/classes`                                               | 登录            | 班级列表（按权限收敛）                                                           |
-| GET                         | `/classes/:id`                                           | 班级可见        | 班级详情（学生/课程/协作教师）                                                   |
-| POST / PATCH / DELETE       | `/classes` `/classes/:id`                                | 教师/管理员     | 班级增删改                                                                       |
-| GET / POST                  | `/classes/:id/students`                                  | 班级可见 / 可写 | 学生名单 / 添加学生（已存在账号直接转入）                                        |
-| DELETE                      | `/classes/:id/students/:userId`                          | 教师/管理员     | 移出学生                                                                         |
-| POST / DELETE               | `/classes/:id/teachers[/:teacherId]`                     | 教师/管理员     | 分配 / 取消协作教师                                                              |
-| 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`                                             | 教师/管理员     | 课表增删改（广播 `schedule:updated`）                                            |
-| GET                         | `/homeworks?classId=&courseId=&pendingOnly=&keyword=`    | 登录            | 作业列表（学生带完成状态，教师带完成人数）                                       |
-| GET                         | `/homeworks/:id`                                         | 班级可见        | 作业详情                                                                         |
-| POST / PATCH / DELETE       | `/homeworks`                                             | 教师/管理员     | 发布/修改/删除（广播 `homework:new` / `homework:updated`）                       |
-| PATCH                       | `/homeworks/:id/status`                                  | 登录            | 标记完成/取消（广播 `homework:status`）                                          |
-| GET                         | `/notifications?classId=&priority=&unreadOnly=&keyword=` | 登录            | 通知列表（带已读状态）                                                           |
-| GET                         | `/notifications/unread-count`                            | 登录            | 未读数（红点）                                                                   |
-| POST                        | `/notifications`                                         | 教师/管理员     | 发布通知（广播 `notification:new`）；上课时段发布紧急通知需 `confirmDuringClass` |
-| POST                        | `/notifications/:id/read`、`/notifications/read-all`     | 登录            | 标记已读                                                                         |
-| DELETE                      | `/notifications/:id`                                     | 教师/管理员     | 删除通知                                                                         |
-| 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`                                              | 教师/管理员     | 学生账号增删改                                                                   |
-| POST                        | `/students/:id/reset-password`                           | 教师/管理员     | 重置密码                                                                         |
-| GET                         | `/teachers?keyword=`                                     | 教师/管理员     | 教师列表（分配协作教师用）                                                       |
-| POST                        | `/teachers`                                              | 管理员          | 新建教师账号                                                                     |
-| GET                         | `/dashboard/summary` / `/dashboard/term`                 | 登录            | 仪表盘汇总 / 学期周次                                                            |
-| GET                         | `/health`                                                | 公开            | 健康检查（含已挂载模块列表）                                                     |
-
-## WebSocket 事件
-
-连接方式：`io(url, { auth: { token } })`，握手阶段用 JWT 鉴权。
-
-| 事件                                  | 方向            | 载荷                                  |
-| ------------------------------------- | --------------- | ------------------------------------- |
-| `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 }`                 |
-| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限）    |
-
-房间规则（`@classhelper/shared` 的 `SOCKET_ROOMS`）：
-`class:{classId}`、`user:{userId}`、`role:{role}`、`students`、`teachers`。
-客户端断线由 Socket.IO 自动重连（Web 端 store 与后续 EXE 端共用同一套事件名）。
-
-## 权限模型（RBAC）
-
-| 角色      | 可见范围                                                      | 写权限                                  |
-| --------- | ------------------------------------------------------------- | --------------------------------------- |
-| `ADMIN`   | 全部班级                                                      | 全部                                    |
-| `TEACHER` | 自己创建（`Class.teacherId`）或被分配（`ClassTeacher`）的班级 | 仅上述班级                              |
-| `STUDENT` | 仅自己所在班级（`User.classId` + `Enrollment`）               | 无（仅能标记自己的作业状态 / 已读通知） |
-
-实现要点：
-
-- `src/middleware/auth.ts`：JWT 校验后会**回查数据库**，班级/角色变更立即生效。
-- `src/lib/access.ts`：集中实现 `assertClassAccess` / `assertClassWritable` / `resolveClassScope`，
-  列表接口通过 scope 收敛数据（`classId in [...]`），单条接口直接断言。
-- 越权请求统一返回 `403`，未登录返回 `401`（验收脚本已覆盖 10 项越权场景）。
-
-## 模块化设计（可随时增删模块）
-
-后端每个功能是一个独立目录，统一契约 `ApiModule = { name, basePath, router, enabled? }`：
-
-```ts
-// packages/server/src/modules/registry.ts
-export const apiModules: ApiModule[] = [
-  authModule,
-  classesModule,
-  coursesModule,
-  schedulesModule,
-  homeworksModule,
-  notificationsModule,
-  gradesModule,
-  studentsModule,
-  teachersModule, // ← 新增模块只需在这里加一行
-  dashboardModule,
-].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`，三端共用，避免契约漂移。
-
-## 数据库
-
-- 默认：SQLite（Prisma 7 的 libSQL driver adapter，数据文件 `packages/server/prisma/dev.db`）。
-- 模型设计为跨库通用（无 enum、无 `@db.*` 原生类型），**切换到 MySQL 只需改 provider + 连接串**。
-- 完整步骤见 [`docs/mysql.md`](docs/mysql.md)：
 
 ```bash
-pnpm db:switch:mysql
+pnpm install
-pnpm --filter @classhelper/server add @prisma/adapter-mariadb
+cp packages/server/.env.example packages/server/.env   # 至少改 JWT_SECRET
-# 修改 packages/server/.env 的 DATABASE_PROVIDER / DATABASE_URL
+pnpm db:generate
-pnpm db:migrate && pnpm db:seed
+pnpm --filter @classhelper/server db:deploy            # 根 scripts 里没有 db:deploy
+pnpm build:shared                                      # 三端与 seed 的前置产物
+pnpm db:seed
+pnpm dev                                               # 后端 4000 + Web 端 5173
 ```
 
-数据库表：`User` / `Class` / `ClassTeacher` / `Enrollment` / `Course` / `Schedule` /
+`pnpm db:seed` 会写一套演示数据（1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩）：
-`Homework` / `HomeworkStatus` / `Notification` / `NotificationRead` / `Grade`（共 11 张）。
 
-## 验收标准对照
+| 角色                       | 账号          | 密码         |
+| -------------------------- | ------------- | ------------ |
+| 管理员                     | `admin`       | `admin123`   |
+| 教师                       | `teacher1`    | `teacher123` |
+| ClassHelper 班级端（班级） | 班级码 `G101` | `123456`     |
 
-| 验收项                                           | 结果 | 证据                                                                                         |
+- [AGENTS.md](AGENTS.md) —— 工程约定与开发环境注意事项，**改代码前先读它**
-| ------------------------------------------------ | ---- | -------------------------------------------------------------------------------------------- |
+- [docs/reference.md](docs/reference.md) —— 功能章节与源码入口索引
-| 教师 Web 端发布通知，学生端 5 秒内收到           | ✅   | `verify:e2e`：`notification:new` **37–44ms**                                                 |
+- [docs/dev/architecture.md](docs/dev/architecture.md) —— 架构总览
-| 教师发布作业，学生能查看并标记完成               | ✅   | `homework:new` **26–40ms**，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true`    |
-| 教师录入成绩，学生能查看个人成绩                 | ✅   | `grade:updated` **21–25ms**，`/grades/my` 返回记录；批量录入与统计接口通过                   |
-| 学生能查看课表，支持按周切换                     | ✅   | `/schedules/grid?week=1` 返回 30 节，`week` 过滤 `weekStart ≤ week ≤ weekEnd`                |
-| 断网后客户端可查看缓存数据                       | ✅   | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true items=1`；离线横幅 + 缓存统计页可用       |
-| 权限隔离：学生不能访问其他班级数据               | ✅   | 10 项越权断言全部 403/401（学生跨班/跨班作业/跨班课表、教师跨班发布、未登录访问…）           |
-| 上课时段发布紧急通知必须二次确认                 | ✅   | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
-| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅   | `verify:desktop` 四种状态断言 + 截图（`.cache/island-shots/`）                               |
-| 能成功打包 Windows EXE                           | ✅   | `班级小助手-0.1.0-x64-setup.exe` / `-portable.exe` / `win-unpacked/*.exe`（见下表）          |
-| 提供完整 README（启动、构建、打包、默认账号）    | ✅   | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、MySQL 切换、打包与常见问题           |
 
-打包产物验证（对最终 EXE 实测，非仅开发产物）：
+## 致谢
 
-| 产物                                   | 大小    | 冒烟结果                                                                                                 |
+灵动岛的视觉与架构参考 [WinIsland](https://github.com/WinIslandProject/WinIsland)（Windows 上的动态岛）；
-| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+动效语言取自 [beUI](https://beui.dev)；产品官网的版式参考 [ClassIsland 官网](https://www.classisland.tech/)。
-| 服务端安装程序（内置 Node + Web 端）   | 34MB    | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 → **对安装实例跑 62/62 e2e + 15/15 UI** |
+三端的深色主题、图标与动效令牌都是照这些参考自己实现的，没有引入它们的运行时依赖。
-| `release/win-unpacked/班级小助手.exe`  | 234.7MB | ✅ 23/23，`packaged: true`，退出码 0                                                                     |
-| `release/…-x64-portable.exe`（单文件） | 106.9MB | ✅ 打包后冒烟 **23/23**，`packaged: true`，退出码 0（含灵动岛行为与像素校验）                            |
-| `release/…-x64-setup.exe`（客户端）    | 107.2MB | ✅ 构建成功，已嵌入自定义图标；含灵动岛与本次行为修正                                                    |
 
-当前实测：
+<div align="center">
 
-| 验证                                                                                    | 结果                                |
+如果这个项目对你有帮助，欢迎点亮 Star ⭐
-| --------------------------------------------------------------------------------------- | ----------------------------------- |
-| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次）                             | **62/62** ✅                        |
-| `pnpm verify:web`（Web 管理端真实点击 + 手机小屏适配 + 上课时段紧急通知 + PWA）         | **15/15** ✅                        |
-| `pnpm verify:desktop`（客户端冒烟 + 灵动岛行为 + 真实通知链路 + 像素级校验 + 离线回退） | **27/27** ✅                        |
-| `pnpm typecheck` / `pnpm lint` / `pnpm format:check`                                    | 全部通过 ✅                         |
-| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载）                                      | 通过 ✅                             |
-| Docker / Nginx 部署样例                                                                 | 文件已提供，本机无 Docker 未实测 ⚠️ |
 
-## 常见问题（本机环境已知坑）
+</div>
 
-1. **在 DSH 桌面端（Electron 宿主）里执行 pnpm 时，依赖的 `.bin` 不会被注入 PATH**
+### 客户端维护
-   现象：`pnpm run <script>` 报 `'prisma' 不是内部或外部命令`。
-   原因：本机 pnpm 由 Electron 进程承载，bin 目录位于
-   `node_modules/.pnpm/node_modules/.bin`，未注入子进程 PATH。
-   规避：直接用 Node 调用 CLI 入口，例如
-   `node packages/server/node_modules/prisma/build/index.js generate`、
-   `node packages/web-admin/node_modules/vite/bin/vite.js build`。
-   在普通终端（非 Electron 宿主）中 `pnpm <script>` 一切正常。
 
-1.5 **脚本里启动 Electron 时必须清掉 `ELECTRON_RUN_AS_NODE`，并且不要 `import 'electron'` 取路径**
+支持远程关机、重启、注销与锁屏（管理端确认下发，客户端执行并回执），可查看最近一次执行结果。
-现象（两种，都只在本机这种"宿主终端本身是 Electron"的环境里出现）：
+统一更新支持立即安装、放学后安装或空闲时安装，支持取消下发。
-① `node scripts/smoke.mjs` 正常，但 `pnpm verify:desktop` 报
+管理员与教师的默认权限组均可自定义；管理员保留权限管理和系统管理入口。
-`Cannot find module 'electron'`（Electron 退化成纯 Node 运行）；
+课件共享：教师可上传教学文件到服务端，按日期与类型归档，仅向本人授课班级开放或推送；班级客户端支持课件目录、离线补收，以及灵动岛传输进度。使用说明见 [课件上传与传输](docs/app/courseware.md)。
-② `pnpm dist:win` 报 `Unknown argument: .../electron-builder/out/cli/cli.js`。
-原因：本机 `pnpm` 运行在 Electron 内置 Node 上，会给子进程带上 `ELECTRON_RUN_AS_NODE=1`；
-同时 `process.versions.electron` 存在时，`require('electron')` 返回的是 **API 对象而非可执行文件路径**，
-`spawn(process.execPath, [cli.js, …])` 会被 Electron 当成"启动应用"而多出一个位置参数。
-规避（已内置到代码里）：
-
-- `scripts/lib/electron-env.mjs`：`resolveElectronEnv()` 清理变量、`resolveElectronExecutable()` 从
-  `node_modules/electron/path.txt` 定位 electron.exe；
-- `scripts/lib/node-runtime.mjs`：`resolveNodeRuntime()` 明确找一个**真正的 node.exe**，
-  供 electron-builder CLI 与"内置 Node 运行时"打包使用。
-
-2. **不要用 PowerShell 管道调用 `start.cmd`**
-   现象：`& "$install\start.cmd" | Select-Object -First 20` 会一直不返回。
-   原因：脚本内启动的 node 进程在该上下文里继承了管道句柄。
-   规避：双击运行，或用 `Start-Process cmd.exe "/c start.cmd"`（脚本自身 4 秒内退出）。
-
-3. **原生模块会按 Electron ABI 构建**
-   同一原因会让 `node-gyp` / `prebuild-install` 以 `runtime=electron` 为目标，
-   装出的 `.node` 在 Node 进程里无法加载。本项目因此改用 **libSQL 适配器**
-   （`@libsql/win32-x64-msvc` 为 npm 预编译包，无需本地编译），彻底规避该问题。
-
-4. **本机 TLS 中间人证书导致依赖二进制下载失败**
-   现象：`prebuild-install warn install unable to verify the first certificate`。
-   规避：安装时设置 `NODE_OPTIONS=--use-system-ca`（Node ≥ 22.15 支持），
-   并确保 `npm_config_cache` 指向可写目录（如仓库内 `.cache/npm-cache`）。
-
-5. **受限沙箱下 Vite 构建报 `spawn EPERM`**
-   Vite 在 Windows 上通过 `execFile` 解析真实路径，需要放开子进程管道限制后再构建。
-
-6. **Prisma 7 与旧版本差异**
-   `prisma` 的 npm `latest` 标签当前指向 `8.0.0-rc`，本项目**显式锁定 7.10.0**；
-   生成器为 `prisma-client`（输出到 `src/generated/prisma`，已 gitignore），
-   连接串在 `prisma.config.ts` 中配置，且必须通过 driver adapter 接入数据库。
-
-7. **Electron 二进制下载慢或失败**
-   `electron` 的 postinstall 会从 GitHub 拉取约 151MB 发行包，本机实测 10 分钟仍未完成。
-   规避：安装前设置镜像与缓存目录（本项目已把 electron 缓存指向 `.cache/electron`）：
-   `ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/`。
-   打包阶段 `scripts/dist-win.mjs` 已内置该镜像，并优先复用本地已解压的 Electron。
-
-8. **electron-builder 的构建工具（NSIS / winCodeSign）下载慢**
-   通过 `ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/`
-   解决（已内置到 `dist-win.mjs`），实测 nsis-3.0.4.1 与 nsis-resources 正常下载。
-   `scripts/dist-server.mjs` 会直接复用 electron-builder 缓存里的 `makensis`。
-
-9. **应用图标**
-   `pnpm icons` 会用 Electron 渲染 SVG 生成 `packages/desktop-client/build/icon.ico`（多尺寸）、
-   PWA 所需的 PNG 与 `favicon.svg`。electron-builder 与 NSIS 安装程序都会自动使用该图标。
-
-10. **服务端安装包内的 `.cmd` 脚本为什么是英文提示？**
-    cmd.exe 按 OEM 代码页（GBK）解析脚本文件，UTF-8 中文会产生乱码甚至语法错误，
-    因此脚本提示统一用 ASCII，中文说明放在安装向导与 `README.txt` 中。
-
-## 交付清单（阶段 7 · 生产化）
-
-| 路径                                                | 说明                                                             |
-| --------------------------------------------------- | ---------------------------------------------------------------- |
-| `scripts/dist-server.mjs`                           | 服务端 + Web 端打包（内置 Node、依赖、迁移、启停脚本、安装程序） |
-| `scripts/nsis/server-installer.nsi`                 | NSIS 安装程序模板（安装/快捷方式/开机自启/卸载保留数据）         |
-| `scripts/generate-icons.mjs` + `scripts/icons/`     | 图标生成（Electron 渲染 SVG → PNG/ICO）                          |
-| `scripts/ui-smoke/`                                 | Web 管理端 UI 真实点击回归测试                                   |
-| `packages/server/src/middleware/security.ts`        | helmet + 限流（通用/登录）+ 请求耗时日志                         |
-| `packages/server/src/lib/web-static.ts`             | Web 管理端静态托管 + SPA 回退 + 缓存策略                         |
-| `packages/server/src/lib/db-bootstrap.ts`           | 首启动自动迁移 + 自动创建管理员                                  |
-| `packages/web-admin/public/{manifest,sw.js}`        | PWA：可安装为应用 + 离线外壳                                     |
-| `deploy/{Dockerfile,docker-compose.yml,nginx.conf}` | 云部署与 HTTPS 反代样例                                          |
-| `docs/production.md`                                | 生产部署指南（三种形态 + 运维 + 安全清单 + 故障排查）            |
-
-阶段 8（灵动岛 + 上课时段策略）新增文件：
-
-| 路径                                                         | 说明                                                                 |
-| ------------------------------------------------------------ | -------------------------------------------------------------------- |
-| `packages/desktop-client/src/main/island.ts`                 | 灵动岛控制器（窗口/状态机/动画/超时/IPC）                            |
-| `packages/desktop-client/src/preload/island.ts`              | 灵动岛 preload 桥（`islandGetState/islandPush/islandSetClassState`） |
-| `packages/desktop-client/src/island/IslandApp.vue`           | 灵动岛界面（胶囊 / 详情 / 紧急三种形态 + 动画）                      |
-| `packages/desktop-client/src/renderer/island/bridge.ts`      | 上课状态轮询（10s）与通知转发                                        |
-| `packages/server/src/modules/schedules/schedules.service.ts` | `computeClassStatus` / `getClassStatus`（上课时段判定）              |
-| `packages/web-admin/src/components/UrgentClassWarning.vue`   | 上课时段发布紧急通知的全屏二次确认（3 秒倒计时）                     |
-| `scripts/ui-smoke/live-probe.mjs`                            | UI 回归测试的"真实上课时段"探针（自建课表 + 用后清理）               |
-| `scripts/lib/{electron-env,node-runtime}.mjs`                | Electron/Node 运行时定位与宿主环境兼容处理                           |
-| `docs/screenshots/island/*.png`                              | 灵动岛四种形态的自动化留档截图（由冒烟验证生成，含像素级断言）       |
-
-## 后续可选增强
-
-1. 代码签名证书（消除 SmartScreen 提示）。
-2. 客户端"提交类操作离线队列"（当前离线为只读，联网后自动同步读取的数据）。
-3. Socket.IO 多实例广播（引入 `@socket.io/redis-adapter`）与 CI 流水线。
-4. 灵动岛位置/尺寸可配置（多显示器时跟随当前活动屏幕，而非固定主屏）。

deploy/.env.example

@@ -7,7 +7,7 @@
 SERVER_PORT=4000
 
 # 应用版本（镜像标签）
-APP_VERSION=0.1.0
+APP_VERSION=1.1.2
 
 # MySQL 配置
 MYSQL_ROOT_PASSWORD=请改成强密码_root
@@ -30,6 +30,11 @@ CORS_ORIGIN=*
 INITIAL_ADMIN_USERNAME=admin
 INITIAL_ADMIN_PASSWORD=admin123
 
+# 各类账号的默认初始密码（新增/重置时使用）
+
+DEFAULT_CLASS_PASSWORD=123456
+DEFAULT_TEACHER_PASSWORD=123456
+
 # 第 1 教学周的周一（用于"当前周次"）
 TERM_START_DATE=2026-08-31
 

deploy/.env.sqlite.example

@@ -0,0 +1,36 @@
+# ---------------------------------------------------------------------------
+# 班级小助手 · Docker 单容器（SQLite）环境变量
+# 复制为 deploy/.env.sqlite 后填写：cp deploy/.env.sqlite.example deploy/.env.sqlite
+# 配合 deploy/docker-compose.sqlite.yml 使用
+# ---------------------------------------------------------------------------
+
+# 服务端对外端口（宿主机）。注意与同机其他服务错开：80/443 常被反代占用
+SERVER_PORT=4000
+
+# 应用版本（镜像标签）
+APP_VERSION=1.1.2
+
+# JWT 签名密钥（必填，必须 ≥32 位；不能包含 secret / change-me 等示例词）
+# 生成：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# 令牌有效期
+JWT_EXPIRES_IN=7d
+
+# 允许的跨域来源；用域名访问时建议写成具体来源，例如 https://class.example.com
+CORS_ORIGIN=*
+
+# 首次启动创建的管理员账号（**部署后请立即登录修改密码**）
+INITIAL_ADMIN_USERNAME=admin
+INITIAL_ADMIN_PASSWORD=admin123
+
+# 各类账号的默认初始密码（新增/重置时使用）
+
+DEFAULT_CLASS_PASSWORD=123456
+DEFAULT_TEACHER_PASSWORD=123456
+
+# 第 1 教学周的周一（用于"当前周次"）
+TERM_START_DATE=2026-08-31
+
+# 日志级别：debug | info | warn | error
+LOG_LEVEL=info

deploy/Dockerfile

@@ -1,17 +1,17 @@
-# 班级小助手服务端 · 生产镜像
+# ClassHelper 服务端 · 生产镜像
 #
 # 两阶段构建：
 #   build   —— 安装依赖并编译 shared / server / web-admin
 #   runtime —— 仅保留运行时所需内容（生产依赖 + 构建产物），镜像更小
 #
 # 构建（在仓库根目录执行）：
-#   docker build -f deploy/Dockerfile -t classhelper-server:0.1.0 .
+#   docker build -f deploy/Dockerfile -t classhelper-server:1.1.0 .
 #
 # 运行（SQLite + 数据卷）：
 #   docker run -d --name classhelper -p 4000:4000 \
 #     -e JWT_SECRET=<48字节随机串> \
 #     -v classhelper-data:/app/data \
-#     classhelper-server:0.1.0
+#     classhelper-server:1.1.0
 #
 # 生产推荐用 docker compose（见 deploy/docker-compose.yml，含 MySQL 与 HTTPS 反代）
 
@@ -33,7 +33,12 @@ RUN pnpm install --frozen-lockfile --ignore-scripts
 # 再拷贝源码并构建（只构建服务端与 Web 管理端，桌面客户端不参与）
 COPY packages ./packages
 COPY scripts ./scripts
+
+# 必须先生成 Prisma Client：`pnpm install --ignore-scripts` 跳过了 postinstall，
+# 而生成产物 `packages/server/src/generated/prisma` 是 gitignored 的（clone 下来没有），
+# 少了这一步下面的 tsc 会报 "Cannot find module '../generated/prisma/client.js'"。
 RUN pnpm build:shared \
+ && pnpm --filter @classhelper/server run db:generate \
  && pnpm --filter @classhelper/server build \
  && pnpm --filter @classhelper/web-admin build
 

deploy/Dockerfile.linux-package

@@ -0,0 +1,45 @@
+# ---------------------------------------------------------------------------
+# 班级小助手服务端 · Docker 形态镜像（由 install.sh --mode docker 使用）
+#
+# 与仓库根 deploy/Dockerfile 的区别：
+#   - 那份是"从源码构建"（两阶段、需要 pnpm 与全量源码），适合开发与自己打包镜像；
+#   - 这份是"从安装包构建"：安装包里的 server/dist、web、node_modules 已经是**linux-x64 的真实目录**，
+#     所以这里只做 COPY，不需要联网装依赖、不需要构建工具，几十秒就能出镜像。
+#
+# 构建（install.sh 自动执行，也可手工）：
+#   docker build -t classhelper-server:1.1.0 -f Dockerfile .
+# 运行：
+#   docker run -d --name classhelper-server -p 4000:4000 \
+#     --env-file /etc/classhelper/config.env -v classhelper-data:/app/data \
+#     classhelper-server:1.1.0
+# ---------------------------------------------------------------------------
+FROM node:22-slim
+
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=4000
+
+WORKDIR /app
+
+# 运行时会用到的全部内容（安装包里就是这套布局）
+COPY package.json ./
+COPY node_modules ./node_modules
+COPY server ./server
+COPY web ./web
+COPY tools ./tools
+
+# 数据目录（compose 里挂成卷）
+RUN mkdir -p /app/data /app/logs
+
+# 说明：不用 `USER node`
+#   - 镜像只在本机跑，容器本身就是隔离边界；
+#   - 数据卷里的文件需要与宿主机上的 classhelper backup / restore 互通，
+#     用 root 可以避免 uid 不一致导致的权限问题。
+
+EXPOSE 4000
+
+# 健康检查用 Node 自己发请求：slim 镜像里没有 curl/wget
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||4000)+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "server/dist/index.js"]

deploy/bootstrap-env.cjs

@@ -0,0 +1,32 @@
+/** 首次安装生成独立密钥；覆盖升级不改变已有配置。 */
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const MARKER = 'CLASSHELPER_GENERATE_SECRET_ON_INSTALL';
+function initialiseEnvironment(file = path.join(__dirname, '.env')) {
+  const content = fs.readFileSync(file, 'utf8');
+  const line = /^JWT_SECRET=CLASSHELPER_GENERATE_SECRET_ON_INSTALL\r?$/m;
+  if (!line.test(content)) return false;
+  const value = crypto.randomBytes(48).toString('hex');
+  const temporary = file + '.initialising-' + crypto.randomUUID();
+  try {
+    fs.writeFileSync(temporary, content.replace(line, 'JWT_SECRET=' + value), {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  return true;
+}
+module.exports = { initialiseEnvironment, MARKER };
+if (require.main === module) {
+  try {
+    initialiseEnvironment();
+  } catch (error) {
+    console.error('服务端配置初始化失败：' + error.message);
+    process.exitCode = 1;
+  }
+}

deploy/classhelper.service

@@ -0,0 +1,81 @@
+# ---------------------------------------------------------------------------
+# 班级小助手 · 服务端 systemd 单元（Linux）
+#
+# 这是**模板**：`deploy/install.sh` 会把占位符替换成真实值后安装到
+# /etc/systemd/system/classhelper.service。手动部署时照着替换这四处即可：
+#
+#   __NODE__       Node 可执行文件的绝对路径（内置运行时：<安装目录>/runtime/node/bin/node）
+#   __DIR__        安装目录（默认 /opt/classhelper）
+#   __USER__       运行服务的系统用户（默认 classhelper）
+#   __CONFIG__     环境变量文件（默认 /etc/classhelper/config.env）
+#   __CONFIGDIR__  __CONFIG__ 所在目录（需要写权限，见下面的 ReadWritePaths）
+#
+#   sudo sed -e 's#__NODE__#/opt/classhelper/runtime/node/bin/node#' \
+#            -e 's#__DIR__#/opt/classhelper#' \
+#            -e 's#__USER__#classhelper#' \
+#            -e 's#__CONFIGDIR__#/etc/classhelper#' \
+#            -e 's#__CONFIG__#/etc/classhelper/config.env#' \
+#            deploy/classhelper.service > /tmp/classhelper.service
+#   sudo install -m 644 /tmp/classhelper.service /etc/systemd/system/classhelper.service
+#   sudo systemctl daemon-reload && sudo systemctl enable --now classhelper
+#
+# 常用命令（也有对应的 classhelper 封装）：
+#   classhelper status / start / stop / restart / logs -f
+#   systemctl status classhelper
+#   journalctl -u classhelper -f
+# ---------------------------------------------------------------------------
+
+[Unit]
+Description=ClassHelper Server (班级小助手服务端)
+Documentation=https://github.com/LoveChengke/ClassHelper
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=__USER__
+Group=__USER__
+WorkingDirectory=__DIR__
+
+# 配置从这里注入（唯一的配置真身；安装目录里的 .env 是指向它的软链，见 docs/linux-deploy.md）。
+# systemd 会剥掉值两侧的引号，所以同一份文件给 dotenv / shell source / systemd 三种读法都能用。
+# 前面不加 "-"：文件被删掉时直接启动失败，比拿着一份假配置跑起来更容易发现。
+EnvironmentFile=__CONFIG__
+ExecStart=__NODE__ server/dist/index.js
+
+Restart=always
+RestartSec=3
+# Socket.IO 长连接较多：提高文件描述符上限
+LimitNOFILE=65535
+# 优雅退出：给在途请求与 websocket 收尾时间（index.ts 处理 SIGTERM/SIGINT）
+KillSignal=SIGTERM
+TimeoutStopSec=20
+
+# 日志进 journald：journalctl -u classhelper
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=classhelper
+
+# ---------------------------------------------------------------- 加固
+# 为什么 ReadWritePaths 要给整个 __DIR__ 与配置目录，而不是只给 data/logs：
+#   1) Web 端「数据库管理 → 一键切换」会在运行中改写 server/prisma/schema.prisma，
+#      并把重新生成的 Prisma Client 编译进 server/dist/generated —— 那两处都在 __DIR__ 里；
+#   2) 同一功能切换成功后要改写 __CONFIG__（DATABASE_PROVIDER / DATABASE_URL 两行）。
+#   ProtectSystem=full 默认把 /etc 与 /usr 设成只读，ReadWritePaths 是官方的"打洞"方式。
+#   服务本来就以 __USER__ 身份运行，这里给的写权限没有超出它的既有边界。
+ProtectSystem=full
+ProtectHome=true
+PrivateTmp=true
+NoNewPrivileges=true
+ReadWritePaths=__DIR__ __CONFIGDIR__
+
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+# 需要 AF_NETLINK：glibc 解析主机名（MySQL 主机 / GitHub API）时会用到
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
+
+[Install]
+WantedBy=multi-user.target

deploy/docker-compose.sqlite.yml

@@ -0,0 +1,56 @@
+# ClassHelper · Docker 单容器部署（SQLite + 数据卷）
+#
+# 适用：云服务器 / 与别的服务共用一台机器。相比 deploy/docker-compose.yml（MySQL 变体）
+#      少跑一个数据库容器，内存占用小很多；数据落在 Docker 卷 classhelper-data 里。
+#
+# 使用：
+#   1) cp deploy/.env.sqlite.example deploy/.env.sqlite 并填 JWT_SECRET / 管理员密码
+#      （生成密钥：node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"）
+#   2) docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite up -d --build
+#   3) 访问：http://<服务器IP>:${SERVER_PORT}/
+#
+# 首次启动（AUTO_MIGRATE=true）会自动执行 prisma/migrations 里的建表语句并创建管理员账号，
+# 见 packages/server/src/lib/db-bootstrap.ts（"Docker 挂载空数据卷"就是它的目标场景之一）。
+#
+# 备份：docker run --rm -v classhelper-sqlite_classhelper-data:/data -v "$PWD":/backup alpine \
+#         tar czf /backup/classhelper-db.tar.gz -C /data .
+
+name: classhelper-sqlite
+
+services:
+  server:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+      target: runtime
+    image: classhelper-server:${APP_VERSION:-1.4.2}
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      HOST: 0.0.0.0
+      PORT: 4000
+      DATABASE_PROVIDER: sqlite
+      # 必须写绝对路径：容器里 serverRoot 是 /app/server，相对路径会解析到别处
+      DATABASE_URL: file:/app/data/classhelper.db
+      # 首启动自动建表 + 建管理员；生产自检会拒绝 dev.db 与过短的 JWT_SECRET
+      AUTO_MIGRATE: 'true'
+      STARTUP_DB_CHECK: 'true'
+      JWT_SECRET: ${JWT_SECRET:?请在 deploy/.env.sqlite 中设置（≥32 位随机串）}
+      JWT_EXPIRES_IN: ${JWT_EXPIRES_IN:-7d}
+      CORS_ORIGIN: ${CORS_ORIGIN:-*}
+      TRUST_PROXY: '1'
+      RATE_LIMIT_ENABLED: 'true'
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      TERM_START_DATE: ${TERM_START_DATE:-}
+      INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
+      INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
+
+      DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
+      DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
+    ports:
+      - '${SERVER_PORT:-4000}:4000'
+    volumes:
+      - classhelper-data:/app/data
+
+volumes:
+  classhelper-data:

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:-0.1.0}
+    image: classhelper-server:${APP_VERSION:-1.4.2}
     restart: unless-stopped
     environment:
       NODE_ENV: production
@@ -78,8 +78,13 @@ services:
       TERM_START_DATE: ${TERM_START_DATE:-}
       INITIAL_ADMIN_USERNAME: ${INITIAL_ADMIN_USERNAME:-admin}
       INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD:-admin123}
+
+      DEFAULT_CLASS_PASSWORD: ${DEFAULT_CLASS_PASSWORD:-123456}
+      DEFAULT_TEACHER_PASSWORD: ${DEFAULT_TEACHER_PASSWORD:-123456}
     ports:
       - '${SERVER_PORT:-4000}:4000'
+    volumes:
+      - server-data:/app/data
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
@@ -90,4 +95,5 @@ networks:
     driver: bridge
 
 volumes:
+  server-data:
   db-data:

deploy/install-linux.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# 兼容壳：早期文档、脚本与 README 里写的是 deploy/install-linux.sh，
+# 现在安装器统一在 deploy/install.sh（避免两份实现漂移）。
+#
+# 两者参数完全一致：
+#   sudo bash deploy/install-linux.sh --port 8080
+# 等价于
+#   sudo bash deploy/install.sh --port 8080
+# ---------------------------------------------------------------------------
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+printf '\033[33m[classhelper]\033[0m install-linux.sh 已更名为 install.sh，本次自动转发（后续请直接用 install.sh）\n' >&2
+exec bash "${DIR}/install.sh" "$@"

deploy/logrotate.d/classhelper

@@ -0,0 +1,19 @@
+# ---------------------------------------------------------------------------
+# ClassHelper · 日志轮转
+# 由 deploy/install.sh 安装到 /etc/logrotate.d/classhelper
+#
+# copytruncate 而不是 create+信号：安装器与 classhelper 都是"追加写完就关"
+# （`>>` 打开、写完立即关闭），没有常驻 fd 可通知，copytruncate 是这里唯一正确的做法。
+# ---------------------------------------------------------------------------
+
+/var/log/classhelper/*.log {
+    weekly
+    rotate 8
+    missingok
+    notifempty
+    compress
+    delaycompress
+    copytruncate
+    create 0600 root root
+    su root root
+}

deploy/nginx.conf

@@ -92,6 +92,20 @@ server {
     }
 
     # ---------------------------------------------------------------- 接口与页面
+    # 课件流式上传（其余接口继续沿用 8 MB 限制）
+    location /api/courseware/ {
+        client_max_body_size 512m;
+        proxy_pass http://classhelper_backend;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_request_buffering off;
+        proxy_buffering off;
+        proxy_read_timeout 1800s;
+        proxy_send_timeout 1800s;
+    }
+
     location / {
         proxy_pass http://classhelper_backend;
         proxy_http_version 1.1;

deploy/package.runtime.json

@@ -1,12 +1,13 @@
 {
   "name": "classhelper-server-runtime",
-  "version": "0.1.0",
+  "version": "1.4.2",
   "private": true,
   "type": "module",
-  "description": "班级小助手服务端运行时（安装包 / 容器内置）",
+  "description": "ClassHelper 服务端运行时（安装包 / 容器内置）",
   "dependencies": {
     "@libsql/client": "^0.17.0",
     "@prisma/adapter-libsql": "7.10.0",
+    "@prisma/adapter-mariadb": "7.10.0",
     "@prisma/client": "7.10.0",
     "bcryptjs": "^3.0.3",
     "compression": "^1.8.2",
@@ -16,7 +17,10 @@
     "express-rate-limit": "^8.7.0",
     "helmet": "^8.3.0",
     "jsonwebtoken": "^9.0.3",
+    "prisma": "7.10.0",
     "socket.io": "^4.8.3",
+    "typescript": "~5.9.3",
+    "xlsx": "0.18.5",
     "zod": "^4.6.2"
   }
 }

deploy/profile.d/classhelper.sh

@@ -0,0 +1,28 @@
+# ---------------------------------------------------------------------------
+# ClassHelper · 登录 shell 环境变量
+#
+# 由 deploy/install.sh 安装到 /etc/profile.d/classhelper.sh（占位符替换成真实路径）。
+# 生效方式：重新登录，或 `source /etc/profile.d/classhelper.sh`。
+#
+# 说明：`classhelper` 命令本身装在 /usr/local/bin（软链到 $CLASSHELPER_HOME/bin/classhelper），
+#       不依赖这个文件也能用；这里提供的是路径类变量，方便写脚本时引用。
+# ---------------------------------------------------------------------------
+
+# 只在目录真实存在时导出：卸载后残留的 profile.d 不应该污染别人的环境
+if [ -d '__DIR__' ]; then
+  export CLASSHELPER_HOME='__DIR__'
+  export CLASSHELPER_CONFIG='__CONFIG__'
+  export CLASSHELPER_LOG_DIR='__LOGDIR__'
+  export CLASSHELPER_BACKUP_DIR='__BACKUPDIR__'
+  export CLASSHELPER_SERVICE='classhelper'
+
+  case ":${PATH}:" in
+    *":${CLASSHELPER_HOME}/bin:"*) ;;
+    *) export PATH="${PATH}:${CLASSHELPER_HOME}/bin" ;;
+  esac
+fi
+
+# 让 `classhelper` 在非 root 登录时也能补全（bash 补全由 `classhelper completion bash` 输出）
+if [ -n "${BASH_VERSION:-}" ] && [ -r /usr/share/bash-completion/completions/classhelper ]; then
+  . /usr/share/bash-completion/completions/classhelper
+fi

deploy/systemd/classhelper-backup.service

@@ -0,0 +1,22 @@
+# ---------------------------------------------------------------------------
+# 班级小助手 · 定时备份（systemd timer）
+# 由 `classhelper backup schedule daily|weekly` 安装（占位符 __BIN__ / __KEEP__ 由命令替换）
+#
+# 手工安装：
+#   sudo sed -e 's#__BIN__#/usr/local/bin/classhelper#' -e 's#__KEEP__#7#' \
+#     deploy/systemd/classhelper-backup.service > /tmp/x.service ...
+# 然后 systemctl daemon-reload && systemctl enable --now classhelper-backup.timer
+# ---------------------------------------------------------------------------
+
+[Unit]
+Description=ClassHelper 定时备份
+Documentation=https://github.com/LoveChengke/ClassHelper
+After=classhelper.service
+
+[Service]
+Type=oneshot
+ExecStart=__BIN__ backup --quiet --keep __KEEP__
+# 备份失败时不要静默：journalctl -u classhelper-backup 里能看到退出码与原因
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=classhelper-backup

deploy/systemd/classhelper-backup.timer

@@ -0,0 +1,19 @@
+# ---------------------------------------------------------------------------
+# 班级小助手 · 定时备份（触发器）
+# 由 `classhelper backup schedule daily|weekly` 安装；OnCalendar 行由命令按选择替换
+# ---------------------------------------------------------------------------
+
+[Unit]
+Description=ClassHelper 定时备份触发器
+Documentation=https://github.com/LoveChengke/ClassHelper
+
+[Timer]
+OnCalendar=__ONCALENDAR__
+# 错开整点：避免所有装了本服务的机器在同一秒打盘
+RandomizedDelaySec=30m
+# 机器关机期间错过的备份在开机后补一次
+Persistent=true
+Unit=classhelper-backup.service
+
+[Install]
+WantedBy=timers.target

deploy/tools/admin-cli.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+/**
+ * ClassHelper · 离线账号工具（随 Linux 包发布，安装在 ${INSTALL_DIR}/tools/admin-cli.mjs）
+ *
+ * 为什么不用 HTTP API 改密码：`classhelper password` 要能在**服务停机**时救急，
+ * 而调 API 必须先有一个能登录的账号 —— 管理员忘了密码时就是死锁。
+ * 因此这里直连数据库，复用服务端自己的 Prisma Client 与 bcrypt 参数（`server/dist/lib/*`），
+ * 保证写入的哈希与登录校验用的是同一套实现。
+ *
+ * 安全约定（务必保持）：
+ *   - **密码只从 stdin 读**，绝不接受 argv / 环境变量形式的密码（否则会进 shell history 与 ps 输出）；
+ *   - 本工具自己**不打印任何密码**，也不写任何日志；
+ *   - `dump-hash` 会输出 bcrypt 哈希 —— 仅由 root 调用的 `classhelper password` 用于改前备份，
+ *     调用方负责把结果落到 600 权限的文件里。
+ *
+ * 用法（全部由 classhelper 封装，一般不需要手工调）：
+ *   node tools/admin-cli.mjs info
+ *   node tools/admin-cli.mjs list [--json]
+ *   node tools/admin-cli.mjs dump-hash <用户名|class:班级码>
+ *   node tools/admin-cli.mjs set-password <用户名>        # 新密码从 stdin 读
+ *   node tools/admin-cli.mjs set-class-password <班级码>  # 新密码从 stdin 读
+ *   node tools/admin-cli.mjs verify <用户名>              # 待校验密码从 stdin 读
+ *   node tools/admin-cli.mjs restore-hash <备份json路径>
+ *   node tools/admin-cli.mjs snapshot <目标db文件>         # SQLite 一致性快照（VACUUM INTO）
+ *
+ * 退出码：0 成功 / 1 通用失败 / 2 用法错误 / 3 目标不存在 / 4 密码不合规 / 5 数据库不可用
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+/** 安装根目录（tools/ 的上一级） */
+const installDir = path.resolve(scriptDir, '..');
+const serverDist = path.join(installDir, 'server', 'dist');
+
+const EXIT = { OK: 0, FAIL: 1, USAGE: 2, NOT_FOUND: 3, WEAK: 4, NO_DB: 5 };
+
+function fail(message, code = EXIT.FAIL) {
+  process.stderr.write(`admin-cli: ${message}\n`);
+  process.exitCode = code;
+  return null;
+}
+
+/** 一次性读完 stdin（去掉行尾换行；保留内部空白，密码里可以有空格） */
+async function readSecretFromStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+}
+
+/** 与服务端一致的密码强度规则（classhelper 里还有一份交互式版本，两边保持同样口径） */
+function checkStrength(password, username) {
+  const problems = [];
+  if (password.length < 8) problems.push('长度至少 8 位');
+  if (password.length > 128) problems.push('长度不要超过 128 位');
+  const kinds = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((re) => re.test(password)).length;
+  if (kinds < 3) problems.push('需包含小写字母 / 大写字母 / 数字 / 符号 中至少 3 类');
+  if (username && password.toLowerCase() === username.toLowerCase()) problems.push('不能与用户名相同');
+  if (/^(123456|password|admin|classhelper|qwerty|111111|abc123)/i.test(password) && password.length < 12) {
+    problems.push('过于常见，请换一个');
+  }
+  return problems;
+}
+
+/** 懒加载服务端模块：先做"库在不在"的检查，避免 libSQL 在连接时凭空建出一个空库 */
+async function loadServerModules() {
+  const envFile = path.join(serverDist, 'config', 'env.js');
+  if (!fs.existsSync(envFile)) {
+    fail(`找不到服务端产物：${envFile}`, EXIT.NO_DB);
+    return null;
+  }
+  const env = await import(pathToFileURL(envFile).href);
+  if (env.env.databaseProvider === 'sqlite') {
+    // classhelper 做备份时会用 CLASSHELPER_SNAPSHOT_DB 显式指定数据文件（跳过硬编码路径假设）
+    const dbFile = process.env.CLASSHELPER_SNAPSHOT_DB || env.env.sqliteFilePath;
+    if (!dbFile || !fs.existsSync(dbFile)) {
+      fail(
+        `数据库文件不存在：${dbFile || '(未配置)'}\n` +
+          '  提示：全新安装请先 systemctl start classhelper 完成建表（AUTO_MIGRATE）；',
+        EXIT.NO_DB,
+      );
+      return null;
+    }
+  }
+  const db = await import(pathToFileURL(path.join(serverDist, 'lib', 'db.js')).href);
+  const password = await import(pathToFileURL(path.join(serverDist, 'lib', 'password.js')).href);
+  return { env: env.env, prisma: db.prisma, disconnectPrisma: db.disconnectPrisma, ...password };
+}
+
+/** 目标账号：普通用户按 username，班级账号按 Class.code（ClassHelper 班级端登录用的是班级码） */
+async function resolveTarget(prisma, key) {
+  if (key.startsWith('class:')) {
+    const code = key.slice('class:'.length).toUpperCase();
+    const klass = await prisma.class.findUnique({ where: { code } });
+    if (!klass) return { error: `班级码不存在：${code}`, code: EXIT.NOT_FOUND };
+    return { kind: 'class', id: klass.id, label: `班级 ${klass.name}（码 ${klass.code}）`, hash: klass.passwordHash };
+  }
+  const user = await prisma.user.findUnique({ where: { username: key } });
+  if (!user) return { error: `用户名不存在：${key}`, code: EXIT.NOT_FOUND };
+  if (user.role === 'STUDENT') {
+    return {
+      error: `学生没有个人账号（${key} 只是名单记录），ClassHelper 班级端用「班级码 + 班级密码」登录，请用 --class 改班级密码`,
+      code: EXIT.NOT_FOUND,
+    };
+  }
+  return { kind: 'user', id: user.id, label: `${user.name}（${user.username} / ${user.role}）`, hash: user.passwordHash };
+}
+
+/* ------------------------------------------------------------------ 子命令 */
+
+/**
+ * SQLite 一致性快照：`VACUUM INTO` 在服务运行中也能拿到自洽的副本
+ * （直接 cp 数据文件可能抓到写入中的中间状态）。
+ * 目标文件必须不存在 —— 这是 SQLite 的硬要求，先删掉。
+ */
+async function cmdSnapshot(modules, dest) {
+  const { env, prisma } = modules;
+  if (env.databaseProvider !== 'sqlite') {
+    return fail('snapshot 只支持 SQLite；MySQL 请用 mysqldump', EXIT.FAIL);
+  }
+  const target = path.resolve(dest);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.rmSync(target, { force: true });
+  // VACUUM INTO 不接受参数占位符，只能拼字面量 —— 单引号按 SQL 规则翻倍转义
+  await prisma.$executeRawUnsafe(`VACUUM INTO '${target.replace(/'/g, "''")}'`);
+  if (!fs.existsSync(target)) return fail('快照未生成（VACUUM INTO 未报错但没有产出文件）', EXIT.FAIL);
+  process.stdout.write(`${target}\n`);
+}
+
+async function cmdInfo(modules) {
+  const { env, prisma } = modules;
+  const counts = {};
+  for (const model of ['user', 'class', 'course', 'schedule', 'homework', 'notification', 'grade']) {
+    counts[model] = await prisma[model].count();
+  }
+  const payload = {
+    provider: env.databaseProvider,
+    sqliteFile: env.sqliteFilePath || null,
+    serverRoot: env.serverRoot,
+    termStartDate: env.termStartDate || null,
+    counts,
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function cmdList(modules, asJson) {
+  const { prisma } = modules;
+  const users = await prisma.user.findMany({
+    where: { role: { in: ['ADMIN', 'TEACHER'] } },
+    select: { username: true, name: true, role: true, classId: true, updatedAt: true },
+    orderBy: [{ role: 'asc' }, { username: 'asc' }],
+  });
+  const classes = await prisma.class.findMany({
+    select: { code: true, name: true, passwordHash: true },
+    orderBy: { code: 'asc' },
+  });
+
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          users,
+          classes: classes.map((item) => ({ code: item.code, name: item.name, hasPassword: !!item.passwordHash })),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+
+  process.stdout.write('可登录账号（教师 / 管理员）：\n');
+  for (const user of users) {
+    process.stdout.write(`  ${user.role.padEnd(8)} ${user.username.padEnd(16)} ${user.name}\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`);
+  }
+}
+
+async function cmdDumpHash(modules, key) {
+  const { prisma } = modules;
+  const target = await resolveTarget(prisma, key);
+  if (target.error) return fail(target.error, target.code);
+  if (!target.hash) return fail(`${target.label} 当前没有密码（passwordHash 为空）`, EXIT.NOT_FOUND);
+  // 只给调用方（root）看的原始数据，不落到本工具的日志里
+  process.stdout.write(`${JSON.stringify({ target: key, kind: target.kind, id: target.id, hash: target.hash })}\n`);
+}
+
+async function cmdSetPassword(modules, key, readSecret) {
+  const { prisma, hashPassword } = modules;
+  const target = await resolveTarget(prisma, key);
+  if (target.error) return fail(target.error, target.code);
+
+  const secret = await readSecret();
+  const problems = checkStrength(secret, key);
+  if (problems.length > 0) return fail(`密码不合规：${problems.join('；')}`, EXIT.WEAK);
+
+  const hash = await hashPassword(secret);
+  if (target.kind === 'class') {
+    await prisma.class.update({ where: { id: target.id }, data: { passwordHash: hash } });
+  } else {
+    await prisma.user.update({ where: { id: target.id }, data: { passwordHash: hash } });
+  }
+
+  // 写完立刻复核一次：曾经出现过"bcrypt 参数不一致导致写进去的哈希验证不过"的排查成本
+  const ok = await modules.verifyPassword(secret, hash);
+  if (!ok) return fail('写入后复核失败：哈希无法通过校验，请用 restore-hash 回滚', EXIT.FAIL);
+
+  process.stdout.write(`已更新密码：${target.label}\n`);
+}
+
+async function cmdVerify(modules, key, readSecret) {
+  const { prisma, verifyPassword } = modules;
+  const target = await resolveTarget(prisma, key);
+  if (target.error) return fail(target.error, target.code);
+  const secret = await readSecret();
+  const ok = !!target.hash && (await verifyPassword(secret, target.hash));
+  process.stdout.write(`${ok ? 'match' : 'mismatch'}\n`);
+  if (!ok) process.exitCode = EXIT.FAIL;
+}
+
+async function cmdRestoreHash(modules, backupFile) {
+  const { prisma } = modules;
+  if (!fs.existsSync(backupFile)) return fail(`备份文件不存在：${backupFile}`, EXIT.NOT_FOUND);
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(backupFile, 'utf8'));
+  } catch (error) {
+    return fail(`备份文件不是合法 JSON：${error.message}`);
+  }
+  const { target, hash } = payload;
+  if (typeof target !== 'string' || typeof hash !== 'string') {
+    return fail('备份文件缺少 target / hash 字段，拒绝回滚');
+  }
+  if (target.startsWith('class:')) {
+    await prisma.class.update({ where: { code: target.slice('class:'.length).toUpperCase() }, data: { passwordHash: hash } });
+  } else {
+    await prisma.user.update({ where: { username: target }, data: { passwordHash: hash } });
+  }
+  process.stdout.write(`已回滚密码哈希：${target}\n`);
+}
+
+/* ------------------------------------------------------------------ 入口 */
+
+const argv = process.argv.slice(2);
+const command = argv[0] ?? 'help';
+const args = argv.slice(1);
+const wantsJson = args.includes('--json');
+const positional = args.filter((item) => !item.startsWith('--'));
+
+function usage() {
+  process.stdout.write(
+    [
+      'classhelper 离线账号工具（一般由 classhelper 命令调用）',
+      '',
+      '  info                              输出数据库与表行数（JSON）',
+      '  list [--json]                     列出可登录账号与班级账号',
+      '  dump-hash <用户名|class:班级码>    输出当前密码哈希（供改密前备份）',
+      '  set-password <用户名>             从 stdin 读新密码并写入',
+      '  set-class-password <班级码>       从 stdin 读新密码并写入班级账号',
+      '  verify <用户名>                   从 stdin 读密码，输出 match / mismatch',
+      '  restore-hash <备份json路径>       用备份文件里的哈希回滚',
+      '  snapshot <目标db文件>             把 SQLite 库一致性快照到指定路径（VACUUM INTO）',
+      '',
+    ].join('\n'),
+  );
+}
+
+if (command === 'help' || command === '--help' || command === '-h') {
+  usage();
+} else if (
+  ![
+    'info',
+    'list',
+    'dump-hash',
+    'set-password',
+    'set-class-password',
+    'verify',
+    'restore-hash',
+    'snapshot',
+  ].includes(command)
+) {
+  fail(`未知子命令：${command}\n`, EXIT.USAGE);
+  usage();
+} else {
+  const modules = await loadServerModules();
+  if (!modules) {
+    // 已经在 loadServerModules 里设了 exitCode
+  } else {
+    try {
+      switch (command) {
+        case 'info':
+          await cmdInfo(modules);
+          break;
+        case 'list':
+          await cmdList(modules, wantsJson);
+          break;
+        case 'dump-hash':
+          if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
+          else await cmdDumpHash(modules, positional[0]);
+          break;
+        case 'set-password':
+        case 'set-class-password': {
+          const key = command === 'set-class-password' ? `class:${positional[0] ?? ''}` : (positional[0] ?? '');
+          if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
+          else await cmdSetPassword(modules, key, readSecretFromStdin);
+          break;
+        }
+        case 'verify':
+          if (!positional[0]) fail('缺少目标账号', EXIT.USAGE);
+          else await cmdVerify(modules, positional[0], readSecretFromStdin);
+          break;
+        case 'restore-hash':
+          if (!positional[0]) fail('缺少备份文件路径', EXIT.USAGE);
+          else await cmdRestoreHash(modules, positional[0]);
+          break;
+        case 'snapshot':
+          if (!positional[0]) fail('缺少目标文件路径', EXIT.USAGE);
+          else await cmdSnapshot(modules, positional[0]);
+          break;
+        default:
+          usage();
+      }
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    } finally {
+      // 不用 process.exit()：在顶层 await 里硬退会踩 libuv 断言（见 AGENTS.md 的现行工程约定）
+      await modules.disconnectPrisma();
+    }
+  }
+}

deploy/verify-linux.sh

@@ -0,0 +1,307 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# ClassHelper · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
+#
+# 覆盖：安装结果 → 服务可用性 → API 登录 → 改密（含回滚与审计）→ 备份 →
+#       配置读写 → key rotate →（可选）升级 / 回滚 / 卸载
+#
+# 用法（在服务器上，需要 root）：
+#   sudo bash verify-linux.sh                        # 基础链路
+#   sudo bash verify-linux.sh --full --package /tmp/xxx.tar.gz   # 追加升级/回滚
+#   sudo bash verify-linux.sh --admin-password-stdin # 密码从 stdin 读一行（不进 argv/history）
+#
+# 说明：
+#   - 本脚本会**真的**改一次管理员密码（换成随机强密码，再改回去），并真的发一条备份；
+#   - 除了 --purge 的卸载测试，不会删除任何数据；
+#   - 全程不需要外网（升级测试用 --package 指向本地包）。
+# ---------------------------------------------------------------------------
+set -uo pipefail
+
+INSTALL_DIR="/opt/classhelper"
+CONFIG_FILE="/etc/classhelper/config.env"
+LOG_DIR="/var/log/classhelper"
+BACKUP_DIR="/var/backups/classhelper"
+PORT=""
+ADMIN_USER="admin"
+ADMIN_PASSWORD=""
+ADMIN_PASSWORD_FROM_STDIN=0
+DO_FULL=0
+PACKAGE=""
+
+TOTAL=0; PASS=0; FAIL=0
+FAILED=()
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) INSTALL_DIR="$2"; shift 2 ;;
+    --config) CONFIG_FILE="$2"; shift 2 ;;
+    --port) PORT="$2"; shift 2 ;;
+    --user) ADMIN_USER="$2"; shift 2 ;;
+    --admin-password) ADMIN_PASSWORD="$2"; shift 2 ;;
+    --admin-password-stdin) ADMIN_PASSWORD_FROM_STDIN=1; shift ;;
+    --package) PACKAGE="$2"; shift 2 ;;
+    --full) DO_FULL=1; shift ;;
+    -h|--help) sed -n '2,18p' "$0"; exit 0 ;;
+    *) echo "未知参数：$1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -t 1 ]; then G=$'\033[32m'; R=$'\033[31m'; Y=$'\033[33m'; D=$'\033[2m'; B=$'\033[1m'; N=$'\033[0m'; else G=; R=; Y=; D=; B=; N=; fi
+
+section() { printf '\n%s▶ %s%s\n' "$B" "$1" "$N"; }
+check() { # $1=描述 $2=0 通过
+  TOTAL=$((TOTAL + 1))
+  if [ "$2" = "0" ]; then
+    PASS=$((PASS + 1)); printf '  %s✔%s %s\n' "$G" "$N" "$1"
+  else
+    FAIL=$((FAIL + 1)); FAILED+=("$1"); printf '  %s✘%s %s\n' "$R" "$N" "$1"
+  fi
+}
+note() { printf '  %s· %s%s\n' "$D" "$1" "$N"; }
+
+[ "$(id -u)" = "0" ] || { echo "请用 root 运行：sudo bash verify-linux.sh" >&2; exit 1; }
+
+if [ ! -f "$CONFIG_FILE" ]; then
+  echo "找不到安装：${CONFIG_FILE} 不存在（用 --config 指定，或先跑 install.sh）" >&2
+  exit 1
+fi
+read_cfg() { sed -n "s/^[[:space:]]*$1=//p" "$CONFIG_FILE" | tail -n 1 | tr -d '"'; }
+[ -n "$PORT" ] || PORT="$(read_cfg PORT)"
+[ -n "$PORT" ] || PORT=4000
+CLASSHELPER="${INSTALL_DIR}/bin/classhelper"
+API="http://127.0.0.1:${PORT}"
+CURL=(curl -fsS --noproxy '*')
+
+if [ "$ADMIN_PASSWORD_FROM_STDIN" = "1" ]; then IFS= read -r ADMIN_PASSWORD || true; fi
+
+printf '%sClassHelper · Linux 安装验收%s\n' "$B" "$N"
+note "安装目录 ${INSTALL_DIR}｜配置 ${CONFIG_FILE}｜端口 ${PORT}"
+
+# ---------------------------------------------------------------- 1. 安装结果
+
+section "安装结果"
+check "安装目录存在且含 server/dist/index.js" "$([ -f "${INSTALL_DIR}/server/dist/index.js" ] && echo 0 || echo 1)"
+check "版本文件 VERSION 可读" "$([ -s "${INSTALL_DIR}/VERSION" ] && echo 0 || echo 1)"
+check "安装元数据 .installed.json 存在" "$([ -f "${INSTALL_DIR}/.installed.json" ] && echo 0 || echo 1)"
+
+cfg_mode="$(stat -c '%a' "$CONFIG_FILE" 2>/dev/null || echo '?')"
+check "配置文件权限 600（实际 ${cfg_mode}）" "$([ "$cfg_mode" = "600" ] && echo 0 || echo 1)"
+dir_mode="$(stat -c '%a' "$(dirname "$CONFIG_FILE")" 2>/dev/null || echo '?')"
+check "配置目录权限 700（实际 ${dir_mode}）" "$([ "$dir_mode" = "700" ] && echo 0 || echo 1)"
+
+env_link="${INSTALL_DIR}/.env"
+check "安装目录 .env 是指向配置真身的软链（Web 端切库依赖它）" \
+  "$([ -L "$env_link" ] && [ "$(readlink "$env_link")" = "$CONFIG_FILE" ] && echo 0 || echo 1)"
+
+node_bin="${INSTALL_DIR}/runtime/node/bin/node"
+node_ver="$([ -x "$node_bin" ] && "$node_bin" -v 2>/dev/null || echo '')"
+check "内置 Node 可用（${node_ver:-未找到}）" "$([ -n "$node_ver" ] && echo 0 || echo 1)"
+
+check "classhelper 命令已装到 /usr/local/bin" "$([ -x /usr/local/bin/classhelper ] && echo 0 || echo 1)"
+check "安装日志 ${LOG_DIR}/install.log 存在" "$([ -s "${LOG_DIR}/install.log" ] && echo 0 || echo 1)"
+check "审计日志 ${LOG_DIR}/audit.log 存在" "$([ -f "${LOG_DIR}/audit.log" ] && echo 0 || echo 1)"
+check "审计/安装日志权限不放行他人（≤640）" \
+  "$([ "$(stat -c '%a' "${LOG_DIR}/audit.log" 2>/dev/null || echo 644)" -le 640 ] && echo 0 || echo 1)"
+check "/etc/profile.d/classhelper.sh 已写入" "$([ -f /etc/profile.d/classhelper.sh ] && echo 0 || echo 1)"
+profile_home="$(bash -lc 'echo "${CLASSHELPER_HOME:-}"' 2>/dev/null)"
+check "新登录 shell 里 CLASSHELPER_HOME 生效（${profile_home:-空}）" "$([ -n "$profile_home" ] && echo 0 || echo 1)"
+
+# ---------------------------------------------------------------- 2. 服务
+
+section "服务与探针"
+if command -v systemctl >/dev/null 2>&1 && [ -f /etc/systemd/system/classhelper.service ]; then
+  check "systemd 单元已安装" 0
+  check "服务处于 active" "$(systemctl is-active --quiet classhelper && echo 0 || echo 1)"
+  check "服务开机自启（enabled）" "$(systemctl is-enabled --quiet classhelper 2>/dev/null && echo 0 || echo 1)"
+else
+  check "systemd 单元已安装" 1
+fi
+check "/healthz 返回 200" "$("${CURL[@]}" -o /dev/null "${API}/healthz" 2>/dev/null && echo 0 || echo 1)"
+
+status_json="$("$CLASSHELPER" status --json 2>/dev/null || true)"
+check "classhelper status --json 是合法 JSON" "$(printf '%s' "$status_json" | grep -q '"healthy"' && echo 0 || echo 1)"
+check "status 报告 healthy=yes" "$(printf '%s' "$status_json" | grep -q '"healthy": "yes"' && echo 0 || echo 1)"
+check "status 报告的端口与实际一致" "$(printf '%s' "$status_json" | grep -q "\"port\": ${PORT}" && echo 0 || echo 1)"
+check "classhelper help 可执行（非 root 也能看）" "$("$CLASSHELPER" help >/dev/null 2>&1 && echo 0 || echo 1)"
+check "classhelper completion bash 有输出" "$("$CLASSHELPER" completion bash 2>/dev/null | grep -q 'classhelper' && echo 0 || echo 1)"
+
+doctor_out="$("$CLASSHELPER" doctor 2>&1 || true)"
+check "classhelper doctor 无待处理项" "$(printf '%s' "$doctor_out" | grep -q '体检通过' && echo 0 || echo 1)"
+if ! printf '%s' "$doctor_out" | grep -q '体检通过'; then
+  printf '%s' "$doctor_out" | sed 's/^/    /'
+fi
+
+# ---------------------------------------------------------------- 3. API
+
+section "API 与登录"
+TOKEN=""
+login() { # $1=密码 → 输出 token（失败则空）
+  "${CURL[@]}" -X POST "${API}/api/auth/login" -H 'content-type: application/json' \
+    -d "{\"username\":\"${ADMIN_USER}\",\"password\":\"$1\"}" 2>/dev/null \
+    | sed -n 's/.*"token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p'
+}
+
+if [ -z "$ADMIN_PASSWORD" ]; then
+  note "未提供 --admin-password(-stdin)，跳过登录与改密用例"
+else
+  TOKEN="$(login "$ADMIN_PASSWORD")"
+  check "管理员用提供的密码能登录并拿到 token" "$([ -n "$TOKEN" ] && echo 0 || echo 1)"
+  if [ -n "$TOKEN" ]; then
+    classes="$("${CURL[@]}" -H "Authorization: Bearer ${TOKEN}" "${API}/api/classes" 2>/dev/null || true)"
+    check "带 token 能读业务接口 /api/classes" "$(printf '%s' "$classes" | grep -q '"data"' && echo 0 || echo 1)"
+    me="$("${CURL[@]}" -H "Authorization: Bearer ${TOKEN}" "${API}/api/auth/me" 2>/dev/null || true)"
+    check "/api/auth/me 返回的是 ADMIN" "$(printf '%s' "$me" | grep -q '"ADMIN"' && echo 0 || echo 1)"
+  fi
+fi
+
+# ---------------------------------------------------------------- 4. 改密
+
+if [ -n "$TOKEN" ]; then
+  section "password 子命令（改密 → 回滚 → 审计）"
+  # 生成一个一定满足强度要求的密码（大小写+数字+符号，且不落在常见口令里）
+  GENERATED="Ch$(head -c 12 /dev/urandom | od -An -tx1 | tr -d ' \n')!a9Z"
+  before_count="$(grep -c 'action=password' "${LOG_DIR}/audit.log" 2>/dev/null || echo 0)"
+
+  # 密码经管道进 stdin，不出现在 argv / 环境变量 / shell history
+  out="$(printf '%s\n%s\n' "$GENERATED" "$GENERATED" | "$CLASSHELPER" password "$ADMIN_USER" 2>&1)"
+  check "classhelper password 执行成功" "$(printf '%s' "$out" | grep -q '密码已更新' && echo 0 || echo 1)"
+
+  new_token="$(login "$GENERATED")"
+  check "新密码能登录" "$([ -n "$new_token" ] && echo 0 || echo 1)"
+  old_token="$(login "$ADMIN_PASSWORD")"
+  check "旧密码已失效（登录被拒）" "$([ -z "$old_token" ] && echo 0 || echo 1)"
+
+  hash_backup="$(ls -1t "${BACKUP_DIR}"/password-*.json 2>/dev/null | head -n 1 || true)"
+  check "改密前备份了原哈希（${hash_backup:-无}）" "$([ -n "$hash_backup" ] && echo 0 || echo 1)"
+  check "哈希备份权限 600" \
+    "$([ -n "$hash_backup" ] && [ "$(stat -c '%a' "$hash_backup")" = "600" ] && echo 0 || echo 1)"
+
+  after_count="$(grep -c 'action=password' "${LOG_DIR}/audit.log" 2>/dev/null || echo 0)"
+  check "审计日志新增了 password 记录" "$([ "${after_count:-0}" -gt "${before_count:-0}" ] && echo 0 || echo 1)"
+  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)"
+
+  # 先把输出收进变量再 grep：`外部命令 | grep -q` 在 `set -o pipefail` 下，grep 命中即退出会让
+  # 写端收到 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)"
+  list_out="$("$CLASSHELPER" password --list 2>&1 || true)"
+  check "password --list 能列出账号" "$(printf '%s' "$list_out" | grep -q "$ADMIN_USER" && echo 0 || echo 1)"
+
+  # 用改密前保存的哈希把账号恢复原样：比再改一次密码更可靠
+  # （原密码若是 admin123 这类弱口令，改回去会被强度校验挡下 —— 那是产品的正确行为）
+  if [ -n "$hash_backup" ]; then
+    restore_hash_out="$(LOG_LEVEL=error DOTENV_CONFIG_QUIET=true "$node_bin" "${INSTALL_DIR}/tools/admin-cli.mjs" restore-hash "$hash_backup" 2>&1 || true)"
+    check "restore-hash 能把原哈希回滚回来" "$(printf '%s' "$restore_hash_out" | grep -q '已回滚密码哈希' && echo 0 || echo 1)"
+    check "原密码重新可用" "$([ -n "$(login "$ADMIN_PASSWORD")" ] && echo 0 || echo 1)"
+  fi
+else
+  note "跳过改密用例（没有可用的登录会话）"
+fi
+
+# ---------------------------------------------------------------- 5. 备份
+
+section "backup 子命令"
+backup_out="$("$CLASSHELPER" backup --keep 5 2>&1)"
+check "classhelper backup 执行成功" "$(printf '%s' "$backup_out" | grep -q '备份完成' && echo 0 || echo 1)"
+
+latest="$(ls -1dt "${BACKUP_DIR}"/*/ 2>/dev/null | head -n 1)"
+check "生成了新的备份目录" "$([ -n "$latest" ] && echo 0 || echo 1)"
+if [ -n "$latest" ]; then
+  check "备份含 config.env" "$([ -f "${latest}config.env" ] && echo 0 || echo 1)"
+  check "备份 meta.json 带版本号" "$(grep -q '"version"' "${latest}meta.json" 2>/dev/null && echo 0 || echo 1)"
+  db_kind="$(read_cfg DATABASE_PROVIDER)"
+  if [ "$db_kind" = "sqlite" ]; then
+    snap="${latest}classhelper.db"
+    check "备份含 SQLite 快照" "$([ -s "$snap" ] && echo 0 || echo 1)"
+    # 一致性快照必须是完整的 SQLite 文件（VACUUM INTO 产物）
+    check "快照是合法 SQLite 文件（文件头正确）" \
+      "$([ -n "$snap" ] && [ "$(head -c 15 "$snap" 2>/dev/null)" = "SQLite format 3" ] && echo 0 || echo 1)"
+    check "快照权限 600" "$([ -n "$snap" ] && [ "$(stat -c '%a' "$snap")" = "600" ] && echo 0 || echo 1)"
+  else
+    note "数据库是 MySQL，跳过 SQLite 快照用例"
+  fi
+  check "备份目录权限 700" "$([ "$(stat -c '%a' "${latest%/}" 2>/dev/null)" = "700" ] && echo 0 || echo 1)"
+fi
+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. 配置
+
+section "config 子命令"
+check "config get PORT 返回当前端口" "$([ "$("$CLASSHELPER" config get PORT)" = "$PORT" ] && echo 0 || echo 1)"
+masked="$("$CLASSHELPER" config show 2>/dev/null | grep '^JWT_SECRET=')"
+check "config show 对 JWT_SECRET 打码" "$(printf '%s' "$masked" | grep -q '\*\*\*\*' && echo 0 || echo 1)"
+check "config show 没打印出真实密钥" \
+  "$(secret="$(read_cfg JWT_SECRET)"; [ -n "$secret" ] && printf '%s' "$masked" | grep -q -- "$secret" && echo 1 || echo 0)"
+
+# 用一个无害的键做读写往返（不重启服务）
+printf 'CH_VERIFY_PROBE=1\n' >>"$CONFIG_FILE"
+probe="$("$CLASSHELPER" config get CH_VERIFY_PROBE 2>/dev/null)"
+check "config get 能读到新增键" "$([ "$probe" = "1" ] && echo 0 || echo 1)"
+sed -i '/^CH_VERIFY_PROBE=/d' "$CONFIG_FILE"
+
+# ---------------------------------------------------------------- 7. key rotate
+
+if [ -n "$TOKEN" ]; then
+  section "key rotate"
+  if [ "${CLASSHELPER_VERIFY_SKIP_KEY_ROTATE:-0}" = "1" ]; then
+    note "按环境变量跳过"
+  else
+    old_secret="$(read_cfg JWT_SECRET)"
+    # key rotate 无 tty 时会问两次（确认轮换、是否现在重启）；只喂一个 yes 的话第二次读到 EOF，
+    # 重启被跳过 —— 新密钥不生效，下面「旧 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)"
+    check "轮换后服务仍可用" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
+    check "轮换前的 token 已失效（/api/auth/me 返回 401）" \
+      "$(code="$(curl -s --noproxy '*' -o /dev/null -w '%{http_code}' -H "Authorization: Bearer ${TOKEN}" "${API}/api/auth/me")"; [ "$code" = "401" ] && echo 0 || echo 1)"
+    # 轮换后要重新登录，否则后面的用例会带着失效 token 跑
+    TOKEN="$(login "$ADMIN_PASSWORD")"
+    check "轮换后重新登录成功" "$([ -n "$TOKEN" ] && echo 0 || echo 1)"
+  fi
+fi
+
+# ---------------------------------------------------------------- 8. 升级 / 回滚
+
+if [ "$DO_FULL" = "1" ]; then
+  section "upgrade / rollback（--full）"
+  if [ -z "$PACKAGE" ]; then
+    note "未提供 --package，跳过升级用例"
+  else
+    before_version="$("$CLASSHELPER" version 2>/dev/null | awk '{print $2}')"
+    sha="$(sha256sum "$PACKAGE" | awk '{print $1}')"
+    up_out="$("$CLASSHELPER" upgrade --url "$PACKAGE" --sha256 "$sha" --force 2>&1)"
+    check "upgrade 执行成功" "$(printf '%s' "$up_out" | grep -q '升级完成' && echo 0 || echo 1)"
+    check "升级后服务仍就绪" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
+    check "升级后配置未被改动（JWT_SECRET 保持）" \
+      "$([ "$(read_cfg JWT_SECRET)" = "${new_secret:-$(read_cfg JWT_SECRET)}" ] && echo 0 || echo 1)"
+    check "产生了程序快照（可回滚）" "$(ls -1 "${BACKUP_DIR}/rollback" 2>/dev/null | grep -q . && echo 0 || echo 1)"
+    check "坏包被拒绝（sha256 不匹配时不改动任何文件）" \
+      "$("$CLASSHELPER" upgrade --url "$PACKAGE" --sha256 0000000000000000000000000000000000000000000000000000000000000000 2>&1 | grep -q '校验失败' && echo 0 || echo 1)"
+    check "校验失败后服务仍在运行" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
+
+    note "（回滚需要交互确认，这里用 yes 管道）"
+    rb_out="$(printf 'yes\n' | "$CLASSHELPER" rollback 2>&1)"
+    check "rollback 执行成功" "$(printf '%s' "$rb_out" | grep -qE '已回滚到|回滚' && echo 0 || echo 1)"
+    check "回滚后服务仍就绪" "$("${CURL[@]}" -o /dev/null "${API}/healthz" && echo 0 || echo 1)"
+    note "升级前版本 ${before_version}｜升级后 $("$CLASSHELPER" version 2>/dev/null | awk '{print $2}')"
+  fi
+fi
+
+# ---------------------------------------------------------------- 结果
+
+printf '\n'
+if [ "$FAIL" = "0" ]; then
+  printf '%s=== 结果：%s/%s 项通过 ===%s\n' "$G" "$PASS" "$TOTAL" "$N"
+else
+  printf '%s=== 结果：%s/%s 项通过，%s 项失败 ===%s\n' "$R" "$PASS" "$TOTAL" "$FAIL" "$N"
+  printf '%s失败项：%s\n' "$Y" "$N"
+  for item in "${FAILED[@]}"; do printf '  · %s\n' "$item"; done
+fi
+[ "$FAIL" = "0" ] || exit 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,99 @@
+---
+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)。
+
+## 客户端设置页
+
+「设置」是可展开分组，常用子页如下；开发者模式还提供开发者页，自定义岛编辑为灵动岛子路由：
+
+| 子页   | 内容                                                                          |
+| ------ | ----------------------------------------------------------------------------- |
+| 通用   | 服务器连接、离线缓存、作业录入短语、使用引导                                  |
+| 外观   | 浅色 / 深色                                                                   |
+| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝（详见[灵动岛](island.md)） |
+| 提醒   | 本机课程等提醒开关与行为                                                      |
+| 账号   | 当前班级信息、退出登录                                                        |
+| 关于   | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢                   |
+
+`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**，重启后仍保留。

docs/app/calls.md

@@ -0,0 +1,22 @@
+---
+title: 叫人
+description: 点名、优先级、可见范围和客户端展示。
+---
+
+# 叫人
+
+在 Web“通知发布 → 叫人”选学生，填写事由或选择快捷短语，需 call:create 和班级范围权限。
+可调用的学生必须属于相应在读班级且未转出；岗位范围、任课或班主任关系由服务端检查。
+学生没有账号，无法以个人身份调用接口。
+
+| 级别     | 落库优先级 | 经典 fixed 展示                                                    |
+| -------- | ---------- | ------------------------------------------------------------------ |
+| 普通叫人 | HIGH       | 胶囊可点击，上课也允许主动查看；不自动展开打断课堂，下课可自动展开 |
+| 紧急叫人 | URGENT     | 上课也立即展开，收起后仍可主动再打开                               |
+
+自定义 custom 是常驻模式，两种叫人都先提示铃铛，由用户主动查看；详见[通知与提醒](notifications.md)。
+卡片内容包括被叫学生、教师和事由，“收到”复用通知已读机制。
+自定义消息优先于快捷短语，消息长度以接口 schema 校验为准。
+
+`POST /api/calls` 保存为 Notification，带本地所属日期；随后发送 notification:new 班级广播和 call:new 班级会话定向事件。
+定向主体是班级会话，学生本身没有 Socket 房间；双播按消息 id 合并去重。

docs/app/classes.md

@@ -0,0 +1,67 @@
+---
+title: 班级、学生与教师
+description: 名单、班级会话、任课关系与年度升级。
+---
+
+# 班级、学生与教师
+
+## 班级账号
+
+教室客户端使用班级码和班级密码登录，形成 CLASS_DEVICE 会话，主体是班级。
+班级码保存时统一大写；管理员在“班级管理”维护班级码、密码与班主任。
+班级端的已读、作业完成等操作代表全班，学生没有个人登录账号。
+客户端没有修改密码入口；员工本人改密码在 Web 顶栏菜单。
+
+班级名由入学年份和班号组成，例如“2026级1班”；年级独立保存，学年升级时班名不随之改写。
+班主任可以暂空，新学年自动创建的高一班级仅有骨架，需要管理员后续分配教师。
+
+## 学生名单
+
+Web 统一从“学生管理”查看和维护名单；旧 `/roster` 地址转到同一页面，不再提供重复菜单。班级详情中的名单与课程按当前班级的生效范围展示维护入口，任课关系本身不授予跨班名单、课程或班级设置管理权。
+
+Student 存学号、姓名、班级、性别、家长电话和状态，没有密码或角色字段。
+学号为必填唯一标识，格式为 1–32 位字母、数字或 . _ -；不会自动生成登录名。
+具有名单管理键的管理员、本班班主任或全校名单范围的授权员工管理学生；只读账号按名单读取键和范围查看历史。
+名单表格导入要求 import:students、roster:manage 和对应班级范围；学号查重在 Student 表完成，不当成 User 用户名。
+调班保留历史内容原归属；转出独立记账并从现行业务名单过滤，学号不可复用。
+
+## 教师与科目
+
+教师使用工号和密码登录，管理入口受 teacher:read/teacher:manage 等功能权限控制。
+教师名单导入还要求管理员身份和相应导入权限。班主任关系在 Class.teacherId；
+科任关系唯一存于 Course(classId, name, teacherId)，分配任课关系由班级管理权限及服务端断言限制。
+班主任不任教某科就不能修改该科作业/成绩；科任老师有相应权限时可以管理自己任教科目。
+
+删除教师前，服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件；仍有业务内容则返回冲突，避免级联丢失。
+教师本人改密码、管理员修改教师密码、班级账号密码是不同入口；学生没有密码接口。
+
+## 权限、学年与归档
+
+管理员固定拥有全部能力；教师按岗位模板及每项分配的范围获得能力，未显式分配时使用教师默认模板与固定任教范围。
+范围不代替科目写权限，详见[角色与权限](../dev/permissions.md)。
+“学期周次”只维护教学周与日期区间；年度轨道、执行计划与补跑统一在管理员专用的“学年升级”页维护。
+学期周数受全校可配置上限约束，默认上限 30、允许 1–60，见[课表](schedules.md)。
+学年升级按计划时间运行，执行前保存快照，以年份幂等；启动发现漏跑需管理员预览补跑。
+默认高中轨道按高一、高二、高三排列，毕业学段归档，其余升一级；也可配置其他轨道。新班不复制任课关系。归档页查看届别历史与转出记录，
+不再通过手动创建归档来代替年度升级。撤回转出由 roster:manage 控制，原班归档后可指定其他在读班。
+
+## 学生生命周期
+
+资料编辑仅修改学号、姓名、性别与家长电话，不接受状态或班级字段；旧客户端发送这两项会收到 400 和专用接口提示。
+默认名单只显示未归档的 active；状态筛选可查看 inactive、transferred、graduated，“包含归档”另行控制归档标记。
+
+调班、转出、转入、复学、撤回与移出班级均在一个事务内修改学生并写历史，包含批次、学年、原新班级与年级、来源去向学校、操作人和备注。
+调班需同时覆盖源班与目标班；跨年级须管理员勾选允许跨年级并填写备注。目标班必须在读。
+转出保留原班及业务历史，只接受在读或停用学生。转入支持新建学号或选择转出/停用学生，毕业或归档学生不能通过名单入口复活。
+撤回转出可选择另一个在读班，原历史保留。默认删除动作改为停用；硬删除另须管理员确认且无成绩、作业、已读或历史。
+
+## 升级预览与执行
+
+“学年升级”页面独立要求 promotion:manage，全校范围。先保存轨道、有序年级、起始班数、执行时间、开学日和周次重置策略，再预览逐班影响。
+预览包含在读/停用/转出人数、新班码、周次删除行数、阻断和警告、计划哈希。未知年级、缺失届别、重复班号、已有届别档案或新班码冲突会阻断执行。
+执行需确认学年和预览哈希；业务或配置变化后必须重新预览。未来学年禁止执行，过去学年仅 ADMIN 明确补跑。
+
+毕业班所有学生挂届别：在读转毕业，转出和停用保留状态；非毕业班只升到下一学段并清本班开学日覆盖。
+新班只有骨架，开学日取计划值（未配置时为执行学年 9 月 1 日）。保留周次时，旧逐周区间会继续覆盖新学年，页面会警告。
+同年执行幂等，执行记录显示操作人、快照路径、SHA256、明细与错误。快照失败不升级，失败事务回滚后可修正重试。
+撤销归档只清标记并将毕业生恢复在读，转出/停用不变；不回滚年级、不删除新班、不恢复已清空周次，整学年恢复需管理员手工使用快照。

docs/app/courseware.md

@@ -0,0 +1,42 @@
+# 课件上传与传输
+
+教师可在 Web 管理端的「教学事务 → 课件」上传演示文稿、文档、表格、图片、音视频、压缩包等文件，单文件上限为 **512 MB**。
+
+## 上传与可见范围
+
+1. 选择本地文件。
+2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级；仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。
+3. 可新建分类文件夹，使用 `/` 分隔多层目录，例如 `地理/必修一`；不选文件夹时直接按日期归档。
+4. 选择「仅保存云端」或「保存后推送所选班级」，点击上传。
+
+不选择班级时，课件仅自己可见。仅保存云端并指定可见班级后，这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端，再给所选班级创建下载任务；不会从教师电脑直接传到教室电脑。
+
+教师可在列表中按文件名、教师、归档日期和文件类型筛选，修改自己课件的可见范围，或再次推送。再次推送时只能选择「本人授课班级」与「该文件可见范围」的交集。管理员可查看归档列表，但上传和推送自己的文件同样遵守任课关系。
+
+「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限，可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限；升级时自定义权限组需管理员按需授权。
+
+「日期归档」按教师、年、月、日和上传时间选择目录；「文件夹分类」按自建目录筛选，已有文件可随时调整分类。文件夹按教师隔离，分类本身不授予班级下载权限。
+
+## 班级客户端
+
+客户端侧栏新增「课件」，仅列出本班可见的文件，显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机，点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。
+
+「本机归档」独立列出已经接收的课件，离线时也可按教师和日期目录查找。每个服务端与班级会话有独立归档根目录，文件路径采用 `Teachers\老师名字\上传年份\上传月\上传日\上传时间\文件名`，例如 `Teachers\Wanghong\2026\10\18\15-30-42\大气环流.pptx`。目录时间取上传时间，重复推送会复用已校验的文件；同秒同名的不同课件会添加编号，避免覆盖。
+
+收到教师推送后，客户端自动下载；离线时任务保留在服务端，上线后的心跳会补拉，每台设备独立回执。实时通道正常时会立即触发检查；断线时通过心跳继续补收。传输失败会显示原因，推送任务在后续心跳中重试，不会影响远控和在线状态上报。
+
+下载期间，固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256，再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件；重新联网后同步当前可见范围。
+
+修改可见范围后，被移除班级无法再获取文件，尚未完成的推送任务同步取消。已经下载到教室电脑的文件无法远程撤回，需要在本机自行删除。
+
+## 服务端归档与备份
+
+默认文件实体目录为 `<服务端根目录的上一级>/data/courseware/<随机编号>/Teachers/<教师>/<年>/<月>/<日>/<时间>/<文件名>`，随机编号隔离同名教师和同秒上传，旧课件保留原存储位置。可通过环境变量 `COURSEWARE_DIR` 指定文件目录。上传使用流式写入，未完成文件使用 `.part` 临时文件；失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。
+
+数据库迁移新增课件、可见班级、推送、设备回执和分类目录，并记录上传归档路径。SQLite 安装部署按现有自动迁移流程更新；源码开发部署执行 `pnpm --filter @classhelper/server db:deploy`。MySQL 按现有换库流程基于更新后的 schema 建模。
+
+数据库 JSON 备份包含课件元数据和分类目录，但**不包含二进制文件本身**。完整备份必须同时备份 `data/courseware`（自定义目录时备份对应目录）。SQLite Docker 的现有数据卷覆盖此目录；MySQL Docker 配置增加 `server-data:/app/data` 数据卷。复制到新机器时需同时恢复数据库和文件目录。
+
+使用反向代理时，需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时，其他接口维持原有大小限制。
+
+开发验收：`pnpm verify:courseware` 自动使用隔离数据库和临时文件目录，不读取或向真实班级发送课件。

docs/app/grades.md

@@ -0,0 +1,48 @@
+---
+title: 成绩
+description: 录入、按学号查询、排名与关闭个人查询后的集体分析。
+---
+
+# 成绩
+
+Web 管理端支持单条、批量和表格导入成绩；记录通过 Grade.studentId 关联学生名单。
+科目来自班级课程与共享科目目录，分数、总分和等级按录入规则校验。
+成绩写入需 grade:write 或相应导入权限，并通过班级和科目检查：
+管理员可管理，教师只能编辑自己任课科目，无科目内容按班主任规则；班级端不能写成绩。
+表格导入另有管理员/本班班主任门槛，班主任也只能导入符合科目权限的行；它与单条/批量录入的准入不同。
+
+## 查看、排名与隐私
+
+班级客户端可显示本班考试、成绩总览、等级分布，以及按学号查询明细。
+是否允许读取个人数据由 Class.studentGradeQueryEnabled 控制，班级端只读该设置。
+
+| 状态         | 班级端可读取内容                                                     |
+| ------------ | -------------------------------------------------------------------- |
+| 个人查询开启 | 本班原始成绩、个人明细、考试及排名，仍检查班级归属                   |
+| 个人查询关闭 | 页面可打开，只返回服务端集体聚合；个人明细、原始全班成绩和排名被拒绝 |
+
+聚合对少于 5 名学生的样本、稀疏分段及补集抑制，不提供最高/最低分。
+客户端不会先拿个人成绩再做隐藏或聚合；教师/管理员按自身权限读取，不受班级端个人查询开关限制。
+
+考试“是否计入总分”属于 Exam，教师在管理端设置，客户端只展示。
+同一学生同一科多条成绩取最高分，排名并列用 1、2、2、4；总分只在开启时显示。
+图表使用本地 HTML/CSS/SVG 组件。
+
+## 接口入口
+
+以下省略 /api 前缀，详情与参数以 grades.module.ts、grades.schemas.ts 为准。
+
+| 方法与路径                                            | 用途                                               |
+| ----------------------------------------------------- | -------------------------------------------------- |
+| GET /grades/overview                                  | 班级端按开关返回原始总览或集体聚合                 |
+| GET /grades/my                                        | 班级端原始成绩，关闭个人查询时拒绝；员工返回空数组 |
+| GET /grades/collective?classId=                       | 服务端集体分析                                     |
+| GET /grades/student/:studentNo                        | 按学号查询，班级端受班级开关控制                   |
+| GET /grades?classId=&courseId=&studentId=&examName=   | 员工列表，功能键与范围检查                         |
+| GET /grades/stats                                     | 员工统计                                           |
+| GET/PUT /grades/exams                                 | 考试列表 / 设置总分口径                            |
+| GET /grades/ranking                                   | 考试排名，班级端受个人查询开关控制                 |
+| POST /grades、/grades/bulk                            | 单条或批量录入                                     |
+| PATCH /grades/levels、/grades/:id；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,52 @@
+---
+title: 表格与课表导入
+description: 表格预览、名单与成绩校验，以及完整离线档案导入。
+---
+
+# 表格与课表导入
+
+解析与写入均在服务端完成，Web 收集文件、展示预览和逐行结果。
+表格支持成绩、学生、教师与班级任课关系等 kind，类型和模板以 shared/imports 模块为准。
+
+## 表格流程
+
+下载模板 → 选择 xlsx/xls/csv/tsv → 预览列名与映射 → 确认模式并提交。
+文件上限 8 MB，JSON 请求体 12 MB，超限 413 IMPORT_TOO_LARGE；结果含新增/更新/跳过/失败、errors/warnings。
+错误行号包含表头，便于在 Excel 定位。
+
+- 学生成绩按学号匹配，姓名兜底要求同班唯一；转出学生不参与匹配，重复记录和写入模式由服务校验。
+- 学生模板使用学号、姓名、班级、性别、家长电话，无密码；学号 1–32 位字母/数字/._-，在 Student 表查重。
+- 教师模板使用工号、姓名、手机号、初始密码、角色；学生/教师名单导入仍要求管理员和导入权限。
+- 成绩表格导入当前先要求管理员或本班班主任，再校验每行科目任课关系；科任老师的单条/批量成绩写入权限不代表能走表格导入。
+- 任课关系导入用于既有班级、科目和教师的对应关系，不把档案中的 TeacherName 当账号授权。
+
+## 完整 ClassIsland 档案
+
+在“课表档案 → 导入档案”选择或粘贴 JSON，先预览再导入。
+完整输入包含 TimeLayouts、ClassPlans、Subjects 字典，可包含 ClassPlanGroups 和 OrderedSchedules 等配置。
+JSON 只作为离线文件导入，不依赖在线联动插件。
+
+现行写入由 class-plans/profile-import.service.ts 完成：
+
+| 项目      | 写入规则                                                                |
+| --------- | ----------------------------------------------------------------------- |
+| 时间类型  | 0/1/2/3 对应 LESSON/BREAK/DIVIDER/ACTION，保存为关系化时间点            |
+| 课程对齐  | Classes[i] 引用第 i 个上课时间点，课间/分割线不占课位，数据库用显式外键 |
+| 星期      | 完整导入 0=不按天、1–7=周一至周日                                       |
+| 轮换      | 原样保留 WeekCountDiv/WeekCountDivTotal，支持 1–9 周，不降级成每周      |
+| 状态      | 保留空课、停用、临时换课标记和关联层                                    |
+| 群组/预定 | 保存群组及可识别的预定/临时选择                                         |
+| 缺失科目  | 复用该班课程；新建需该班已有班主任，教师名不授予权限                    |
+| merge     | 基于班级与来源 id 生成稳定 id，重复导入更新同一套对象                   |
+| replace   | 事务内删除该班预定和日课表后写入，保留的对象以实现为准                  |
+
+日课表导入需本班班主任/管理员检查。旧 /imports/class-plan/preview 是扁平预览，
+不完整展示群组/空课/停用等结构；提交直接调用完整导入，不能把预览的单双周列当作实际数据模型。
+完整导入失败时事务回滚；部分缺失引用可能返回 warnings，须检查导入结果和日课表编辑器。
+
+## 时间配置兼容入口
+
+旧 /imports/time-layout 接口保留，写入和删除需 timetable:manage，现行写入同步关系化时间点。
+常规使用时间表/日课表编辑器或整套档案导入；旧预览解析兼容性不代表完整导入接受所有旧输入形态。
+
+接口索引见[REST API](../dev/api.md)，迁移边界见[当前实现约定](../dev/implementation.md)。

docs/app/index.md

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

docs/app/island.md

@@ -0,0 +1,79 @@
+---
+title: 灵动岛
+description: 经典提醒、自定义常驻方案、课程与课件传输。
+---
+
+# 灵动岛
+
+灵动岛是客户端的独立透明窗口，不占任务栏。设置中可选择经典 fixed 或自定义 custom，默认 fixed。
+自定义当前即常驻模式；旧 residentEnabled 字段只作兼容，不是另一个独立开关。
+两种布局共用一个原生窗口，切布局不会新开第二个岛。
+
+## 两种消息展示
+
+| 场景              | 经典 fixed                     | 自定义 custom              |
+| ----------------- | ------------------------------ | -------------------------- |
+| 空闲              | 默认隐藏，可选细缝             | 显示常态组件行             |
+| 课间普通通知/作业 | 胶囊，点击详情                 | 铃铛和未处理数量，点击查看 |
+| 课堂普通通知/作业 | 暂存，下课补弹                 | 铃铛提示，允许主动查看     |
+| 普通叫人          | 课堂也保留可点胶囊，不自动展开 | 铃铛提示，主动查看         |
+| 紧急通知/紧急叫人 | 无论课堂状态立即展开           | 铃铛提示，由用户主动展开   |
+| 无消息时点击      | 按经典空闲状态处理             | 展示方案的无通知展开内容   |
+| 处理完成          | 队列清空后隐藏或细缝           | 回到常态组件行             |
+
+多条消息按 id 去重，按优先级和时间排序；详情显示列表与“展开更多”，超出工作区提示到应用中操作。
+“知道了/标为已读”按当前列表语义处理；本机刚录的作业通过指纹避免重复提醒自己。
+课堂发布紧急通知的二次确认是服务端规则，见[通知](notifications.md)，不因本机布局改变。
+
+经典布局的历史展示图（供外观参考，具体行为以上表和当前设置为准）：
+
+| 场景     | 展示图                                  |
+| -------- | --------------------------------------- |
+| 经典胶囊 | ![胶囊](../images/island-4-pill.png)    |
+| 展开详情 | ![详情](../images/island-5-clicked.png) |
+| 紧急通知 | ![紧急](../images/island-3-urgent.png)  |
+
+## 编辑自定义方案
+
+“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
+页面上方排列当前组件，右上角选择配置方案；刷新图标重置当前方案，加号新建方案，文件夹菜单提供方案设置、复制、删除及 JSON 导入导出。
+下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器，并保留班级通知、作业和叫人组件。
+从组件库拖入上方的行或容器以添加，拖动已有组件调整顺序或跨行移动；也可点击组件库添加到选中的容器或当前行。
+分别编辑常态 rows 与无消息展开 expandedRows，点选组件打开内容、外观、尺寸与隐藏条件设置；行可以新增、排序、设为主要行或删除。
+“进入编辑模式”切换为实际内容预览，支持预览缩放；退出后回到组件标签排列。轮播和滚动容器在编辑时展示全部子组件，便于选择和排列。
+倒计时可指定目标名称与日期，也可按课表倒数至上课、下课或放学。
+天气简报需填写地点名称及经纬度，使用 [Open-Meteo](https://open-meteo.com/en/docs) 的天气数据，每 15 分钟更新；断网时保留本次客户端运行中的缓存并标明“缓存”。天气提示根据天气概况生成，不提供官方气象预警。
+方案保存到本机 config.json.islandLayout，不增加服务端同步。
+编辑预览不创建额外桌面窗口；打开编辑页不自动切布局，应用后启用自定义方案。
+保存按序进行，失败可重试，主题与关怀模式沿用客户端设置。
+
+## 外观、位置与输入
+
+经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距；自定义内容根据实际测量适配工作区。
+自定义方案可配置缩放、圆角、颜色和行间距，默认值与范围在 shared/island-layout.ts。
+左右边距只在左/右停靠时生效，居中锚点仍在屏幕中线。
+触摸屏自动进入触摸模式，保留触摸命中和失焦宽限；鼠标模式按光标控制输入穿透。
+自定义常驻内容支持鼠标避让淡化及反转，交互入口、展开/编辑和触摸操作按实现暂停避让。
+应用内动画开关决定岛动画，不能用主窗口的减少动态效果说明替代岛自身规则。
+
+经典几何与配色参考见[设计令牌](../dev/winisland-design-tokens.md)，实现入口见[当前实现约定](../dev/implementation.md)。
+
+## 课程与课件
+
+准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关，课程依据服务端解析后的课表。
+
+自定义常驻岛的「课程表」组件可选「当前时间点 / 下一节课 / 今日时间点」：
+「今日时间点」显示当天全部时间点，只有当前项展开显示起止时间，其余折叠只显示课程名；
+课间休息与「默认隐藏」的上课时间点折叠时完全隐藏，轮到它们时才展开；分割线显示一条竖线，行动不显示。
+课中课程表不再常驻显示倒计时，只在最后一分钟由既有的「下课提醒」页显示「距下课还剩」；
+倒计时阈值沿用本机提醒设置（默认 60 秒）。没有时间点数据时退回按课表条目显示课程。
+经典 fixed 岛的课中提醒条保持原有倒计时行为。
+
+课件接收时显示文件名、类型、教师、字节和进度，覆盖当前固定/自定义内容；完成后校验 SHA256 并回执。
+客户端不会自动执行收到的文件，见[课件](courseware.md)。
+
+## 验证与排查
+
+默认 verify:desktop/verify:packaged 是后台快速检查，不显示岛或托盘。
+只有显式 --visual 或 verify:desktop:visual 才进行桌面像素、透明度、动画和截图验收。
+若出现多岛，先确认是否存在用户实例与显式视觉验证实例；不要把默认后台冒烟解释成可见验证岛。

docs/app/notifications.md

@@ -0,0 +1,50 @@
+---
+title: 通知与提醒
+description: 优先级、课堂确认与经典/自定义常驻模式的提醒区别。
+---
+
+# 通知与提醒
+
+Web 发布通知需 notification:publish 和班级范围权限。通知按本地 assignDate 归档，支持按日期、发布人查看与批量发布。
+服务端保存后立即广播；上课暂存与是否自动展开是客户端本机展示规则。
+
+## 优先级与本机展示
+
+共享优先级为 LOW（低）、NORMAL（普通）、HIGH（重要）、URGENT（紧急）。
+经典固定模式和自定义常驻模式有不同展示：
+
+| 场景                   | 经典 fixed                                 | 自定义 custom                          |
+| ---------------------- | ------------------------------------------ | -------------------------------------- |
+| 普通/重要/低通知、作业 | 课间显示胶囊；上课暂存，下课补弹           | 常驻内容旁提示铃铛与去重数量，点击查看 |
+| 紧急通知/紧急叫人      | 无论是否上课立即展开                       | 提示铃铛，由用户主动展开               |
+| 普通叫人               | 上课保留可点击胶囊，不自动展开；课间可展开 | 提示铃铛，可主动查看                   |
+| 主动查看               | 普通通知受课堂状态限制，叫人和紧急可点开   | 上课也可主动展开                       |
+
+经典紧急通知默认约 45 秒收起；列表与消息处理见[灵动岛](island.md)。课件传输另显示专用进度。
+
+## 课堂发布紧急通知
+
+上课时发布 URGENT，服务端先返回 409 URGENT_DURING_CLASS。
+Web 显示全屏确认和倒计时，再次请求带 confirmDuringClass:true 才放行。
+这是服务端发布校验，不受客户端选择 fixed/custom 影响；普通叫人和紧急叫人走[叫人](calls.md)的接口规则。
+
+## 已读与撤回
+
+客户端通知页有未读数，打开详情可标已读；班级会话的已读操作代表全班在读学生。
+删除需相应员工权限和范围，实时撤回会清理客户端列表、缓存与岛队列。
+同 id 的通知与叫人双播合并，不重复计数。
+
+## 接口入口
+
+以下省略 /api，均先鉴权；具体功能键及范围见[REST API](../dev/api.md)。
+
+| 方法与路径                                            | 用途                                                                  |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| GET /notifications                                    | 列表；classId、priority、unreadOnly、keyword、date/from/to、createdBy |
+| GET /notifications/days、/notifications/creators      | 日期与发布人归档                                                      |
+| GET /notifications/unread-count                       | 未读数                                                                |
+| POST /notifications、/notifications/bulk              | 单班/批量发布，批量逐班返回结果                                       |
+| POST /notifications/:id/read、/notifications/read-all | 标记已读                                                              |
+| DELETE /notifications/:id                             | 撤回                                                                  |
+
+ClassIsland 在线提醒渠道已移除；本机提醒设置不会写回旧渠道字段。

docs/app/schedules.md

@@ -0,0 +1,49 @@
+---
+title: 课表
+description: 日课表、共享作息、轮换、临时换课和教学周。
+---
+
+# 课表
+
+Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表，客户端提供“今天”时间轴和“本周”视图。
+上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
+
+编辑工作区参照 [ClassIsland 档案编辑器](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/ProfileSettingsWindow.axaml) 的课表交互实现，作为管理端内的普通页面展示，沿用全站的导航、间距、控件及浅色/深色主题。顶部切换课表、时间表、科目和调课；课表页默认进入单表编辑：左侧按课表群分组的课表列表，中间逐节选择科目，右侧切换「科目 / 课表信息」。底部仍可切换列表、周和月视图。旧管理页地址 `/schedules` 自动进入同一页面，侧栏和顶部导航始终可用。
+
+点击每天列头的「新课表」选择时间表并创建日课表。周视图点击网格中的课时后可用右侧科目按钮快速填充，支持选择是否自动移动到下一节；方向键可移动焦点，Delete 可清空选中课程。课表名称、时间表、启用星期、轮换规则、生效周次与群组在右侧「课表信息」中维护。列表视图提供批量排课、复制粘贴、拖动交换课程等操作。
+
+时间表页采用 ClassIsland 式编辑器：左侧时间表列表（新建、复制、搜索），顶部按类型添加上课、课间休息、分割线、行动，中间可在列表视图与时间轴视图之间切换，右侧编辑选中时间点，左下设置默认上课/课间时长，右下缩放。时间轴视图可按分钟拖动时间点的开始/结束把柄，并按 1 分钟取整；列表视图可拖动排序。保存仍走页面顶部「保存」或 Ctrl+S；切周与实时刷新保留草稿，切换班级和离开页面时提醒未保存的修改。
+
+上课时间点可以设置一个默认课程。日课表里**没有单独条目**的课时会回退到该默认课程；已有条目（包括显式空课）不会被覆盖。「覆盖现有课程」会把这门课写入所有引用该时间表的日课表。默认隐藏的上课时间点只在轮到时才在主界面显示；课间休息类型代表下课时间，折叠时完全隐藏，轮到它时才展开。
+
+完整档案可在页头「导入/导出」中导入或导出 JSON，保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航，点击日期后由服务端解析教学周并进入周视图。
+
+## 日课表与时间表
+
+时间表保存时间点：上课、课间、分割线、行动；日课表引用时间表，每节课程通过外键关联时间点。
+可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
+时间点排序不会改变课程关联。行动配置当前保存数据，不执行外部动作。
+
+日课表按星期、周次范围和轮换规则启用，支持 1–9 周轮换；单双周是 2 周轮换的特例，第 1 教学周为单周。
+可以预定某天使用某张表，临时换课/叠加层保留原表。相同日期的最终启用选择由服务端唯一解析器完成。
+
+## 教学周
+
+班级有自己的学期周数；全校上限由“学期周次”设置，默认 30、可设 1–60，班级不能超过该上限。
+默认班级周数为 20。管理员可在界面修改全校开学日和逐周起止区间，班级可有独立设置。
+计算优先使用班级逐周区间、再全校区间；无适用区间时按开学日线性计算。
+开学日解析还会参考第 1 周起点，环境变量 TERM_START_DATE 是兜底，具体顺序见 `lib/term.ts`。
+
+## 上课状态与提醒
+
+`GET /api/schedules/current?classId=<id>&at=<ISO时间>` 返回 inClass/current/next/week/serverTime 等状态；at 用于诊断。
+`/schedules` 是新模型的兼容门面，旧 Schedule 只保留迁移审计记录。
+经典岛普通通知上课暂存、下课补弹；普通叫人保留可点击胶囊，紧急消息立即展开。
+自定义常驻岛先显示铃铛，由用户主动查看。紧急通知在课堂发布仍需服务端二次确认。
+
+## 权限与导入
+
+日课表写入需 schedule:write，并通过管理员或本班班主任检查；时间表写入需 timetable:manage。
+离线导入完整 ClassIsland 档案可创建班级自有作息，不依赖在线联动插件。
+完整导入保留 1–9 周轮换、空课、停用、群组和预定；旧预览界面的单双周展示不代表新模型只能表达双周。
+见[表格与课表导入](imports.md)。修改后广播 schedule:updated，客户端刷新。

docs/app/toc.yml

@@ -0,0 +1,22 @@
+- name: 应用帮助
+  href: index.md
+- name: 课表
+  href: schedules.md
+- name: 作业
+  href: homeworks.md
+- name: 课件上传与传输
+  href: courseware.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,119 @@
+---
+title: REST API
+description: 现行接口分组、关键路径和权限边界。
+---
+
+# REST API
+
+API 前缀 /api，JWT 使用 Authorization: Bearer。成功/失败结构以 `lib/http.ts` 为准，
+校验错误映射 422 VALIDATION_ERROR，表格体积超限为 413 IMPORT_TOO_LARGE。
+全部挂载入口以 `modules/registry.ts` 为准；完整参数、返回类型、权限和枚举以模块的 module/schemas/service 与 shared 契约为准。
+本页列常用入口，不重复复制每条路由实现。
+
+## 身份与班级
+
+| 方法与路径（省略 /api）                                                 | 行为及边界                                                     |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
+| POST /auth/login、/auth/class-login                                     | 员工/班级登录，共享登录限流；学生无账号                        |
+| GET /auth/me；POST /auth/logout；PATCH /auth/password                   | 当前身份、退出、员工本人改密码                                 |
+| GET/POST /classes；GET/PATCH/DELETE /classes/:id                        | 班级查询/管理，读取 class:read；写入 class:manage 且仅管理员   |
+| PATCH /classes/:id/class-account、/classes/:id/head-teacher             | 班级凭据 class:account + 班主任；班主任分配仅管理员            |
+| PUT /classes/:id/subject-teachers                                       | 任课关系设置，Course 为唯一来源                                |
+| GET/PATCH /classes/:id/student-grade-query                              | 查看/修改班级个人成绩查询开关，班级端不能修改                  |
+| GET/POST /classes/:id/students；DELETE /classes/:id/students/:studentId | 本班名单及维护，受名单功能权限和班级关系约束                   |
+| /students、/teachers                                                    | 名单与账号 CRUD；读/写使用不同权限键，具体角色限制读取对应模块 |
+| POST /teachers/:id/reset-password                                       | 指定新密码或默认重置；学生无对应接口                           |
+| /permissions/me、/catalog、/groups、/users                              | 当前有效权限、目录、组与账号分组                               |
+
+## 教学与文件
+
+| 路径/动作                                                                                                  | 行为及边界                                                                           |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| /courses                                                                                                   | 班级科目与任课关系                                                                   |
+| GET /schedules、/grid、/current、/active-week                                                              | 新关系模型的兼容投影，按班级范围读取                                                 |
+| POST/PATCH/DELETE /schedules[/:id]                                                                         | 兼容 CRUD，写新模型，不双写旧 Schedule                                               |
+| POST /schedules/swap、/overlay、/scheduled；GET /schedules/scheduled；DELETE /schedules/scheduled/:id      | 换课、临时层、预定                                                                   |
+| /time-layouts；POST /time-layouts/:id/clone、/:id/import                                                   | 时间表 CRUD/克隆/导入，写入 timetable:manage                                         |
+| /class-plans；PUT /class-plans/:id/entries；PATCH /class-plans/:id/enabled                                 | 日课表 CRUD、整表保存、启用，写入 schedule:write + 班主任/管理员                     |
+| POST /class-plans/:id/clone、/class-plans/import、/class-plans/import/profile；GET /class-plans/:id/export | 复制、导入导出及完整档案导入；导入另需 import:schedule                               |
+| /class-plan-groups；GET /class-plan-groups/selection；POST /class-plan-groups/select                       | 群组及当前/临时选择                                                                  |
+| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions                                                 | 作业、批量、完成与未交；员工功能键+科目检查，班级端可录作业                          |
+| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all                 | 通知、归档和已读；发布需 notification:publish，课堂紧急须确认                        |
+| POST /calls                                                                                                | 叫人，call:create + 范围检查                                                         |
+| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目               |
+| /imports/template、/table/preview、/table/commit                                                           | 表格导入，按 kind 再检查对应导入键、管理键、班级和科目                               |
+| /imports/class-plan/preview、/imports/class-plan                                                           | 预览与提交均需 import:schedule + schedule:write；提交走关系化导入                    |
+| /imports/time-layout[/:id]、/time-layout/preview                                                           | 时间配置兼容入口，导入需 import:schedule + timetable:manage，删除需 timetable:manage |
+| GET /class-plans/profile?classId=                                                                          | 完整档案导出，按班级范围读取，保留时间点与课表关联                                   |
+| GET /courseware、/courseware/:id、/:id/download                                                            | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围                         |
+| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id               | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制                   |
+| GET/POST /courseware/folders；PATCH /courseware/:id/folder                                                 | 员工 courseware:write；目录与课件均限本人                                            |
+| GET /courseware/transfers；POST /courseware/transfers/:id/ack                                              | 班级端补领、逐设备回执                                                               |
+
+## 设备、系统与运维
+
+| 路径/动作                                                                                               | 行为及边界                                                                       |
+| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| POST /clients/heartbeat、/clients/commands/:id/ack                                                      | 登录设备心跳/回执，校验 deviceKey 和归属                                         |
+| POST /clients/update-progress                                                                           | 设备上传下载、校验、等待、安装和失败状态，校验设备班级归属                       |
+| GET /clients/devices；DELETE /clients/devices/:id                                                       | 设备读取/维护，分别检查功能键和范围                                              |
+| POST /clients/commands                                                                                  | remote:control + 对应范围，白名单动作                                            |
+| POST /clients/updates                                                                                   | client:update-push，安装策略 immediate/after-school/idle                         |
+| GET /update/check                                                                                       | 员工需 update:check；强制刷新另检查 update:force                                 |
+| GET /update/client/releases                                                                             | 缓存版本读取，按路由允许的读取权限                                               |
+| POST /update/client/fetch、/update/client/releases；DELETE /update/client/releases/:version             | 安装包写入口仅管理员 client:update                                               |
+| GET /update/client/download/:version                                                                    | 本班 CLASS_DEVICE 或 client:read + 有效班级范围                                  |
+| /term；POST /term/auto；GET /term/holidays                                                              | 学期读取/编辑/假日建议，term:read/term:write                                     |
+| GET/PUT /term/promotion；POST /term/promotion/run                                                       | 升级计划与执行，promotion:manage + 全校范围，执行要求确认与计划哈希              |
+| /archives、/archives/transferred、/archives/transferred/:id/restore                                     | 历史归档需 archive:manage 全校范围；撤回转出需 roster:manage；不提供手动创建归档 |
+| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage；目标空库、快照及换库子进程保护                                  |
+| /system/settings、/autostart、/diagnostics                                                              | system:manage，非安装形态自启动返回不可用原因                                    |
+| /ai/settings、/interpret、/audit                                                                        | ai:manage/ai:use；只解析待确认动作，密钥只进不出                                 |
+| /dashboard/summary、/dashboard/term                                                                     | 按范围读取看板与周次                                                             |
+
+探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。
+课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。
+心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。
+更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。
+
+## 权限治理与学生年度流程
+
+| 方法与路径（省略 /api）                              | 参数与权限边界                                                                                                                          |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| GET /permissions/scopes                              | permission:manage；返回可选年级、部建议和计划年级                                                                                       |
+| GET /permissions/groups/:id/members                  | permission:manage；包含显式分组及角色默认回落的生效成员                                                                                 |
+| GET /permissions/audit?page=&pageSize=               | permission:manage；分页操作人、目标、前后 JSON，pageSize 最大 100                                                                       |
+| POST/PATCH/DELETE /permissions/groups[/:id]          | 仅 ADMIN；仅可分配键，范围校验，教师默认模板固定 TEACHING，内置组不可删                                                                 |
+| PUT /permissions/users/:id/groups                    | assignments 整体替换，每项 groupId/scope/scopeValue；兼容 groupIds 按建议范围分配；空数组恢复教师默认模板；ADMIN 不可分配               |
+| GET /students?status=&includeArchived=               | roster:read；默认 active，归档单独筛选；历史状态不会再被在读条件覆盖                                                                    |
+| POST /students                                       | roster:manage；仅 active/inactive，学号重复 409，班级不得归档                                                                           |
+| PATCH /students/:id                                  | roster:manage；仅资料字段；classId/status 明确返回 400                                                                                  |
+| POST /students/transfer                              | roster:manage；studentIds、toClassId（null 表示移出）、note；跨年级需 ADMIN、allowGradeChange=true 与备注                               |
+| POST /students/transfer-out                          | roster:manage；studentIds、note、toSchool；仅 active/inactive，毕业/归档/重复转出 409                                                   |
+| POST /students/transfer-in                           | roster:manage；指定 toClassId，新建用 studentNo/name，重入用 studentId；可传 fromSchool/note                                            |
+| POST /students/:id/restore                           | roster:manage；可传 toClassId/note；转出或停用恢复，原班归档时应另选在读班                                                              |
+| POST /archives/transferred/:id/restore               | 兼容同上，权限改为 roster:manage                                                                                                        |
+| DELETE /students/:id                                 | roster:manage；默认停用；hard=true&confirm=true 仅 ADMIN，存在业务或历史则 409                                                          |
+| GET /students/transfers；GET /students/:id/transfers | roster:read；不排除转出状态；支持 studentId/classId/batchId/academicYear 与分页                                                         |
+| GET/PUT /term/promotion                              | promotion:manage 全校范围；读取计划、执行时间、应执行学年与记录；保存兼容旧 month/day/hour/classCount，也接受 plan                      |
+| POST /term/promotion/preview                         | promotion:manage 全校范围；year；只读返回逐轨道逐班统计、阻断项、警告、新班码、周次影响、planHash                                       |
+| POST /term/promotion/run                             | promotion:manage 全校范围；year、planHash、confirm:true；过去学年还须 ADMIN + catchUp:true；未来年份 400；阻断或哈希变化 409 带 details |
+| POST /classes/promote                                | promotion:manage 与各目标范围；仅 classIds，不收自由 grade；从计划推导下一学段，毕业学段 409                                            |
+| PATCH /classes/:id                                   | 不再接受 grade，旧请求返回 400；改年级须走升级入口                                                                                      |
+| DELETE /archives/:id                                 | archive:manage 全校范围；仅撤销归档标记，保留转出与停用状态，不回滚年级、新班及周次                                                     |
+
+生命周期历史以 kind 为事实源，mode 为派生兼容字段；新响应另含 batchId、academicYear、fromGrade/toGrade、fromSchool/toSchool。
+归档详情含 inactive 列表、inactiveCount 和按学生去重的 transferInCount；升级记录含 operatorId/operatorName、detailsJson、snapshotSha256、error。
+所有学生与历史写入在同一事务，提交后再广播旧班与新班。班级详情只有持 roster:read 且在对应范围内的员工才能获得学生明细。
+
+## 分配级范围与班级设置
+
+`GET /permissions/catalog` 增加 meta（kind/risk/relation/allowedScopes）。模板 DTO 的 defaultScope/defaultScopeValue/defaultScopeLabel 及兼容 scope 字段都是建议范围；kind、inactiveKeys、warnings 展示模板类别和停用键。成员 DTO 的 assignments 是实际分配，groupIds 为派生值；ADMIN fixed=true。
+
+`GET /permissions/users/:id/effective` 仅 ADMIN，返回 permissions、entries（每键 scopes/classes/classCount）、conflicts、headOnlyKeys。可选 query assignments 为 JSON 数组，预览尚未保存的整体分配；预览与实际授权共用求值器。
+
+`PATCH /classes/:id/settings` 使用 class:settings + 本班班主任（ADMIN 例外）保存 termWeeks/termStartDate。管理员 `PATCH /classes/:id` 只接收 enrollmentYear/classIndex。`PATCH /classes/:id/class-account` 使用 class:account + 本班班主任。全局周次仅管理员，带 classId 的周次写走 class:settings + 班主任。时间表写入按存储 classId 分流，班级时间表需要 schedule:write + 班主任，全校时间表仅管理员。
+
+成绩 overview/collective/exams/ranking 显式检查 grade:read，班级端由服务断言限本班并执行查询开关。设备 heartbeat/update-progress/commands/:id/ack 仅接受绑定本班的 CLASS_DEVICE，不接受教师个人设备。
+
+`GET /permissions/me` 同时返回 classScopes、manageScopes、allScopeKeys，供 Web 按钮与班级选择器显示实际能力范围；manageScopes 对名单、日课表、导入和考试配置叠加班主任或显式组织范围规则。界面范围提示不替代服务端断言。

docs/dev/architecture.md

@@ -0,0 +1,79 @@
+---
+title: 架构总览
+description: 工作区结构、模块注册、共享契约与数据流。
+---
+
+# 架构总览
+
+ClassHelper 是 pnpm workspace：Express/Prisma/Socket.IO 服务端、Vue Web 管理端、Electron 桌面客户端与共享包。
+依赖版本以根和各包的 `package.json`、`pnpm-lock.yaml` 为准。文档站和纯静态官网不在 workspace 内。
+
+## 目录与入口
+
+| 路径                                          | 职责                                        |
+| --------------------------------------------- | ------------------------------------------- |
+| `packages/shared/src/`                        | 类型、权限目录、动效、课表/岛/课件契约      |
+| `packages/server/src/app.ts`                  | 探针、限流、中间件、模块挂载、静态 Web 托管 |
+| `packages/server/src/index.ts`                | 启动、自检、HTTP、Socket.IO 与退出清理      |
+| `packages/server/src/modules/registry.ts`     | 全部启用模块的唯一注册表                    |
+| `packages/server/src/lib/`                    | 鉴权范围、日课表解析、周次、快照与系统设置  |
+| `packages/server/prisma/`                     | 单一 schema、SQLite 迁移、演示 seed         |
+| `packages/web-admin/src/router/`              | Web 路由、标题、图标、权限                  |
+| `packages/web-admin/src/config/navigation.ts` | 菜单分组，页面属性读取路由                  |
+| `packages/desktop-client/src/main/`           | 窗口、配置、岛、设备代理、更新、课件下载    |
+| `packages/desktop-client/src/preload/`        | contextBridge 白名单                        |
+| `packages/desktop-client/src/island/`         | 经典岛、自定义运行时、课程与课件提醒        |
+| `packages/desktop-client/src/renderer/`       | 主窗口页面、状态、IndexedDB 与岛桥接        |
+| `scripts/` / `deploy/`                        | 验证、版本、打包、部署与运维                |
+| `docs/` / `website/`                          | 文档站与官网，Pages 构建时拼接              |
+
+## 模块与数据流
+
+功能模块使用 `*.module.ts` 路由、`*.schemas.ts` 校验、`*.service.ts` 业务；新增/下线改 `registry.ts`。
+注册表包含教学业务、课件、日课表/时间表/群组、权限、客户端、系统、AI、升级和数据管理模块。
+路由与模块总数直接读取注册表，不在文档复制另一份数组。
+
+教师在 Web 提交 → 服务端校验权限、班级和科目范围 → 写数据库 → 事件总线按房间广播 → Web/客户端刷新。
+客户端先维护 IndexedDB 缓存，断网读取缓存；主窗口通过 preload 与主进程通信，主进程管理唯一原生岛窗口。
+课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。
+
+客户端统一更新由服务端缓存安装包、校验设备权限并通过心跳下发。客户端下载并校验 SHA256 后，
+把安装交给独立的 Windows 原生助手；助手从本机 `updates` 目录运行，再次验包并确认就绪，
+主进程复核更新策略后才退出。助手等待旧进程结束、执行安装并检查安装版的新版本及启动状态，
+失败写入 `install-result.json` 并尝试恢复客户端；成功仍以新版心跳为最终回执。
+排障日志为同目录下的 `install-helper.log`。Windows 构建使用系统 .NET Framework 编译器生成助手，
+教室机运行时不需要安装开发工具；助手与安装包均随客户端构建，不能只替换主进程 JS。
+
+更新专项验证使用 `pnpm verify:update-download`、Windows 下的 `pnpm verify:update-installer`。
+显式执行 `pnpm verify:client-update:real` 会创建临时数据库、班级和独立应用标识，真实安装并升级
+测试副本，再卸载测试安装，报告保存在 `.cache/client-update-real/`；它不属于普通冒烟，
+不会使用真实班级或桌面自动化，也不修改根版本号。
+传入 `--portable --unicode-paths --prefix-version` 可覆盖便携运行转安装版、中文空格路径和带 `v` 的目标版本号。
+
+## 工程边界
+
+- 三端契约只放 shared，改后先 `pnpm build:shared`。
+- 学生不是账号；班级会话读取 `Class`，教师/管理员读取 `User`。
+- 功能权限在路由判定，范围与科目权限在 service 判定；前端同规则隐藏入口。
+- 课表以关系模型为真值，所有在线启用选择走 `lib/class-plan.ts`；周次走 `lib/term.ts`。
+- 作业/通知使用本地 `assignDate`；实时使用 `SOCKET_EVENTS/SOCKET_ROOMS` 和 `emitToClass/emitToSession`。
+- 数据库备份清单随模型维护，课件文件另行备份。
+- Electron 保留 CSP 与导航限制，桥接只传纯数据；打包凭据门禁不能取消。
+- ClassIsland 在线联动已退役，仅保留离线 JSON 导入与设计参考。
+
+完整规则见 [AGENTS.md](https://github.com/LoveChengke/ClassHelper/blob/master/AGENTS.md)。
+
+## 开发启动
+
+```bash
+pnpm install
+# 复制 packages/server/.env.example 为 .env，并配置独立 JWT_SECRET 与数据库
+pnpm db:generate
+pnpm --filter @classhelper/server db:deploy
+pnpm build:shared
+# 只有明确需要重建演示数据时才运行 pnpm db:seed（会清空业务表）
+pnpm dev
+```
+
+后端 4000、Web dev 5173、桌面 dev 5174、官网 5180、文档预览 5181。
+生产服务端托管已构建的 Web 管理端；详见[安装服务端](../get-started/server.md)和[验收](testing.md)。

docs/dev/data-model.md

@@ -0,0 +1,95 @@
+---
+title: 数据模型
+description: 现行模型职责、迁移与快照边界。
+---
+
+# 数据模型
+
+模型定义以 `packages/server/prisma/schema.prisma` 为准，迁移以 `prisma/migrations/` 为准。
+仅维护一份 schema，SQLite/MySQL 切换改 provider；不使用 Prisma enum 和 `@db.*`。
+
+## 模型职责
+
+| 模型                   | 职责                                                |
+| ---------------------- | --------------------------------------------------- |
+| `User`                 | 教师与管理员账号；学生不在此表，班级凭据在 Class    |
+| `Student`              | 学生名单、学号、在读/转出/毕业状态，无密码和角色    |
+| `StudentClassTransfer` | 生命周期历史，kind/batchId/学年/班级年级及学校快照  |
+| `ArchivedYear`         | 毕业届别与统计快照                                  |
+| `TermWeek`             | 逐周日期区间，classId 空串为全校默认                |
+| `Class`                | 班级、班级码/密码、班主任、周数与成绩查询开关       |
+| `Course`               | 班级+科目+教师任课关系，含简称和室外标记            |
+| `Schedule`             | 旧课表迁移审计来源，现行接口不再以它为业务真值      |
+| `Homework`             | 作业与本地 assignDate；dueAt 为遗留列               |
+| `HomeworkStatus`       | 按 studentId 记录作业完成状态                       |
+| `Notification`         | 通知/叫人记录、优先级与本地 assignDate              |
+| `NotificationRead`     | 按 studentId 记录已读                               |
+| `TimeLayout`           | 共享或班级自有时间表；旧 items JSON 保留迁移审计    |
+| `Grade`                | studentId、课程、考试、分数和等级                   |
+| `PermissionAudit`      | 权限与人工升级审计，操作人和前后 JSON，不建账号外键 |
+| `PermissionGroup`      | 岗位模板与建议 scope/scopeValue                     |
+| `PermissionGroupItem`  | 组内权限键                                          |
+| `UserPermissionGroup`  | 账号与模板的分配及实际 scope/scopeValue             |
+| `AppSetting`           | 周次、升级、AI 和系统设置                           |
+| `ClientDevice`         | deviceKey、心跳、更新目标与状态                     |
+| `ClientCommand`        | 白名单远控、有效期与执行回执                        |
+| `ClientRelease`        | 服务端缓存安装包、SHA256 与大小                     |
+| `AiAudit`              | 助手解析审计，不保存 API Key                        |
+| `Exam`                 | 考试名称与是否计入总分                              |
+| `TimeLayoutItem`       | 有序时间点及类型，被课程显式引用                    |
+| `ClassPlanGroup`       | 班级课表群组、全局/默认标记                         |
+| `ClassPlan`            | 日课表、时间表、轮换、启用与临时层规则              |
+| `ClassPlanEntry`       | 日课表与时间点、课程的外键关联、空课/停用/换课标记  |
+| `ScheduledClassPlan`   | 按本地日期预定日课表                                |
+| `PromotionRun`         | 年度升级幂等与审计                                  |
+| `Courseware`           | 文件元数据、上传教师、存储路径与 SHA256             |
+| `CoursewareFolder`     | 教师自建分类目录，按上传者隔离                      |
+| `CoursewareVisibility` | 课件可见班级                                        |
+| `CoursewarePush`       | 按班级的推送任务                                    |
+| `CoursewareReceipt`    | 按设备的课件接收回执                                |
+
+学生和账号分离：Student 没有密码/角色；教师/管理员存 User，CLASS_DEVICE 只是 Class 登录形成的会话。
+任课关系只在 Course；班主任关系在 Class.teacherId，可以与任课关系指向同一账号。
+课表真值是 ClassPlan/ClassPlanEntry/TimeLayoutItem，旧 Schedule 与 TimeLayout.items 不再参与现行业务写入。
+周次口径见[课表](../app/schedules.md)，成绩限制见[成绩](../app/grades.md)。
+
+## 迁移与启动
+
+不要删除或重写已应用的 SQLite 迁移目录。源码开发使用 `pnpm --filter @classhelper/server db:deploy`。
+安装形态由 `lib/db-bootstrap.ts` 执行启动迁移，账本 `_ch_migrations` 记录已执行目录。
+升级迁移包含学生表拆分、联动退役、关系化课表、权限范围、年度升级和课件表；具体顺序读取 migrations。
+历史学生迁移中的 STUDENT 只用于搬运旧数据，不是现行账号角色。
+MySQL 建模走受支持的换库流程，不能直接执行 SQLite SQL，详见[MySQL](../management/mysql.md)。
+
+## 快照与文件
+
+`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 是备份/导入/跨库迁移表清单，按依赖顺序导出，恢复阶段临时关闭外键检查并分批写入。
+模型新增或删除必须同步此清单；不要在文档复制固定表数。
+JSON 快照包含课件元数据、可见范围、推送与回执，**不含文件实体**；完整备份需带上课件目录。
+User.careMode 是预留列；当前 Web 偏好在 localStorage，客户端偏好在本机 config.json，不宣称已有跨设备同步。
+
+## 修改模型时
+
+1. 同步 schema、迁移、shared 契约、服务层、相关前端与快照清单。
+2. 核对外键级联与删除护栏，特别是教师的班级、课程、作业、通知和课件。
+3. 在临时库验证新建和旧库升级；不对真实业务库运行 seed/reset。
+4. 重新生成 Prisma Client，并按修改范围执行[验收](testing.md)。
+
+## 权限与生命周期迁移
+
+`20261023000000_promotion_permission` 为已初始化的 ADMIN 默认组补 promotion:manage；默认组尚未创建时允许不插入，由运行时模板创建。
+`20261023010000_student_lifecycle_audit` 增加 PermissionAudit、StudentClassTransfer 的批次/学年/班级年级/学校快照、ArchivedYear.inactiveCount、PromotionRun 的操作人/明细/摘要/错误。
+旧 mode 按 single/batch → class-change、transfer-out → transfer-out、restore-transfer → restore 迁移后删除该列，避免双事实源。
+旧行的新字符串为空，学年为空，统计默认零；不臆造无法恢复的历史年级或批次。
+
+SNAPSHOT_TABLES 已加入 PermissionAudit，新增字段随模型导出。旧快照没有审计表可恢复为空，旧历史 mode 在恢复时转为 kind；
+没有新增列的旧行使用 schema 默认值。执行记录与升级快照不自动清理。
+升级计划存 AppSetting.term.promotionPlan，时间存 term.promotionAt，无需新增学校或学生账号模型。
+
+## 授权分配迁移
+
+`20261031000000_authz_assignments` 为 UserPermissionGroup 增加 scope（默认 TEACHING）与 scopeValue。先按旧模板范围回填分配，再将模板 SELF_CLASS/空值和 SELF_CLASS/HEAD 规范为 TEACHING/HEAD。教师默认模板建议范围固定 TEACHING；旧 ADMIN 默认模板与旧管理员专用键保留在库中，由运行时忽略。
+
+同一成员可将同一模板分配到多个范围，唯一约束为 userId/groupId/scope/scopeValue。PermissionGroup 的范围列仅作建议，不参与已有分配求值。
+
+快照表集合和版本 1 保持兼容。恢复旧模板时映射 SELF_CLASS；旧 UserPermissionGroup 没有范围列时按快照内对应模板推导，缺组回落 TEACHING。新快照按实际分配列恢复。真实库升级前先备份快照，隔离回归不替代真实库升级演练。

docs/dev/implementation.md

@@ -0,0 +1,54 @@
+---
+title: 当前实现约定
+description: 课表、周次、学年、岛、设备与课件的现行实现入口。
+---
+
+# 当前实现约定
+
+本页维护当前工作区的实现契约，不汇总多批构建的验收数字。验证命令与实际范围见[验收与测试](testing.md)。
+
+## 关系化课表
+
+`ClassPlan/ClassPlanEntry/TimeLayoutItem` 是业务真值。时间点外键独立于排序，`Schedule` 与旧 JSON 列仅保留迁移审计来源。
+兼容 `/schedules` 写入新模型，日课表、周视图和上课状态共用 `lib/class-plan.ts`。
+解析顺序是预定、当日临时课表、同日临时层、有效临时群/选定或默认群的规则匹配、全局群、无群默认。
+轮换使用 weekday/weekCountDiv/weekCountDivTotal 与周次范围，支持 1–9 周；没有新增 Profile 实体。
+完整档案导入直接保留轮换、空课、停用、时间类型、群组与预定，不经过单双周中间格式。
+旧数据同班同日同周同时间冲突仅最小 id 进入新表，旧行保留；缺失的历史群组、临时层与时间点名称无法恢复。
+
+## 权限、成绩与年度升级
+
+能力、分配范围、业务关系统一由 lib/authz 的 principal/scope/relations/assert 维护；access 只提供带显式键的窄封装。ADMIN 固定全集，TEACHER 过滤管理员专用键。
+全校周数上限在 `term.maxWeeks`，默认 30、允许 1–60；开学日和逐周区间支持全校与班级设置。
+个人成绩查询关闭后只返回服务端集体聚合，个人明细、原始全班成绩与排名拒绝读取；样本不足或稀疏分段抑制。
+年度升级由 `term.promotionPlan`、`term.promotionAt` 和 `PromotionRun.year` 管理，先存快照；运行期到点执行，启动漏跑需管理员预览补跑。
+毕业班归档，其余升一级，新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。
+
+## 岛与本机配置
+
+方案存 `config.json.islandLayout`，默认 fixed。当前 custom 即常驻，归一化将兼容字段 residentEnabled 与 custom 对齐。
+`LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`，只有一个原生岛窗口。
+自定义常态行与无消息展开行独立编辑，通知列表复用 `ClassicNotifications.vue`；编辑页是主窗口设置子路由。
+自定义模式通过铃铛提示新消息，点击查看；经典模式普通通知上课暂存、普通叫人可点开胶囊、紧急消息自动展开。
+课程提醒配置独立保存，课件传输期间由 `CoursewareTransfer.vue` 显示进度。
+
+## 设备维护与文件
+
+设备心跳和命令只走 `/api/clients/*`。切服务端或登录状态变化要重置代理计时，并隔离迟到响应；deviceKey 不变。
+更新从服务端缓存下载，客户端验 SHA256，按下发策略安装；远控白名单动作执行后回执，测试只用假执行器。
+课件上限 512 MB，服务端流式落盘后创建元数据和推送，客户端逐设备验摘要并回执，不自动运行文件。
+JSON 快照含课件表，完整恢复还必须带文件实体目录。细节见[课件](../app/courseware.md)。
+
+## 学生与权限写入契约
+
+学生状态/班级写入口集中在 `lib/student-lifecycle.ts`，班级名单添加/移出、名单导入、转出和转入均复用它。
+资料 PATCH 不承担状态或班级迁移。学生与历史在事务内提交，UUID 标识批次，事务后广播两端班级，历史读取不附带在读过滤。
+权限、功能对应范围、业务关系依次断言；权限只在当前请求对象上复用，下一请求重新计算。
+范围解析在 shared，实际范围存分配记录，模板范围仅作新分配建议。各键独立合并，无键为空集；默认教师范围固定 TEACHING。
+权限组或成员分配与 PermissionAudit 同事务，成员权限一次预取计算。
+
+年度升级服务由计划推导所有轨道的下一学段。预览哈希覆盖配置、班级、学生和周次，执行事务内重新计算；
+先保存全库快照并计算 SHA256，再以年份唯一键提交升级。毕业班所有状态挂届别，非毕业班仅升级及清班级开学日覆盖。
+周次是否清空由计划决定，预览公开影响。服务保留 runPromotion(year, dryRun) 内部兼容签名；HTTP 执行必须提供哈希、确认并检查年份。
+
+实时班级事件按 core/homework/notification/grade/courseware 分房间，事件总线按 shared 映射选择通道，教师仅订阅对应读键范围。HTTP 与 Socket 握手共用数据库身份加载；敏感权限与账号变更使旧订阅失效。事务路径传递同一数据库连接给授权断言，保留原/目标资源的校验。

docs/dev/index.md

@@ -0,0 +1,51 @@
+---
+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`         | 三端共用的类型 / 常量 / 权限 / 工具函数                         |
+
+核心链路：
+
+```
+教师在 Web 端发布内容
+        │  REST API（JWT 鉴权）
+        ▼
+   后端服务（Express + Prisma）
+        │  写库 + 按班级房间广播
+        ▼
+ Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI（含灵动岛）
+
+                                  ▲                          │
+                                  └──── 老师下发的提醒 ◄──────┘
+```
+
+## 这一章有什么
+
+| 页面                                         | 内容                                             |
+| -------------------------------------------- | ------------------------------------------------ |
+| [架构总览](architecture.md)                  | 目录结构、技术栈、模块化设计、几条贯穿全局的约定 |
+| [REST API](api.md)                           | 接口分组、常用路径与权限边界                     |
+| [实时事件（Socket.IO）](realtime.md)         | 事件清单、房间规则、新增事件要改哪三处           |
+| [数据模型](data-model.md)                    | 模型职责、迁移与快照边界                         |
+| [角色与权限](permissions.md)                 | 权限矩阵与实现位置                               |
+| [动效层与主题](motion.md)                    | beUI 令牌、CSS `linear()` 弹簧、深色主题         |
+| [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token                 |
+| [验收与测试](testing.md)                     | 隔离验收、后台冒烟与显式视觉模式                 |
+| [版本迭代与发布](release.md)                 | 改版本号、出安装包、发 Release 的完整流程        |
+
+## 仓库里另外两份文档
+
+- **[功能与源码索引](../reference.md)** —— 各帮助章节与源码入口的统一索引；功能行为在对应章节维护，按源码核验。
+- **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
+  工程约定与开发环境注意事项，**改代码前必读**。里面每一条硬约定都对应一处容易踩空的地方，
+  规则与实际实现冲突时应查源码并同步修正。

docs/dev/motion.md

@@ -0,0 +1,138 @@
+---
+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：从点击位置扩散的圆整页换肤                                                |
+| 灵动岛                | 独立 SpringValue 帧积分与过冲钳制，见设计令牌                                                  |
+
+### 灵动岛使用独立弹簧
+
+经典与自定义岛的形变使用 `src/island/spring.ts` 的 SpringValue，渲染层驱动岛体几何，主进程管理原生窗口与命中。
+它与 shared/motion.ts 的 CSS 弹簧是不同实现，不能互相替换参数。默认阻尼、换向与过冲钳制见[设计令牌](winisland-design-tokens.md)。
+岛动画由应用开关及可见性控制，主窗口 prefers-reduced-motion 规则不直接替代岛自身设置。
+
+另外岛的 `: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,76 @@
+---
+title: 角色与权限
+description: 能力目录、岗位模板、分配范围与业务关系的授权契约。
+---
+
+# 角色与权限
+
+授权依次检查能力、该能力的数据范围、数据行上的业务关系。服务端统一入口为 `lib/authz/`，路由预检不能替代服务断言。共享目录 `PERMISSION_META` 提供分类、风险、关系提示、合法范围、标签和默认角色；完整键目录读取源码，不在文档维护固定数量。
+
+## 身份与模板
+
+| 主体                 | 生效能力                                           |
+| -------------------- | -------------------------------------------------- |
+| ADMIN                | 固定拥有全部目录键及全校范围，忽略权限组           |
+| TEACHER              | 显式分配模板的可分配能力并集；管理员专用键永久无效 |
+| 未显式分配的 TEACHER | 数据库教师默认模板与固定 TEACHING 范围             |
+| CLASS_DEVICE         | 空集；接口明确允许班级端并校验本班关系             |
+
+学生是 Student 名单记录，没有账号。HEAD/SUBJECT 是班主任和科任关系，级长/部长是岗位模板，不增加 User.role。权限管理只允许 ADMIN；旧 ADMIN 默认模板保留存储但隐藏、忽略。
+
+`PermissionGroup` 保存能力和新分配的建议范围，`UserPermissionGroup` 保存实际 `scope/scopeValue`。模板改建议范围不会改变已有分配；模板改能力会影响其成员。同一模板可分配不同范围，多条分配按键取并集。空分配恢复默认模板，界面不会将未分组成员自动转换成显式默认组。
+
+## 能力目录与范围
+
+能力分为管理员专用、班级级、组织只读。管理员专用能力包括组织与账号维护、权限/系统/数据库、全局周次、全校时间表、升级归档、安装包管理等；具体清单以 `PERMISSION_META.kind` 为准。`teacher:read` 和 `update:check` 为组织只读，忽略班级范围。其余班级级能力按分配范围求值。
+
+| 范围     | 语义                       |
+| -------- | -------------------------- |
+| TEACHING | 本人担任班主任或任课的班级 |
+| HEAD     | 仅本人担任班主任的班级     |
+| GRADE    | 指定一个年级               |
+| DIVISION | 指定多个年级               |
+| ALL      | 全校                       |
+
+`parsePermissionScope` 统一校验范围。GRADE/DIVISION 必须选择已有年级或升级计划中的年级，范围值按逗号分隔、去重排序；其余范围值必须为空串。旧 SELF_CLASS 仅在迁移和旧快照恢复中映射为 TEACHING/HEAD，不是运行时枚举。
+
+`loadAuthPrincipal` 在请求主体上缓存只读能力和分配快照，没有可变的“当前权限键”。`classIdsFor(user, key)` 和 `classWhere(user, key)` 强制传键，无键或无授权返回空集合；不会合并其他能力的范围。`classWhere` 过滤 Class 表主键，下游子表使用明确的 classId 条件。
+
+## 关系与写入
+
+| 操作                                          | 功能与关系                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------------------- |
+| 建班/删班/届别班号、班主任/任课分配、教师账号 | 管理员专用，记录审计；最后一个管理员不可降级或删除                               |
+| 班级账号                                      | class:account + 本班班主任，管理员例外；班级码只给班主任或管理员                 |
+| 班级学期设置/班级周次                         | class:settings + 本班班主任，管理员例外                                          |
+| 名单、日课表与课程写入                        | 对应写键；TEACHING/HEAD 要求班主任，显式年级/部/全校范围允许范围内维护           |
+| 学生/课表导入                                 | 导入键与相应写键同时满足；先校验全部班级再写，学生及任课导入使用事务             |
+| 班级时间表写入                                | schedule:write + 本班班主任；按存储 classId 校验，所有引用班级也要校验           |
+| 全校时间表、全局周次                          | 管理员；班级设置使用独立接口                                                     |
+| 作业/成绩写入                                 | assertContentWrite；有科目要求该科任教，无科目要求班主任；原科目与目标科目都检查 |
+| 作业提交/未交名单                             | homework:write + 同样的科目关系；班级端明确允许本班作业                          |
+| 通知/叫人                                     | 发布能力和范围，再检查班主任/任课关系；班级端限本班                              |
+| 通知删除                                      | notification:delete + 发布者/班主任/管理员                                       |
+| 课件                                          | 本人文件、对应功能范围与本人授课班级共同约束，不赋予班主任同事文件访问权         |
+
+ALL 也不能替代班主任、任课、发布者关系，只有 ADMIN 无条件绕过关系。班级端可代录作业，不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接，不能因事务路径省略授权。
+
+成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后，本班设备仍可获得集体聚合，个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护，服务端执行稀疏样本和补集抑制。
+
+## 实时与设备
+
+班级房间为 `class:{id}:{channel}`，事件映射见 `SOCKET_EVENT_CHANNELS`。班级端加入本班全部通道；教师按各域读键及范围加入，core 由 class:read/schedule:read 决定。显式订阅再次校验通道，握手与 HTTP 共用数据库身份加载；权限/账号变更断开旧订阅。
+
+心跳、进度和命令回执只接受 CLASS_DEVICE，deviceKey 必须属于会话班级。远控只排队允许的系统指令，自动化始终假执行。安装包登记/删除使用管理员 client:update；班级推送使用 client:update-push。下载要求本班班级端或有范围的 client:read。版本与文件名在请求校验和路径构造两处拒绝不安全路径段。
+
+## 权限页与审计
+
+权限页默认展示成员与范围，每条分配独立选择范围，保存前预览新增/移除能力、每键合并范围、班级列表、混合范围提示、班主任专属提示和风险标记。模板页仅提供可分配能力，旧管理员键显示为停用。组织只读能力标注“不限班级”。路由用 `meta.permission` 检查读取能力；维护页面额外用 `meta.menuActions` 声明可执行动作，动作须在至少一个可读班级生效才显示侧栏、搜索及页签，有部分功能可操作就保留入口。`permissions/me.actionScopes` 结合范围和班主任、任课、发布者关系提供动作班级；班级管理动作另用 `manageScopes`。纯查看页面按读取能力展示，服务端始终做最终判定。
+
+学期周次维护入口要求全校周次写能力或至少一个可维护的本班设置范围。非全校维护者进入后默认选择可编辑班级，仍可切换查看授权范围内的其他班级。
+
+目录、模板、成员、分配预览和审计的公开契约见[API](api.md)。模板/分配和账号敏感操作写入 PermissionAudit；审计不保存密码明文或哈希。迁移与快照兼容见[数据模型](data-model.md)。
+
+## 验证
+
+`pnpm check:authz` 扫描旧授权符号和缺少显式键的查询，并接入 lint。`pnpm verify:authz` 使用临时 SQLite 验证接管班级、管理员提权、跨键借范围、科目改挂、跨班时间表/周次/导入、成绩隐私、通道订阅、设备冒用和旧快照等攻击场景。其他专项回归保留生命周期、课表、课件、设备与升级覆盖。验证不触及真实班级、不访问外网、不执行系统指令。

docs/dev/realtime.md

@@ -0,0 +1,52 @@
+---
+title: 实时事件（Socket.IO）
+description: 实际事件与房间、断线恢复和客户端提醒分工。
+---
+
+# 实时事件（Socket.IO）
+
+连接使用 `io(url, { auth: { token } })`，服务端握手校验 JWT 并与 HTTP 共用数据库身份加载。
+事件与房间定义在 shared 的 `constants.ts`，载荷类型在 shared 的 `types.ts`，以这些契约和发送点为准。
+
+## 房间与定向推送
+
+| 房间                      | 作用                                               |
+| ------------------------- | -------------------------------------------------- |
+| class:{classId}:{channel} | 某班级对应读域的业务广播                           |
+| session:{id}              | 会话定向名；员工 id 为账号 id，班级端 id 为班级 id |
+| role:{role}               | 角色房间名，定义在共享常量                         |
+| teacher:{id}              | 教师房间名，定义在共享常量                         |
+| students                  | 班级端连接的广播房间，代表全班，不是个人学生账号   |
+| teachers                  | 教师和管理员连接的广播房间                         |
+
+`realtime/socket.ts` 按域加入授权班级房间，并加入 session/role 与 students/teachers 房间；connected 载荷列出实际已加入房间。
+业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。
+叫人记录属于班级通知，并发送班级广播与班级会话定向事件；学生本身没有连接和个人房间。
+
+## 主要事件
+
+| 事件                                              | 内容                                                       |
+| ------------------------------------------------- | ---------------------------------------------------------- |
+| connected                                         | `{ sessionId, role, rooms }`                               |
+| notification:new / notification:deleted           | 通知新增/撤回；客户端同步列表、缓存和岛队列                |
+| homework:new / homework:updated / homework:status | 作业新增、修改/删除与完成状态                              |
+| grade:updated                                     | 成绩变化通知；载荷按范围与隐私规则发送，客户端按需重新读取 |
+| schedule:updated / class:updated                  | 课表/班级变化，重新加载对应数据                            |
+| courseware:changed                                | 课件列表/可见范围/推送变化，触发客户端检查                 |
+| client:release-progress                           | 服务端缓存客户端安装包的进度                               |
+| call:new                                          | 叫人内容，与 notification:new 按同 id 合并去重             |
+| class:join / class:leave / ping                   | 客户端订阅/离开班级、探活；join 重新校验范围               |
+
+事件没有持久离线消息队列保证。重连后由页面和恢复钩子重新拉取业务数据。
+普通通知上课暂存是客户端岛控制器的本机行为，服务端仍即时落库广播；
+断线通知补弹由客户端未读读取逻辑处理，课件未收任务由服务端保存、客户端心跳补领。
+经典/自定义模式的展示差异见[通知与提醒](../app/notifications.md)。
+
+## 修改事件
+
+同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。
+不要手写事件名；只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。
+
+## 读域订阅
+
+现行班级房间为 `class:{id}:{channel}`。channel 为 core/homework/notification/grade/courseware，事件映射来自 shared 的 SOCKET_EVENT_CHANNELS。旧 `class:{id}` 仅保留兼容名称，生产不订阅。班级端加入本班全部域；教师按对应读键和分配范围加入。`class:join` 接受旧 classId 字符串或 `{classId, channels}`，后者逐通道校验，有任一无权则拒绝整次请求。握手回查账号与角色，权限变更断开旧订阅。

docs/dev/release.md

@@ -0,0 +1,83 @@
+---
+title: 版本迭代与发布
+description: 版本单一来源、本地与发布文件名、验证和发布同步。
+---
+
+# 版本迭代与发布
+
+日常文档/代码维护不自动改版本。版本唯一修改入口是 scripts/version.mjs；先执行 pnpm version:check。
+正式新发布执行 pnpm version:bump patch|minor|major，指定固定版本的本地重构建保持版本不变。
+版本落点由脚本清单决定，不另维护“文件数/落点数”。
+
+## 构建与验证
+
+```bash
+pnpm version:check
+pnpm lint
+pnpm typecheck
+pnpm check:icons
+pnpm docs:check
+pnpm verify:e2e
+pnpm verify:v14
+pnpm verify:courseware
+pnpm build:desktop
+pnpm verify:desktop
+pnpm --filter @classhelper/web-admin build
+pnpm verify:web:isolated
+pnpm dist:all
+pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe" --offline
+```
+
+以上按发布改动范围执行；显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
+完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本，最新包核验完成后按用户要求清理旧归档。
+2026-10-18 工作区清理后，1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
+
+## 产物与文件名
+
+| 本地构建产物                                                                | GitHub Release 上传名                      |
+| --------------------------------------------------------------------------- | ------------------------------------------ |
+| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-setup.exe              | ClassHelper-<版本>-x64-client-setup.exe    |
+| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe           | ClassHelper-<版本>-x64-client-portable.exe |
+| releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe       | ClassHelper-<版本>-x64-server-setup.exe    |
+| releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz | 同名                                       |
+
+Windows 服务端安装包只携带配置占位符，首次安装时生成独立的 JWT 密钥；覆盖升级保留原有 `.env`。`pnpm verify:server-bootstrap` 验证密钥独立性和配置保留，打包后还需在解包副本中复验。
+
+Linux 还需同名 .tar.gz.sha256。正式 Linux 包在 Linux runner 运行 pnpm dist:server:linux；
+Windows 上的交叉构建仅作验证，可能缺目标平台的 Prisma engine。
+构建中间物可再生成，不将 win-unpacked、server staging 或解包副本当交付物保留。
+
+## 更新日志与校验
+
+releases/ReleaseNotes-<版本>.md 维护本批包的功能、升级须知、实际验证范围与文件清单。
+它描述该构建批次，不能把之后的源码功能写成旧包已经包含。
+SHA256SUMS-<版本>.txt 用上传名记录各文件哈希；本地查验必须先按上表映射，不能因为本地文件没带 client/server 后缀就判断丢包。
+可在 PowerShell 对 client/server 安装包运行 Get-FileHash -Algorithm SHA256，将三项实际结果按上传名写入清单。
+不要仅对客户端目录做重定向而漏掉服务端；Linux 行待 CI 完成后同步。
+
+## 发布同步
+
+完成验证和本地更新日志后，检查 diff，按用户授权提交和推送 master；不要把其他未完成改动一并提交。
+将三个 Windows 包复制到独立的 .cache/release-staging/<版本>/，使用上传名，避免通配符混入别的版本。
+先准备当前 Windows SHA256 清单并随 Release 上传。创建 Release 时显式 --target master 或明确提交，说明用 --notes-file。
+ClassIsland 插件已退役，不再上传插件资产。
+
+```bash
+# <版本> 和提交均替换为本次实际值
+gh release create v<版本> --target master --title "ClassHelper v<版本>" --notes-file releases/ReleaseNotes-<版本>.md
+gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256SUMS-<版本>.txt
+```
+
+推送 v* tag 触发 release-linux-server.yml，按 tag 检出，在 Ubuntu 构建并上传 Linux 包、独立 .sha256，合并跨组件清单。
+等待 Actions 成功，再下载 Linux 文件和最终 SHA256SUMS 同步回本地；检查清单的 Windows 行仍与本次文件一致。
+如需重跑，可手动运行该 workflow，指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
+
+官网和文档站由 pages.yml 拼装同一个站点：官网根、文档 /docs/。文档版本徽标读根 package.json，
+官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线，分别确认结果。
+官网行为变化同步 README 与相应帮助章节，功能索引放[源码索引](../reference.md)。
+
+## 已发布版本与回滚
+
+已公开且用户安装的版本建议发补丁版本修复，避免同号不同内容使更新缓存/忽略版本与摘要失配。
+用户明确要求固定版本重构建时，按要求保持版本，并清楚区分本地包和远端资产；不自动改远端 tag/Release。
+仅说明或文档错误直接修改说明/文档；线上故障按对应部署形态从完整备份恢复。

docs/dev/testing.md

@@ -0,0 +1,76 @@
+---
+title: 验收与测试
+description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
+---
+
+# 验收与测试
+
+按改动范围选择验证；数量和结果读取本次输出，不沿用历史报告数字。
+默认客户端冒烟为后台快速模式；动画、透明度、桌面截图必须显式视觉模式。
+
+## 命令与前置条件
+
+| 命令                                             | 覆盖/前置条件                                                                |
+| ------------------------------------------------ | ---------------------------------------------------------------------------- |
+| pnpm lint / pnpm typecheck / pnpm check:icons    | 静态检查；typecheck 会先构建 shared                                          |
+| pnpm docs:check                                  | docfx 严格构建，需 .NET SDK 与 docfx                                         |
+| pnpm verify:e2e                                  | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务            |
+| pnpm verify:web:isolated                         | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物                         |
+| pnpm verify:web                                  | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务                |
+| pnpm verify:lifecycle                            | 临时 SQLite 验证权限治理、事务故障回滚、状态机、历史、多轨道、计划哈希和快照 |
+| pnpm verify:v14                                  | 临时库验证关系课表、周次、范围、隐私与升级等                                 |
+| pnpm verify:courseware                           | 临时库和文件目录的课件专项，不向真实班级推送                                 |
+| pnpm verify:client-agent                         | 假系统适配器验证命令、回执和更新策略                                         |
+| pnpm verify:client-migrations                    | 临时旧库验证迁移、联动退役与默认组持久化                                     |
+| pnpm verify:review-client                        | 无窗口逻辑回归                                                               |
+| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数                    |
+| pnpm verify:desktop                              | 先 pnpm build:desktop；隐藏快速检查，独立 userData                           |
+| pnpm verify:desktop:online                       | 显式联网，需要测试管理员并创建临时教师/班级                                  |
+| pnpm verify:desktop:visual                       | 显式使用桌面，完整岛几何/动画/透明度/截图检查                                |
+| pnpm verify:packaged --exe <客户端EXE>           | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面                   |
+
+联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
+开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
+不得回退到真实班级、重置真实密码或向真实班级发测试通知；远控与安装器使用假执行器。
+桌面进程超时和失败日志先定位，不能因为一个历史脆弱用例名称就断言当前失败必然正常。
+
+## 常用检查顺序
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm check:icons
+pnpm docs:check
+pnpm verify:e2e
+pnpm verify:v14
+pnpm verify:lifecycle
+pnpm verify:client-migrations
+pnpm verify:courseware
+pnpm build:desktop
+pnpm verify:desktop
+pnpm --filter @classhelper/web-admin build
+pnpm verify:web:isolated
+```
+
+仅文档修改只需格式、链接与 docs:check；不因此重打包或占用桌面。
+改打包/运行时裁剪还要构建实际副本并跑 packaged；Linux 交付修改需 Linux 真机/CI 验证和 bash 语法检查。
+
+## 故障定位
+
+- 临时服务失败查 .cache/v14-verification 下本次日志；不要改业务 .env 或密码迁就测试。
+- 显式联网管理员变量：桌面 ELECTRON_SMOKE_ADMIN/ELECTRON_SMOKE_ADMIN_PASSWORD，Web UI_SMOKE_ADMIN/UI_SMOKE_ADMIN_PASS。
+- 视觉用例需要真实桌面与稳定帧，先区分状态未稳定、窗口遮挡和实际回归，再针对原因重跑。
+- Element Plus dialog 关闭后 DOM 仍保留，应检查 overlay 的可见状态。
+- 本地 HTTP 探测绕过代理；Prisma 生成物和 shared/dist 缺失时先补前置构建。
+
+## 截图
+
+docs/images 为 README/文档展示图；docs/screenshots 为回归留档；website/assets/shots 为官网素材。
+只把显式视觉验收采集、人工确认过的正片用作展示，不把窗口对照图或旧失败截图直接发布。
+Web 采集入口 `website/tools/capture-shots.mjs`，先准备隔离测试服务和数据。
+岛/客户端采集使用 smoke.mjs --visual，并按需 --online；ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。
+日常 quick 模式不会生成完整视觉截图，不能把 quick 通过表述为动画/透明度已验证。
+
+权限与年度流程回归入口为 `scripts/verify-lifecycle.mjs`，为子进程指定临时库与测试密钥，不使用业务 .env 的登录凭据。
+旧库升级脚本动态读取最新迁移，另建重构前夹具校验 ADMIN 默认组补键、历史 kind 映射、空组保留及重复启动。
+事务回滚用 SQLite 触发器模拟历史写入失败，不能通过删除断言或放宽状态规则通过测试。

docs/dev/toc.yml

@@ -0,0 +1,23 @@
+- 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: 灵动岛设计令牌
+  href: winisland-design-tokens.md
+- name: 验收与测试
+  href: testing.md
+- name: 版本迭代与发布
+  href: release.md
+
+- name: 当前实现约定
+  href: implementation.md

docs/dev/winisland-design-tokens.md

@@ -0,0 +1,59 @@
+---
+title: 灵动岛设计令牌
+description: 本地经典/自定义岛的几何、外观与动画入口。
+---
+
+# 灵动岛设计令牌
+
+经典岛以 WinIsland 的连续圆角和形变为设计参考，自定义组件行以 ClassIsland 为参考。
+当前数值与行为以本仓库 shared 常量和渲染实现为准；本页不把上游音乐/歌词/媒体功能列为 ClassHelper 功能。
+
+## 经典几何与外观
+
+| 来源                                                 | 内容                                                  |
+| ---------------------------------------------------- | ----------------------------------------------------- |
+| shared/src/constants.ts 的 DEFAULT_ISLAND_APPEARANCE | 默认宽 268、高 44、圆角 20、字号 13、边距 8，顶部居中 |
+| ISLAND_APPEARANCE_RANGES                             | 滑块与主进程归一化共用的范围                          |
+| ISLAND_SIZE_DELTA                                    | 展开、紧急与叫人相对尺寸                              |
+| ISLAND_SHADOW_PAD                                    | 窗口边界的透明留白                                    |
+| ISLAND_LIST_METRICS / islandListLayout               | 主进程和渲染层共用列表度量，控制行数与工作区高度      |
+| desktop-client/src/island/squircle.ts                | 超椭圆路径                                            |
+| desktop-client/src/island/classic-island.css         | 经典底色、文字、图形与状态样式                        |
+
+classic 的 black/glass/tinted 是本地 CSS 外观；glass 使用半透明色，不采样桌面模糊。
+不要对透明岛调用 setBackgroundMaterial：系统材质作用于整窗矩形，可能破坏逐像素透明。
+投影常驻，只随形态改参数，避免切换 filter 创建合成表面的闪帧。
+默认停靠中线不受左右边距影响，只有左/右停靠使用水平边距。
+
+## 自定义常驻行
+
+CLASSISLAND_ISLAND_METRICS 位于 shared/src/island-layout.ts：
+
+| 参数                    | 本地值               |
+| ----------------------- | -------------------- |
+| 单行基准高度 / 水平留白 | 40 / 12 px           |
+| 次要/正文/强调/大字号   | 14 / 16 / 18 / 20 px |
+| 默认缩放 / 范围         | 1 / 0.75–2.5         |
+| 默认圆角 / 最大         | 8 / 20 px            |
+| 默认不透明度 / 行距     | 0.5 / 5 px           |
+| 鼠标避让淡化比例        | 0.05                 |
+
+方案有常态 rows 和无通知展开 expandedRows，运行时由 CustomIslandRuntime.vue 测量自然内容，
+再按屏幕工作区与方案缩放适配。字体与外观覆盖按组件契约生效，不能拿经典固定宽高解释自定义内容尺寸。
+
+## 动画与命中
+
+经典与自定义岛的形变都使用 src/island/spring.ts 的 SpringValue；默认 stiffness=0.10、damping=0.68，
+换向保留部分动量，按剩余距离限速并钳制过冲。不同用途可能覆盖 snapThreshold 等参数，以调用点为准。
+这是独立的帧积分，不等同于主窗口 shared/motion.ts 的 CSS 弹簧。
+应用内动画开关、原生窗口可见性与文档可见性控制运行时动画和静止落定。
+
+鼠标模式按光标命中控制穿透；触摸模式处理贴合、输入区域与失焦宽限，自定义常驻模式还维护独立交互入口和窗口形状。
+几何改变时同步实际窗口、命中矩形和测量，不在动画中反推自然尺寸。
+视觉验收必须显式 --visual；本页数值不代表本次已完成像素验收。
+
+## 修改入口
+
+外观范围改 shared，经典样式改 classic-island.css，自定义样式改 custom-runtime.css 和 custom-island.css，
+原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步编辑器和运行时。
+展示行为见[灵动岛](../app/island.md)，测试见[验收与测试](testing.md)。

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,137 @@
+---
+title: 常见问题
+description: 装不上、连不上、改了不生效——最常被问到的那些问题。
+---
+
+# 常见问题
+
+## 安装与启动
+
+### 双击客户端"点了没反应"
+
+**关窗只是隐藏到托盘，进程还在。** 再双击 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. 服务器上如果开了系统代理，内网地址可能被代理接管 —— 浏览器与客户端**不会**自动绕过
+   请在系统代理中为内网服务端设置绕过规则；
+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. 确认客户端登录的是这条通知对应的班级。
+4. 反向代理放行 `/socket.io/` 的 WebSocket 升级了吗？
+
+### 屏幕上出现了第二个灵动岛，点它反应不对
+
+先确认是否有人显式运行了 `verify:desktop:visual` 或 `verify:packaged --visual`；视觉实例由脚本控制，会自行开合。
+默认 `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 与日志编码等）
+  记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
+- 功能行为的权威说明在[完整参考](reference.md)；
+- 都不是的话，去 [Issues](https://github.com/LoveChengke/classhelper/issues) 提一个，
+  附上版本号（Web 端顶栏 / 客户端「设置 → 关于」里都有）和日志。

docs/get-started/client.md

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

docs/get-started/first-content.md

@@ -0,0 +1,36 @@
+---
+title: 发布第一条内容
+description: 通知、作业、叫人、成绩与课件的首次操作。
+---
+
+# 发布第一条内容
+
+先完成班级、学生与任课关系配置。页面是否可见及能否发布，由实际功能权限、班级范围和科目关系共同决定。
+
+## 通知与叫人
+
+在“通知发布”选班、填写标题/内容、选择优先级后发布；叫人使用该页叫人入口，选择学生和事由。
+通知有低/普通/重要/紧急四档，叫人分普通 HIGH 与紧急 URGENT。
+经典岛普通通知上课暂存，普通叫人保留可点击胶囊，紧急消息立即展开；自定义常驻岛先提示铃铛，主动查看。
+上课发布紧急通知需服务端二次确认，Web 确认框倒计时结束后才能再次提交。
+完整行为见[通知](../app/notifications.md)和[叫人](../app/calls.md)。
+
+## 作业
+
+在“作业发布”选班、科目、所属日期，填写标题与要求；附件为受校验的 http(s) 或站内链接。
+作业按所属日期展示，可补录历史日期；科目写权限以本人任课关系为准。
+教室客户端可录作业和维护未交名单；本机录入的内容不会再提醒自己。
+可选全屏看板与字号/日期等偏好，详见[作业](../app/homeworks.md)。
+
+## 成绩
+
+在“成绩录入”选择班级、考试，单条/批量录入或导入表格。
+具备功能权限后，仍只能写自己任教科目；表格导入还要求管理员/本班班主任，按行返回错误和警告，文件上限 8 MB。
+班级端个人查询开关开启时可看本班明细与排名，关闭后只看服务端集体分析。
+见[成绩](../app/grades.md)和[导入](../app/imports.md)。
+
+## 课件
+
+在“教学事务 → 课件”上传文件，选择本人授课班级并设置“仅保存”或“保存后推送”。
+文件先保存到服务端，班级端按可见范围下载；推送离线补领、逐设备回执，客户端不自动运行文件。
+单文件上限 512 MB，详见[课件上传与传输](../app/courseware.md)。

docs/get-started/index.md

@@ -0,0 +1,38 @@
+---
+title: 快速上手
+description: 从零把 ClassHelper跑起来：装服务端、认管理端、建班级排课、装 ClassHelper 班级端、发第一条内容。
+---
+
+# 快速上手
+
+ClassHelper不是一个单机软件，它由三部分组成，**必须先有服务端，管理端与客户端才有内容可看**：
+
+| 组成部分       | 装在哪                                  | 谁用                       | 必须先装？       |
+| -------------- | --------------------------------------- | -------------------------- | ---------------- |
+| **服务端**     | 一台能一直开着的机器（服务器/办公电脑） | —（它同时托管 Web 管理端） | ✅ 是            |
+| **Web 管理端** | 不用装 —— 浏览器打开服务端地址即可      | 老师、班主任、管理员       | 跟着服务端一起有 |
+| **桌面客户端** | 教室的电脑 / 教室大屏                   | 学生看课表作业、老师录作业 | 服务端就绪之后   |
+
+按顺序走下面这几页就行，全程大约半小时（不含下载时间）：
+
+1. [系统要求](requirements.md) —— 先确认机器和网络够用
+2. [安装服务端](server.md) —— Windows 安装包 / Linux 一键脚本 / Docker / 源码跑
+3. [认识 Web 管理端](web-admin.md) —— 登录进去，认一认界面
+4. [建班级、排课表](setup-class.md) —— 这是后面所有功能的前提
+5. [装 ClassHelper 班级端](client.md) —— 教室机器用班级码登录
+6. [发布第一条内容](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,75 @@
+---
+title: 系统要求
+description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环境与网络要求。
+---
+
+# 系统要求
+
+## 服务端
+
+Windows 服务端安装包自带 Node；Linux 包不内置 Node，一键安装器检测或安装兼容运行时。
+默认使用内嵌 SQLite，无需另装数据库服务；MySQL 形态需可用数据库。
+
+| 项目     | 要求                                                                       |
+| -------- | -------------------------------------------------------------------------- |
+| 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker  |
+| 内存     | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB）              |
+| 磁盘     | 预留程序、数据库、备份和课件文件空间；课件最多 512 MB/文件，按实际使用增长 |
+| CPU      | 任意 x64；不需要独显                                                       |
+
+**Linux 的运行时要求**：安装器下载的官方 Node linux-x64 运行时通常要求 glibc ≥ 2.28。
+CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
+判据：
+
+```bash
+ldd --version | head -1
+```
+
+**外网**：更新检查/下载安装包、假日建议和配置的在线 AI 服务等功能可能访问外网。
+基础教学业务可在内网运行；使用离线包、手工周次和 mock/关闭在线 AI，相关联网失败按接口返回原因处理。
+
+## 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,37 @@
+---
+title: 建班级、排课表
+description: 班级、名单、任课关系与日课表的首次配置。
+---
+
+# 建班级、排课表
+
+## 创建班级
+
+管理员在“班级管理”填写入学年份、班号、年级等资料；班级名称按年份和班号生成，如“2026级1班”。
+设置班主任、学期周数及班级凭据；班主任可暂空，但发布依赖教师归属的内容前需先完成配置。
+班级周数默认 20，受全校可配置上限限制，全校默认上限 30、范围 1–60。
+保存班级码与密码，教室客户端用它登录；已读和作业状态操作代表全班。
+
+## 录入学生与教师
+
+学生是名单，填写学号和姓名，不创建账号、密码或自动登录名。
+学号 1–32 位字母/数字/._-，不能复用；支持管理员表格导入，班主任有名单管理权限时可维护本班。
+教师使用工号账号，管理员在教师管理录入或导入。
+在班级详情按科目配置任课老师：任课关系只存 Course，决定该科作业/成绩写权限。
+班主任不任教某科就不能改该科内容，详见[班级与人员](../app/classes.md)。
+
+## 配置作息与日课表
+
+先在“时间表与课表编辑”维护时间表的上课/课间等时间点，再创建班级日课表并为时间点选择课程。
+按星期、周次范围和 1–9 周轮换设置启用规则，也可复制、临时换课或预定某天。
+时间表写入需 timetable:manage；日课表写入需 schedule:write 并通过本班班主任/管理员检查。
+可以从 ClassIsland 完整 JSON 离线导入作息、日课表、群组与预定，见[导入](../app/imports.md)。
+
+## 校对周次与提醒
+
+管理员在“学期周次”设置开学日、全校上限和逐周日期，班级可以有独立区间。
+在周视图和客户端今天时间轴核对当前课程、下一节、上下课时刻。
+经典岛普通通知上课暂存、普通叫人保留可点胶囊、紧急消息立即展开；自定义常驻岛先提示铃铛，主动点击查看。
+验证应使用独立测试班级，详见[验收](../dev/testing.md)，不要给业务班级发送测试通知。
+
+下一步：[装班级端](client.md)。

docs/get-started/toc.yml

@@ -0,0 +1,14 @@
+- 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: 发布第一条内容
+  href: first-content.md

docs/get-started/web-admin.md

@@ -0,0 +1,38 @@
+---
+title: 认识 Web 管理端
+description: 登录、菜单分组、权限与移动布局。
+---
+
+# 认识 Web 管理端
+
+服务端启动后，用浏览器打开 http://<服务器地址>:4000/，教师或管理员以工号和密码登录。
+学生无个人账号，教室客户端使用[班级登录](client.md)。新安装按部署配置创建初始管理员，首次使用后修改初始密码。
+
+## 菜单与权限
+
+侧栏按以下分组组织，具体页面由路由权限筛选，并支持浅色/深色和关怀模式。
+
+| 分组       | 主要页面                                                     |
+| ---------- | ------------------------------------------------------------ |
+| 工作台     | 仪表盘、AI 助手                                              |
+| 教学事务   | 课表、时间表与日课表编辑、作业、通知、课件、成绩             |
+| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、学年升级、毕业归档 |
+| 设备运维   | 客户端在线状态、命令、更新与安装策略                         |
+| 系统管理   | 权限组、系统设置、大模型设置、数据库管理                     |
+
+班级、学生、学期周次、学年升级和归档页面按各自生效权限开放；教师管理和数据库页面仍保留角色门槛。
+名单、教学页与设备页还按对应数据范围开放，写按钮需额外管理键。
+每次操作服务端继续校验，不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
+顶栏提供本人密码、使用引导、检查更新与退出等入口。
+
+## 引导与手机
+
+首次登录展示使用引导，完成/跳过后记住；可从顶栏“使用引导”重看。
+小屏侧栏收进抽屉，表格在卡片内横向滚动；支持安装 PWA，需要 HTTPS 或 localhost 安全上下文。
+同局域网手机填写服务器局域网地址，不用 localhost；公网反代见[生产部署](../management/production.md)。
+
+下一步：[建班级、排课表](setup-class.md)。
+
+权限页选组会替代角色默认模板，保存前可查看新增/移除权限与影响成员；保留默认能力时同时选择同角色默认组。
+名单页默认在读，历史状态与包含归档分开筛选；资料编辑、调班、转出、转入/复学各有专用入口。
+学年升级先保存计划、预览阻断项和周次影响，再输入学年确认执行；执行记录保留快照与 SHA256。

docs/index.md

@@ -0,0 +1,69 @@
+---
+title: 首页
+description: ClassHelper（Class Helper）的官方文档：安装部署、功能说明、运维手册与开发参考。
+---
+
+# ClassHelper文档
+
+ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统。**一份代码，三个交付物**：
+装在服务器上的后端、给老师用的 Web 管理端、装在教室机器的桌面客户端（ClassHelper 班级端 / 教室大屏）。
+
+<p class="ch-tagline">
+老师发一条通知，教室那台机器上的客户端和灵动岛会实时显示；学生打开客户端就能看到当天的课表和作业。
+</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 班级端跑起来，大约半小时。</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 按班级房间广播，客户端与灵动岛实时更新。
+
+**二、课堂提醒有明确规则。** 经典岛普通通知暂存到下课，普通叫人保留可点胶囊，紧急消息立即展开；
+自定义常驻岛先显示铃铛，由用户主动查看。课堂发布紧急通知还需服务端确认。
+
+**三、离线可用。** 客户端先写 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`，**仅管理员可见**，接口要求 `database:manage`），
+把过去要手工做的数据库运维都收进了界面。
+
+## 它能做什么
+
+| 能力         | 说明                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、快照清单中各表的行数、连接串（MySQL 密码脱敏）                                           |
+| 连接测试     | 对任意目标库试连（切换前的第一步）                                                                                                                     |
+| **一键切换** | SQLite ⇄ MySQL：自动「备份当前库 → 改写 schema provider → 生成客户端 / 建表 → 子进程迁移全部数据 → 改写 `.env`」，异步任务带步骤进度，**失败自动回滚** |
+| 备份 / 恢复  | gzip JSON 快照存在 `<数据目录>/backups/`；手动备份 / 从备份恢复（整库覆盖）/ 删除                                                                      |
+| 定时备份     | enabled + 间隔小时数 + 保留份数，配置存在 `data/database-settings.json`；服务端每 10 分钟检查一次到点任务（**进程不运行不补跑**）                      |
+| 快捷导入导出 | 下载快照 JSON（跨库通用）/ 下载数据库文件（仅 SQLite）/ 导入快照（整库覆盖，base64 上传）                                                              |
+
+## 关键设计：只有一种快照格式
+
+**备份、导入导出、跨库迁移共用同一种「JSON 快照」**：
+
+- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出；
+- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联，表清单与恢复顺序由 `lib/snapshot.ts` 统一维护；
+- 分批 `createMany` 写入。
+
+相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复；格式与缺失表由快照校验器检查。
+课件元数据包含在快照中，文件实体不包含，完整备份需另带 `data/courseware` 或 COURSEWARE_DIR 指定目录。
+
+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

@@ -0,0 +1,560 @@
+# Linux 部署与运维指南
+
+本文覆盖服务端在 Linux 上的**一键安装**与日常运维（`classhelper` 命令）。
+适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+（自动识别 apt / yum / dnf）。
+
+不想看长文的话，最短路径就是这**一行**（在服务器上执行）：
+
+```bash
+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
+```
+
+---
+
+## 1. 三种形态怎么选
+
+| 形态                   | 适合                                  | 命令              | 说明                                                  |
+| ---------------------- | ------------------------------------- | ----------------- | ----------------------------------------------------- |
+| **直接安装（native）** | 有一台 Linux 服务器/Mini 主机，单机跑 | `install.sh` 选 1 | systemd 管理，自带 Node 运行时，SQLite 或 MySQL       |
+| **直接安装 + MySQL**   | 多终端共享数据、已有 MySQL            | `install.sh` 选 2 | 连接串写在配置里；库要先建好                          |
+| **Docker**             | 机器上已有 Docker、想与其他服务隔离   | `install.sh` 选 3 | 用安装包里随带的 Dockerfile 构建镜像 + compose 起容器 |
+
+> 只想先看看这台机器能不能装：`bash install.sh --check`（**不需要 root**，不改动任何东西）。
+> Windows 机器用服务端安装包（`pnpm dist:server` 的产物），不需要本文。
+
+---
+
+## 2. 安装包从哪来
+
+Linux 安装包命名固定为：
+
+```
+classhelper-server-linux-x64-<版本>.tar.gz          ← install.sh / classhelper upgrade 都认这个名字
+classhelper-server-linux-x64-<版本>.tar.gz.sha256   ← 旁边那份校验值
+```
+
+它发布在 [GitHub Releases](https://github.com/LoveChengke/ClassHelper/releases) 上。
+
+**为什么 Linux 包要单独出一个**：`@libsql/linux-x64-gnu`、`@prisma/adapter-libsql` 这些依赖是平台相关的，
+Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 Linux 跑不起来，因此正式 Linux 包在 Linux 上构建，交叉构建限制见下文。
+仓库里的 [`.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.2`）；
+2. 推送 v* tag 会自动触发；也可在 Actions 的「发布 Linux 服务端安装包」中手动指定 tag 运行；
+3. 跑完 Release 里会多出 Linux 包与更新后的 `SHA256SUMS-<版本>.txt`。
+
+内网离线分发也可以：在能上网的机器上 `pnpm dist:server:linux`，把 tar.gz 拷进去，
+用 `install.sh --package /path/to/xxx.tar.gz --sha256 <哈希>` 安装。
+
+### 没有 Linux 机器时（交叉构建）
+
+`pnpm dist:server:linux` 在非 Linux 上也**能跑**：脚本会用 npm 的 `--os=linux --cpu=x64`
+按目标平台解析可选依赖，所以 `@libsql/linux-x64-gnu` 这些"按平台分发"的包会被正确装进来。
+适合本地快速打一个包去验证安装与运维流程。逐项核对过的结论：
+
+| 项                       | 结论                                                                                                                                                                                               |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite 驱动              | ✅ 包内是 `@libsql/linux-x64-gnu` + `linux-x64-musl`，**没有任何 win32 残留**                                                                                                                      |
+| 服务端本体               | ✅ Node + libsql + express + socket.io 都是纯 JS 或已就位的 Linux 原生包                                                                                                                           |
+| 运维命令                 | ✅ `status` / `doctor` / `password` / `backup` / `upgrade` / `rollback` 都不依赖平台差异                                                                                                           |
+| Web 端「一键切换数据库」 | ⚠ **可能失败**：这条链路要调 prisma CLI 的 schema engine，CLI 在运行期按平台扫 `@prisma/engines/schema-engine-debian-openssl-3.0.x` 这类路径，而交叉包里只有宿主平台的 `schema-engine-windows.exe` |
+
+所以交叉包**能装、能跑、能验收**，只是那一个 Web 端功能存疑 —— 它会在包内写入 `.cross-built` 标记，
+`classhelper doctor` 会据此提示你（不会静默）。**正式发布一律用 GitHub Actions 那条路。**
+
+```bash
+# 开发机（Windows 也可以）
+pnpm dist:server:linux
+# → releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz（+ .sha256）
+#   重跑很快：node scripts/dist-server.mjs --platform linux --reuse-deps（复用已装的 node_modules）
+```
+
+---
+
+## 3. 一键安装
+
+### 3.1 交互式（推荐第一次用）
+
+```bash
+sudo bash install.sh
+```
+
+TUI 会依次问：形态 → 安装目录 → 端口 → 数据库 → 初始管理员密码 → 是否要 Nginx 配置 / 放行防火墙。
+每一问都有默认值，直接回车即可。
+
+### 3.2 非交互（自动化 / 批量部署）
+
+```bash
+# 全部默认：/opt/classhelper、4000 端口、SQLite、内置 Node
+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.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.2.tar.gz <<< 'MySQL密码'
+```
+
+完整参数见 `bash install.sh --help`。要点：
+
+| 参数                                     | 作用                                                       |
+| ---------------------------------------- | ---------------------------------------------------------- |
+| `--package <url｜file://路径>`           | 安装包地址（默认从 GitHub Release 取最新版）               |
+| `--sha256 <哈希>`                        | 强制校验安装包哈希                                         |
+| `--admin-password-stdin`                 | 从 stdin 读一行作为初始管理员密码                          |
+| `--node-source bundled｜system｜tarball` | 内置 Node / 系统 Node / 指定压缩包                         |
+| `--node-mirror <url>`                    | Node 下载镜像（默认 `https://npmmirror.com/mirrors/node`） |
+| `--node-tarball <url｜路径>`             | 内网离线时直接用本地 Node 包                               |
+| `--with-nginx` / `--open-firewall`       | 顺带生成反代配置 / 放行端口                                |
+| `--yes`                                  | 全默认、不再交互                                           |
+| `--check`                                | 只体检（无需 root）                                        |
+| `--force`                                | 覆盖已有配置；在无 systemd 的机器上只铺文件不装服务        |
+
+**幂等性**：重复执行就是覆盖安装。已有的 `config.env`（含 `JWT_SECRET`）与 `data/` 一律保留，
+用户不会被踢下线；端口与数据库形态也沿用旧配置，不会被改回默认值。
+
+### 3.3 安装器做了什么
+
+1. 识别发行版与包管理器，补齐 `curl / tar / gzip / ca-certificates`（只装缺的）；
+2. 创建系统用户与组 `classhelper`（`--system`，nologin）；
+3. 建目录、收权限（见下一节）；
+4. 下载安装包 → 校验 sha256 → 解压铺文件；
+5. 下载 Node（默认走 npmmirror 镜像，从 `SHASUMS256.txt` 同时取版本号与哈希）；
+6. 生成 `/etc/classhelper/config.env`（随机 `JWT_SECRET`，权限 600）；
+7. 装 systemd 单元、`/usr/local/bin/classhelper`、`/etc/profile.d/classhelper.sh`、logrotate；
+8. 启动服务并轮询 `/healthz`，通过后才算安装成功；
+9. 全过程写 `/var/log/classhelper/install.log`。
+
+### 3.4 Docker 形态
+
+`install.sh` 选 3（或 `--mode docker`）：用安装包里随带的 `Dockerfile` 直接构建镜像
+（包的 `node_modules` 已经是 linux 的真实目录，**构建时不需要联网装依赖**，几十秒出镜像），
+然后写一份 `/etc/classhelper/compose.yml` 拉起容器。
+
+```bash
+classhelper status          # 走 docker compose ps / logs
+classhelper restart         # 重建容器
+classhelper password admin  # 通过 docker exec 在容器里执行同一份 admin-cli
+classhelper backup          # 容器内做一致性快照再取出来
+```
+
+Docker 形态与直接安装的差异：
+
+|                   | 直接安装                                      | Docker                                                                                                |
+| ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| 数据位置          | `<安装目录>/data`                             | Docker 卷 `classhelper-data`                                                                          |
+| 配置              | `/etc/classhelper/config.env`（systemd 注入） | 同一份文件（compose `env_file`）                                                                      |
+| 升级 / 回滚       | 替换程序文件后重启服务                        | 同一套流程：替换构建上下文 → 重建镜像（`classhelper-server:local`）→ `compose up -d --force-recreate` |
+| 恢复数据          | `classhelper backup restore <目录>`           | 需手工 `docker cp` 回容器（命令里有提示）                                                             |
+| `backup schedule` | 支持（systemd timer）                         | 用宿主机 cron 调 `classhelper backup --quiet`                                                         |
+
+> Docker 形态的镜像用**稳定标签** `classhelper-server:local`（另打一个 `classhelper-server:<版本>` 便于追溯）。
+> 版本号写在 compose 里的话，升级替换完程序文件后那个标签就过期了，`compose up` 会一直沿用旧镜像 ——
+> 表现为"升级成功但行为没变"。`classhelper` 自己按 `VERSION` 决定要不要重建镜像。
+
+---
+
+## 4. 目录、权限与配置
+
+```
+/opt/classhelper/                 安装目录（--dir 可改）
+├── server/                       后端程序（入口 server/dist/index.js）
+│   ├── dist/  prisma/            产物 + 迁移 SQL（首启动 AUTO_MIGRATE 自动执行）
+│   ├── prisma.config.ts  tsconfig.generate.json    数据库「一键切换」用
+├── web/                          Web 管理端（由后端托管）
+├── node_modules/                 生产依赖（真实目录，非软链）
+├── tools/admin-cli.mjs           离线改密 / 数据库快照工具
+├── bin/classhelper               运维命令本体（/usr/local/bin/classhelper 软链到它）
+├── runtime/node/                 内置 Node 运行时
+├── systemd/ logrotate.d/ profile.d/   模板（安装时拷到 /etc 下）
+├── Dockerfile                    Docker 形态构建用
+├── data/                         数据库 + Web 端自建快照（备份就是拷这里）
+├── logs/                         预留
+├── VERSION                       当前版本
+├── .installed.json               安装元数据（形态/版本/端口，classhelper 靠它决策）
+└── .env  →  /etc/classhelper/config.env    （软链，见下）
+
+/etc/classhelper/                 目录 700，属主 classhelper
+└── config.env                    配置文件，**权限 600**，唯一真身
+/var/log/classhelper/             安装日志 install.log + 审计日志 audit.log
+/var/backups/classhelper/         备份 + 程序快照（回滚用）
+```
+
+### 4.1 为什么安装目录里的 `.env` 是软链
+
+Web 端「数据库管理 → 一键切换数据库」在运行中改写的是 **`<安装目录>/.env`**
+（`packages/server/src/modules/database/database.service.ts`），而 systemd 是通过
+`EnvironmentFile=/etc/classhelper/config.env` 注入环境变量的。dotenv 不覆盖已存在的环境变量 →
+如果这两处不是同一份文件，**切换看起来成功、重启后又连回旧库**。
+
+所以安装器把 `<安装目录>/.env` 做成指向 `config.env` 的软链：两种读法落到同一个真身。
+`classhelper doctor` 会专门检查这条软链，别手工删掉。
+
+### 4.2 配置项
+
+配置就是一份 `KEY=VALUE` 的 env 文件，systemd / dotenv / `source` 三种读法都兼容
+（含空白或 `#` 的值请加双引号）。最常见的几项：
+
+| KEY                                                   | 默认                          | 说明                                                                     |
+| ----------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------ |
+| `PORT` / `HOST`                                       | `4000` / `0.0.0.0`            | 监听端口与地址                                                           |
+| `DATABASE_PROVIDER`                                   | `sqlite`                      | `sqlite` 或 `mysql`                                                      |
+| `DATABASE_URL`                                        | `file:../data/classhelper.db` | SQLite 相对 `<安装目录>/server` 解析；MySQL 是连接串                     |
+| `JWT_SECRET`                                          | 随机                          | 登录令牌签名密钥。**换掉＝所有用户重新登录**（`classhelper key rotate`） |
+| `JWT_EXPIRES_IN`                                      | `7d`                          | 令牌有效期                                                               |
+| `CORS_ORIGIN`                                         | `*`                           | 走域名/反代时建议收敛成 `https://你的域名`                               |
+| `TRUST_PROXY`                                         | `1`                           | 前面有 Nginx 时保持 1，限流才按真实 IP 统计                              |
+| `AUTO_MIGRATE`                                        | `true`                        | 空库首启动自动建表 + 建管理员                                            |
+| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD`   | `admin` / `admin123`          | **只在空库首次初始化时生效**，之后改密码用 `classhelper password`        |
+| `DEFAULT_CLASS_PASSWORD` / `DEFAULT_TEACHER_PASSWORD` | `123456`                      | 新建班级 / 重置教师时的初始密码                                          |
+| `TERM_START_DATE`                                     | 空                            | 第 1 教学周的周一（`YYYY-MM-DD`），影响"当前周次"                        |
+
+改配置的三种方式（都会先自动备份、改完问你是否重启）：
+
+```bash
+sudo classhelper config show                 # 敏感值打码查看
+sudo classhelper config get PORT
+sudo classhelper config set CORS_ORIGIN https://class.example.com   # 敏感项会改成交互输入
+sudo classhelper config edit                 # 用 $EDITOR 直接编辑
+sudo classhelper port 8080                   # 改端口的快捷方式
+```
+
+> 手工改也可以（`vim /etc/classhelper/config.env`），但记得改完 `classhelper restart`，
+> 并确认权限仍是 600。
+
+---
+
+## 5. `classhelper` 运维命令
+
+安装后可直接使用（`/usr/local/bin/classhelper`）。除 `help` / `version` / `completion` 外都需要 root。
+
+### 5.1 查看与诊断
+
+```bash
+classhelper status              # 服务状态、版本、端口、数据库、各类路径
+classhelper status --json       # 同上，机器可读（接监控用）
+classhelper doctor              # 完整体检：权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份
+classhelper logs -f             # 实时日志（= journalctl -u classhelper -f）
+classhelper logs -n 200 --since "1 hour ago"
+classhelper logs --unit classhelper-backup     # 看定时备份的日志
+```
+
+`doctor` 会把每一项标成 `✔` / `✘`，失败项后面直接跟修复建议，例如：
+
+```
+  ✘ 安装目录 .env 是指向配置真身的软链
+  ✔ Node 运行时可用且 ≥20.19（v22.20.0）
+  ✘ 最近 7 天内有备份（无）
+建议依次处理：
+  · ln -sfn /etc/classhelper/config.env /opt/classhelper/.env（Web 端「一键切换数据库」依赖它）
+  · classhelper backup；长期可用 classhelper backup schedule daily
+```
+
+### 5.2 改密码
+
+```bash
+sudo classhelper password                 # 改 admin
+sudo classhelper password teacher1        # 改指定教师
+sudo classhelper password --list          # 列出可登录账号与班级账号（含是否已设密码）
+sudo classhelper password --class G101    # 改某个班的班级密码（ClassHelper 班级端登录用）
+```
+
+安全约定（照要求逐条落实）：
+
+- 密码**交互输入、不回显**；不接受命令行传参，因此不会进 shell history、也不出现在 `ps` 里；
+- 强度校验：≥8 位，小写/大写/数字/符号至少 3 类，不得与用户名相同，常见弱口令直接拒绝；
+  需二次确认，连续 3 次不合规即退出（密码不变）；
+- 改前把**原密码哈希**备份到 `/var/backups/classhelper/password-<时间戳>.json`（权限 600），
+  写入失败或写入后复核不通过会**自动回滚**原哈希；
+- 全过程写审计日志，**审计里只有"谁对谁做了什么、结果如何"，没有密码**；
+- 自动化可以用管道传入（仍不进 history）：
+
+```bash
+printf '%s\n%s\n' "$NEW_PW" "$NEW_PW" | sudo classhelper password admin
+```
+
+> 顺带说明：改密码不需要重启服务（登录时读库校验）；已登录的会话仍有效，
+> 要让所有会话立刻失效用 `classhelper key rotate`。
+
+### 5.3 备份与恢复
+
+```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`（密码经 `MYSQL_PWD` 传给子进程，不进 argv）；
+- `restore` 前会先自动备份现状，恢复对象是配置与数据（不是程序）；
+- 程序文件快照（回滚用）在 `/var/backups/classhelper/rollback/`，是另一类东西，`backup list` 会分开列。
+
+### 5.4 升级与回滚
+
+```bash
+sudo classhelper upgrade --check          # 只检查有没有新版本（查 GitHub Release）
+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 → 备份数据与配置 → 快照当前程序文件 →
+停服 → 替换程序文件（mv 原子替换，data/ 配置/ 运行时原地不动）→ 起服 → 轮询 /healthz
+   ↘ 失败：自动用刚才的快照回滚并重新起服，再告诉你失败原因
+```
+
+两点必须知道：
+
+1. **升级不会回滚数据库结构**。如果新版执行过迁移，回滚程序前要确认旧版还能读新库，
+   必要时用 `classhelper backup restore` 连数据一起回退；
+2. 替换程序文件用的是"改名 + 就位"而不是删除重写 —— 升级时正在运行的就是 `bin/classhelper` 自己，
+   必须先改名再放新文件，运行中的进程继续读旧 inode，否则会读到半个脚本。
+
+### 5.5 服务与配置
+
+```bash
+sudo classhelper start | stop | restart | reload    # reload 与 restart 同义（服务端不支持热重载）
+sudo classhelper port                               # 看当前端口
+sudo classhelper port 8080                          # 改端口（顺带提示放行防火墙）
+sudo classhelper config show [--reveal]
+sudo classhelper config set KEY VALUE
+sudo classhelper key rotate                         # 轮换 JWT_SECRET（所有用户需重新登录）
+```
+
+### 5.6 其它
+
+```bash
+classhelper version
+classhelper help
+source <(classhelper completion bash)     # 补全（安装时已装到 /usr/share/bash-completion）
+```
+
+### 5.7 卸载
+
+```bash
+sudo classhelper uninstall
+```
+
+会依次问：保留配置？保留数据？保留备份？默认全部保留 —— 数据与配置会被**搬到**
+`/var/backups/classhelper/uninstall-<时间戳>/`，然后才删除程序目录，不会悄悄丢数据。
+
+```bash
+sudo classhelper uninstall --yes      # 不问，用默认（保留配置/数据/备份）
+sudo classhelper uninstall --purge    # 全删（含备份与数据），不可恢复
+```
+
+---
+
+## 6. 环境变量文件
+
+安装器会写 `/etc/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
+export CLASSHELPER_CONFIG=/etc/classhelper/config.env
+export CLASSHELPER_LOG_DIR=/var/log/classhelper
+export CLASSHELPER_BACKUP_DIR=/var/backups/classhelper
+export PATH=$PATH:$CLASSHELPER_HOME/bin
+```
+
+新登录的 shell 自动生效；当前会话要手工 `source /etc/profile.d/classhelper.sh`。
+`classhelper` 命令本身装在 `/usr/local/bin`（软链），所以**不登录也照样能用**。
+
+---
+
+## 7. 反向代理与 HTTPS（公网部署必做）
+
+```bash
+sudo bash install.sh --with-nginx     # 或者安装后手工：
+sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
+```
+
+要点：
+
+- `client_max_body_size 12m`（表格导入最大 8MB，base64 后约 11MB）；
+- Socket.IO 需要 `Upgrade` / `Connection` 头与较长的 `proxy_read_timeout`（模板里已配）；
+- 配置里保持 `TRUST_PROXY=1`，并把 `CORS_ORIGIN` 收敛成你的域名；
+- 证书用 certbot 或你自己的证书，装好后 `nginx -t && nginx -s reload`。
+
+---
+
+## 8. 故障排查
+
+| 现象                     | 先查什么                                                                                                                                                                                                                            |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 服务起不来               | `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`（直连数据库，不需要登录）                                                                                                                                                                         |
+| ClassHelper 班级端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠                                                                                                                                                              |
+| CentOS 7 装完立刻退出    | glibc < 2.28，见下面的"已知限制"                                                                                                                                                                                                    |
+
+---
+
+## 9. 已知限制
+
+### CentOS 7 / glibc < 2.28
+
+Node 官方的 linux-x64 二进制要求 **glibc ≥ 2.28**，而 CentOS 7 是 2.17 —— 直接装官方包会表现成
+"装完服务立刻退出、日志里什么也没有"。安装器会自动检测 glibc，低于 2.28 时改用
+[unofficial-builds](https://unofficial-builds.nodejs.org/) 的 **glibc-217** 构建（功能一致，只是编译基线更低）。
+
+但即便这样，个别原生依赖仍可能不兼容，CentOS 7 支持属于**尽力而为**：
+
+- CentOS 7 已于 2024-06 EOL，**新部署请用 Rocky Linux 9 / AlmaLinux 9 / Ubuntu 22.04+**；
+- 若坚持用 CentOS 7，建议装完立刻跑一遍 `classhelper doctor` 与本文第 10 节的验收清单。
+
+### 其它
+
+- 直接安装形态要求 **systemd**（容器里没有 `/run/systemd/system` 时会明确拒绝；
+  容器场景请用 Docker 形态）。
+- Docker 形态的数据恢复需要手工 `docker cp`（数据在容器卷里，宿主机上看不到那个文件）；
+  `classhelper backup restore` 会给出具体命令。
+- `classhelper reload` 等价于 restart（服务端没有 SIGHUP 处理）。
+- 升级包只发 x64；arm64 需要自行构建（`node scripts/dist-server.mjs --platform linux` 跑在 arm64 机器上）。
+
+---
+
+## 10. 验收清单
+
+下面这套在干净的 **Ubuntu 22.04** 与 **Rocky Linux 9** 上各跑一遍。
+`deploy/verify-linux.sh` 会把第 3~8 步自动跑完并打印 `=== 结果：N/N 项通过 ===`。
+
+### 10.0 准备
+
+```bash
+# 在开发机：做出 Linux 包（或在 Actions 里下载）
+pnpm dist:server:linux
+scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz root@<服务器>:/tmp/
+scp deploy/install.sh deploy/verify-linux.sh root@<服务器>:/tmp/
+```
+
+### 10.1 体检（不需要 root）
+
+```bash
+bash /tmp/install.sh --check
+```
+
+期望：系统/包管理器/glibc/docker/端口/磁盘逐项列出，末尾「体检通过」。
+端口被占用、缺 curl、没有 systemd 都会在这里被点出来。
+
+### 10.2 安装
+
+```bash
+sudo bash /tmp/install.sh --yes \
+  --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz \
+  --admin-password-stdin <<< 'Verify-Pass-2026!'
+```
+
+期望：末尾出现「安装完成」与「服务已就绪 ✅」，并打印管理端地址。
+
+### 10.3 自动验收
+
+```bash
+sudo bash /tmp/verify-linux.sh --admin-password-stdin <<< 'Verify-Pass-2026!'
+```
+
+覆盖项：
+
+| 分组       | 检查内容                                                                                                                                                       |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 安装结果   | 程序文件、`VERSION`、`.installed.json`、`config.env` 600、配置目录 700、`.env` 软链、内置 Node、`/usr/local/bin/classhelper`、安装/审计日志、profile.d 生效    |
+| 服务       | systemd 单元、active、enabled、`/healthz` 200、`status --json` 合法且 healthy                                                                                  |
+| 体检       | `classhelper doctor` 无待处理项、`help` / `completion` 可用                                                                                                    |
+| API        | 用初始密码登录拿 token、带 token 读 `/api/classes` 与 `/api/auth/me`                                                                                           |
+| 改密       | 改密成功 → 新密码可登录 → **旧密码被拒** → 原哈希已备份且 600 → 审计有记录且**不含密码明文** → 弱密码被拒 → stdin 结束不卡死 → `restore-hash` 把原密码回滚回来 |
+| 备份       | 备份目录/文件/权限、SQLite 快照是合法库文件、`backup list`                                                                                                     |
+| 配置       | `config get/show`、敏感值打码、读写往返                                                                                                                        |
+| key rotate | 密钥确实变了且 ≥32 位、服务仍可用、**旧 token 变 401**、重新登录成功                                                                                           |
+
+追加升级/回滚链路（会真的替换一次程序文件）：
+
+```bash
+sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x64-1.0.1.tar.gz \
+  --admin-password-stdin <<< 'Verify-Pass-2026!'
+```
+
+覆盖：升级成功 → 服务恢复 → 配置未被改动 → 产生程序快照 → **坏哈希被拒绝且服务不受影响** →
+`rollback` 回到旧版且服务可用。
+
+### 10.4 手工补验（自动化覆盖不到的）
+
+```bash
+# ① 浏览器打开 http://<IP>:4000/ ，用 admin 登录，改一次密码再登录
+# ② 在隔离测试服务创建临时教师和班级，用其班级凭据登录客户端，验证提醒后清理临时数据
+# ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
+#    期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
+# ④ 卸载：sudo classhelper uninstall --yes
+#    期望：服务停止、单元删除、/usr/local/bin/classhelper 消失、
+#         数据与配置被搬到 /var/backups/classhelper/uninstall-*/
+# ⑤ 重启机器后服务自动起来（systemctl is-enabled classhelper）
+```
+
+### 10.5 Rocky 9 的差异点
+
+- 包管理器走 `dnf`，依赖包名与 apt 不同（`install.sh` 已按 `PKG` 分支处理）；
+- 默认没有 `curl` 之外的工具时会被补装，注意首次安装需要能访问 dnf 源；
+- 防火墙默认是 `firewalld`：用 `--open-firewall` 或手工
+  `firewall-cmd --add-port=4000/tcp --permanent && firewall-cmd --reload`；
+- SELinux（Enforcing）：服务读写 `/opt/classhelper` 与 `/etc/classhelper` 一般不受影响，
+  若日志里出现 `Permission denied` 且路径正常，先 `ausearch -m avc -ts recent` 看是不是 SELinux，
+  可以用 `semanage fcontext` 加规则，或临时 `setenforce 0` 验证判断。
+
+---
+
+## 11. 安全清单
+
+- [ ] 改掉默认管理员密码：`classhelper password admin`（**公网部署第一件事**）
+- [ ] 公网服务前面加 Nginx + HTTPS，`CORS_ORIGIN` 收敛到具体域名
+- [ ] 定期备份：`classhelper backup schedule daily`，并确认备份能恢复（`backup restore` 演练一次）
+- [ ] 配置与备份权限：`config.env` 600、`/etc/classhelper` 700、备份目录 700
+- [ ] `classhelper doctor` 无待处理项；关注"最近 7 天内有备份"
+- [ ] 审计日志（`/var/log/classhelper/audit.log`）随日志轮转保留，必要时接集中日志
+- [ ] 只在需要时使用 `--purge`；卸载默认保留数据与备份
+- [ ] 升级包一律校验 sha256（`upgrade` 内网分发时也要带 `--sha256`）

docs/management/mysql.md

@@ -0,0 +1,47 @@
+---
+title: MySQL 切换指南
+description: 通过快照和受支持的换库流程切换 SQLite/MySQL，保留迁移历史。
+---
+
+# MySQL 切换指南
+
+默认数据库为 SQLite，服务端也支持 MySQL/MariaDB。唯一 schema 为 packages/server/prisma/schema.prisma；
+Prisma 通过 libSQL 或 MariaDB driver adapter 访问，两种适配器已随运行时依赖内置。
+角色、优先级等以 String 加 API 校验存储，不用 Prisma enum 或 @db.*。
+
+## 已有数据的切换
+
+管理员在“数据库管理 → 一键切换数据库”填写**空目标库**连接串，并完成界面确认。
+还须 database:manage；页面和具体接口各自检查权限。
+
+1. 备份并导出当前数据库为 JSON 快照。
+2. 测试目标连接，确认目标为空。
+3. 改写 schema provider，子进程生成对应 Prisma Client。
+4. 打包形态编译生成的 TypeScript 客户端。
+5. 子进程基于当前 schema 建表，并用 apply-snapshot 写入快照。
+6. 成功后写入 .env 的 DATABASE_PROVIDER/DATABASE_URL；重启服务端连接新库。
+
+失败时回滚 schema，环境配置仅在成功后写入。快照覆盖的表以 lib/snapshot.ts 为准。
+目标已有表时拒绝；回到 SQLite 也应指定新空文件，不能删除正在使用的数据库。
+旧源库请保留到验证完成。课件实体不在 JSON 内，换主机时需另复制文件目录，见[课件](../app/courseware.md)。
+
+## 源码开发与配置
+
+scripts/use-database.mjs 只切换 schema provider，不迁移数据、不改 .env、不替代完整换库流程。
+如果只准备一个全新的开发环境，可用 pnpm db:switch:mysql，再配置独立空库并生成客户端；
+建模和导入仍按受支持流程完成。配置示例：
+
+```dotenv
+DATABASE_PROVIDER=mysql
+DATABASE_URL="mysql://classhelper:your-password@127.0.0.1:3306/classhelper"
+```
+
+SQLite 迁移目录属于仓库升级历史，不要为了切库删除它，也不要对已有数据运行 db:seed/db:reset。
+SQLite SQL 不直接应用到 MySQL；换库流程基于当前 schema 建表，保留原迁移用于 SQLite 升级。
+Prisma Client 与实际 provider 必须一致；切换后未重启时旧进程仍连接旧库。
+
+## 部署核验
+
+确认新库连接、表行数、班级登录、课表和成绩读取；保留切换前快照。
+生产凭据放 .env 或部署密钥中，不提交 Git。完整备份和各形态命令见[数据库管理](database.md)。
+Linux 正式包应在 Linux 构建，否则 Prisma engine 可能是宿主平台版本，见[Linux 部署](linux-deploy.md)。

docs/management/production.md

@@ -0,0 +1,401 @@
+# 生产部署指南
+
+本文档覆盖三种上线形态，按适用场景选择：
+
+| 形态                  | 适用场景                                      | 产物                                                                                                                     | 验证状态                                                 |
+| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）      | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe`                                                  | ✅ 已验证（静默安装 / 启停 / 卸载 / UI）                 |
+| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案）  | `deploy/Dockerfile` + `deploy/docker-compose.yml`                                                                        | ⚠️ 文件已提供，尚未实机验证                              |
+| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令 | ⚠️ 实机验收清单见 [linux-deploy.md](linux-deploy.md) §10 |
+| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义            | 在仓库里构建后直接跑（见第四节）                                                                                         | ✅ 已验证（端到端验收通过）                              |
+
+---
+
+## 一、Windows 安装包（形态 A）
+
+### 1.1 生成安装包
+
+```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 的机器上手动跑，见第四节。
+
+打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
+生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
+
+### 1.2 安装
+
+双击安装程序即可，**无需管理员权限**（当前用户级安装）：
+
+- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
+- 静默安装：`"ClassHelper 服务端-1.2.0-x64-setup.exe" /S`
+- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
+- 桌面：`ClassHelper 服务端.lnk`（打开管理端）
+- **开机自启动可选**：安装向导的组件页里勾选（默认勾选），装完之后还能在管理端「系统设置」里随时开关
+  （`GET/PUT /api/system/autostart`）；勾选时写的是 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`
+- 卸载信息注册到「应用和功能」
+
+安装完成后服务会自动启动并完成首次初始化：
+
+1. 数据库为空 → 自动执行随包迁移（`AUTO_MIGRATE=true`）建表
+2. 自动创建管理员账号（默认 `admin / admin123`，日志中会提示尽快修改）
+3. 打开 http://127.0.0.1:4000/ 即为 Web 管理端
+
+### 1.3 目录与配置
+
+```
+%LOCALAPPDATA%\Programs\ClassHelperServer\
+├── node.exe              内置 Node 运行时
+├── server\dist\          后端程序（入口 index.js）
+├── server\prisma\        迁移 SQL（首启动自动执行）
+├── web\                  Web 管理端（由后端托管）
+├── data\                 数据库、课件与其他持久化文件（完整备份另含 .env）
+├── logs\server.log       UTF-8 日志（含请求耗时）
+├── .env                  全部配置
+├── start.cmd / stop.cmd / restart.cmd / status.cmd
+└── install-service.cmd / uninstall-service.cmd
+```
+
+常用命令：
+
+```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   :: 删除计划任务
+```
+
+### 1.4 升级
+
+1. `stop.cmd` 停止服务
+2. 备份 `data` 目录
+3. 运行新版本安装程序（**覆盖安装会保留原有 `.env`，JWT 密钥与端口设置不变，用户无需重新登录**）
+4. `start.cmd` 启动（数据库结构如变更，会在首启动时自动补迁移）
+
+### 1.5 卸载
+
+开始菜单 → 卸载（或 `uninstall.exe`，静默：`uninstall.exe /S`）。
+
+卸载会停止服务、删除快捷方式与注册表项、删除程序文件，并把 `data` 目录重命名为
+**`data.backup` 保留**，避免误删数据库；确认不需要后再手动删除。
+
+---
+
+## 二、Docker + MySQL（形态 B，云部署推荐）
+
+> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
+> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。
+
+```bash
+cp deploy/.env.example deploy/.env
+# 生成 JWT 密钥并填入 deploy/.env
+node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+
+docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
+```
+
+组成：
+
+| 服务      | 作用                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `db`      | MySQL 8.4（utf8mb4、数据卷 `db-data`）                               |
+| `migrate` | 一次性任务：安装 mariadb 适配器并执行 `prisma migrate deploy`        |
+| `server`  | 后端 + Web 管理端（多阶段构建，仅含生产依赖），暴露 `${SERVER_PORT}` |
+
+要点：
+
+- 服务端容器 `NODE_ENV=production` + `STARTUP_DB_CHECK=true`：**数据库不可用会拒绝启动**
+  （避免带病对外服务）；健康检查打 `/readyz`。
+- 数据卷：MySQL 用 `db-data`；若坚持用 SQLite，把 `/app/data` 挂成卷即可（见 Dockerfile 注释）。
+- 首次启动会按 `INITIAL_ADMIN_USERNAME/PASSWORD` 创建管理员（请在部署后立即改密码）。
+- 反向代理上启用 HTTPS：见 `deploy/nginx.conf`，并在服务端环境变量中设置
+  `TRUST_PROXY=1`、`CORS_ORIGIN=https://你的域名`。
+
+### 2.1 单容器变体（SQLite，推荐给内存小的机器 / 与别的服务共用一台机器）
+
+`deploy/docker-compose.sqlite.yml` 只跑**服务端一个容器**，不额外起 MySQL：数据落在 Docker 卷
+`classhelper-data` 的 `/app/data/classhelper.db`，首次启动由 `AUTO_MIGRATE=true` 自动建表并创建管理员
+（`packages/server/src/lib/db-bootstrap.ts` 的"空数据卷"分支）。
+
+```bash
+cp deploy/.env.sqlite.example deploy/.env.sqlite   # 填 JWT_SECRET、管理员密码、端口
+docker compose -f deploy/docker-compose.sqlite.yml --env-file deploy/.env.sqlite up -d --build
+```
+
+适用场景与注意点：
+
+- 机器内存紧张（比如 2G 小机器上还跑着别的服务）时，比 MySQL 变体少一个数据库进程；
+- 端口用 `SERVER_PORT` 指定，**别抢占 80/443**（那通常是同机反代占用的）；
+- 生产自检会拒绝 `dev.db` 与过短的 `JWT_SECRET`，因此 `DATABASE_URL` 必须是绝对路径且不含 `dev.db`；
+- 备份就是整个卷：`docker run --rm -v classhelper-sqlite_classhelper-data:/data -v "$PWD":/backup alpine tar czf /backup/classhelper-db.tar.gz -C /data .`
+
+> `deploy/Dockerfile` 的构建阶段会先跑 `pnpm --filter @classhelper/server run db:generate`：
+> 生成产物 `packages/server/src/generated/prisma` 是 gitignored 的，而 `--ignore-scripts` 跳过了
+> postinstall，少了这一步 `tsc` 会直接编译失败。
+
+---
+
+## 三、Linux 部署（形态 C，推荐一键安装器）
+
+适用：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky / AlmaLinux，任何有 systemd 的服务器
+（容器环境用下面的 Docker 形态）。**完整指南见 [linux-deploy.md](linux-deploy.md)**，这里是速查。
+
+### 3.1 一键安装（推荐）
+
+Linux 包由 GitHub Actions 在 ubuntu runner 上构建（平台相关的依赖只能在 Linux 上装），
+产物挂在 Release 上；也可以本地 `pnpm dist:server:linux` 后把 tar.gz 拷到服务器。
+安装器脚本两个文件都在仓库的 `deploy/` 下：
+
+```bash
+# 开发机：做出 Linux 包并连同脚本一起拷到服务器
+pnpm dist:server:linux
+scp releases/server/*/linux-x64/classhelper-server-linux-x64-*.tar.gz deploy/install.sh deploy/verify-linux.sh \
+    root@<服务器>:/tmp/
+
+# 服务器上
+bash /tmp/install.sh --check            # 只体检（不需要 root，不改动系统）
+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.2.tar.gz
+```
+
+安装器做的事：识别发行版与包管理器补依赖 → 建系统用户 `classhelper` → 下载包并校验 sha256 →
+铺文件（`server/` `web/` `node_modules/` `tools/` `bin/`）→ 下载内置 Node 运行时 →
+写 `/etc/classhelper/config.env`（随机 `JWT_SECRET`，权限 600）→ 装 systemd 单元与
+`/usr/local/bin/classhelper` → 启动并轮询 `/healthz` 通过为止。全过程写
+`/var/log/classhelper/install.log`。
+
+重跑就是**覆盖安装**：`config.env`（含密钥）与 `data/` 保留，已登录用户不会被踢下线。
+
+### 3.2 安装后的布局与运维
+
+```
+/opt/classhelper/              程序、node_modules、内置 Node、data/、tools/、bin/
+/etc/classhelper/config.env    唯一配置真身（600）；安装目录里的 .env 是指向它的软链
+/var/log/classhelper/          install.log + audit.log
+/var/backups/classhelper/      备份与程序快照（回滚用）
+```
+
+> 为什么安装目录的 `.env` 是软链：Web 端「数据库管理 → 一键切换」改写的是 `<安装目录>/.env`，
+> 而 systemd 用 `EnvironmentFile=` 注入同一份配置；两处不是同一个文件时，切换会"看起来成功、
+> 重启后又连回旧库"。软链把两者收成一份真身（`classhelper doctor` 会检查它）。
+
+日常运维全部走 `classhelper`（`classhelper help` 看全部）：
+
+| 事项   | 命令                                                                                     |
+| ------ | ---------------------------------------------------------------------------------------- |
+| 状态   | `classhelper status [--json]`                                                            |
+| 体检   | `classhelper doctor`（权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份）             |
+| 改密码 | `classhelper password [用户名]`（交互输入、不回显、不进 shell history）                  |
+| 备份   | `classhelper backup`；每日自动：`classhelper backup schedule daily`                      |
+| 升级   | `classhelper upgrade [--check]`（下载 + 校验 sha256 + 备份 + 替换 + 探针，失败自动回滚） |
+| 回滚   | `classhelper rollback [--list]`                                                          |
+| 日志   | `classhelper logs -f`                                                                    |
+| 改配置 | `classhelper config set KEY VALUE` / `config show` / `port 8080`                         |
+| 换密钥 | `classhelper key rotate`（所有用户需重新登录）                                           |
+| 卸载   | `classhelper uninstall`（默认保留配置、数据与备份）                                      |
+| 服务   | `classhelper start｜stop｜restart｜reload`                                               |
+
+### 3.3 手动部署（不想用安装器 / 没有 systemd）
+
+没有 systemd 的容器里可以用安装器的"只铺文件"模式，再自己托管进程：
+
+```bash
+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
+```
+
+完全手工也可以（等价步骤，便于排查）：解包后把 `server/` `web/` `node_modules/` `tools/` 铺到安装目录，
+配置写到 `/etc/classhelper/config.env`（`JWT_SECRET` 用 `openssl rand -hex 48`），再用
+`deploy/classhelper.service` 模板生成单元 —— 注意模板有 5 个占位符
+（`__NODE__` `__DIR__` `__USER__` `__CONFIG__` `__CONFIGDIR__`）：
+
+```bash
+sudo sed -e "s#__NODE__#/opt/classhelper/runtime/node/bin/node#" \
+         -e "s#__DIR__#/opt/classhelper#" -e "s#__USER__#classhelper#" \
+         -e "s#__CONFIG__#/etc/classhelper/config.env#" -e "s#__CONFIGDIR__#/etc/classhelper#" \
+  deploy/classhelper.service > /tmp/classhelper.service
+sudo install -m 644 /tmp/classhelper.service /etc/systemd/system/classhelper.service
+sudo systemctl daemon-reload && sudo systemctl enable --now classhelper
+```
+
+### 3.4 Nginx + HTTPS
+
+```bash
+sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
+sudo nano /etc/nginx/conf.d/classhelper.conf     # 改 server_name 与证书路径
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+`deploy/nginx.conf` 已经处理了最容易踩的两点：`/socket.io/` 的 WebSocket 升级头，
+以及 `X-Forwarded-For/X-Forwarded-Proto` 透传（配合配置里的 `TRUST_PROXY=1`，限流才会按真实 IP 统计）。
+用 certbot 签证书：
+
+```bash
+sudo apt install -y certbot python3-certbot-nginx
+sudo certbot --nginx -d class.example.com
+```
+
+### 3.5 验收
+
+```bash
+sudo bash /tmp/verify-linux.sh --admin-password-stdin <<< 'StrongPass!2026'
+# 追加升级 / 回滚链路（会真的替换一次程序文件）：
+sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x64-1.0.1.tar.gz \
+  --admin-password-stdin <<< 'StrongPass!2026'
+```
+
+覆盖安装结果、服务探针、API 登录、改密（含审计与回滚）、备份、配置读写、key rotate、
+升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
+[linux-deploy.md](linux-deploy.md) 第 10 节。
+
+---
+
+## 四、手动部署（形态 D）
+
+目标机已有 Node.js（≥ 20.19）时，不需要任何安装包，直接在仓库里构建后跑：
+
+```bash
+pnpm install
+pnpm build:shared
+pnpm --filter @classhelper/server build
+pnpm --filter @classhelper/web-admin build
+```
+
+按目标机的实际情况写好 `packages/server/.env`（端口、数据库、密钥、跨域），然后：
+
+```bash
+pnpm --filter @classhelper/server start      # 或 node packages/server/dist/index.js
+```
+
+> 想把这份构建结果整体拷到另一台机器，就自己带上这四样：
+> `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 首次启动自动建表 + 建管理员）
+- 显式迁移：`pnpm db:migrate` / `npx prisma migrate deploy`（MySQL 必须走这条）
+
+---
+
+## 五、环境变量清单
+
+| 变量                                                | 默认                   | 说明                                                        |
+| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
+| `NODE_ENV`                                          | `development`          | `production` 会启用生产校验、HSTS、更严的限流               |
+| `HOST` / `PORT`                                     | `0.0.0.0` / `4000`     | 监听地址与端口                                              |
+| `DATABASE_PROVIDER`                                 | `sqlite`               | `sqlite` 或 `mysql`                                         |
+| `DATABASE_URL`                                      | `file:./prisma/dev.db` | SQLite 相对路径以 `server` 根为基准；MySQL 用连接串         |
+| `AUTO_MIGRATE`                                      | `false`                | SQLite 启动时补跑随包迁移，空库另创建管理员                 |
+| `JWT_SECRET`                                        | —                      | **必填**，至少 16 位；生产需 ≥32 位且拒绝示例密钥           |
+| `JWT_EXPIRES_IN`                                    | `7d`                   | 令牌有效期                                                  |
+| `CORS_ORIGIN`                                       | `*`                    | 允许来源，多个用逗号分隔；生产建议写具体域名                |
+| `TRUST_PROXY`                                       | `false`                | 反向代理层数（Nginx 填 `1`），影响限流与日志中的真实 IP     |
+| `RATE_LIMIT_ENABLED`                                | `true`                 | 通用限流（生产 600 次/5 分钟）+ 登录限流（20 次/10 分钟）   |
+| `STARTUP_DB_CHECK`                                  | `true`                 | 启动校验数据库；生产不可用时直接退出                        |
+| `PID_FILE`                                          | —                      | PID 文件路径（安装包启停脚本依赖），相对 `server` 根        |
+| `WEB_DIST_DIR`                                      | 自动探测               | Web 管理端产物目录（`../web-admin/dist` 或 `./web`）        |
+| `LOG_LEVEL`                                         | `info`                 | `debug` / `info` / `warn` / `error`                         |
+| `DEFAULT_CLASS_PASSWORD`                            | `123456`               | 新建班级时班级账号（ClassHelper 班级端登录）的默认密码      |
+| `DEFAULT_TEACHER_PASSWORD`                          | `123456`               | 新增/重置教师账号的默认密码（管理员录入教师用）             |
+| `COURSEWARE_DIR`                                    | 默认 data/courseware   | 课件文件实体目录；需纳入完整备份                            |
+| `TERM_START_DATE`                                   | —                      | 开学日环境兜底；界面全校/班级设置与逐周区间优先，见课表帮助 |
+| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123`   | 空库首启动创建的管理员                                      |
+
+---
+
+## 六、运维
+
+### 6.1 探针与监控
+
+| 端点          | 用途                                                 |
+| ------------- | ---------------------------------------------------- |
+| `/healthz`    | 存活探针：进程活着即 200（容器 liveness / 守护进程） |
+| `/readyz`     | 就绪探针：数据库可连才 200，否则 503（负载均衡摘流） |
+| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长             |
+
+### 6.2 日志
+
+- 输出到 stdout/stderr，安装包形态由启停脚本重定向到 `logs\server.log`（UTF-8）。
+- 访问日志含方法、路径、状态码与耗时；5xx 记 error、4xx 记 warn。
+- 容器形态建议交给 Docker 日志驱动或采集到 ELK/Loki。
+
+### 6.3 备份与恢复
+
+| 形态   | 备份                                                                   | 恢复                     |
+| ------ | ---------------------------------------------------------------------- | ------------------------ |
+| SQLite | 停止服务后复制 `data/classhelper.db`（Linux：`/opt/classhelper/data`） | 替换该文件后启动         |
+| MySQL  | `mysqldump -u classhelper -p classhelper > backup.sql`                 | `mysql ... < backup.sql` |
+
+课件文件实体不在 JSON/SQL 数据快照里，完整备份还需 `data/courseware` 或 `COURSEWARE_DIR` 指定目录。
+
+建议：每日自动备份 + 保留 7 份；变更 `JWT_SECRET` 会导致所有用户重新登录，请勿在无必要时更换。
+
+### 6.4 安全清单（上线前逐项确认）
+
+- [ ] 修改 `admin` 与教师账号的默认密码
+- [ ] `JWT_SECRET` 使用随机值（≥48 字节），且妥善保管
+- [ ] 公网访问必须经 HTTPS 反向代理（`deploy/nginx.conf` 可直接用）
+- [ ] `CORS_ORIGIN` 收敛到具体域名，不要留 `*`
+- [ ] `TRUST_PROXY=1` 并确认限流按真实 IP 生效（`/api` 响应头有 `RateLimit`）
+- [ ] 数据库账号使用最小权限，仅授权业务库
+- [ ] 定期备份并验证可恢复
+- [ ] 关注 `/readyz` 与 `logs/server.log` 的 5xx
+
+---
+
+## 七、故障排查
+
+| 现象                                        | 排查方向                                                                                                                                                                                                       |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 浏览器打不开管理端                          | `status.cmd`；`logs\server.log` 是否有启动报错；端口是否被占用                                                                                                                                                 |
+| 启动即退出（生产）                          | 数据库不可用（`DATABASE_URL`/MySQL 未就绪）或 `JWT_SECRET` 未按生产要求配置                                                                                                                                    |
+| 页面能开但接口 401                          | 令牌过期或更换过 `JWT_SECRET`，重新登录                                                                                                                                                                        |
+| 限流误伤（自己人）                          | 反向代理未设 `TRUST_PROXY=1`，导致所有请求都算作代理 IP                                                                                                                                                        |
+| 实时推送不生效                              | 反向代理未放行 `/socket.io/` 的 WebSocket 升级（见 nginx 样例）                                                                                                                                                |
+| 安装后服务没起来                            | 查看 `logs\server.error.log`；`start.cmd` 会输出就绪等待结果                                                                                                                                                   |
+| 数据库文件损坏                              | 从备份恢复 `data/classhelper.db`；SQLite 场景请确保同一时间只有一个服务实例                                                                                                                                    |
+| 升级后需要重新登录                          | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限                                                                                                                                  |
+| 报 `does not provide an export named ...`   | 安装包内的 `node_modules/@classhelper/shared/dist` 是旧构建（打包机没有先构建 shared）。重新执行 `pnpm dist:server`，该脚本会先构建 shared/server/web 并校验产物新鲜度                                         |
+| 报 `node.exe` 不是有效应用 / 服务启动即退出 | 安装包内置的 `node.exe` 被误打成 Electron 可执行文件（打包机在 Electron 宿主里跑 pnpm 时会取到 `process.execPath`）。已由 `scripts/lib/node-runtime.mjs` 修正；可用 `install\node.exe -v` 确认能打印 Node 版本 |
+| **Linux**：`systemctl start` 后立刻退出     | `journalctl -u classhelper -n 50`；常见原因：`.env` 里 `JWT_SECRET` 为空/太短、`node` 路径在 unit 里不对（脚本用 `command -v node` 的结果）、`data/` 不可写（`chown classhelper:classhelper`）                 |
+| **Linux**：403/500 且日志提示 `EACCES`      | `ProtectSystem=full` 下服务只能写 `ReadWritePaths`；若自定义了数据目录，记得同步改 unit 里的这两项                                                                                                             |
+| **Linux**：`npm install` 报网络/代理错误    | 目标机需要能访问 npm registry；离线环境可在别的机器 `npm install --omit=dev` 后把整个 `node_modules` 一起拷过去                                                                                                |
+| **Linux**：SQLite 提示 `database is locked` | 同一数据库文件只允许一个服务实例；确认没有重复启动（`systemctl status` + `pgrep -af 'server/dist/index.js'`），需要并发就换 MySQL                                                                              |
+
+---
+
+## 八、性能与容量参考
+
+- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），接口与实时推送均已通过端到端验收。
+- 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
+  当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
+- 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），
+  成绩页含 ECharts 独立分包，按需加载。

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,133 @@
+---
+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 班级端）
+
+Web「客户端」可缓存安装包并推送目标版本，客户端从本服务下载并校验 SHA256，按立即、放学后或空闲策略安装。管理页显示下载字节与百分比、校验中、等待安装、安装中和失败原因。安装前先上报「正在更新，将会短暂离线」，新版上线后的心跳确认「已完成更新，版本 xxxx」；仅离线不会被判为更新成功。关闭自动更新的客户端会显示原因。
+
+从 Releases 取新的 `setup.exe` 覆盖安装即可，配置在 `%APPDATA%`，不受影响。
+
+> 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录，
+> 用户打开的还是旧的 `resources/app.asar` —— 表现为"改了但界面不生效"。
+> 停止客户端后使用新安装程序覆盖安装，再对**实际安装副本**跑一次打包版冒烟确认。
+
+## 升级前的准备清单
+
+- [ ] 备份数据库、配置与课件实体（完整复制 `data`/`COURSEWARE_DIR`，数据库用对应快照或 dump）；
+- [ ] 记下当前版本号，必要时能回滚到它；
+- [ ] 挑一个没课的时间 —— 升级期间实时推送会中断；
+- [ ] 升级后确认 `/readyz` 是 200，并且客户端顶栏的实时通道显示"已连接"。
+
+## 给维护者
+
+打版本、出安装包、发 Release 的完整流程见[版本迭代与发布](../dev/release.md)。
+
+### 客户端远控与更新修复
+
+先升级服务端，再推送修复后的客户端安装包。服务端兼容旧客户端读取顶层心跳字段，旧设备也可领取更新；第一次升级前仍遵循旧客户端的空闲安装条件。新客户端支持立即、放学后和空闲安装三种策略。放学后取指定的最早时间与当天最后一节课结束时间中的较晚者；设备离线时在再次上线后处理。

docs/mysql.md

@@ -1,90 +0,0 @@
-# MySQL 切换指南
-
-本项目默认使用 **SQLite（libSQL 内嵌模式）** 跑本地开发，数据模型与访问层已按
-MySQL 兼容方式设计，可平滑切换到云端 MySQL / MariaDB 统一存储。
-
-## 为什么默认是 SQLite
-
-- 本地零依赖即可跑通全部功能（无需安装数据库服务）
-- `schema.prisma` 刻意只使用跨库通用类型
-  （`String` / `Int` / `Float` / `Boolean` / `DateTime`，无 `enum`、无 `@db.*` 原生类型）
-
-## 设计上的兼容约定
-
-| 约定                                  | 说明                                                                                                                              |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| 不使用 Prisma `enum`                  | 角色（`ADMIN/TEACHER/STUDENT`）与优先级（`LOW/NORMAL/HIGH/URGENT`）以 `String` 存储，由 zod 在 API 层校验，两种数据库行为完全一致 |
-| 主键为 `String @default(cuid())`      | 不依赖自增，便于多端离线生成与合并                                                                                                |
-| 时间统一 `DateTime`                   | 由应用层与驱动适配器负责时区，不使用数据库原生时间函数                                                                            |
-| 唯一约束仅使用 `@@unique` / `@unique` | SQLite 与 MySQL 语义一致                                                                                                          |
-| 级联删除使用 Prisma 的 `onDelete`     | 由 Prisma 生成对应外键动作                                                                                                        |
-
-## 切换步骤
-
-### 1. 修改 provider
-
-```bash
-# 自动把 prisma/schema.prisma 的 provider 改成 mysql
-node scripts/use-database.mjs mysql
-```
-
-### 2. 安装 MySQL 驱动适配器
-
-Prisma 7 要求所有数据库都通过 driver adapter 接入，MySQL 对应 `@prisma/adapter-mariadb`
-（该适配器基于 `mariadb` 驱动，兼容 MySQL 8）。
-
-```bash
-pnpm --filter @classhelper/server add @prisma/adapter-mariadb
-```
-
-`packages/server/src/lib/db.ts` 已经内置分支：当 `DATABASE_PROVIDER=mysql` 时会动态加载该适配器，
-因此只需要安装依赖 + 配置环境变量，服务端代码无需改动。
-
-### 3. 配置环境变量
-
-编辑 `packages/server/.env`：
-
-```dotenv
-DATABASE_PROVIDER=mysql
-DATABASE_URL="mysql://classhelper:your-password@127.0.0.1:3306/classhelper"
-```
-
-> 云端部署时把 `127.0.0.1` 换成云数据库内网/公网地址；
-> 生产环境请同时修改 `JWT_SECRET` 与 `CORS_ORIGIN`。
-
-### 4. 重建迁移并生成客户端
-
-SQLite 与 MySQL 的 DDL 方言不同，**必须重新生成迁移文件**：
-
-```bash
-# 删除 SQLite 迁移历史（迁移文件是方言相关的）
-rm -rf packages/server/prisma/migrations
-# 重新生成并应用（需要目标库可连接，且账号有建表权限）
-pnpm db:migrate
-# 初始化演示数据
-pnpm db:seed
-```
-
-也可以先只生成 SQL 供 DBA 审核：
-
-```bash
-pnpm --filter @classhelper/server exec prisma migrate dev --create-only --name init_mysql
-```
-
-### 5. 回到 SQLite
-
-```bash
-node scripts/use-database.mjs sqlite
-# 同步 .env：DATABASE_PROVIDER=sqlite、DATABASE_URL="file:./prisma/dev.db"
-rm -rf packages/server/prisma/migrations   # 若之前已切换成 MySQL 迁移
-pnpm db:migrate
-```
-
-## 生产部署注意事项
-
-1. **连接池**：Prisma 7 的 driver adapter 使用底层驱动（`mariadb`）的连接池设置，
-   与 Prisma 6 默认值不同（例如默认无连接超时）。建议通过适配器参数显式设置连接上限与时区。
-2. **时区**：`Grade.publishedAt`、`Homework.dueAt` 等字段建议在数据库会话中统一为 UTC，
-   三端展示时再按本地时区格式化（前端使用 `@classhelper/shared` 的 `formatDate`）。
-3. **迁移部署**：CI/CD 中使用 `prisma migrate deploy`（对应 `pnpm db:deploy`）而不是 `migrate dev`。
-4. **备份**：切换云数据库后，`packages/server/prisma/dev.db` 不再被使用，可从 `.gitignore` 之外移除。

docs/production.md

@@ -1,238 +0,0 @@
-# 生产部署指南
-
-本文档覆盖三种上线形态，按适用场景选择：
-
-| 形态                  | 适用场景                                     | 产物                                                   | 本机验证情况                           |
-| --------------------- | -------------------------------------------- | ------------------------------------------------------ | -------------------------------------- |
-| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `release-server/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
-| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`      | ⚠️ 文件已提供，本机无 Docker 未实测    |
-| **C. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | `pnpm dist:server` 的免安装目录                        | ✅ 免安装目录已实测（54 项端到端）     |
-
----
-
-## 一、Windows 安装包（形态 A）
-
-### 1.1 生成安装包
-
-```bash
-pnpm dist:server          # 首次会执行一次 npm install（约 2 分钟）
-pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳过 npm install
-```
-
-产物：
-
-| 路径                                                  | 说明                                            |
-| ----------------------------------------------------- | ----------------------------------------------- |
-| `release-server/classhelper-server/`                  | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
-| `release-server/班级小助手服务端-0.1.0-x64-setup.exe` | 安装程序（约 34 MB，NSIS）                      |
-
-打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
-生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
-
-### 1.2 安装
-
-双击安装程序即可，**无需管理员权限**（当前用户级安装）：
-
-- 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
-- 静默安装：`"班级小助手服务端-0.1.0-x64-setup.exe" /S`
-- 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
-- 桌面：`班级小助手服务端.lnk`（打开管理端）
-- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
-- 卸载信息注册到「应用和功能」
-
-安装完成后服务会自动启动并完成首次初始化：
-
-1. 数据库为空 → 自动执行随包迁移（`AUTO_MIGRATE=true`）建表
-2. 自动创建管理员账号（默认 `admin / admin123`，日志中会提示尽快修改）
-3. 打开 http://127.0.0.1:4000/ 即为 Web 管理端
-
-### 1.3 目录与配置
-
-```
-%LOCALAPPDATA%\Programs\ClassHelperServer\
-├── node.exe              内置 Node 运行时
-├── server\dist\          后端程序（入口 index.js）
-├── server\prisma\        迁移 SQL（首启动自动执行）
-├── web\                  Web 管理端（由后端托管）
-├── data\                 classhelper.db + server.pid（备份只需复制此目录）
-├── logs\server.log       UTF-8 日志（含请求耗时）
-├── .env                  全部配置
-├── start.cmd / stop.cmd / restart.cmd / status.cmd
-└── install-service.cmd / uninstall-service.cmd
-```
-
-常用命令：
-
-```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   :: 删除计划任务
-```
-
-### 1.4 升级
-
-1. `stop.cmd` 停止服务
-2. 备份 `data` 目录
-3. 运行新版本安装程序（**覆盖安装会保留原有 `.env`，JWT 密钥与端口设置不变，用户无需重新登录**）
-4. `start.cmd` 启动（数据库结构如变更，会在首启动时自动补迁移）
-
-### 1.5 卸载
-
-开始菜单 → 卸载（或 `uninstall.exe`，静默：`uninstall.exe /S`）。
-
-卸载会停止服务、删除快捷方式与注册表项、删除程序文件，并把 `data` 目录重命名为
-**`data.backup` 保留**，避免误删数据库；确认不需要后再手动删除。
-
----
-
-## 二、Docker + MySQL（形态 B，云部署推荐）
-
-> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
-> 目录布局、迁移方式与服务端完全一致）。
-
-```bash
-cp deploy/.env.example deploy/.env
-# 生成 JWT 密钥并填入 deploy/.env
-node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
-
-docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
-```
-
-组成：
-
-| 服务      | 作用                                                                 |
-| --------- | -------------------------------------------------------------------- |
-| `db`      | MySQL 8.4（utf8mb4、数据卷 `db-data`）                               |
-| `migrate` | 一次性任务：安装 mariadb 适配器并执行 `prisma migrate deploy`        |
-| `server`  | 后端 + Web 管理端（多阶段构建，仅含生产依赖），暴露 `${SERVER_PORT}` |
-
-要点：
-
-- 服务端容器 `NODE_ENV=production` + `STARTUP_DB_CHECK=true`：**数据库不可用会拒绝启动**
-  （避免带病对外服务）；健康检查打 `/readyz`。
-- 数据卷：MySQL 用 `db-data`；若坚持用 SQLite，把 `/app/data` 挂成卷即可（见 Dockerfile 注释）。
-- 首次启动会按 `INITIAL_ADMIN_USERNAME/PASSWORD` 创建管理员（请在部署后立即改密码）。
-- 反向代理上启用 HTTPS：见 `deploy/nginx.conf`，并在服务端环境变量中设置
-  `TRUST_PROXY=1`、`CORS_ORIGIN=https://你的域名`。
-
----
-
-## 三、手动部署（形态 C）
-
-```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`（端口、数据库、密钥、跨域），然后：
-
-```cmd
-start.cmd      :: Windows
-# 或直接：node server/dist/index.js   （Linux/macOS 用系统 node）
-```
-
-数据库初始化二选一：
-
-- 让服务自愈：`.env` 中 `AUTO_MIGRATE=true`（SQLite 首次启动自动建表 + 建管理员）
-- 显式迁移：`pnpm db:migrate` / `npx prisma migrate deploy`（MySQL 必须走这条）
-
----
-
-## 四、环境变量清单
-
-| 变量                                                | 默认                   | 说明                                                      |
-| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
-| `NODE_ENV`                                          | `development`          | `production` 会启用生产校验、HSTS、更严的限流             |
-| `HOST` / `PORT`                                     | `0.0.0.0` / `4000`     | 监听地址与端口                                            |
-| `DATABASE_PROVIDER`                                 | `sqlite`               | `sqlite` 或 `mysql`                                       |
-| `DATABASE_URL`                                      | `file:./prisma/dev.db` | SQLite 相对路径以 `server` 根为基准；MySQL 用连接串       |
-| `AUTO_MIGRATE`                                      | `false`                | SQLite 空库时自动执行随包迁移并创建管理员                 |
-| `JWT_SECRET`                                        | —                      | **必填**，≥32 位；生产环境仍为示例值会拒绝启动            |
-| `JWT_EXPIRES_IN`                                    | `7d`                   | 令牌有效期                                                |
-| `CORS_ORIGIN`                                       | `*`                    | 允许来源，多个用逗号分隔；生产建议写具体域名              |
-| `TRUST_PROXY`                                       | `false`                | 反向代理层数（Nginx 填 `1`），影响限流与日志中的真实 IP   |
-| `RATE_LIMIT_ENABLED`                                | `true`                 | 通用限流（生产 600 次/5 分钟）+ 登录限流（20 次/10 分钟） |
-| `STARTUP_DB_CHECK`                                  | `true`                 | 启动校验数据库；生产不可用时直接退出                      |
-| `PID_FILE`                                          | —                      | PID 文件路径（安装包启停脚本依赖），相对 `server` 根      |
-| `WEB_DIST_DIR`                                      | 自动探测               | Web 管理端产物目录（`../web-admin/dist` 或 `./web`）      |
-| `LOG_LEVEL`                                         | `info`                 | `debug` / `info` / `warn` / `error`                       |
-| `DEFAULT_STUDENT_PASSWORD`                          | `123456`               | 新增学生的默认密码                                        |
-| `TERM_START_DATE`                                   | —                      | 第 1 教学周的周一，用于"当前周次"与课表默认视图           |
-| `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123`   | 空库首启动创建的管理员                                    |
-
----
-
-## 五、运维
-
-### 5.1 探针与监控
-
-| 端点          | 用途                                                 |
-| ------------- | ---------------------------------------------------- |
-| `/healthz`    | 存活探针：进程活着即 200（容器 liveness / 守护进程） |
-| `/readyz`     | 就绪探针：数据库可连才 200，否则 503（负载均衡摘流） |
-| `/api/health` | 详情：环境、数据库、已挂载模块、运行时长             |
-
-### 5.2 日志
-
-- 输出到 stdout/stderr，安装包形态由启停脚本重定向到 `logs\server.log`（UTF-8）。
-- 访问日志含方法、路径、状态码与耗时；5xx 记 error、4xx 记 warn。
-- 容器形态建议交给 Docker 日志驱动或采集到 ELK/Loki。
-
-### 5.3 备份与恢复
-
-| 形态   | 备份                                                   | 恢复                     |
-| ------ | ------------------------------------------------------ | ------------------------ |
-| SQLite | 停止服务后复制 `data/classhelper.db`                   | 替换该文件后启动         |
-| MySQL  | `mysqldump -u classhelper -p classhelper > backup.sql` | `mysql ... < backup.sql` |
-
-建议：每日自动备份 + 保留 7 份；变更 `JWT_SECRET` 会导致所有用户重新登录，请勿在无必要时更换。
-
-### 5.4 安全清单（上线前逐项确认）
-
-- [ ] 修改 `admin` 与教师账号的默认密码
-- [ ] `JWT_SECRET` 使用随机值（≥48 字节），且妥善保管
-- [ ] 公网访问必须经 HTTPS 反向代理（`deploy/nginx.conf` 可直接用）
-- [ ] `CORS_ORIGIN` 收敛到具体域名，不要留 `*`
-- [ ] `TRUST_PROXY=1` 并确认限流按真实 IP 生效（`/api` 响应头有 `RateLimit`）
-- [ ] 数据库账号使用最小权限，仅授权业务库
-- [ ] 定期备份并验证可恢复
-- [ ] 关注 `/readyz` 与 `logs/server.log` 的 5xx
-
----
-
-## 六、故障排查
-
-| 现象                                        | 排查方向                                                                                                                                                                                                       |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 浏览器打不开管理端                          | `status.cmd`；`logs\server.log` 是否有启动报错；端口是否被占用                                                                                                                                                 |
-| 启动即退出（生产）                          | 数据库不可用（`DATABASE_URL`/MySQL 未就绪）或 `JWT_SECRET` 未按生产要求配置                                                                                                                                    |
-| 页面能开但接口 401                          | 令牌过期或更换过 `JWT_SECRET`，重新登录                                                                                                                                                                        |
-| 限流误伤（自己人）                          | 反向代理未设 `TRUST_PROXY=1`，导致所有请求都算作代理 IP                                                                                                                                                        |
-| 实时推送不生效                              | 反向代理未放行 `/socket.io/` 的 WebSocket 升级（见 nginx 样例）                                                                                                                                                |
-| 安装后服务没起来                            | 查看 `logs\server.error.log`；`start.cmd` 会输出就绪等待结果                                                                                                                                                   |
-| 数据库文件损坏                              | 从备份恢复 `data/classhelper.db`；SQLite 场景请确保同一时间只有一个服务实例                                                                                                                                    |
-| 升级后需要重新登录                          | 说明 `.env` 被覆盖（JWT 密钥变化）；覆盖安装应保留 `.env`，请检查安装目录权限                                                                                                                                  |
-| 报 `does not provide an export named ...`   | 安装包内的 `node_modules/@classhelper/shared/dist` 是旧构建（打包机没有先构建 shared）。重新执行 `pnpm dist:server`，该脚本会先构建 shared/server/web 并校验产物新鲜度                                         |
-| 报 `node.exe` 不是有效应用 / 服务启动即退出 | 安装包内置的 `node.exe` 被误打成 Electron 可执行文件（打包机在 Electron 宿主里跑 pnpm 时会取到 `process.execPath`）。已由 `scripts/lib/node-runtime.mjs` 修正；可用 `install\node.exe -v` 确认能打印 Node 版本 |
-
----
-
-## 七、性能与容量参考
-
-- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。
-- 多校区 / 高并发建议切 MySQL，并横向扩容服务端（Socket.IO 需要配置 Redis adapter 才能多实例广播，
-  当前为单实例广播；如需多实例请参考 `packages/server/src/realtime/socket.ts` 引入 `@socket.io/redis-adapter`）。
-- 静态资源已设置 immutable 长缓存 + gzip；Web 管理端为 SPA，首屏包体约 900 KB（gzip 约 290 KB），
-  成绩页含 ECharts 独立分包，按需加载。

docs/reference.md

@@ -0,0 +1,33 @@
+---
+title: 功能与源码索引
+description: 当前功能说明、开发契约与实现入口，避免重复维护多份产品说明书。
+---
+
+# 功能与源码索引
+
+本文为现行文档入口。功能规则在对应章节维护；源码行为发生变化时，同步修改对应章节。
+旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。
+
+| 主题               | 文档                                                                                                     | 工作区源码入口                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| 架构与模块         | [架构总览](dev/architecture.md)                                                                          | `server/src/modules/registry.ts`                                           |
+| 日课表、作息与轮换 | [课表](app/schedules.md)                                                                                 | `server/src/lib/class-plan.ts`、`modules/class-plans/`                     |
+| 学生、教师、班级   | [班级、学生与教师](app/classes.md)                                                                       | `server/src/lib/access.ts`、`modules/students/`                            |
+| 权限组与岗位范围   | [角色与权限](dev/permissions.md)                                                                         | `shared/src/permissions.ts`、`server/src/lib/permission-scope.ts`          |
+| 作业               | [作业](app/homeworks.md)                                                                                 | `server/src/modules/homeworks/`                                            |
+| 通知与叫人         | [通知](app/notifications.md)、[叫人](app/calls.md)                                                       | `server/src/modules/notifications/`、`calls/`                              |
+| 课件               | [课件上传与传输](app/courseware.md)                                                                      | 三端 `courseware` 模块与 `shared/src/courseware.ts`                        |
+| 成绩与隐私         | [成绩](app/grades.md)                                                                                    | `server/src/modules/grades/`                                               |
+| 经典与自定义常驻岛 | [灵动岛](app/island.md)                                                                                  | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` |
+| 导入               | [表格与课表导入](app/imports.md)                                                                         | `server/src/modules/imports/`、`class-plans/profile-import.service.ts`     |
+| API 与实时         | [REST API](dev/api.md)、[实时事件](dev/realtime.md)                                                      | `server/src/modules/`、`realtime/`、`shared/src/constants.ts`              |
+| 数据模型与迁移     | [数据模型](dev/data-model.md)                                                                            | `server/prisma/schema.prisma`、`migrations/`                               |
+| 数据库管理         | [数据库管理](management/database.md)、[MySQL](management/mysql.md)                                       | `server/src/lib/snapshot.ts`、`modules/database/`                          |
+| 安装与升级         | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs`                                       |
+| 验证与发布         | [验收](dev/testing.md)、[发布](dev/release.md)                                                           | 根 `package.json`、`scripts/`、`.github/workflows/`                        |
+| 当前实现约定       | [实现约定](dev/implementation.md)                                                                        | 课表、升级、岛、课件与设备维护的关键边界                                   |
+
+表中的包路径均相对仓库 `packages/`；脚本和部署目录相对仓库根。
+源码总入口：[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。
+代理工程规则见 [AGENTS.md](https://github.com/LoveChengke/ClassHelper/blob/master/AGENTS.md)。
+ClassIsland 仅保留离线 JSON 导入与设计参考，在线联动插件及相关接口已退役。