chore(release): 重打包并提交 1.4.0 交付物

- 增加课件上传、班级可见范围、设备补收与传输进度
- 整合自定义灵动岛编辑器和相关客户端交互
- 同步三端契约、数据库迁移、部署配置与隔离回归
- 按源码统一文档与官网说明，移除过时任务书和审查记录
- 保持产品版本为 1.4.0

.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

.gitignore

@@ -39,7 +39,7 @@ eslint-report.json
 .DS_Store
 Thumbs.db
 
-# 参考用的第三方源码包（设计 token 已提取到 docs/winisland-design-tokens.md）
+# 设计参考压缩包（令牌见 docs/dev/winisland-design-tokens.md）
 WinIsland-master.zip
 releases/
 
@@ -48,3 +48,8 @@ releases/
 .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

deploy/Dockerfile

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

deploy/classhelper

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · 运维命令（Linux）
+# ClassHelper · 运维命令（Linux）
 #
 # 安装位置：<安装目录>/bin/classhelper，并在 /usr/local/bin/classhelper 建软链，
 #           因此任何用户在任何目录都能直接敲 `classhelper`。
@@ -284,7 +284,7 @@ svc_restart() {
   fi
 }
 
-# 就绪探针：本地请求**必须**绕开系统代理（否则拿到的是代理返回的 404，见 AGENTS.md §7 第 1 条）
+# 就绪探针：本地请求**必须**绕开系统代理（否则拿到的是代理返回的 404，见 AGENTS.md 的现行工程约定）
 probe_ready() {
   command -v curl >/dev/null 2>&1 || return 1
   curl -fsS --noproxy '*' --max-time 3 -o /dev/null "http://127.0.0.1:$(current_port)/healthz" >/dev/null 2>&1
@@ -668,7 +668,7 @@ EOF
     return 0
   fi
 
-  printf '%s班级小助手服务端%s v%s\n\n' "$C_BOLD" "$C_RESET" "$(current_version)"
+  printf '%sClassHelper 服务端%s v%s\n\n' "$C_BOLD" "$C_RESET" "$(current_version)"
   printf '  %-10s %s\n' "服务状态" "$([ "$active" = "active" ] && printf '%s运行中%s' "$C_GREEN" "$C_RESET" || printf '%s未运行%s' "$C_RED" "$C_RESET")（开机自启：${enabled}）"
   printf '  %-10s %s\n' "健康探针" "$([ "$healthy" = "yes" ] && printf '%s通过%s' "$C_GREEN" "$C_RESET" || printf '%s无响应%s' "$C_RED" "$C_RESET")"
   printf '  %-10s %s\n' "安装形态" "${MODE}"
@@ -1522,7 +1522,7 @@ EOF
 
 cmd_help() {
   cat <<EOF
-${C_BOLD}班级小助手 · 运维命令${C_RESET}
+${C_BOLD}ClassHelper · 运维命令${C_RESET}
 
 用法：classhelper <子命令> [参数]
 
@@ -1534,7 +1534,7 @@ ${C_BOLD}查看与诊断${C_RESET}
 ${C_BOLD}账号${C_RESET}
   password [用户名]              修改密码（默认 admin）；交互输入、不回显、不进历史
   password --list                列出可登录账号与班级账号（含是否已设密码）
-  password --class <班级码>      修改班级密码（学生端用「班级码 + 班级密码」登录）
+  password --class <班级码>      修改班级密码（ClassHelper 班级端用「班级码 + 班级密码」登录）
 
 ${C_BOLD}备份与恢复${C_RESET}
   backup [--note 说明] [--keep N]    备份配置 + 数据库到 ${BACKUP_DIR}

deploy/docker-compose.sqlite.yml

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

deploy/docker-compose.yml

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

deploy/install.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · 服务端 Linux 一键安装器
+# ClassHelper · 服务端 Linux 一键安装器
 #
 # 支持：Ubuntu 20.04+ / Debian 11+ / CentOS 7+ / Rocky Linux / AlmaLinux 8+
 #       （自动识别 apt / yum / dnf；直接安装形态要求 systemd）
@@ -44,6 +44,7 @@
 #     --node-tarball <url|路径>    直接用指定的 Node 压缩包（内网离线场景）
 #     --with-nginx                 顺带放一份 Nginx 反代配置（不自动申请证书）
 #     --open-firewall              按检测到的防火墙放行端口
+#     --no-autostart               不设开机自启（默认设为自启；装完仍可 systemctl enable 改回来）
 #     --yes                        全部用默认值，不再交互（CI / 验收用）
 #
 # 幂等：重复执行 = 覆盖安装。已有 config.env（含 JWT_SECRET）与 data/ 一律保留，不重置密钥。
@@ -53,7 +54,7 @@ set -euo pipefail
 
 # ---------------------------------------------------------------- 集中变量
 
-PRODUCT="班级小助手"
+PRODUCT="ClassHelper"
 SERVICE_NAME="classhelper"
 
 INSTALL_DIR="/opt/classhelper"
@@ -91,6 +92,10 @@ NODE_DIR_NAME="runtime/node"
 
 WITH_NGINX=0
 OPEN_FIREWALL=0
+# 是否设为开机自启（systemd enable）。需求：「支持选择开机自启动」——
+# 安装器只负责**默认值**，装完之后随时可以用 `systemctl disable/enable classhelper` 改
+# （Windows 侧对应 Web 管理端「系统设置」里的开关，见 PUT /api/system/autostart）。
+AUTOSTART=1
 ASSUME_YES=0
 CHECK_ONLY=0
 UNINSTALL=0
@@ -179,10 +184,10 @@ usage() {
     return 0
   fi
   cat <<'USAGE'
-班级小助手 · 服务端 Linux 安装器
+ClassHelper · 服务端 Linux 安装器
 
 （本次是从远端直接执行的，没有本地脚本文件可读，这里只列常用参数；
-  完整说明见 https://github.com/LoveChengke/ClassHelper/blob/master/docs/linux-deploy.md ）
+  完整说明见 https://github.com/LoveChengke/ClassHelper/blob/master/docs/management/linux-deploy.md ）
 
   --mode native|docker         安装形态（默认 native：systemd + 内置 Node）
   --dir /opt/classhelper       安装目录        --port 4000        服务端口
@@ -231,6 +236,8 @@ parse_args() {
       --node-tarball) NODE_TARBALL="${2:-}"; NODE_SOURCE="tarball"; shift 2 ;;
       --with-nginx) WITH_NGINX=1; shift ;;
       --open-firewall) OPEN_FIREWALL=1; shift ;;
+      --autostart) AUTOSTART=1; shift ;;
+      --no-autostart) AUTOSTART=0; shift ;;
       --install-docker) INSTALL_DOCKER=1; shift ;;
       --yes|-y) ASSUME_YES=1; shift ;;
       --force) FORCE=1; shift ;;
@@ -477,6 +484,7 @@ collect_answers() {
   fi
   if ask_yes_no "顺带放一份 Nginx 反向代理配置到 ${CONFIG_DIR}/nginx.conf？" "n"; then WITH_NGINX=1; fi
   if ask_yes_no "按检测到的防火墙放行端口 ${PORT}？" "n"; then OPEN_FIREWALL=1; fi
+  if ask_yes_no "设为开机自启（systemctl enable ${SERVICE_NAME}）？" "y"; then AUTOSTART=1; else AUTOSTART=0; fi
 }
 
 # ---------------------------------------------------------------- 用户与目录
@@ -532,6 +540,12 @@ resolve_package_url() {
     sudo bash install.sh --package /tmp/classhelper-server-linux-x64-1.1.2.tar.gz"
     fi
   fi
+  # tag 一律补上 v 前缀：Release 的 tag 是 v1.3.0，而 --version 的用法是 `--version 1.3.0`（不带 v）——
+  # 直接拿 VERSION 去拼就成了 .../download/1.3.0/...，GitHub 按 tag 精确匹配，必然 404
+  # （2026-10-11 实测：`install.sh --version 1.3.0` 下载 404，而 `classhelper upgrade --version 1.3.0` 正常
+  #  —— 因为 classhelper 的 resolve_download 一直有这句，install.sh 漏了）。
+  # 传 `v1.3.0`、`1.3.0`、或者不传（走 latest）三种写法都落在这里。
+  tag="v${tag#v}"
   ver="${tag#v}"
   # 注意这里用 GITHUB_REPO_URL 而不是 GITHUB_RELEASES_PAGE：后者本身已经以 /releases 结尾，
   # 再拼一次就变成 .../releases/releases/download/... （必然 404，实测踩到）。
@@ -793,7 +807,7 @@ write_config() {
 
   cat >"$CONFIG_FILE" <<EOF
 # ---------------------------------------------------------------------------
-# 班级小助手服务端配置（由 install.sh 生成于 $(date '+%F %T')）
+# ClassHelper 服务端配置（由 install.sh 生成于 $(date '+%F %T')）
 #
 # 这是**唯一的配置真身**：安装目录里的 .env 是指向本文件的软链，
 # systemd 通过 EnvironmentFile 读本文件；改完执行 classhelper restart 生效。
@@ -830,7 +844,7 @@ BCRYPT_ROUNDS=10
 INITIAL_ADMIN_USERNAME=admin
 ${admin_line}
 
-# 新建班级 / 重置教师账号时的默认密码（学生端用「班级码 + 班级密码」登录）
+# 新建班级 / 重置教师账号时的默认密码（ClassHelper 班级端用「班级码 + 班级密码」登录）
 DEFAULT_CLASS_PASSWORD=123456
 DEFAULT_TEACHER_PASSWORD=123456
 
@@ -844,7 +858,7 @@ EOF
 
 link_env_file() {
   # Web 端「数据库管理 → 一键切换」改写的是 <安装目录>/.env，而 systemd 注入的是 config.env；
-  # 用软链把两者收成一份真身，否则切换看起来成功、重启后又连回旧库（详见 docs/linux-deploy.md）
+  # 用软链把两者收成一份真身，否则切换看起来成功、重启后又连回旧库（详见 docs/management/linux-deploy.md）
   local link="${INSTALL_DIR}/.env"
   if [ -e "$link" ] && [ ! -L "$link" ]; then
     warn "安装目录里存在真实文件 .env，已改名保留为 .env.bak.$(date +%s) 再建立软链"
@@ -901,8 +915,12 @@ EOF
   fi
   chmod 644 "/etc/systemd/system/${SERVICE_NAME}.service"
   systemctl daemon-reload
+  if [ "${AUTOSTART}" = "1" ]; then
     systemctl enable "$SERVICE_NAME" >/dev/null
     log "已安装 /etc/systemd/system/${SERVICE_NAME}.service 并设为开机自启"
+  else
+    log "已安装 /etc/systemd/system/${SERVICE_NAME}.service（**未**设为开机自启；需要时执行 systemctl enable ${SERVICE_NAME}）"
+  fi
 }
 
 install_aux_files() {
@@ -973,7 +991,7 @@ install_docker_engine() {
 write_compose() {
   local compose="${CONFIG_DIR}/compose.yml"
   cat >"$compose" <<EOF
-# 班级小助手 · 由 install.sh 生成的 compose 文件（${MODE} 形态）
+# ClassHelper · 由 install.sh 生成的 compose 文件（${MODE} 形态）
 # 配置见 ${CONFIG_FILE}（改完执行 classhelper restart 重建容器）
 # 数据在 Docker 卷 classhelper-data 里；备份用 classhelper backup
 #
@@ -1025,7 +1043,7 @@ setup_nginx() {
     install -m 600 "${INSTALL_DIR}/nginx.conf" "$target"
   else
     cat >"$target" <<EOF
-# 班级小助手 · Nginx 反向代理（替换 server_name 与证书路径后启用）
+# ClassHelper · Nginx 反向代理（替换 server_name 与证书路径后启用）
 server {
     listen 80;
     server_name class.example.com;
@@ -1148,7 +1166,7 @@ print_result() {
   printf '  1. 改掉默认密码：%sclasshelper password admin%s\n' "$C_CYAN" "$C_RESET"
   printf '  2. 公网访问请上 HTTPS：改好 %s/nginx.conf 的域名与证书，并把 CORS_ORIGIN\n' "$CONFIG_DIR"
   printf '     收敛到你的域名（classhelper config set CORS_ORIGIN https://your.domain）\n'
-  printf '  3. 学生端「服务器地址」填 http://%s:%s 或你的域名\n' "$ip" "$PORT"
+  printf '  3. ClassHelper 班级端「服务器地址」填 http://%s:%s 或你的域名\n' "$ip" "$PORT"
   printf '%s────────────────────────────────────────────────────────────%s\n' "$C_GREEN" "$C_RESET"
 }
 

deploy/logrotate.d/classhelper

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

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

deploy/profile.d/classhelper.sh

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

deploy/tools/admin-cli.mjs

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

deploy/verify-linux.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # ---------------------------------------------------------------------------
-# 班级小助手 · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
+# ClassHelper · Linux 安装与运维链路验收（在**已安装的服务器上**运行）
 #
 # 覆盖：安装结果 → 服务可用性 → API 登录 → 改密（含回滚与审计）→ 备份 →
 #       配置读写 → key rotate →（可选）升级 / 回滚 / 卸载
@@ -74,7 +74,7 @@ CURL=(curl -fsS --noproxy '*')
 
 if [ "$ADMIN_PASSWORD_FROM_STDIN" = "1" ]; then IFS= read -r ADMIN_PASSWORD || true; fi
 
-printf '%s班级小助手 · Linux 安装验收%s\n' "$B" "$N"
+printf '%sClassHelper · Linux 安装验收%s\n' "$B" "$N"
 note "安装目录 ${INSTALL_DIR}｜配置 ${CONFIG_FILE}｜端口 ${PORT}"
 
 # ---------------------------------------------------------------- 1. 安装结果

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,43 @@
+---
+title: 班级、学生与教师
+description: 名单、班级会话、任课关系与年度升级。
+---
+
+# 班级、学生与教师
+
+## 班级账号
+
+教室客户端使用班级码和班级密码登录，形成 CLASS_DEVICE 会话，主体是班级。
+班级码保存时统一大写；管理员在“班级管理”维护班级码、密码与班主任。
+班级端的已读、作业完成等操作代表全班，学生没有个人登录账号。
+客户端没有修改密码入口；员工本人改密码在 Web 顶栏菜单。
+
+班级名由入学年份和班号组成，例如“2026级1班”；年级独立保存，学年升级时班名不随之改写。
+班主任可以暂空，新学年自动创建的高一班级仅有骨架，需要管理员后续分配教师。
+
+## 学生名单
+
+Student 存学号、姓名、班级、性别、家长电话和状态，没有密码或角色字段。
+学号为必填唯一标识，格式为 1–32 位字母、数字或 . _ -；不会自动生成登录名。
+管理员或本班班主任在具备名单管理权限后管理学生，教师也可按授权范围只读名单。
+名单表格导入仍要求管理员及相应导入权限；学号查重在 Student 表完成，不当成 User 用户名。
+调班保留历史内容原归属；转出独立记账并从现行业务名单过滤，学号不可复用。
+
+## 教师与科目
+
+教师使用工号和密码登录，管理入口受 teacher:read/teacher:manage 等功能权限控制。
+教师名单导入还要求管理员身份和相应导入权限。班主任关系在 Class.teacherId；
+科任关系唯一存于 Course(classId, name, teacherId)，分配任课关系由班级管理权限及服务端断言限制。
+班主任不任教某科就不能修改该科作业/成绩；科任老师有相应权限时可以管理自己任教科目。
+
+删除教师前，服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件；仍有业务内容则返回冲突，避免级联丢失。
+教师本人改密码、管理员修改教师密码、班级账号密码是不同入口；学生没有密码接口。
+
+## 权限、学年与归档
+
+角色给默认权限模板，实际入口由可编辑权限组决定；岗位组还能配置年级或部范围。
+范围不代替科目写权限，详见[角色与权限](../dev/permissions.md)。
+学期周数受全校可配置上限约束，默认上限 30、允许 1–60，见[课表](schedules.md)。
+学年升级按计划时间运行，执行前保存快照，以年份幂等；启动发现漏跑需管理员预览补跑。
+高三归档、高一/高二升一级，新高一不复制任课关系。归档页查看届别历史与转出记录，
+不再通过手动创建归档来代替年度升级。撤回转出等操作仍受归档与管理员业务检查约束。

docs/app/courseware.md

@@ -0,0 +1,37 @@
+# 课件上传与传输
+
+教师可在 Web 管理端的「教学事务 → 课件」上传演示文稿、文档、表格、图片、音视频、压缩包等文件，单文件上限为 **512 MB**。
+
+## 上传与可见范围
+
+1. 选择本地文件。
+2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级；仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。
+3. 选择「仅保存云端」或「保存后推送所选班级」，点击上传。
+
+不选择班级时，课件仅自己可见。仅保存云端并指定可见班级后，这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端，再给所选班级创建下载任务；不会从教师电脑直接传到教室电脑。
+
+教师可在列表中按文件名、教师、归档日期和文件类型筛选，修改自己课件的可见范围，或再次推送。再次推送时只能选择「本人授课班级」与「该文件可见范围」的交集。管理员可查看归档列表，但上传和推送自己的文件同样遵守任课关系。
+
+「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限，可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限；升级时自定义权限组需管理员按需授权。
+
+## 班级客户端
+
+客户端侧栏新增「课件」，仅列出本班可见的文件，显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机，点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。
+
+收到教师推送后，客户端自动下载；离线时任务保留在服务端，上线后的心跳会补拉，每台设备独立回执。实时通道正常时会立即触发检查；断线时通过心跳继续补收。传输失败会显示原因，推送任务在后续心跳中重试，不会影响远控和在线状态上报。
+
+下载期间，固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256，再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件；重新联网后同步当前可见范围。
+
+修改可见范围后，被移除班级无法再获取文件，尚未完成的推送任务同步取消。已经下载到教室电脑的文件无法远程撤回，需要在本机自行删除。
+
+## 服务端归档与备份
+
+默认文件实体目录为 `<服务端根目录的上一级>/data/courseware/YYYY-MM-DD/<类型>/<随机编号>`，展示名称与扩展名单独保存在数据库中。可通过环境变量 `COURSEWARE_DIR` 指定文件目录。上传使用流式写入，未完成文件使用 `.part` 临时文件；失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。
+
+数据库迁移 `20261018000000_add_courseware` 新增课件、可见班级、推送和设备回执四张表。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 档案
+
+在“课表管理 → 导入 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,66 @@
+---
+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，拖动调整结构，设置内容、外观、尺寸与隐藏条件。
+方案保存到本机 config.json.islandLayout，不增加服务端同步。
+编辑预览不创建额外桌面窗口；打开编辑页不自动切布局，应用后启用自定义方案。
+保存按序进行，失败可重试，主题与关怀模式沿用客户端设置。
+
+## 外观、位置与输入
+
+经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距；自定义内容根据实际测量适配工作区。
+自定义方案可配置缩放、圆角、颜色和行间距，默认值与范围在 shared/island-layout.ts。
+左右边距只在左/右停靠时生效，居中锚点仍在屏幕中线。
+触摸屏自动进入触摸模式，保留触摸命中和失焦宽限；鼠标模式按光标控制输入穿透。
+自定义常驻内容支持鼠标避让淡化及反转，交互入口、展开/编辑和触摸操作按实现暂停避让。
+应用内动画开关决定岛动画，不能用主窗口的减少动态效果说明替代岛自身规则。
+
+经典几何与配色参考见[设计令牌](../dev/winisland-design-tokens.md)，实现入口见[当前实现约定](../dev/implementation.md)。
+
+## 课程与课件
+
+准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关，课程依据服务端解析后的课表。
+课件接收时显示文件名、类型、教师、字节和进度，覆盖当前固定/自定义内容；完成后校验 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,39 @@
+---
+title: 课表
+description: 日课表、共享作息、轮换、临时换课和教学周。
+---
+
+# 课表
+
+Web 管理端可查看周课表并编辑时间表与日课表，客户端提供“今天”时间轴和“本周”视图。
+上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
+
+## 日课表与时间表
+
+时间表保存时间点：上课、课间、分割线、行动；日课表引用时间表，每节课程通过外键关联时间点。
+可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
+时间点排序不会改变课程关联。行动配置当前保存数据，不执行外部动作。
+
+日课表按星期、周次范围和轮换规则启用，支持 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,74 @@
+---
+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:manage 与管理员业务断言            |
+| PATCH /classes/:id/class-account、/classes/:id/head-teacher             | 班级凭据/班主任维护                                            |
+| 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 | 复制、导入导出及完整档案导入                                           |
+| /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                                                           | 旧预览与完整档案提交；提交走关系化导入                                 |
+| /imports/time-layout[/:id]、/time-layout/preview                                                           | 时间配置兼容入口，写入/删除需 timetable:manage                         |
+| GET /courseware、/courseware/:id、/:id/download                                                            | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围           |
+| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id               | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制     |
+| GET /courseware/transfers；POST /courseware/transfers/:id/ack                                              | 班级端补领、逐设备回执                                                 |
+
+## 设备、系统与运维
+
+| 路径/动作                                                                                               | 行为及边界                                                           |
+| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| POST /clients/heartbeat、/clients/commands/:id/ack                                                      | 登录设备心跳/回执，校验 deviceKey 和归属                             |
+| GET /clients/devices；DELETE /clients/devices/:id                                                       | 设备读取/维护，分别检查功能键和范围                                  |
+| POST /clients/commands                                                                                  | remote:control + 对应范围，白名单动作                                |
+| POST /clients/updates                                                                                   | client:update，安装策略 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                                                                    | 已登录下载，不挂员工权限键，供班级端更新                             |
+| /term；POST /term/auto；GET /term/holidays                                                              | 学期读取/编辑/假日建议，term:read/term:write                         |
+| GET/PUT /term/promotion；POST /term/promotion/run                                                       | 升级计划、预览和执行，system:manage，执行还做业务校验                |
+| /archives、/archives/transferred、/archives/transferred/:id/restore                                     | 历史归档与撤回转出，archive: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)。

docs/dev/architecture.md

@@ -0,0 +1,66 @@
+---
+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 与主进程通信，主进程管理唯一原生岛窗口。
+课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。
+
+## 工程边界
+
+- 三端契约只放 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,74 @@
+---
+title: 数据模型
+description: 现行模型职责、迁移与快照边界。
+---
+
+# 数据模型
+
+模型定义以 `packages/server/prisma/schema.prisma` 为准，迁移以 `prisma/migrations/` 为准。
+仅维护一份 schema，SQLite/MySQL 切换改 provider；不使用 Prisma enum 和 `@db.*`。
+
+## 模型职责
+
+| 模型                   | 职责                                               |
+| ---------------------- | -------------------------------------------------- |
+| `User`                 | 教师与管理员账号；学生不在此表，班级凭据在 Class   |
+| `Student`              | 学生名单、学号、在读/转出/毕业状态，无密码和角色   |
+| `StudentClassTransfer` | 调班与转出历史，保留班级/姓名快照                  |
+| `ArchivedYear`         | 毕业届别与统计快照                                 |
+| `TermWeek`             | 逐周日期区间，classId 空串为全校默认               |
+| `Class`                | 班级、班级码/密码、班主任、周数与成绩查询开关      |
+| `Course`               | 班级+科目+教师任课关系，含简称和室外标记           |
+| `Schedule`             | 旧课表迁移审计来源，现行接口不再以它为业务真值     |
+| `Homework`             | 作业与本地 assignDate；dueAt 为遗留列              |
+| `HomeworkStatus`       | 按 studentId 记录作业完成状态                      |
+| `Notification`         | 通知/叫人记录、优先级与本地 assignDate             |
+| `NotificationRead`     | 按 studentId 记录已读                              |
+| `TimeLayout`           | 共享或班级自有时间表；旧 items JSON 保留迁移审计   |
+| `Grade`                | studentId、课程、考试、分数和等级                  |
+| `PermissionGroup`      | 默认/自定义/岗位组及 scope/scopeValue              |
+| `PermissionGroupItem`  | 组内权限键                                         |
+| `UserPermissionGroup`  | 账号与组的多对多分配                               |
+| `AppSetting`           | 周次、升级、AI 和系统设置                          |
+| `ClientDevice`         | deviceKey、心跳、更新目标与状态                    |
+| `ClientCommand`        | 白名单远控、有效期与执行回执                       |
+| `ClientRelease`        | 服务端缓存安装包、SHA256 与大小                    |
+| `AiAudit`              | 助手解析审计，不保存 API Key                       |
+| `Exam`                 | 考试名称与是否计入总分                             |
+| `TimeLayoutItem`       | 有序时间点及类型，被课程显式引用                   |
+| `ClassPlanGroup`       | 班级课表群组、全局/默认标记                        |
+| `ClassPlan`            | 日课表、时间表、轮换、启用与临时层规则             |
+| `ClassPlanEntry`       | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
+| `ScheduledClassPlan`   | 按本地日期预定日课表                               |
+| `PromotionRun`         | 年度升级幂等与审计                                 |
+| `Courseware`           | 文件元数据、上传教师、存储路径与 SHA256            |
+| `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)。

docs/dev/implementation.md

@@ -0,0 +1,40 @@
+---
+title: 当前实现约定
+description: 课表、周次、学年、岛、设备与课件的现行实现入口。
+---
+
+# 当前实现约定
+
+本页维护当前工作区的实现契约，不汇总多批构建的验收数字。验证命令与实际范围见[验收与测试](testing.md)。
+
+## 关系化课表
+
+`ClassPlan/ClassPlanEntry/TimeLayoutItem` 是业务真值。时间点外键独立于排序，`Schedule` 与旧 JSON 列仅保留迁移审计来源。
+兼容 `/schedules` 写入新模型，日课表、周视图和上课状态共用 `lib/class-plan.ts`。
+解析顺序是预定、当日临时课表、同日临时层、有效临时群/选定或默认群的规则匹配、全局群、无群默认。
+轮换使用 weekday/weekCountDiv/weekCountDivTotal 与周次范围，支持 1–9 周；没有新增 Profile 实体。
+完整档案导入直接保留轮换、空课、停用、时间类型、群组与预定，不经过单双周中间格式。
+旧数据同班同日同周同时间冲突仅最小 id 进入新表，旧行保留；缺失的历史群组、临时层与时间点名称无法恢复。
+
+## 权限、成绩与年度升级
+
+默认权限组、岗位范围、科目写权限分别由 permissions/permission-scope/access 维护，范围并集不授予任课权。
+全校周数上限在 `term.maxWeeks`，默认 30、允许 1–60；开学日和逐周区间支持全校与班级设置。
+个人成绩查询关闭后只返回服务端集体聚合，个人明细、原始全班成绩与排名拒绝读取；样本不足或稀疏分段抑制。
+年度升级由 `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)。

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,69 @@
+---
+title: 角色与权限
+description: 功能权限、岗位范围与班级科目边界。
+---
+
+# 角色与权限
+
+授权分为功能权限、数据范围和业务关系三层，任何一层拒绝都不能操作。
+shared 的 `permissions.ts` 定义键、标签、默认模板与班级关系规则；服务端 `lib/permissions.ts`、
+`lib/permission-scope.ts`、`lib/access.ts` 分别计算生效键、查询范围和具体业务断言。
+
+## 身份与权限组
+
+账号角色为 ADMIN、TEACHER；班级登录形成 CLASS_DEVICE 会话。学生是 Student 名单，不是账号。
+HEAD/SUBJECT 是班级关系，级长/部长是岗位组，均不新增 User.role。
+
+| 情况         | 有效功能权限                                          |
+| ------------ | ----------------------------------------------------- |
+| 已分配权限组 | 所有分组键的并集，可以比角色默认更少                  |
+| 没有分组     | 数据库对应角色的可编辑默认组                          |
+| ADMIN        | 同上，始终额外保留 permission:manage 与 system:manage |
+| CLASS_DEVICE | 空集；通过明确允许班级会话的接口与业务断言操作        |
+
+每请求读取生效权限，编辑后无需等待令牌过期。内置组可改不可删，默认组不是写死的全权限快捷方式。
+路由使用 requirePermission（AND）、requireAnyPermission（OR），员工与班级端共享读取入口按 requireStaffPermission 等规则检查。
+具体 API 的额外角色限制以模块路由和服务断言为准，不能把“默认只分配给管理员”写成所有接口硬编码 ADMIN。
+
+## 数据范围与科目
+
+| 岗位/身份   | 范围                                          |
+| ----------- | --------------------------------------------- |
+| 管理员      | 全部班级；仍须功能键                          |
+| 班主任/教师 | 自己担任班主任或任课的班级，按分组 scope 收敛 |
+| 级长        | 配置年级                                      |
+| 部长        | 配置的一组年级，scopeValue 用逗号分隔         |
+| 班级端      | 登录绑定班级                                  |
+
+空年级/部配置不放行。设备写操作只合并含对应功能键的分组范围，不能借只读组扩权。
+科目编辑再由 `assertCanManageSubjectContent` 检查：管理员可管理，教师仅自己任课科目，无科目内容归班主任。
+班主任不任教某科就不能改该科的作业或成绩；班级端只允许作业写入，不能写成绩。
+
+| 业务             | 主要功能键与额外边界                                                         |
+| ---------------- | ---------------------------------------------------------------------------- |
+| 名单读取/管理    | roster:read / roster:manage；管理仍须管理员或本班班主任断言                  |
+| 教师列表/维护    | teacher:read / teacher:manage；导入名单另检查导入权限和角色                  |
+| 日课表写入       | schedule:write + 管理员/本班班主任                                           |
+| 全校时间表写入   | timetable:manage；默认给 ADMIN                                               |
+| 作业/成绩        | homework:write / grade:write 或 grade:import，再按班级科目收口               |
+| 通知/叫人        | notification:publish / call:create，再检查班级范围                           |
+| 课件             | courseware:read / courseware:write，上传和推送自己的文件还受本人授课班级约束 |
+| 客户端维护/远控  | client:read、client:manage、remote:control，写操作按对应键范围               |
+| 版本与安装包写入 | client:update；旧 client:update-push 不再作为写入口要求                      |
+| 数据库/系统/权限 | database:manage / system:manage / permission:manage                          |
+
+完整键目录读取 `PERMISSION_KEYS`，不在文档维护固定键数。
+
+## 前端门控与成绩隐私
+
+Web 菜单属性来自路由，`meta.roles` 粗筛、`meta.permission` 细筛；先 ensurePermissions 再按生效集合判断。
+服务端仍检查功能、范围与业务关系，直接构造请求不能绕过。
+岗位范围可以扩大读范围，不能自动扩大科目写权限，也不能替代课件的本人任课关系。
+班级成绩查询开关仅员工按业务权限修改；关闭后班级端仍看集体聚合，个人明细、原始全班成绩和排名返回拒绝。
+稀疏分段与补集抑制，服务端不向客户端下发个人原始成绩再聚合。
+
+## 设备维护
+
+`/api/clients/heartbeat` 和命令回执供已登录设备使用，不依赖班级端的空权限集合；服务端校验 deviceKey 与班级归属。
+远控从管理端确认下发，客户端执行后回传真实结果。更新文件由服务端缓存，教室机验 SHA256，
+按立即、放学后、空闲策略安装；关闭自动更新不会强制安装。详见[更新与升级](../management/upgrade.md)。

docs/dev/realtime.md

@@ -0,0 +1,49 @@
+---
+title: 实时事件（Socket.IO）
+description: 实际事件与房间、断线恢复和客户端提醒分工。
+---
+
+# 实时事件（Socket.IO）
+
+连接使用 `io(url, { auth: { token } })`，服务端在握手校验 JWT。
+事件与房间定义在 shared 的 `constants.ts`，载荷类型在 shared 的 `types.ts`，以这些契约和发送点为准。
+
+## 房间与定向推送
+
+| 房间            | 作用                                               |
+| --------------- | -------------------------------------------------- |
+| class:{classId} | 某班级的业务广播                                   |
+| session:{id}    | 会话定向名；员工 id 为账号 id，班级端 id 为班级 id |
+| role:{role}     | 角色房间名，定义在共享常量                         |
+| teacher:{id}    | 教师房间名，定义在共享常量                         |
+| students        | 班级端连接的广播房间，代表全班，不是个人学生账号   |
+| teachers        | 教师和管理员连接的广播房间                         |
+
+`realtime/socket.ts` 当前显式 join 可访问的 class 房间与 students/teachers 广播房间；
+同时在 connected 载荷列出 session/role 名。不能把共享常量或该列表当成所有房间均已成功 join 的证明，实际订阅以 join 调用为准。
+业务经 `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` 及相关缓存/岛逻辑。
+不要手写事件名；只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。

docs/dev/release.md

@@ -0,0 +1,81 @@
+---
+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 | 同名                                       |
+
+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,69 @@
+---
+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: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: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 通过表述为动画/透明度已验证。

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,86 @@
+---
+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)。

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

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

@@ -23,8 +23,8 @@ curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/Love
 ```
 
 > **别写成 `bash -c "$(curl …)" --check`**：`bash -c '代码' 第一个参数` 里那个参数会变成 `$0`，
-> 不是 `$1` —— 脚本收不到它（实测踩到：本意是体检，结果走进了交互式安装）。
-> 先落盘再执行没这个坑，也不会因为下载中断而执行到半个脚本。
+> 不是 `$1` —— 脚本收不到它（想体检却会走进交互式安装）。
+> 先落盘再执行没这个问题，也不会因为下载中断而执行到半个脚本。
 
 以下是"已有安装包 / 内网离线"的用法：
 
@@ -38,7 +38,7 @@ 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 起容器 |
@@ -60,12 +60,12 @@ 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`](../.github/workflows/release-linux-server.yml)
+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. GitHub → Actions → 「发布 Linux 服务端安装包」→ Run workflow → 填 tag → 运行；
+2. 推送 v* tag 会自动触发；也可在 Actions 的「发布 Linux 服务端安装包」中手动指定 tag 运行；
 3. 跑完 Release 里会多出 Linux 包与更新后的 `SHA256SUMS-<版本>.txt`。
 
 内网离线分发也可以：在能上网的机器上 `pnpm dist:server:linux`，把 tar.gz 拷进去，
@@ -75,10 +75,10 @@ Windows 开发机上 `npm install` 出来的 `node_modules` 拷到 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` 都不依赖平台差异                                                                                                           |
@@ -127,7 +127,7 @@ sudo bash install.sh --yes --database mysql --mysql-host 10.0.0.5 --mysql-db cla
 完整参数见 `bash install.sh --help`。要点：
 
 | 参数                                     | 作用                                                       |
-| --- | --- |
+| ---------------------------------------- | ---------------------------------------------------------- |
 | `--package <url｜file://路径>`           | 安装包地址（默认从 GitHub Release 取最新版）               |
 | `--sha256 <哈希>`                        | 强制校验安装包哈希                                         |
 | `--admin-password-stdin`                 | 从 stdin 读一行作为初始管理员密码                          |
@@ -170,7 +170,7 @@ classhelper backup          # 容器内做一致性快照再取出来
 Docker 形态与直接安装的差异：
 
 |                   | 直接安装                                      | Docker                                                                                                |
-| --- | --- | --- |
+| ----------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | 数据位置          | `<安装目录>/data`                             | Docker 卷 `classhelper-data`                                                                          |
 | 配置              | `/etc/classhelper/config.env`（systemd 注入） | 同一份文件（compose `env_file`）                                                                      |
 | 升级 / 回滚       | 替换程序文件后重启服务                        | 同一套流程：替换构建上下文 → 重建镜像（`classhelper-server:local`）→ `compose up -d --force-recreate` |
@@ -225,7 +225,7 @@ Web 端「数据库管理 → 一键切换数据库」在运行中改写的是 *
 （含空白或 `#` 的值请加双引号）。最常见的几项：
 
 | KEY                                                   | 默认                          | 说明                                                                     |
-| --- | --- | --- |
+| ----------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------ |
 | `PORT` / `HOST`                                       | `4000` / `0.0.0.0`            | 监听端口与地址                                                           |
 | `DATABASE_PROVIDER`                                   | `sqlite`                      | `sqlite` 或 `mysql`                                                      |
 | `DATABASE_URL`                                        | `file:../data/classhelper.db` | SQLite 相对 `<安装目录>/server` 解析；MySQL 是连接串                     |
@@ -285,7 +285,7 @@ classhelper logs --unit classhelper-backup     # 看定时备份的日志
 sudo classhelper password                 # 改 admin
 sudo classhelper password teacher1        # 改指定教师
 sudo classhelper password --list          # 列出可登录账号与班级账号（含是否已设密码）
-sudo classhelper password --class G101    # 改某个班的班级密码（学生端登录用）
+sudo classhelper password --class G101    # 改某个班的班级密码（ClassHelper 班级端登录用）
 ```
 
 安全约定（照要求逐条落实）：
@@ -389,7 +389,7 @@ sudo classhelper uninstall --purge    # 全删（含备份与数据），不可
 ## 6. 环境变量文件
 
 安装器会写 `/etc/profile.d/classhelper.sh`（内容见
-[`deploy/profile.d/classhelper.sh`](../deploy/profile.d/classhelper.sh)）：
+[`deploy/profile.d/classhelper.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/profile.d/classhelper.sh)）：
 
 ```sh
 export CLASSHELPER_HOME=/opt/classhelper
@@ -423,7 +423,7 @@ sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
 ## 8. 故障排查
 
 | 现象                     | 先查什么                                                                                                                                                                                                                            |
-| --- | --- |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 服务起不来               | `classhelper doctor` → `classhelper logs -n 100`。常见：端口被占用、MySQL 连接串错、`data/` 权限                                                                                                                                    |
 | 装完打不开页面           | `classhelper status` 看探针与监听地址；云服务器还要在**安全组**放行端口                                                                                                                                                             |
 | 页面能打开但是**空白**   | 1.1.0 的服务端在 HTTP 直连访问时会下发 CSP `upgrade-insecure-requests`，浏览器把所有子资源改写成 https 加载而服务器没有 TLS，于是整页空白（HTML/接口都正常）。已修复的版本按请求协议条件下发；若暂不能升级，唯一正解是上 HTTPS 反代 |
@@ -432,7 +432,7 @@ sudo cp deploy/nginx.conf /etc/nginx/conf.d/classhelper.conf
 | 升级卡住/失败            | 失败会自动回滚；看 `classhelper logs -n 100`，确认磁盘余量 ≥1GB                                                                                                                                                                     |
 | `classhelper` 命令找不到 | `ls -l /usr/local/bin/classhelper`；被删了就重装或 `ln -sfn <安装目录>/bin/classhelper /usr/local/bin/classhelper`                                                                                                                  |
 | 忘记管理员密码           | `sudo classhelper password admin`（直连数据库，不需要登录）                                                                                                                                                                         |
-| 学生端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠 |
+| ClassHelper 班级端连不上 | 客户端「服务器地址」填 `http://IP:端口` 或域名；确认没有多余路径与斜杠                                                                                                                                                              |
 | CentOS 7 装完立刻退出    | glibc < 2.28，见下面的"已知限制"                                                                                                                                                                                                    |
 
 ---
@@ -503,7 +503,7 @@ 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` 可用                                                                                                    |
@@ -527,7 +527,7 @@ sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x6
 
 ```bash
 # ① 浏览器打开 http://<IP>:4000/ ，用 admin 登录，改一次密码再登录
-# ② 学生端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
+# ② 在隔离测试服务创建临时教师和班级，用其班级凭据登录客户端，验证提醒后清理临时数据
 # ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
 #    期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
 # ④ 卸载：sudo classhelper uninstall --yes

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

@@ -2,12 +2,12 @@
 
 本文档覆盖三种上线形态，按适用场景选择：
 
-| 形态                  | 适用场景                                     | 产物                                                     | 本机验证情况                           |
-| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
-| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `releases/server/<版本>/安装包/班级小助手服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
-| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`        | ⚠️ 文件已提供，本机无 Docker 未实测    |
-| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](../deploy/install.sh) + `classhelper` 运维命令             | ⚠️ 本机无 Linux，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
-| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | `pnpm dist:server` 的免安装目录                          | ✅ 免安装目录已实测（163 项端到端）    |
+| 形态                  | 适用场景                                      | 产物                                                                                                                     | 验证状态                                                 |
+| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| **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 环境的服务器、需要自定义            | 在仓库里构建后直接跑（见第四节）                                                                                         | ✅ 已验证（端到端验收通过）                              |
 
 ---
 
@@ -23,9 +23,12 @@ pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳
 产物：
 
 | 路径                                                                    | 说明                       |
-| ----------------------------------------------------------------------- | ----------------------------------------------- |
-| `releases/server/<版本>/免安装/`                                        | 免安装目录，可直接拷到任意 Windows x64 机器运行 |
-| `releases/server/<版本>/安装包/班级小助手服务端-<版本>-x64-setup.exe`   | 安装程序（约 62 MB，NSIS）                      |
+| ----------------------------------------------------------------------- | -------------------------- |
+| `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | 安装程序（约 62 MB，NSIS） |
+
+> 组装出来的运行时（内置 Node + 生产依赖 + 后端与 Web 产物，约 335 MB）是打安装包的中间物，
+> 落在 `.cache/server-staging/<版本>/`，脚本打完就删 —— 交付目录里只留安装程序。
+> 需要在有 Node 的机器上手动跑，见第四节。
 
 打包内容：内置 **Node 运行时**（目标机无需安装 Node.js）、后端产物、Web 管理端产物、
 生产依赖（真实目录，非软链）、迁移 SQL、`.env`（随机 JWT 密钥）、启停脚本。
@@ -35,10 +38,11 @@ pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳
 双击安装程序即可，**无需管理员权限**（当前用户级安装）：
 
 - 安装目录：`%LOCALAPPDATA%\Programs\ClassHelperServer`
-- 静默安装：`"班级小助手服务端-1.1.2-x64-setup.exe" /S`
+- 静默安装：`"ClassHelper 服务端-1.2.0-x64-setup.exe" /S`
 - 开始菜单：启动服务 / 停止服务 / 重启服务 / 打开管理端 / 使用说明 / 卸载
-- 桌面：`班级小助手服务端.lnk`（打开管理端）
-- 自动加入当前用户开机自启（`HKCU\...\CurrentVersion\Run`）
+- 桌面：`ClassHelper 服务端.lnk`（打开管理端）
+- **开机自启动可选**：安装向导的组件页里勾选（默认勾选），装完之后还能在管理端「系统设置」里随时开关
+  （`GET/PUT /api/system/autostart`）；勾选时写的是 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run\ClassHelperServer`
 - 卸载信息注册到「应用和功能」
 
 安装完成后服务会自动启动并完成首次初始化：
@@ -55,7 +59,7 @@ pnpm dist:server -- --reuse-deps   # 迭代打包：复用已安装依赖，跳
 ├── server\dist\          后端程序（入口 index.js）
 ├── server\prisma\        迁移 SQL（首启动自动执行）
 ├── web\                  Web 管理端（由后端托管）
-├── data\                 classhelper.db + server.pid（备份只需复制此目录）
+├── data\                 数据库、课件与其他持久化文件（完整备份另含 .env）
 ├── logs\server.log       UTF-8 日志（含请求耗时）
 ├── .env                  全部配置
 ├── start.cmd / stop.cmd / restart.cmd / status.cmd
@@ -97,8 +101,8 @@ uninstall-service.cmd   :: 删除计划任务
 
 ## 二、Docker + MySQL（形态 B，云部署推荐）
 
-> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
-> 目录布局、迁移方式与服务端完全一致）。
+> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
+> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。
 
 ```bash
 cp deploy/.env.example deploy/.env
@@ -203,7 +207,7 @@ printf '%s\n' 'StrongPass!2026' | sudo bash /tmp/install.sh --yes \
 日常运维全部走 `classhelper`（`classhelper help` 看全部）：
 
 | 事项   | 命令                                                                                     |
-| ------ | --------------------------------------------------------------------------------------- |
+| ------ | ---------------------------------------------------------------------------------------- |
 | 状态   | `classhelper status [--json]`                                                            |
 | 体检   | `classhelper doctor`（权限 / Node / 服务单元 / 探针 / 数据库 / 磁盘 / 备份）             |
 | 改密码 | `classhelper password [用户名]`（交互输入、不回显、不进 shell history）                  |
@@ -269,26 +273,31 @@ sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x6
 升级与回滚整条链路，末尾打印 `=== 结果：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
-pnpm dist:server -- --reuse-deps      # 得到 releases/server/<版本>/免安装/ 免安装目录
 ```
 
-把该目录拷贝到目标机，编辑 `.env`（端口、数据库、密钥、跨域），然后：
+按目标机的实际情况写好 `packages/server/.env`（端口、数据库、密钥、跨域），然后：
 
-```cmd
-start.cmd      :: Windows
-# 或直接：node server/dist/index.js   （Linux/macOS 用系统 node，见上面的形态 C）
+```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 首次启动自动建表 + 建管理员）
@@ -299,13 +308,13 @@ start.cmd      :: Windows
 ## 五、环境变量清单
 
 | 变量                                                | 默认                   | 说明                                                        |
-| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
+| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
 | `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 位；生产环境仍为示例值会拒绝启动            |
+| `AUTO_MIGRATE`                                      | `false`                | SQLite 启动时补跑随包迁移，空库另创建管理员                 |
+| `JWT_SECRET`                                        | —                      | **必填**，至少 16 位；生产需 ≥32 位且拒绝示例密钥           |
 | `JWT_EXPIRES_IN`                                    | `7d`                   | 令牌有效期                                                  |
 | `CORS_ORIGIN`                                       | `*`                    | 允许来源，多个用逗号分隔；生产建议写具体域名                |
 | `TRUST_PROXY`                                       | `false`                | 反向代理层数（Nginx 填 `1`），影响限流与日志中的真实 IP     |
@@ -314,9 +323,10 @@ start.cmd      :: Windows
 | `PID_FILE`                                          | —                      | PID 文件路径（安装包启停脚本依赖），相对 `server` 根        |
 | `WEB_DIST_DIR`                                      | 自动探测               | Web 管理端产物目录（`../web-admin/dist` 或 `./web`）        |
 | `LOG_LEVEL`                                         | `info`                 | `debug` / `info` / `warn` / `error`                         |
-| `DEFAULT_CLASS_PASSWORD`                            | `123456`               | 新建班级时班级账号（学生端登录）的默认密码                |
+| `DEFAULT_CLASS_PASSWORD`                            | `123456`               | 新建班级时班级账号（ClassHelper 班级端登录）的默认密码      |
 | `DEFAULT_TEACHER_PASSWORD`                          | `123456`               | 新增/重置教师账号的默认密码（管理员录入教师用）             |
-| `TERM_START_DATE`                                   | —                      | 第 1 教学周的周一，用于"当前周次"与课表默认视图           |
+| `COURSEWARE_DIR`                                    | 默认 data/courseware   | 课件文件实体目录；需纳入完整备份                            |
+| `TERM_START_DATE`                                   | —                      | 开学日环境兜底；界面全校/班级设置与逐周区间优先，见课表帮助 |
 | `INITIAL_ADMIN_USERNAME` / `INITIAL_ADMIN_PASSWORD` | `admin` / `admin123`   | 空库首启动创建的管理员                                      |
 
 ---
@@ -344,6 +354,8 @@ start.cmd      :: Windows
 | 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 安全清单（上线前逐项确认）
@@ -382,7 +394,7 @@ start.cmd      :: Windows
 
 ## 八、性能与容量参考
 
-- 单机 SQLite 形态适合**单校规模**（数千用户、每天数百次写操作），实测 62 项接口与实时推送全部达标。
+- 单机 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），

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

docs/mysql.md

@@ -1,134 +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 生成对应外键动作                                                                                                        |
-
-## 切换到 MySQL
-
-### 方式一：Web 管理端「数据库管理 → 一键切换」（推荐，v1.0.0 新增）
-
-管理员在 Web 管理端打开 **数据库管理** 页（`/database`，仅 ADMIN 可见），在「一键切换数据库」卡片里：
-
-1. 选目标类型（SQLite ⇄ MySQL）并填**空库**连接串（有表的库会被拒绝，防误覆盖）；
-2. 输入「确认迁移」→ 点「开始迁移」。
-
-界面会自动依次执行（带步骤进度条）：
-
-1. **备份当前数据库**（gzip JSON 快照存 `<数据目录>/backups/`，失败可回滚）；
-2. 导出当前数据为快照；
-3. 测试目标库连接；
-4. 检查目标库为空；
-5. 改写 `schema.prisma` 的 provider；
-6. 子进程 `prisma generate` 生成新方言的 Prisma 客户端；
-7. （打包形态）把生成的 `.ts` 客户端编译进 `dist/generated`；
-8. 子进程 `prisma db push` 在目标库建表；
-9. 子进程 `dist/tools/apply-snapshot.js` 把快照写入目标库；
-10. 全部成功后改写 `.env` 的 `DATABASE_PROVIDER` / `DATABASE_URL`。
-
-**完成后必须重启服务端**（安装版运行 `restart.cmd`，开发模式重跑 `pnpm dev:server`）才会连接新库。
-中途任一步失败会**回滚 `schema.prisma`**，`.env` 不被改写 —— 现有数据库与配置保持可用。
-
-> 同一页还提供：连接状态检测（版本 / 体积 / 各表行数）、连接测试、手动与**定时备份**、
-> 备份恢复、快照导出导入、SQLite 数据库文件下载。备份与导入导出共用同一种 JSON 快照格式，
-> 因此**任意备份都能恢复回任意一种受支持的数据库**。
->
-> 只支持 SQLite 与 MySQL 两种主库：Redis 等键值库不是 Prisma 支持的主数据库（无法建表/迁移），
-> 接口层直接拒绝。
-
-### 方式二：命令行手工切换
-
-#### 1. 修改 provider
-
-```bash
-# 自动把 prisma/schema.prisma 的 provider 改成 mysql
-node scripts/use-database.mjs mysql
-```
-
-#### 2. MySQL 驱动适配器（自 v1.0.0 起已随包内置）
-
-Prisma 7 要求所有数据库都通过 driver adapter 接入，MySQL 对应 `@prisma/adapter-mariadb`
-（该适配器基于 `mariadb` 驱动，兼容 MySQL 8）。**它已在 `packages/server/package.json` 的
-依赖里**（数据库管理模块的连接测试/迁移需要），因此无需再手动安装：
-
-```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
-```
-
-> 只搬数据、不要演示数据时，用界面的「下载快照 / 导入快照」更省事：
-> 旧库导出 JSON → 切库建表 → 新库导入，一份快照也可用 CLI 迁移：
-> `node server/dist/tools/apply-snapshot.js --provider mysql --url "mysql://..." --file snapshot.json`
-
-#### 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
-```
-
-> 用界面「一键切换」回 SQLite 时，目标库同样必须是空文件：删除旧 `.db` 或指定一个新路径。
-
-## 生产部署注意事项
-
-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` 之外移除。
-   界面「定时备份」把快照写进 `<数据目录>/backups/`（MySQL 模式下即安装根 `data/backups/`），
-   **服务端进程不运行时不会补跑**；关键环境建议同时用数据库自带的备份策略。
-5. **安装包体积**：切换链路需要随包内置 `prisma` CLI 与 `typescript` 编译器（Prisma 7 生成器产出
-   `.ts`，切换后需在目标机编译进 `dist/generated`），服务端安装包因此约 34MB → 71MB。

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 导入与设计参考，在线联动插件及相关接口已退役。

docs/serve.mjs

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

docs/templates/classhelper/layout/_master.tmpl

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

docs/templates/classhelper/public/main.css

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

docs/toc.yml

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

docs/winisland-design-tokens.md

@@ -1,593 +0,0 @@
-# WinIsland 视觉设计系统（Design Token 规格）
-
-来源：`D:\classhelper\.cache\winisland-ref\WinIsland-master`（只读 checkout）。
-所有数值均取自代码常量，标注了「常量名 = 值 @ 文件」。未在代码中找到的项明确写「未找到」。
-
-关键前提：**岛内所有几何尺寸都乘以 `compact_scale`（默认 1.0）或 `expanded_scale`（默认 1.0）**，
-下文数值默认 scale = 1.0。文字颜色在渲染入口被硬编码为 `Color::WHITE`（`src/core/render.rs`
-`draw_expanded_layer` / `draw_compact_layer` 传 `text_color: Color::WHITE`, `text_color_sec: Color::WHITE`），
-所有"次级/次要"文字靠 **alpha** 或 **灰度通道值** 表达，而不是换颜色。
-
----
-
-## 1. 几何（几何 token）
-
-### 1.1 两个状态的尺寸
-
-| 项       | compact / mini                  | expanded                             | 来源                                                                                          |
-| -------- | ------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
-| 宽       | `base_width = 120.0`            | `expanded_width = 360.0`             | `src/core/config.rs` `AppConfig::default()`                                                   |
-| 高       | `base_height = 27.0`            | `expanded_height = 200.0`            | 同上                                                                                          |
-| 圆角 r   | `h / 2`（=13.5）→ 胶囊/体育场形 | `min(48*scale, w/2, h/2)` = **48.0** | `src/window/app/frame.rs` `default_target_r`；`src/utils/shape.rs` `expanded_island_radius()` |
-| 全局缩放 | `compact_scale = 1.0`           | `expanded_scale = 1.0`               | `src/core/config.rs`                                                                          |
-
-圆角函数原文（`src/utils/shape.rs`）：
-
-```rust
-pub(crate) fn expanded_island_radius(w: f32, h: f32, scale: f32) -> f32 {
-    (48.0 * scale).min(w / 2.0).min(h / 2.0).max(0.0)
-}
-```
-
-compact 圆角：`IslandSprings::new` 里 `r = (base_height * compact_scale) / 2.0`（`src/window/app.rs`）；
-展开时 `default_target_r = compact_content_h / 2.0`（`src/window/app/frame.rs` `update_spring_targets`）。
-
-### 1.2 compact 宽度的动态规则（不是固定 120）
-
-`src/window/app/layout.rs` `compute_lyric_target_width()`：
-
-- 无媒体 / 不在播放态：宽 = `base_width` = **120**
-- 有媒体但无歌词：宽 = `base_width + 35.0` = **155**
-- 有歌词（不滚动）：`w = 60.0 + 文本宽`，再 `clamp(base_width+35, MAX_LYRIC_WIDTH)`
-  - `min_w = base_width + 35.0`、`MAX_LYRIC_WIDTH = 700.0`（`src/core/config.rs`）
-- 有歌词（滚动模式，`lyrics_scroll = true`）：`natural_w = 60.0 + text_w`，超过 `lyrics_scroll_max_width`（默认
-  `300.0`，`default_lyrics_scroll_max_width`）则固定为该上限；内部可用文本宽 = `(fixed_w - 59.0) * compact_scale`
-- 二级歌词存在时：高度 = `max(base_height*scale, mini_lyric_pair_height)`，
-  其中 `lyric_pair_height = 主字号*(1 + 0.85 + 0.18) + 8*scale`
-  （`SECONDARY_LYRIC_SCALE = 0.85`、`LYRIC_PAIR_GAP_SCALE = 0.18` @ `src/core/render/mini.rs`）
-  → 默认字号 12 时 = 12×2.03 + 8 = **32.36 px 高**，r ≈ 16.18
-
-### 1.3 挂件（compact widget）导致的最小宽度
-
-`src/ui/widget/compact/mod.rs`：
-
-- `CONTENT_EDGE_INSET = 9.0`、`CONTENT_GAP = 7.0`
-- `widget_width()`：`Time = 48.0`、`ResourceUsage = 132.0`
-- 三组对齐宽度：`aligned_layout_width = 9*2 + left + center + right + 7*(占用组数-1)`
-- 单侧扩展宽：`extension_width = CONTENT_EDGE_INSET + strip_width + CONTENT_GAP`
-  （例：左 Time → 9+48+7 = **64**；ResourceUsage → 9+132+7 = **148**）
-- 最终 compact 宽 = `max(布局宽, base_width)`
-
-### 1.4 compact overlay（通知 / 音量）会替换 base 尺寸
-
-| overlay | 宽                                         | 高                                        | 圆角             | 来源                                                                                                    |
-| ------- | ------------------------------------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
-| 通知    | `max(base_width, 330.0) * scale` = **330** | `max(base_height, 82.0) * scale` = **82** | `h/2` = **41**   | `src/ui/compact/notification.rs` `target_size()`；r 取自 `src/window/app/frame.rs`（`size.height/2.0`） |
-| 音量    | `(base_width + 72.0) * scale` = **192**    | `(base_height + 10.0) * scale` = **37**   | `h/2` = **18.5** | `src/ui/compact/volume.rs` `target_size()`                                                              |
-
-### 1.5 隐藏态尺寸
-
-- `hidden_width` 默认 `5.0`（`default_hidden_width` @ `src/core/config.rs`），
-- `MIN_HIDDEN_WIDTH = 0.0`、`MAX_HIDDEN_WIDTH = 400.0`
-- 隐藏时高度收缩到 `hidden_width * compact_scale`，并保留 `hidden_reveal_h = 1.0`（1px 可点击边）；
-  位移距离 `hide_distance = concealed_height + TOP_OFFSET`（`src/window/app/layout.rs`）
-
-### 1.6 锚点（两种状态之间什么不动）
-
-定位全部来自 `src/window/app/layout.rs` `compute_island_layout()` / `compute_window_position()`：
-
-- **顶部居中停靠（默认）**：`island_y = TOP_OFFSET = 10.0`（**顶边固定**），
-  `offset_x = (os_w - w) / 2.0`（**水平中心固定**）
-- **底部停靠**：`island_y = os_h - TOP_OFFSET - h`（**底边固定**，向上生长）
-- **左/右停靠**：`offset_x = TOP_OFFSET` 或 `os_w - TOP_OFFSET - w`（对应侧边固定）
-- `TOP_OFFSET: i32 = 10`（`src/core/config.rs`）＝ 岛顶边距屏幕顶 10 px
-- 状态切换由三个弹簧同时插值：`w/h/r` 参数为 `stiffness = 0.10, damping = 0.68`（`src/window/app/frame.rs`），
-  页面横移 `view` 用 `0.12 / 0.68`；隐藏用 `(0.12, 0.70)` 隐藏 / `(0.08, 0.78)` 显示
-- **compact 内容不跟随变大的岛做垂直居中重排**：mini 内容画在 `stable_island_y`（= 顶边）加上 `base_h` 带内居中
-  （`src/core/render/mini.rs`：封面 `y = stable_offset_y + (base_h - size)/2`，歌词 `center_y = stable_offset_y + base_h/2`）。
-  效果＝岛向下长大，胶囊内容始终贴在顶部那条带里。
-- 交叉淡出：`expanded_alpha = expansion_progress² * (1-hide_progress)`，
-  `mini_alpha = clamp(1 - expansion_progress*1.5, 0, 1) * (1-hide_progress)`
-  （`MINI_FADE_RATE = 1.5` @ `src/core/render.rs`）→ 即进度 0~0.667 之间完成交叉淡出
-
-### 1.7 有没有"挖孔/刘海"造型？
-
-**没有。** 代码里没有 `SetWindowRgn` / `CreateRoundRectRgn` / notch / cutout 相关调用（已全仓 grep 确认），
-也没有"顶部贴边 + 上方两角变直角"的特例分支。造型是：
-
-- 一个**悬浮胶囊**（compact，r = h/2），**距屏幕顶 10 px**；
-- 展开后是**四角一致的连续超椭圆**（squircle），r 最大 48。
-
-圆角实现不是普通圆弧，而是 Flutter `RoundedSuperellipse` 的移植（`src/utils/shape.rs`，
-注释标明 "Rounded-superellipse geometry adapted from Flutter under the BSD-3-Clause license"）：
-
-- `superellipse_parameters()`：11 项查表 `PARAMETERS`（如 `(2.0, 1.13276676) … (6.43023796, 2.98020421)`），
-  ratio > 5 时线性外推 `exponent = 6.43023796 + 1.559599389*(ratio-5.0)`、`factor = 2.98020421 + 0.522807185*(ratio-5.0)`
-- `Octant::new()`：13 项 `BEZIER_FACTORS`（`(0.7078, 8.3194) … (0.9705, 1.2880)`），用 conic + cubic 拼四分之一角
-- 路径缓存 `PATH_CACHE_CAPACITY = 64`
-- **Web 复刻提示**：CSS `border-radius` 是正圆角，观感会偏"软"；要还原请用 SVG path 或
-  `corner-shape: squircle`（若可用）/ `clip-path` 近似。**未找到**等价的简单圆角公式——真实几何就是上面那张表。
-- **本仓库的落地实现**（`packages/desktop-client/src/island/squircle.ts`）：不查表，用单参数超椭圆近似
-  `point = center + r·(sign(cos a)·|cos a|^p, sign(sin a)·|sin a|^p)`，`p = 2/n`、`n = 4.2`，
-  四角分别以 `TR(w-r,r) → BR(w-r,h-r) → BL(r,h-r) → TL(r,r)`、起始角 `-π/2, 0, π/2, π` 各扫 `π/2`，
-  每角 14 段。**四个角必须各用自己的圆心 + 角度参数**：早期版本四个角共用同一个"偏移向量"，
-  左上/右下被切成缺一块（用户反馈的"左上角和右下角怎么缺一块 / 圆角边缘割裂"），
-  现已由 `verify:desktop` 的「连续圆角四角一致」断言（四角沿对角线边界步进两两一致 + 路径绕行 \|winding\|≈2π）长期守住。
-
-### 1.8 窗口留白 / 裁切
-
-- `PADDING: f32 = 80.0`（`src/core/config.rs`）；窗口尺寸 = `(岛宽 + 80, 岛高 + 80)`
-  （`src/window/app/layout.rs` `required_window_size()`）→ **岛四周各 40 px 透明留白**，供阴影/动画使用
-- 绘制时 `canvas.clip_path(island_path, ClipOp::Intersect)`，所有内容裁在岛形内；
-  1px 描边在 `canvas.restore()` **之后**绘制（`src/core/render.rs` `draw_island()`）
-- 挂件网格额外内缩，避免内容进圆角（`src/ui/widget/expanded/mod.rs` `widget_grid_layout`）：
-  ```rust
-  corner_inset = radius * (1.0 - FRAC_1_SQRT_2);      // 48 * 0.29289 = 14.06
-  inset = (corner_inset + 8.0*scale).max(24.0*scale); // = 24.0（scale=1）
-  gap = 7.0 * scale;
-  ```
-
-### 1.9 expanded 内容网格
-
-- `WIDGET_GRID_COLS = 6`、`WIDGET_GRID_ROWS = 3`、`WIDGET_GRID_SLOTS = 18`（`src/core/config.rs`）
-- 槽位宽 = `(inner_w - 7*5) / 6`，高 = `(inner_h - 7*2) / 3`；
-  用 360×200、inset 24 计算：inner = 312×152 → **slot ≈ 46.17 × 46.0**（`src/ui/widget/expanded/mod.rs`）
-- 组件占格 `WidgetKind::span()`：`Clock = (2,1)`、`ResourceUsage = (2,1)`、`Calendar = (2,2)`、`Settings = (1,1)`
-  （`src/core/config.rs`）
-
----
-
-## 2. 配色（颜色 token）
-
-### 2.1 岛背景（`src/core/render/background.rs` `draw_background()`）
-
-| 样式                        | 颜色值                                                         | 说明                 |
-| --------------------------- | -------------------------------------------------------------- | -------------------- |
-| `default`（`SOLID_STYLE`）  | `Color::BLACK` = **#000000**，完全不透明                       | `bg_color`           |
-| `glass` + host backdrop     | `Color::from_argb(150, 10, 10, 14)` = **rgba(10,10,14,0.588)** | `draw_host_glass()`  |
-| `glass` 无 backdrop（回退） | `Color::from_argb(205, 32, 32, 36)` = **rgba(32,32,36,0.804)** | `fallback_color`     |
-| `dynamic` 底色              | `Color::from_rgb(32, 32, 36)` = **#202024**，不透明            | `draw_effect_base()` |
-| `dynamic` 叠加层            | `Color::from_argb(120, 20, 20, 24)` = **rgba(20,20,24,0.471)** | 盖在旋转模糊封面之上 |
-| `dynamic` 无封面回退        | 同 glass 分支（150/10,10,14 或 205/32,32,36）                  |                      |
-
-`dynamic` 封面动效参数（同一函数）：
-
-- 集显：`rotate_speed = 0.015 rad/s, drift_speed_x = 0.075, drift_speed_y = 0.06, drift_amp_x = 10.0, drift_amp_y = 7.5`
-- 独显：`rotate_speed = 0.03, drift_speed_x = 0.15, drift_speed_y = 0.12, drift_amp_x = 20.0, drift_amp_y = 15.0`
-- 旋转矩形边长 `side_len = diagonal * 1.3`
-
-**亚克力/backdrop 真实实现**（`src/window/d3d.rs` + `src/utils/win32.rs`）：
-Windows 11 `DWMWA_USE_HOSTBACKDROPBRUSH`，失败时退回 `SetWindowCompositionAttribute`
-（`AccentPolicy { state: 5, flags: 0, gradient_color: 0 }`，state 5 = host backdrop）；
-再用 `Compositor::CreateHostBackdropBrush()` + `RoundedRectangleGeometry` 裁圆角
-（`HOST_BACKDROP_INSET = 1.0`，几何 = `w-2, h-2, radius-1`）。
-**未找到**任何模糊半径数值——模糊由系统 HostBackdropBrush 决定。
-
-### 2.2 描边（`src/core/render.rs` `draw_island_border()`）
-
-```rust
-BORDER_WIDTH = 1.0;  BORDER_INSET = BORDER_WIDTH / 2.0;   // 0.5
-SOLID_STYLE = "default";  SOLID_BORDER_ALPHA = 30;  EFFECT_BORDER_ALPHA = 40;
-```
-
-- 颜色 = **纯白**，alpha：
-  - `default` 样式：`rgba(255,255,255, 30/255=0.118)`，**并再乘 `(1 - expansion_progress)`**（展开后描边消失）
-  - `glass` / `dynamic`：`rgba(255,255,255, 40/255=0.157)`，不随展开衰减
-- 描边矩形 = `(x+0.5, y+0.5, w-1, h-1)`，圆角 `r-0.5`
-
-### 2.3 阴影（`src/core/render.rs` `draw_expanded_shadow()`，仅展开时）
-
-- 颜色 `Color::from_argb((28.0 * opacity) as u8, 0,0,0)` = **rgba(0,0,0,0.11)**
-- `opacity = expansion_progress² * (1 - hide_progress)`，`opacity <= 0.01` 直接跳过
-- 偏移 `offset_y = 2.0 * scale`；模糊 `sigma = min(3.0*scale, margin/3.0)`（margin = 到画布边界的余量）
-- 用 `ClipOp::Difference` 只画在岛形之外
-- **未找到内阴影**（没有任何 inner shadow 实现）
-
-### 2.4 分隔线
-
-| 位置                 | 颜色                                               | 尺寸                                                               | 来源                                              |
-| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
-| compact 挂件之间     | `rgba(255,255,255, 0.14*alpha)`                    | 宽 `max(scale,1)`，从 `top+25%h` 到 `bottom-25%h`                  | `src/ui/widget/compact/mod.rs` `draw_separator()` |
-| compact 资源占用内部 | `rgba(255,255,255, 0.10*alpha)`                    | 宽 `max(0.75*scale, 0.75)`，半高 `DIVIDER_HALF_HEIGHT = 6.0*scale` | `src/ui/widget/compact/resource_usage.rs`         |
-| expanded 资源环分隔  | `rgba(白, 0.09*alpha)`                             | 宽 `scale.max(0.75)`，从 `y+0.2h` 到 `y+0.8h`                      | `src/ui/widget/expanded/resource_usage.rs`        |
-| 设置窗口分隔线       | `rgba(255,255,255,26)` 暗 / `rgba(20,28,40,18)` 亮 | —                                                                  | `src/utils/color.rs`                              |
-
-### 2.5 文字颜色与不透明度分层
-
-主文字一律 **#FFFFFF**；次级用 alpha：
-
-| 元素               | 有效颜色                                                     | 来源                                                 |
-| ------------------ | ------------------------------------------------------------ | ---------------------------------------------------- |
-| 通知 app 名        | `rgba(255,255,255, 0.65*alpha)`                              | `src/ui/compact/notification.rs`                     |
-| 通知标题           | `rgba(255,255,255, alpha)`                                   | 同上                                                 |
-| 通知详情           | `rgba(255,255,255, 0.72*alpha)`                              | 同上                                                 |
-| 音量标签           | `rgba(255,255,255, 0.9*alpha)`                               | `src/ui/compact/volume.rs`                           |
-| expanded 歌手      | `rgba(白, alpha*0.6)`                                        | `src/ui/expanded/music_view.rs` `draw_track_text()`  |
-| 迷你歌词主行       | 白 alpha                                                     | `src/core/render/mini.rs`                            |
-| 迷你歌词次行       | `rgb(176,176,176)`（`SECONDARY_LYRIC_CHANNEL = 176`）        | 同上                                                 |
-| 逐字歌词"未唱"部分 | `rgb(190,190,190)`（`PENDING_LYRIC_CHANNEL = 190`）          | 同上                                                 |
-| 进度条时间         | 白，`PROGRESS_TIME_IDLE_ALPHA = 0.5` → hover 1.0（线性插值） | `src/ui/expanded/music_view.rs`                      |
-| 挂件时钟           | 白 alpha（bold）                                             | `src/ui/widget/expanded/time.rs`                     |
-| 挂件日历 月        | `0.78*alpha`                                                 | `src/ui/widget/expanded/calendar.rs`                 |
-| 挂件日历 日        | `1.0*alpha`                                                  | 同上                                                 |
-| 挂件日历 星期      | `0.62*alpha`                                                 | 同上                                                 |
-| 挂件资源 数值      | `1.0*alpha`（bold）                                          | `src/ui/widget/expanded/resource_usage.rs`           |
-| 挂件资源 标签      | `0.58*alpha`                                                 | 同上                                                 |
-| 封面占位块         | `rgba(白, 0.15*alpha)`                                       | `src/ui/expanded/music_view.rs` `draw_placeholder()` |
-
-### 2.6 强调色 / 状态色
-
-岛内（`src/ui/widget/resource_usage.rs`）：
-
-```rust
-CPU_COLOR      = rgb(50, 190, 246)   // #32BEF6
-RAM_COLOR      = rgb(175, 82, 222)   // #AF52DE
-WARNING_COLOR  = rgb(255, 159, 10)   // #FF9F0A
-CRITICAL_COLOR = rgb(255, 69, 58)    // #FF453A
-```
-
-阈值曲线 `usage_color(base, usage)`：
-
-- `usage <= 0.75` → base
-- `0.75 < usage <= 0.9` → base ↔ WARNING 线性混合，`t = (usage-0.75)/0.15`
-- `0.9 < usage` → WARNING ↔ CRITICAL 线性混合，`t = (usage-0.9)/0.1`
-  采样间隔 `SAMPLE_INTERVAL = 1s`；无数值时显示 `—`。
-
-进度条/音量条（`src/ui/expanded/music_view.rs`、`src/ui/compact/volume.rs`）：
-
-```rust
-PROGRESS_TRACK_ALPHA = 0.15;      // 轨道 rgba(白, 0.15*alpha)
-PROGRESS_TIME_IDLE_ALPHA = 0.5;   // 时间文字静止透明度
-// 音量轨道 rgba(255,255,255, 0.28*alpha)，填充纯白 alpha
-```
-
-音量的"填充"就是**白色**（不是强调色），图标仍是白色。
-
-可视化条颜色**来自专辑封面**（`src/ui/expanded/music_view/palette.rs`）：
-
-- 把封面画到 8×8 的 GPU surface（`PALETTE_SAMPLE_SIZE = 8`）读回求平均 RGB
-- `primary = brighten(avg, 1.3)`、`secondary = brighten(avg, 1.5)`
-- `brighten` 用 BT.601 亮度 `0.299R + 0.587G + 0.114B`；若 < 80 则整体加 `80 - brightness`（抬到最低亮度 80）
-- 调色板 = `[primary, secondary, primary]`，缓存上限 50 条
-- 无封面默认值（`default_media_palette`）：`rgb(180,180,180)` + `rgb(100,100,100)`
-- 采样完全失败的兜底：`rgb(200,200,200)`
-
-### 2.7 不同状态是否不同配色？
-
-- **同一套**：底 + 白字 + alpha 分层；通知 / 音量 / 音乐 / 挂件没有各自的独立配色，
-  视觉区分靠 **尺寸（330×82 / 192×37 / 120×27）** 与 **内容排版**，而不是换色。
-- 差异只在两处：**可视化条用封面取色**（2.6），**资源占用用 CPU/RAM/警告/危险四色**（2.6）。
-- 岛背景三样式（default/glass/dynamic）才是真正的配色分支（2.1）。
-
-### 2.8 设置窗口色板（另一套，`src/utils/color.rs`，供参考）
-
-暗色主题 `dark_settings_theme()`：
-
-```
-win_bg #1C1C1E  sidebar_bg #242426  group_bg #2C2C2E  card_highlight #48484A
-accent #0A84FF  text_pri #F5F5F7   text_sec #AEAEB2  disabled #636366
-danger #E6372D  toggle_on #30D158  toggle_off #636366
-sidebar_hover rgba(255,255,255,20)  separator rgba(255,255,255,26)
-popup_bg #323234  popup_border rgba(255,255,255,40)  popup_shadow rgba(0,0,0,60)
-popup_separator rgba(255,255,255,30)  control_bg #3A3A3C  control_hover #48484A
-control_disabled #303032  control_border rgba(255,255,255,36)
-group_border rgba(255,255,255,24)  shadow rgba(0,0,0,45)  scrollbar rgba(255,255,255,60)
-```
-
-亮色主题 `light_settings_theme()`：
-
-```
-win_bg #F4F5F7  sidebar_bg #FAFAFC  group_bg #FFFFFF  card_highlight #EFF2F7
-text_pri #1F2228  text_sec #5B626E  disabled #9297A1  accent #0067C0
-danger #C42B1C  toggle_on #0078D4  toggle_off #B0B5BE
-selection_bg #E0EEFA  selection_text #005599
-sidebar_hover rgba(20,32,48,14)  separator rgba(24,32,44,18)
-popup_bg #FFFFFF  popup_border rgba(20,28,40,24)  popup_shadow rgba(20,28,40,20)
-control_bg #F7F8FA  control_hover #EBEFF4  control_disabled #F1F2F5
-control_border rgba(20,28,40,24)  group_border rgba(20,28,40,14)
-shadow rgba(20,28,40,20)  scrollbar rgba(52,58,68,52)
-```
-
-设置窗口另有"岛预览"配色（与真实渲染略有差异，`src/utils/settings_ui/renderer/widget_preview.rs`）：
-glass 预览 `rgba(24,24,28,220)`；dynamic 预览为线性渐变 **`rgb(18,12,36)` → `rgb(8,24,48)`**（左上→右下）；
-default 预览 `rgb(10,10,10)`；预览描边 alpha `52`(glass) / `38`(其他)；预览阴影 `rgba(0,0,0,72)`，偏移 +4。
-→ 若前端需要一张**静态渐变**替代 `dynamic`，这两个色值就是现成可抄的。
-
----
-
-## 3. 排版（字体 token）
-
-### 3.1 字体族（`src/utils/font.rs`）
-
-1. 用户自定义字体：`config.custom_font_path` → `FontMgr::new_from_data()`（优先于全部）
-2. ASCII 文本：`"Microsoft YaHei"` → `"Segoe UI"` → 系统默认（`legacy_make_typeface`）
-3. 非 ASCII：逐字符匹配 `match_family_style_character("", style, &["zh-CN","ja-JP","en-US"], ch)`，
-   再依次尝试 `"Segoe UI Emoji"` → `"Microsoft YaHei"` → `"Segoe UI Symbol"` → `"Segoe UI"`
-4. 合成粗体：`needs_synthetic_bold()` = 请求 `weight >= 600` 且字体本身 `weight < 600` → `font.set_embolden(true)`
-5. 亚像素渲染始终开启 `font.set_subpixel(true)`
-
-字重只有两档：`FontStyle::bold()`（700）与 `FontStyle::normal()`（400）；
-滚动文本判定粗体用 `style.weight() >= 700`（`src/utils/scroll.rs`）。
-
-**字距 / 行高**：代码里**未找到** letter-spacing 或 line-height 参数；
-行距全部通过显式 y 偏移实现（见下表）。文本绘制走 Skia `draw_str`，
-大字文本（标题/歌手）`render_as_paths = true`（`src/utils/scroll.rs` 调用点）。
-
-### 3.2 字号表（默认 `config.font_size = 0.0` 时用内置值；>0 时用户值参与计算）
-
-| 用途                 | 字号                                         | 字重                  | 说明 / 来源                                                                                        |
-| -------------------- | -------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
-| mini 歌词主行        | `font_size*0.8*scale` 或 **12.0\*scale**     | normal                | `src/core/render/mini.rs` `lyric_font_size()`                                                      |
-| mini 歌词次行        | 主字号 × `SECONDARY_LYRIC_SCALE = 0.85`      | normal                | 同上                                                                                               |
-| mini 歌词对高度      | `主*(1+0.85+0.18) + 8*scale`                 | —                     | `lyric_pair_height()`                                                                              |
-| mini 插件文字（主）  | `font_size*0.7*scale` 或 **11.0\*scale**     | **bold**              | `PLUGIN_FONT_SCALE = 0.7`、`DEFAULT_PLUGIN_FONT_SIZE = 11.0`                                       |
-| mini 插件文字（次）  | 主 × `0.8`                                   | normal                | `PLUGIN_SECONDARY_FONT_SCALE = 0.8`，行距 `font_size*1.3`（`PLUGIN_SECONDARY_LINE_SPACING = 1.3`） |
-| expanded 曲名        | `font_size*scale` 或 **15.0\*scale**         | **bold**              | `src/ui/expanded/music_view.rs`                                                                    |
-| expanded 歌手        | 同上 **15.0\*scale**                         | normal                | 基线 = 曲名基线 + `22.0*scale`                                                                     |
-| 进度时间             | `font_size*0.67*scale` 或 **10.0\*scale**    | normal                | `PROGRESS_TIME_FONT_SCALE = 0.67`、`DEFAULT_PROGRESS_TIME_FONT_SIZE = 10.0`                        |
-| 通知 app 名          | **11.0\*scale**                              | normal                | `src/ui/compact/notification.rs`                                                                   |
-| 通知标题             | **13.0\*scale**                              | **bold**              | 同上                                                                                               |
-| 通知详情             | **11.0\*scale**                              | normal                | 行间距 `DETAIL_LINE_GAP = 21.0*scale`                                                              |
-| 音量标签             | **12.0\*scale**                              | normal                | `src/ui/compact/volume.rs`                                                                         |
-| compact 时钟挂件     | `clamp(h*0.43, 10, 12)`                      | **bold**              | `src/ui/widget/compact/time.rs`                                                                    |
-| compact 资源—标签    | `METRIC_LABEL_SIZE = 7.0*scale`              | **bold**              | `src/ui/widget/compact/resource_usage.rs`                                                          |
-| compact 资源—数值    | `METRIC_VALUE_SIZE = 10.0*scale`             | **bold**              | 同上                                                                                               |
-| expanded 时钟挂件    | `min(h*0.60, w*0.31)`，最小 `13.0*scale`     | **bold**              | `src/ui/widget/expanded/time.rs`                                                                   |
-| expanded 日历—月     | `clamp(h*0.14, 9, 15)*scale`                 | **bold**              | `src/ui/widget/expanded/calendar.rs`                                                               |
-| expanded 日历—日     | `min(h*0.53, w*0.70)`，最小 `26.0*scale`     | **bold**              | 同上                                                                                               |
-| expanded 日历—星期   | `clamp(h*0.12, 8, 12)*scale`                 | normal                | 同上                                                                                               |
-| expanded 资源—圆环值 | `clamp(d*0.27, 7, 10.5*scale)`，d = 圆环直径 | **bold**              | `src/ui/widget/expanded/resource_usage.rs`                                                         |
-| expanded 资源—标签   | `clamp(h*0.12, 6, 8*scale)`                  | **bold**              | 同上                                                                                               |
-| 设置窗口—行标签/值   | **13.0**                                     | normal                | `src/utils/settings_ui/renderer/items.rs`                                                          |
-| 设置窗口—页签标签    | **11.5**                                     | normal（选中为 bold） | `src/window/settings/renderer.rs`                                                                  |
-| 设置窗口—弹窗项      | **12.0**                                     | normal                | 同上                                                                                               |
-| 设置窗口—Markdown    | `BODY_SIZE = 12.0`，`LINE_HEIGHT = 18.0`     | —                     | `src/window/settings/pages/plugins/markdown.rs`                                                    |
-
-字体基线规则（值得照抄）：
-
-- 居中对齐用 **字形包围盒** 居中：`baseline_y = bounds.top + (bounds.h - glyph.h)/2 - glyph.top`
-  （`src/ui/widget/expanded/mod.rs` `draw_widget_text_centered()`）
-- 时间文字基线 = 进度条中心 + `0.35*字号`（`PROGRESS_TIME_BASELINE_SCALE = 0.35`）
-- 迷你歌词单行时 `primary_y = center_y + size/3`；双行时按堆叠高度对齐（见 5.1）
-
-### 3.3 是否随窗口尺寸 / 用户设置缩放
-
-- 随 `compact_scale` / `expanded_scale` 缩放（乘在所有尺寸上）
-- 字号受 `config.font_size`（默认 0 = 用内置值）影响：只有 mini 歌词、mini 插件、expanded 曲名/歌手、进度时间用它
-- 挂件字号是**几何驱动**的（按自身矩形宽高 clamp），与 `font_size` 无关
-- 设置窗口有自己的 `settings_theme`（`system` / 暗 / 亮）
-
----
-
-## 4. 层级与效果
-
-### 4.1 圆角
-
-见 1.7。总结：连续超椭圆（squircle），compact 满圆角（h/2），expanded 最大 48。
-挂件卡片 `widget_corner_radius = min(12.0*scale, min(w,h)/2)`（`src/ui/widget/expanded/mod.rs`）。
-迷你封面 `MINI_COVER_RADIUS = 5.0`，expanded 封面 `16.0*scale`，通知图标 `11.0*scale`。
-
-### 4.2 阴影 / 发光
-
-- **外阴影**：仅 expanded，`rgba(0,0,0,0.11)`，y+2，blur σ = `min(3*scale, margin/3)`（见 2.3）
-- **内阴影**：**未找到**
-- **发光**：只出现在资源占用圆环——`glow` 圆半径 `diameter*0.57`，颜色 `accent`，alpha `0.07*alpha`
-  （`src/ui/widget/expanded/resource_usage.rs`）
-- 设置窗口：窗口阴影 `rgba(0,0,0,90)`、弹出菜单阴影 `theme.popup_shadow` + 偏移 +2（`src/window/settings/renderer.rs`）；
-  拖拽幽灵阴影 `rgba(0,0,0,90)`，偏移 +4
-
-### 4.3 模糊半径（全部数值）
-
-| 场景                    | 参数                                                                                                        | 来源                        |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------- |
-| 运动模糊（整体）        | 横向 = `                                                                                                    | w速度                       | *0.3 +                              | view速度                                                          | *w*0.4`，纵向 = ` | h速度 | *0.3`；上限集显 `(4.0, 3.5)`、独显 `(12.0, 10.0)`；仅在 σ>0.1 时 `saveLayer` | `src/utils/blur.rs` `calculate_blur_sigmas()`、`src/core/render.rs` `MIN_BLUR_SIGMA = 0.1` |
-| 封面翻转                | `σ = (1-                                                                                                    | cos                         | )^0.6 * 8.0 * scale`，x 方向再 ×0.3 | `src/ui/expanded/music_view.rs`                                   |
-| 暂停按钮速度模糊        | `                                                                                                           | 弹簧速度                    | * 16.0 * scale`，上限 `2.5*scale`   | `PAUSE_CONTROL_BLUR_SCALE = 16.0`、`PAUSE_CONTROL_MAX_BLUR = 2.5` |
-| 快进/快退按钮           | `(1 - t/0.3).max(0) * 6.0 * scale`，x×0.3                                                                   | 同文件 `draw_skip_button()` |
-| 歌词切换（Blur 模式）   | `σ = 6.0*scale`，x 压缩 `LYRIC_TRANSITION_BLUR_X_SCALE = 0.25`，位移 `LYRIC_TRANSITION_OFFSET = 10.0*scale` | `src/core/render/mini.rs`   |
-| dynamic 背景封面        | 先降采样到 **64×64**，再 `image_filters::blur((8.0, 8.0), TileMode::Clamp)`                                 | `src/utils/backdrop.rs`     |
-| host backdrop（亚克力） | **未找到数值**（由系统 HostBackdropBrush 决定，仅 `HOST_BACKDROP_INSET = 1.0`）                             | `src/window/d3d.rs`         |
-
-### 4.4 不透明度分层与可见性阈值
-
-```
-MIN_VISIBLE_OPACITY = 0.01                // 低于此不绘制
-MIN_BLUR_SIGMA      = 0.1
-MINI_FADE_RATE      = 1.5                 // mini 淡出速率
-COLLAPSED_VISUALIZER_HEIGHT_SCALE = 0.45  // 收起时可视化高度 = 45%
-```
-
-- `expanded_alpha = expansion_progress² * (1 - hide_progress)`（平方 → 展开"迟入场"）
-- `mini_alpha     = clamp(1 - expansion_progress*1.5, 0, 1) * (1 - hide_progress)`
-- 可视化高度比例 `visualizer_height_scale = 0.45 + 0.55 * expansion_progress`
-- 歌词额外淡出 `LYRIC_EXPANSION_FADE_RATE = 2.5`（`src/core/render/mini.rs`）
-- 展开页横向滑动：`page_shift = view_offset * current_w`；
-  音乐页 `translate(-page_shift)`，挂件页 `translate(current_w - page_shift)`
-  （`src/core/render/expanded.rs`）；`view` 弹簧 `0.12/0.68`
-
-### 4.5 卡片四周留白 / 裁切
-
-见 1.8：窗口 = 岛 + 80（每侧 40 透明）；内容 `clip_path(Intersect)`；
-描边在裁切外画；挂件网格 inset 24。
-
----
-
-## 5. 布局骨架
-
-### 5.1 compact（mini）120×27
-
-`src/core/render/mini.rs`：
-
-```
-MIN_MINI_CONTENT_WIDTH  = 45.0    // 可用宽小于此不画内容
-MINI_COVER_SIZE         = 18.0    // 封面尺寸
-MINI_COVER_LEFT_INSET   = 10.0    // 封面左边距
-MINI_COVER_RADIUS       = 5.0     // 封面圆角
-MINI_VISUALIZER_RIGHT_INSET  = 17.0
-MINI_VISUALIZER_WIDTH_SCALE  = 0.55
-MINI_VISUALIZER_SMOOTHING    = (0.6, 0.08)   // (上升, 下降)
-LYRIC_LEFT_INSET   = 30.0
-LYRIC_RIGHT_INSET  = 29.0
-```
-
-- **左**：18×18 封面，x = 10，y 垂直居中（`(base_h - 18)/2 = 4.5`），圆角 5，中心裁剪
-- **中**：歌词，可用区 x ∈ [30, w-29]，垂直居中；主行居中（滚动模式改为左对齐并从 x=30 起滚动），
-  次行始终水平居中；主行单行时 `y = center_y + size/3`，双行时
-  `stack_h = size + size*0.85 + size*0.18`，主行 `y = center_y - stack_h/2 + size*0.8`，
-  次行 `y = center_y + stack_h/2 - secondary*0.2`
-- **右**：可视化条，中心 x = `w - 17`，中心 y = `base_h/2`
-- 无媒体时改由 compact 挂件条接管：Left / Center / Right 三组；
-  有 mini 内容时只画 Left 与（Center+Right）两组并贴两端，并在内容两侧画竖分隔线
-  （`src/ui/widget/compact/mod.rs` `draw()`）
-- 挂件宽：时间 **48**、资源 **132**；边缘 inset **9**；组内间距 **7**
-
-### 5.2 expanded 音乐页 360×200
-
-`src/ui/expanded/music_view.rs` 常量全表：
-
-```
-CONTENT_PADDING            = 24.0   // 四周内边距
-COVER_SIZE                 = 64.0   // 封面 64×64，圆角 16.0*scale，位置 (24,24)
-TRACK_TEXT_GAP             = 18.0   // 封面右到文字左
-TRACK_TEXT_RIGHT_INSET     = 70.0   // 文字右侧预留（给可视化条）
-TRACK_TITLE_BASELINE_OFFSET= 26.0   // 曲名基线 y = 24 + 26 = 50
-PROGRESS_TOP_GAP           = 24.0   // 进度条中心 y = 24 + 64 + 24 = 112
-PROGRESS_TIME_WIDTH        = 28.0   // 两端时间文字预留宽
-PROGRESS_TIME_GAP          = 4.0
-PROGRESS_BAR_HEIGHT        = 6.5    // 常态条高
-PROGRESS_BAR_HOVER_GROWTH  = 3.5    // hover 增至 10.0
-PLAYBACK_CONTROLS_TOP_GAP  = 42.0   // 控制行中心 y = 112 + bar_h/2 + 42 ≈ 157.25
-SKIP_BUTTON_GAP            = 75.0   // 上一首/下一首中心距播放键 75
-PAGE_ARROW_RIGHT_INSET     = 7.5    // 右侧翻页条 x = w - 7.5，y = h/2
-PAGE_ARROW_FADE_RATE       = 5.0
-COLLAPSED_VISUALIZER_INSET = 17.0   // 视觉条右侧 inset 随展开 17 → 37
-EXPANDED_VISUALIZER_INSET  = 37.0
-VISUALIZER_TITLE_OFFSET    = 4.0    // 视觉条中心 y = 曲名基线 - 4
-```
-
-- **左**：64 封面；**中**：曲名(15 bold)/歌手(15, α0.6) 两行，x = 24+64+18 = **106**；**右**：可视化条
-- 进度条：左右各内缩 24，两端 28 宽时间 + 4 间距；条圆角 = bar_h/2；
-  填充宽度 `max(bar_total_w*progress, bar_h)`；填充只圆左端（RRect 左上/左下半径 = bar_h/2，右侧 0）
-- 控制行中心 x = 180；播放键在中心、上一首 105、下一首 255
-- 点击热区（`src/ui/expanded/music_view/controls.rs`）：播放 **40×40**，上/下一首 **36×36**，
-  进度条热区高 **16.0\*scale**，封面整块可双击（激活媒体 App）
-- 动画参数：`PROGRESS_SMOOTHING = 0.15`、`PROGRESS_HOVER_SMOOTHING = 0.18`、
-  `PROGRESS_HOVER_SNAP_THRESHOLD = 0.005`、`PROGRESS_START_THRESHOLD = 0.02`、`PROGRESS_JUMP_THRESHOLD = 0.3`、
-  `PLAY_STATE_RESPONSE = 0.18`、`SKIP_ANIMATION_DURATION_SECS = 0.5`、封面翻转 0.6s、
-  `PAUSE_CONTROL_STIFFNESS = 0.18`、`PAUSE_CONTROL_DAMPING = 0.64`、`PAUSE_CONTROL_MIN_SCALE = 0.8`、
-  `PAUSE_CONTROL_MAX_SCALE = 1.03`、`PAUSE_CONTROL_PRESS_VELOCITY = -0.18`
-- 播放/暂停过渡：`cover_scale = 0.85 + 0.15*pause_t`、`cover_brightness = 0.75 + 0.25*pause_t`
-  （即暂停时封面缩小到 85% 并压暗到 75%），图标用 `smoothstep` 交叉淡出
-
-### 5.3 expanded 挂件页（同 360×200）
-
-- 6×3 网格，inset 24，gap 7（见 1.9）
-- 卡片：背景 `rgba(28,28,30, 0.05*alpha)`，描边 `1px rgba(255,255,255, 0.16*alpha)`，圆角 `min(12*scale, min(w,h)/2)`
-- 左侧翻页条 x = **7.5**，y = `h/2`（3×14 圆角矩形，α0.4）；右侧同（x = w-7.5）
-- 内置挂件各视图排布：
-  - **时钟**：整卡居中，字号 `min(h*0.6, w*0.31)`（≥13），bold，`HH:MM` 格式
-  - **日历**：月 `y+0.08h..0.26h`（bold，α0.78）／日 `y+0.27h..0.75h`（bold，字号 `min(0.53h,0.70w)`，≥26）／
-    星期 `y+0.78h..0.92h`（normal，α0.62）
-  - **资源占用（2×1）**：中间竖分隔（α0.09，`y+0.2h..0.8h`）；两个圆环各占一半：
-    环心 `(center_x, top+0.43h)`，直径 `min(0.58h, 0.62w)`（≥20），描边 `min(3*scale, d*0.12)` 圆头，
-    底环 α0.13，进度弧从 **-90°** 起扫 `usage*360°`（α0.92），值文字 bold 居中，标签在 `top+0.76h`（α0.58）
-  - **设置（1×1）**：整卡居中齿轮图标，`icon_scale = min(w,h)*0.38/24`，α0.72
-
-### 5.4 compact 各业务视图差异
-
-| 视图                                                                                                                                                                     | 尺寸   | 排布                                                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 时间挂件                                                                                                                                                                 | 48×27  | 居中 `HH:MM`，字号 `clamp(0.43h, 10..12)` bold，基线 `center_y + size*0.36`                                                                         |
-| 资源挂件                                                                                                                                                                 | 132×27 | 两个 metric 各 `(w-8)/2` 宽；标签 7px bold 在左（accent α0.78），数值 10px bold 在右（白）；                                                        |
-| 文字基线 `center_y + scale`；下方 2px 进度轨（y = 基线+5），轨 α0.13，填充 accent α0.9；中间分隔 α0.1，半高 6                                                            |
-| 通知                                                                                                                                                                     | 330×82 | 图标 42×42 圆角 11 @ x+18 垂直居中；文本左 = 有图标 `x+72` / 无图标 `x+20`；右内缩 18；                                                             |
-| app 名基线 `top+22`（11px α0.65）；标题 13px bold，基线 `top+34`（无 app 名）/ `top+43`（有 app 名）/ 垂直居中 `top+(h+13)/2`（两者皆无）；详情 11px α0.72 在标题下 21px |
-| 音量                                                                                                                                                                     | 192×37 | 喇叭图标 20px，中心 `x = left+21`；标签 12px @ `left+37`（α0.9）；轨道从 `label_x + label_w + 26` 到 `right-14`，高 4 圆角 2，轨 α0.28，填充白 α1.0 |
-
-### 5.5 动画时长（通知 / 音量）
-
-- 通知：`DISPLAY_DURATION = 5s`，`ENTER_DURATION = 220ms`（`ease_out_cubic = 1-(1-t)³`），
-  `FADE_DURATION = 280ms`；入场位移 `(1-enter)*7.0*scale`（从上滑下 7px）
-- 音量：`DISPLAY_DURATION = 1600ms`，`FADE_DURATION = 240ms`，
-  `VOLUME_CHANGE_THRESHOLD = 0.002`（音量变化阈值，低于此不显示）
-- 歌词切换进度用 `smoothstep`：`p*p*(3-2p)`（`src/core/render/mini.rs`）
-- 长文本跑马灯（`src/utils/scroll.rs`）：先停 **2.0s**，再以 **35.0\*scale px/s** 滚动，
-  循环间隔 `full_w + 50*scale`，裁剪区 `(x, y-size*1.2, max_w, size*1.5)`
-
----
-
-## 6. 图标
-
-**体系**：全部是 Skia 内的 **SVG path 数据 + 填充（`PaintStyle::Fill`）**，没有线性描边图标体系，
-也没有 icon font。颜色一律单色：由 `text_color`（= 白）+ alpha 决定；只有资源环用 accent 色。
-**未找到**线宽（stroke-width）概念——唯一的描边图标是设置窗口的翻页箭头（`1.8px`, round cap/join）。
-
-| 图标             | 路径坐标系               | 缩放                                                                                  | 实际视觉尺寸                                               | 来源                                                                                             |
-| ---------------- | ------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| 播放 ▶           | 640 单位（128..544）     | `0.083 * scale`                                                                       | ≈ 34.5 × 37 px                                             | `src/icons/controls.rs` `draw_play_button`                                                       |
-| 暂停 ⏸           | 640 单位                 | `0.083 * scale`                                                                       | ≈ 34.5 × 37 px                                             | `draw_pause_button`                                                                              |
-| 快退/快进三角    | 640 单位（中心 336,320） | `path_scale * global_scale`，静止 `0.050`（左）与 `0.055`（右）；动画中 `0.050~0.055` | 约 21 × 22 px                                              | `draw_control_triangle`，`src/ui/expanded/music_view.rs` `draw_skip_button`（中心 ±10.92*scale） |
-| 音乐（封面占位） | 1024 单位                | `scale*1.8`，内部 `0.024`                                                             | 随卡片                                                     | `src/icons/music.rs`                                                                             |
-| 设置齿轮         | 1024 单位                | `min(w,h)*0.38/24`，内部 `0.024`                                                      | 卡片 38% 短边                                              | `src/icons/settings.rs`                                                                          |
-| 音量（4 档）     | 25.75 单位               | `size / 25.75`，偏移 `(-11.089286, -7.883929)`                                        | 传 20.0*scale                                              | `src/icons/volume.rs`；档位 `level<=0→静音, <=1/3→低, <=2/3→中, else→高`                         |
-| 翻页指示条       | 不是 path                | —                                                                                     | `3.0*scale × 14.0*scale` 圆角矩形，圆角 `2.0*scale`，α×0.4 | `src/icons/arrows.rs`                                                                            |
-
-其他图标使用点：
-
-- 通知 App 图标：`AppDisplayInfo::GetLogo(Size{64,64})`，按 alpha>8 计算可见包围盒，等比缩放塞进 42×42，圆角 11 裁切
-- 封面：64×64（expanded）与 18×18（mini），中心裁剪，`FilterMode::Linear + MipmapMode::Linear`
-- 迷你封面圆角 5、expanded 封面圆角 16（连续超椭圆路径，不是普通 `clip_rrect`）
-
----
-
-## 7. 明确「未找到」的项
-
-1. **刘海/挖孔造型**：不存在（无 `SetWindowRgn`、无顶部直角特例）
-2. **内阴影 / inset shadow**：代码中无任何实现
-3. **字距（letter-spacing）与行高倍数**：无；行距全靠显式 y 偏移
-4. **亚克力的模糊半径/透明度数值**：由 Windows `HostBackdropBrush` 系统决定，代码只给 `HOST_BACKDROP_INSET = 1.0`
-   → Electron 侧**没有**等价物：`setBackgroundMaterial('acrylic')` 是整窗系统材质（跟随应用主题、覆盖窗口矩形），
-   不能像 `DWMWA_USE_HOSTBACKDROPBRUSH` 那样只画在圆角形状里；本项目因此改用无 backdrop 的降级色（见 §8）
-5. **强调色用于岛内 UI**：岛内几乎没有强调色（只有资源占用的 CPU/RAM/警告/危险色）；
-   统一强调色 `#0A84FF` 仅存在于**设置窗口**（`COLOR_ACCENT`）
-6. **岛自身的亮/暗主题**：岛屿永远是深底白字；明暗主题只在设置窗口
-7. **固定渐变色背景**：真实 `dynamic` 背景是封面图，没有固定渐变；
-   仅设置页预览用 `rgb(18,12,36) → rgb(8,24,48)`（可当静态替代）
-8. **CSS 等价的超椭圆圆角公式**：真实实现是 Flutter 超椭圆查表（`src/utils/shape.rs`），没有简单的 border-radius 参数
-
----
-
-## 8. 给 Web/Electron 复刻的映射速查
-
-- 岛容器：定位在屏幕顶上 `top: 10px`、水平居中，尺寸与圆角用 spring 插值
-  （`cubic-bezier` 或 JS 弹簧，参考 `stiffness 0.10 / damping 0.68`）；`overflow: hidden` 做裁切
-- compact：`120×27`（有歌词时宽度跟着文本走，上限 700；只有媒体无歌词时 155），`border-radius: 13.5px`（胶囊）
-- expanded：`360×200`，`border-radius: 48px`（想要 iOS 味请用 SVG 超椭圆路径）
-- 背景：`#000` 不透明；"glass" **不要**照搬 WinIsland 的 host backdrop —— Electron 的
-  `setBackgroundMaterial()` 是"整窗系统材质"，覆盖范围是窗口矩形而不是卡片形状，且明暗跟随应用主题，
-  在浅色主题下会给卡片垫出一圈浅色面板（详见 `packages/desktop-client/src/main/island.ts`）；
-  我们改用 WinIsland 自己的**无 backdrop 降级色** `rgba(32,32,36,.804)` 画在卡片上；
-  "dynamic" 用封面模糊层 + `rgba(20,20,24,.471)` 叠加
-- 描边：`1px solid rgba(255,255,255,.118)`（纯色样式，展开时淡出）/ `.157`（glass、dynamic）
-- 阴影：仅展开 `0 2px σ rgba(0,0,0,.11)`（σ ≈ 3px）
-- 文字：`-apple-system / "Microsoft YaHei" / "Segoe UI"`，白 + alpha 分层（.65 / .72 / .9 / .6 / .5 / .58 / .62）
-- 图标：内联 SVG，`fill: currentColor`，播放/暂停按 640 坐标系、尺寸 ≈ 34.5×37
-
----
-
-## 附：班级小助手实际采纳了哪些（本次重写对照表）
-
-| WinIsland 做法                                           | 出处                                                                                                 | 我们的落地                                                                                                                         | 验证                                            |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| **窗口一次建大包围盒，形变发生在窗口内**                 | `window/app/layout.rs` `required_window_size()` + `PADDING=80`                                       | 窗口固定为「最大形态 + `ISLAND_SHADOW_PAD(10)`」，开合期间**一帧都不 setBounds**                                                   | 逐帧窗口签名恒为 `476x282@482,-2`（只有 1 种）  |
-| 尺寸/圆角由弹簧驱动                                      | `utils/physics.rs` + `app.rs` `IslandSprings`（w/h/r = `0.10/0.68`）                                 | `src/island/spring.ts` 同参数同更新式（dt 以帧计、`damping^dt`、换向保留 35% 动量 + 20% 距离上限），并加**零过冲钳制**             | 岛中心/边缘波动 0.00px、无过冲                  |
-| 连续圆角（超椭圆）                                       | `utils/shape.rs` `continuous_rounded_rect_path` / `expanded_island_radius = min(48*scale, w/2, h/2)` | `src/island/squircle.ts` 超椭圆角路径；展开半径 `min(48×圆角/20, w/2, h/2)`                                                        | 形状 bbox 与卡片框一致（±2px）                  |
-| 内容交叉淡入 `expanded=progress²`、`mini=1-1.5×progress` | `core/render.rs`（`MINI_FADE_RATE=1.5`）                                                             | 两层常驻、透明度按同一公式                                                                                                         | 截图与 DOM 断言                                 |
-| 描边 1px 白 alpha 30（纯色）/ 40（glass）                | `core/render.rs` `BORDER_*_ALPHA`                                                                    | `--wn-border` 取同值（`.118` / `.157`）                                                                                            | 计算样式断言                                    |
-| 展开投影 `rgba(0,0,0,.11)`、y+2、σ=3                     | `draw_expanded_shadow`                                                                               | `drop-shadow(0 2px 3px rgba(0,0,0,.11))`                                                                                           | 截图                                            |
-| 纯黑底 / 亚克力（HostBackdropBrush）                     | `background.rs` + `win32.rs` `DWMWA_USE_HOSTBACKDROPBRUSH`                                           | 纯黑底 / **glass 用 CSS 半透明深色卡**（WinIsland 无 backdrop 降级色 `rgba(32,32,36,.804)`）；**不调用** `setBackgroundMaterial()` | 计算样式 + 「卡片外圈透出桌面」整屏截图像素断言 |
-| `set_cursor_hittest` 命中控制                            | `frame.rs`（`set_cursor_hittest`）                                                                   | 默认 `setIgnoreMouseEvents(true,{forward:true})`，渲染层命中测试后切换                                                             | 岛内 true / 岛外 false                          |
-| 空闲细缝 `hidden_width = 5`                              | `core/config.rs`                                                                                     | 6px 宽竖条（窗口固定，不再受 Windows 最小窗口高度限制）                                                                            | 空闲 `6x22` → 来消息 `268x44`                   |
-| 6 个停靠位 `DockPosition`                                | `core/config.rs`                                                                                     | 顶/底 × 左/中/右 6 锚点，岛（而非窗口）精确落在锚点                                                                                | 6 锚点坐标断言                                  |
-| `font_size` = 基础字号 × 各文本系数                      | `core/render/mini.rs`、`ui/expanded/music_view.rs`                                                   | 基础字号 11–20px × 系数表（标题 1.08/正文 0.95/次要 0.78/徽标与按钮 0.76/胶囊 0.92、0.74）                                         | 13→19px 全部文本倍率 1.462                      |
-| 未采纳：音乐/歌词/小组件/音量浮窗                        | `ui/expanded/**`、`ui/widget/**`                                                                     | 业务不同（我们做通知/作业/叫人/紧急）                                                                                              | —                                               |

eslint.config.mjs

@@ -26,7 +26,7 @@ export default tseslint.config(
       '**/dist-electron/**',
       '**/release/**',
       '**/release-server/**',
-      // 交付产物归集目录（pnpm dist:* 的输出，见 AGENTS.md §4）：里面是构建后的压缩 JS，不该进 lint
+      // 交付产物归集目录（pnpm dist:* 的输出，见 AGENTS.md 的现行工程约定）：里面是构建后的压缩 JS，不该进 lint
       '**/releases/**',
       '**/build/**',
       '**/coverage/**',
@@ -34,6 +34,8 @@ export default tseslint.config(
       '**/.cache/**',
       '**/.pnpm-store/**',
       '**/.probe/**',
+      // 文档站（docfx）的构建产物：里面是 docfx 模板自带的压缩 JS 与生成的 HTML
+      '**/docs/_site/**',
       '**/*.d.ts',
     ],
   },

package.json

@@ -1,8 +1,8 @@
 {
   "name": "class-helper",
-  "version": "1.1.2",
+  "version": "1.4.0",
   "private": true,
-  "description": "班级小助手 - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
+  "description": "ClassHelper - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
   "packageManager": "pnpm@11.8.0",
   "engines": {
     "node": ">=20.19.0"
@@ -15,7 +15,6 @@
     "dev:desktop": "pnpm build:shared && pnpm --filter @classhelper/desktop-client dev",
     "build": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && pnpm --filter @classhelper/desktop-client build",
     "build:desktop": "pnpm build:shared && pnpm --filter @classhelper/desktop-client build",
-    "build:classisland-plugin": "node packages/classisland-plugin/scripts/build.mjs",
     "check:icons": "node scripts/check-icons.mjs",
     "typecheck": "pnpm build:shared && pnpm -r --no-bail typecheck",
     "lint": "eslint .",
@@ -29,19 +28,32 @@
     "db:studio": "pnpm --filter @classhelper/server db:studio",
     "db:switch:mysql": "node scripts/use-database.mjs mysql",
     "db:switch:sqlite": "node scripts/use-database.mjs sqlite",
-    "verify:e2e": "pnpm --filter @classhelper/server verify:e2e",
+    "verify:e2e": "node scripts/verify-e2e-isolated.mjs",
+    "verify:courseware": "node scripts/verify-courseware.mjs",
+    "verify:v14": "node scripts/verify-v14.mjs",
+    "verify:client-agent": "node scripts/verify-client-agent.mjs",
+    "verify:review-client": "node scripts/verify-review-client.mjs",
+    "verify:review-api": "node scripts/verify-review-api.mjs",
+    "verify:clients-api": "node scripts/verify-clients-api.mjs",
+    "verify:client-migrations": "node scripts/verify-client-migrations.mjs",
     "verify:desktop": "pnpm --filter @classhelper/desktop-client smoke",
     "verify:web": "node scripts/ui-smoke/run.mjs",
+    "verify:web:isolated": "node scripts/verify-e2e-isolated.mjs --web",
     "verify:packaged": "node scripts/verify-packaged.mjs",
-    "verify:classisland": "pnpm --filter @classhelper/server verify:classisland",
-    "verify:classisland-plugin": "node packages/classisland-plugin/scripts/verify.mjs",
     "icons": "node scripts/generate-icons.mjs",
+    "version:check": "node scripts/version.mjs",
+    "version:bump": "node scripts/version.mjs --bump",
+    "docs:build": "node docs/build.mjs",
+    "docs:serve": "node docs/build.mjs --serve",
+    "pages:build": "node scripts/build-pages.mjs",
+    "dev:site": "pnpm docs:build && node website/serve.mjs",
+    "docs:check": "node docs/build.mjs --check",
     "dist:win": "pnpm --filter @classhelper/desktop-client dist:win",
-    "dist:dir": "pnpm --filter @classhelper/desktop-client dist:dir",
     "dist:server": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs",
     "dist:server:linux": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs --platform linux",
-    "dist:classisland-plugin": "node packages/classisland-plugin/scripts/build.mjs --cipx",
-    "dist:all": "pnpm dist:server && pnpm dist:win && pnpm dist:classisland-plugin"
+    "dist:all": "pnpm dist:server && pnpm dist:win",
+    "verify:desktop:visual": "node packages/desktop-client/scripts/smoke.mjs --visual",
+    "verify:desktop:online": "node packages/desktop-client/scripts/smoke.mjs --online"
   },
   "devDependencies": {
     "concurrently": "^10.0.5",

packages/classisland-plugin/.gitignore

@@ -1,4 +0,0 @@
-# .NET 构建产物（与仓库根的 .gitignore 分开：根 .gitignore 是 GBK 编码，apply_patch 读不了）
-bin/
-obj/
-cipx/

packages/classisland-plugin/ClassHelper.ClassIslandPlugin.csproj

@@ -1,45 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <!--
-      ClassIsland 2.0 / 2.1.0.x 面向 net8.0；2.1.1 起改为 net10.0。
-      本插件按 net8.0 交付，因此 SDK 版本固定到最后一个 net8.0 的版本（2.1.0.1），
-      这样 ClassIsland 2.0.x 与 2.1.0.x 都能加载（apiVersion 见 manifest.yml）。
-    -->
-    <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <LangVersion>12</LangVersion>
-    <RootNamespace>ClassHelper.ClassIslandPlugin</RootNamespace>
-    <AssemblyName>ClassHelper.ClassIslandPlugin</AssemblyName>
-    <ClassIslandPluginSdkVersion>2.1.0.1</ClassIslandPluginSdkVersion>
-    <!-- 插件由 ClassIsland 加载，不需要生成自带运行时（ExcludeAssets 见下） -->
-    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
-    <!-- 设置页是 .axaml：需要让 Avalonia 的默认项把 **/*.axaml 收成 AvaloniaXaml 并编译 -->
-    <EnableDefaultItems>true</EnableDefaultItems>
-    <!-- 绑定走运行时解析：插件与主程序各自编译，编译期绑定会因看不到对方的类型而失败 -->
-    <AvaloniaUseCompiledBindingsByDefault>false</AvaloniaUseCompiledBindingsByDefault>
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
-    <GenerateDocumentationFile>false</GenerateDocumentationFile>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <!-- 运行时与原生资源由 ClassIsland 本体提供，插件只编译期依赖 -->
-    <PackageReference Include="ClassIsland.PluginSdk" Version="$(ClassIslandPluginSdkVersion)">
-      <ExcludeAssets>runtime;native</ExcludeAssets>
-    </PackageReference>
-  </ItemGroup>
-
-  <ItemGroup>
-    <None Update="manifest.yml">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-    <None Update="README.md">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-    <None Update="icon.png">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
-</Project>

packages/classisland-plugin/Properties/launchSettings.json

@@ -1,10 +0,0 @@
-{
-  "profiles": {
-    "ClassIsland 插件": {
-      "commandName": "Executable",
-      "executablePath": "$(ClassIsland_DebugBinaryFile)",
-      "commandLineArgs": "-epp $(TargetDir)",
-      "workingDirectory": "$(ClassIsland_DebugBinaryDirectory)"
-    }
-  }
-}

packages/classisland-plugin/README.md

@@ -1,163 +0,0 @@
-# 班级小助手联动插件
-
-把 [ClassIsland](https://classisland.tech) 与 [班级小助手](https://github.com/LoveChengke/ClassHelper) 连起来：
-让班级小助手**读到教室真实的课表与上课状态**，也让老师的提醒**在教室的 ClassIsland 上弹出来**。
-
-## 它能做什么
-
-| 方向                             | 说明                                                                                                        |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| ClassIsland → 班级小助手         | 上报课表与节次时间、上报上课状态（当前科目 / 下一节 / 本节起止时间）                                        |
-| 班级小助手 → ClassIsland         | 老师在 Web 端下发提醒 → 教室的 ClassIsland 上**全屏弹出**（可语音朗读），播完回执、不重复弹                 |
-| 班级小助手 → ClassIsland（可选） | 把班级小助手上排好的课表**镜像**回 ClassIsland（新建 `班级小助手-<班级名>` 档案课表，不改动老师原有的课表） |
-
-## 安装
-
-1. 把插件放进 ClassIsland 的插件目录，二选一：
-   - 用打包好的 `ClassHelper.ClassIslandPlugin.cipx`：ClassIsland →「设置 → 插件 → 从文件安装」；
-   - 或直接把 `ClassHelper.ClassIslandPlugin/` 目录（含 `manifest.yml` 与 dll）丢进插件目录
-     （Windows 默认 `%APPDATA%\ClassIsland\Plugins`，便携版在安装目录下的 `Plugins`）。
-2. 重启 ClassIsland，在「设置 → 插件」里确认「班级小助手联动」已启用。
-3. 打开「设置 → 班级小助手联动」，填入：
-   - **服务器地址**：班级小助手后端地址，例如 `http://127.0.0.1:4000`；
-   - **设备令牌**：在班级小助手 Web 端「ClassIsland 联动」页面为本班新建一台设备后复制（形如 `chci_...`，只显示一次）。
-4. 点「立即上报」验证连接状态；状态卡片显示「已连接」即接入成功。
-
-## 配置项（全部在「设置 → 班级小助手联动」里）
-
-| 配置项                       | 说明                                                                                               |
-| ---------------------------- | -------------------------------------------------------------------------------------------------- |
-| 服务器地址                   | 班级小助手后端地址（含端口；末尾斜杠与多余的 `/api` 后缀都会被自动容错）                           |
-| 设备令牌                     | 由 Web 端「ClassIsland 联动」页生成；服务端只存 sha256，明文只在页面上出现一次                     |
-| 上报课表到班级小助手         | 把 ClassIsland 里**已启用**的课表同步过去（合并写入：同星期同时间更新，不产生重复行）              |
-| 把班级课表镜像回 ClassIsland | 反方向同步，新建带前缀的档案课表；关闭后仍会照常上报「现在上什么课」                               |
-| 自动上报                     | 启动 / 课程事件（上课、下课、放学、状态变化）/ 定时各上报一次；关闭后只能用「立即上报」手动触发    |
-| 上报间隔（秒）               | 定时上报间隔，最小 15 秒，教室机器建议 60 秒                                                       |
-| 接收班级小助手提醒           | **本机总闸**：关掉后本机忽略老师下发的提醒（提醒仍留在班级通知中心）                               |
-| 语音朗读                     | 是否允许本机朗读（老师下发时也勾了「语音朗读」才会念，两个条件都满足才出声）                       |
-| 默认显示时长（秒）           | 老师未指定时长时用这个值；单条提醒可以在 Web 端单独指定更长的时长                                  |
-| 提醒轮询间隔（秒）           | **老师按下发送 → 教室弹出之间的最大延迟**（插件不持有长连接，是轮询取回的），默认 10 秒、最小 5 秒 |
-| 显示调试信息                 | 展开设备标识、与服务端的时钟差、配置目录等，排查「为什么同步不上」时打开                           |
-
-设置保存在 `<插件配置目录>/Settings.json`（随 ClassIsland 档案备份走，升级插件不丢）。
-改动即时生效 —— 改地址 / 令牌 / 间隔会立刻重建上报定时器，不需要重启 ClassIsland。
-
-> **上课时段策略（与 ClassHelper 客户端同一套规则）**：
-> 上课时段里，通知类提醒会**先暂存、下课后自动补弹**；**紧急提醒**与**叫人**属于「主动通知」，立刻弹。
-> 暂存期间不回执，服务端会保留这条待提醒。
-
-> **课间**：镜像回 ClassIsland 的课表会自动补上课间 —— **每两节之间**一段
-> （上一节下课 → 下一节上课），**最后一节之后不补**（放学）。课间由插件按课目时间算出来，
-> 不依赖班级小助手那边是否维护节次时间表，因此 ClassIsland 档案里一定有完整作息。
-
-> **两个方向各自需要的开关**：
->
-> - 服务端 → ClassIsland（镜像课表）：插件「把班级课表镜像回 ClassIsland」**且** Web 端该设备「镜像课表」都打开；
-> - ClassIsland → 服务端（上报课表）：插件「上报课表到班级小助手」打开；
->   关着时是正常行为（日志会写「仅状态（本机「上报课表到班级小助手」开关已关闭）」），不是上报失败；
-> - ClassIsland 里一张课表都没有时不会上报课表（日志会写「ClassIsland 里没有**启用的课表**」）。
-
-> **提醒到底会不会弹，取决于两个开关：**
->
-> 1. 教室机器的 **ClassHelper 客户端**在「设置 → 通知显示位置」里选了「只在 ClassHelper 客户端弹」时，
->    服务端根本不会推过来（此时本插件收不到东西，属正常）；
-> 2. 本插件的「接收班级小助手提醒」关掉时，即使推过来也不弹。
->
-> 两者都开着，提醒才会在 ClassIsland 上出现。
-
-## 工作原理（为什么这么写）
-
-- **不用跨进程 IPC，插件内直接读课程服务**：ClassIsland 的 IPC 暴露的是缓存数据，不足以还原课表；
-  插件直接读 `ILessonsService`（当前科目 / 状态 / 时间点）与 `IProfileService`（档案里的课表、时间表、科目），
-  拿到的才是「教室此刻真实的状态」。
-- **「上报即拉取」，不引入 Socket 依赖**：每次上报的返回值里会顺带带一条「尚未确认的提醒」，
-  插件收到就交给提醒提供方显示；应用启动时额外拉一次 `pending`，
-  补上「教室机器关机期间老师发的通知」。上报间隔本身就是心跳，插件因此少一个长连接故障面。
-- **提醒必须由「提醒提供方」发出**：只有通过 `NotificationProviderBase` 发出的提醒，
-  才会走 ClassIsland 主界面的全屏特效 / 语音 / 音效那一整套流程，因此插件注册了
-  「班级小助手提醒」提供方（可以在 ClassIsland 的「提醒」设置里整体开关它）。
-- **回执时机 = 真的播完**：回执挂在提醒的 `Completed` / `Canceled` 上，
-  中途退出 ClassIsland 不会回执，下次上报会重发 —— 既不静默丢提醒，也不会重复弹。
-- **镜像时重建时间点**：ClassIsland 的 `ClassPlan.Classes[i]` 必须与时间表里
-  **第 i 个 `TimeType == 0`（上课）的时间点**一一对应，
-  因此镜像接口为每条课目带上 `startTime` / `endTime`，插件据此重建时间表
-  （课间点从服务端的时间表里按起始时刻对齐）。少一个时间点，整份课表就会错位。
-- **单双周口径与三端一致**：`WeekCountDiv/WeekCountDivTotal` ⇄ `ALL/ODD/EVEN`
-  与 `@classhelper/shared` 的 `weekParityFromDiv` / `weekDivFromParity` 互逆；
-  3 周及以上的轮换本系统无法表达，会降级为「每周」并在日志里提示。
-- **非破坏性**：镜像只创建 / 更新名字以 `班级小助手-` 开头的课表与时间表；
-  老师手动建的课表不删不改名，同一星期已有启用课表时会在日志里给出重叠提示。
-
-## 上机联调记录（ClassIsland 2.1.0.1 实测）
-
-下面几条都是把插件装进真实 ClassIsland 跑出来的问题与结论，改动理由就写在这里，避免以后被“顺手优化”回去：
-
-1. **提醒内容必须在 UI 线程构造并显示。** 上报回调在线程池上，而提醒模板里的图标是 Avalonia 对象
-   （`LucideIconSource → IconSource → AvaloniaObject` 的构造函数会 `Dispatcher.VerifyAccess()`），
-   在线程池上直接构造会抛 `Call from invalid thread`，表现就是“ClassHelper 客户端收到了、ClassIsland 毫无反应”。
-   现在统一用 `Dispatcher.UIThread.Post` 切回 UI 线程。
-2. **同一条提醒在播放期间要按 id 去重。** 服务端在收到回执前会一直把提醒算作“待弹出”，
-   而轮询间隔（默认 10 秒）可能小于提醒时长（最长 120 秒）—— 不去重就会一遍遍重复弹。
-   只有播完（`Completed`/`Canceled`）才把 id 从“正在播放”里移除并回执。
-3. **不要自己拼图标串。** 双图标遮罩模板的默认图标由模板自己创建（`new LucideIconSource("\ue0ff")` 这种**字形字符**），
-   自己传 `"fluent(...)"` 之类既可能格式不对、也可能字形不存在。紧急提醒改用 ClassIsland 自带的**滚动文本**正文来表达。
-4. **`Subject.Fallback` 是占位符（名字就是 `???`）。** 没有课表时 ClassIsland 会把它挂到
-   `CurrentSubject`/`NextClassSubject` 上，直接上报会让 Web 端显示“正在上 ???”，因此上报前归一化成“没有科目”。
-
-实测截图（真机弹出提醒的遮罩）：[普通提醒](../../docs/screenshots/classisland/02-normal-mask.png)、
-[紧急提醒](../../docs/screenshots/classisland/01-urgent-mask.png)。
-
-## 构建与打包
-
-```bash
-pnpm build:classisland-plugin      # Release 构建（产物：packages/classisland-plugin/bin/Release）
-pnpm dist:classisland-plugin       # 追加打包 .cipx 并归集到 releases/classisland-plugin/
-pnpm verify:classisland-plugin     # 45 项静态契约校验（清单一致性 / 注册完整性 / DTO ↔ 服务端契约）
-```
-
-构建脚本会把 NuGet 缓存与临时目录指到仓库内的 `.cache/`（避免写满 C 盘），
-并在打包后自检「清单 / 程序集名 / 版本号」三者一致。
-
-## 开发提示
-
-- 需要 **.NET 8 SDK**；SDK 包固定 `ClassIsland.PluginSdk 2.1.0.1`（2.1.1 起改为 net10.0，
-  本插件按 net8.0 交付，因此 2.0.x / 2.1.0.x 都能加载，见 `manifest.yml` 的 `apiVersion`）。
-- 设置页是 Avalonia 的 `.axaml`（继承 `SettingsPageBase`）；绑定走运行时解析
-  （`AvaloniaUseCompiledBindingsByDefault=false`），因为插件与主程序各自编译，编译期绑定看不到对方类型。
-- **开发机没有安装 ClassIsland 本体**，所以插件只能做到编译 + 打包 + 静态校验；
-  运行期行为需要在装了 ClassIsland 的机器上按上面的「安装」步骤实测。
-
-## 常见问题
-
-**填好令牌后点「立即上报」，提示 `HTTP 404`（响应不是班级小助手的标准格式）**
-这台机器上的**系统代理拦了内网请求**。Windows 的代理设置里 `127.0.0.1` 并不在默认绕过列表里，
-于是浏览器/插件对「本地服务」的请求也被送到代理，拿到的是**代理自己的 404 错误页**。
-插件已对本地/内网地址（localhost、回环、10/172.16-31/192.168、链路本地、无点主机名）**强制直连、绕开系统代理**；
-如果仍然报 404，请依次检查：
-
-1. 服务器地址是否写成了别的端口 / 别的机器（提示里会带上实际请求的完整 URL，照着核对最快）；
-2. 该地址在浏览器里打开 `<服务器地址>/api/health` 是否返回 `{"success":true,...}`；
-3. 反向代理（Nginx 等）是否把 `/api/integrations` 也转发到了后端。
-
-**上报失败，提示「设备令牌无效」**
-在 Web 端重置该设备的令牌，然后把新令牌填回插件设置（旧令牌会立即失效）。
-
-**发布提醒后 ClassIsland 没反应，或者要等一会儿才弹**
-插件不持有长连接，提醒是**轮询取回**的：默认最多 10 秒（设置页「提醒轮询间隔」可调到 5 秒）。超过这个时间还没弹，按下面逐条排查。
-
-**ClassIsland 上完全不弹提醒**
-
-1. 确认插件设置里打开了「接收提醒」；
-2. 确认 Web 端「ClassIsland 联动」页面上该设备是「已接入」状态（停用后服务端会直接 403）；
-3. 提醒会在 24 小时后过期，避免教室机器一开机弹出一堆旧通知。
-
-**课表上报了但班级小助手上没变化**
-确认插件设置里打开了「上报课表到服务端」，且 Web 端该设备的「回传课表」开关也是允许状态。
-
-**镜像开关打开了，但 ClassIsland 的课表没变**
-镜像需要 Web 端该设备开启「镜像课表」且班级里已有课表；插件只在**上报时**顺路拉取镜像，
-所以打开开关后点一下「立即上报」或等一个上报间隔即可。镜像不会覆盖老师原有的课表。
-
-## 许可
-
-与班级小助手仓库一致。