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

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

.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/
 
@@ -51,3 +51,5 @@ packages/server/prisma/database-settings.json
 
 # 文档站构建产物（pnpm docs:build 生成，由 GitHub Pages 发布；见 docs/）
 docs/_site/
+
+packages/data/courseware/

README.md

@@ -17,26 +17,24 @@
 [![仓库大小](https://img.shields.io/github/repo-size/LoveChengke/ClassHelper?style=flat-square&color=3cb371)](https://github.com/LoveChengke/ClassHelper)
 
 ClassHelper是给中小学班级用的一套信息管理系统。<br/>
-**老师发一条通知，教室那台机器上的灵动岛和 [ClassIsland](https://classisland.tech) 会同时弹出来**；<br/>
+**老师发一条通知，教室客户端与灵动岛会实时提醒**；<br/>
 学生打开客户端就能看到当天的课表和作业。
 
-#### [🚀 软件下载](https://github.com/LoveChengke/ClassHelper/releases/latest) | [📚 使用文档](docs/index.md) | [🧭 完整参考](docs/reference.md) | [💬 反馈问题](https://github.com/LoveChengke/ClassHelper/issues)
+#### [🚀 软件下载](https://github.com/LoveChengke/ClassHelper/releases/latest) | [📚 使用文档](docs/index.md) | [🧭 功能与源码索引](docs/reference.md) | [💬 反馈问题](https://github.com/LoveChengke/ClassHelper/issues)
 
 </div>
 
 ## 它由什么组成
 
-一份代码，四个交付物：
+一份代码，三个交付物：
 
 | 装在哪                  | 是什么                                                               | 谁在用               |
-| -------------------------- | ---------------------------------------------------------------------------------- | ---------------------- |
+| ----------------------- | -------------------------------------------------------------------- | -------------------- |
-| 教师的电脑 / 学校服务器    | **服务端**（Express + Prisma + Socket.IO），同时托管 Web 管理端                     | 其它三端               |
+| 教师的电脑 / 学校服务器 | **服务端**（Express + Prisma + Socket.IO），同时托管 Web 管理端      | 管理端与客户端       |
 | 浏览器（手机也行）      | **Web 管理端**（Vue 3 + Element Plus，PWA 可安装）                   | 老师、班主任、管理员 |
 | 教室那台机器 / 学生电脑 | **桌面客户端**（Electron + Vue 3），含「灵动岛」浮窗、托盘、离线缓存 | 教室大屏、学生       |
-| 教室机器上的 ClassIsland   | **联动插件**（.NET 8 / C#），上报课表与上课状态、把老师的提醒弹到大屏上             | 教室机器               |
 
-老师在 Web 端发布内容 → 服务端落库并按班级房间广播 → 客户端与灵动岛实时更新；
+老师在 Web 端发布内容 → 服务端落库并按班级房间广播 → 客户端与灵动岛实时更新。
-落到 ClassIsland 上的那部分走设备令牌的独立通道，教室网络不好也不影响。
 
 ## 功能
 
@@ -45,17 +43,14 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 - [x] 仪表盘：本班人数、课程、课表、作业、通知、成绩一屏概览
 - [x] 班级管理：建班自动生成班级码与班级密码，随时更换班主任、按科目配置各科任课老师
 - [x] 学生 / 教师管理：单个录入或导入名单（xlsx / xls / csv / tsv）
-- [x] 课表管理：按周排课、单双周，可直接从 ClassIsland 档案导入课表与节次时间
+- [x] 课表管理：日课表、共享作息、1–9 周轮换、群组与临时换课；支持完整 ClassIsland 档案离线导入
 - [x] 作业发布：按「所属日期」归类，支持附件与未交名单
-- [x] 通知发布：三档优先级；在**上课时段**发紧急通知会被拦下来并要求二次确认
+- [x] 通知发布：四档优先级；在**上课时段**发紧急通知会被拦下来并要求二次确认
 - [x] 叫人：点名某位同学到办公室，分「普通」与「紧急」两级
 - [x] 成绩录入：单条 / 批量 / 表格导入，带等级分布与得分率统计；单科排名自动出，可选「各科相加排总分榜」
-- [x] ClassIsland 联动：签发设备令牌、下发提醒、把课表镜像回教室大屏
+- [x] 客户端管理：查看设备在线状态与版本，远控关机、重启、注销与锁屏；推送更新可选立即、放学后或空闲时安装
 - [x] 数据库管理：连接体检、备份与恢复、SQLite ⇄ MySQL 一键切换
-- [x] 权限组：39 个权限键，建组分配账号 —— 没分组的按角色默认生效，分组后只按组的并集算
+- [x] 权限组：按功能键建组分配账号，支持岗位与年级范围 —— 默认组可自定义，没分组的按角色默认组生效，分组后只按组的并集算
-- [x] 客户端（合并页）：一个班一张卡片，大屏与灵动岛两条链路一起看；勾选可批量下发课表 / 更新，点进去做逐台操作
-- [x] 课表同步按需：点「下发课表」把课表写进教室并停用冲突的旧课表，点「获取课表」把教室的课表取回来 —— 没有"一直同步"
-- [x] 客户端设备：每台教室机器的版本、在线状态与最后心跳；一键推送更新，可下发关机 / 重启 / 注销 / 锁屏
 - [x] 大模型助手：一句话解析成待确认的作业 / 通知 / 叫人，点确认才落库
 - [x] 通知与作业批量发布：勾多个班一次发完，个别班失败不影响其余班级
 - [x] 系统设置：开发者模式、运行诊断、开机自启开关（仅安装形态）
@@ -68,7 +63,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 - [x] 课表：「今天」时间轴（大时钟 + 正在上 / 下一节 + 距下课倒计时）与周视图
 - [x] 作业看板：按科目分卡、可全屏铺满、字号可调，也能切回列表
 - [x] 通知中心：未读红点、优先级标签、点击自动标为已读
-- [x] 成绩总览：全班成绩表格 + 柱状图 + 等级分布；按考试看单科排名，老师开启后还有总分排名
+- [x] 成绩总览：开启个人查询时显示本班成绩与排名；关闭后仅展示服务端集体分析，保留隐私限制
 - [x] 教室机器可直接录入作业、勾选未交名单
 - [x] 离线优先：断网回退 IndexedDB 缓存，恢复连接后自动同步
 - [x] 断网期间错过的通知，重新上线时补弹一次；渲染进程崩了会安静地自己重建窗口
@@ -76,19 +71,13 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 
 ### 灵动岛（桌面通知浮窗）
 
-- [x] 通知、新作业、叫人都会上岛：先是胶囊，点开是详情卡
+- [x] 通知、新作业、叫人都会上岛：经典模式使用胶囊与详情卡，自定义模式使用常驻内容与铃铛
 - [x] 多条消息展开为竖排列表，按重要程度排序，放不下时提示去应用内看
-- [x] **上课时段不打扰**：普通通知暂存到下课再弹；紧急通知与叫人立刻弹
+- [x] **经典模式上课时段不打扰**：普通通知暂存，普通叫人可点开胶囊，紧急消息立即展开；自定义模式点击铃铛查看
 - [x] 尺寸、圆角、字号、主题色、停靠位置（顶部 / 底部 × 左 / 中 / 右）都可以调
 - [x] 纯黑 / 毛玻璃 / 主题色渐变三种底
 - [x] 触摸屏（希沃白板这类一体机）也能点开
-
+- [x] 自定义常驻岛：分别编辑常态与无通知展开内容，收到消息显示铃铛，点击查看通知
-### ClassIsland 联动
-
-- [x] 教室机器上报课表与上课状态，Web 端能看到「现在在上什么」
-- [x] 老师发的提醒在教室大屏上全屏弹出，支持语音朗读，播完回执不重复弹
-- [x] 可以把 ClassHelper排好的课表镜像回 ClassIsland，不影响老师原有的课表
-- [x] 提醒弹在客户端还是 ClassIsland，由教室那台机器自己选
 
 ### 部署与运维
 
@@ -110,7 +99,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 <summary>展开其余页面……</summary>
 
 | 页面       | 截图                                                           |
-| --- | --- |
+| ---------- | -------------------------------------------------------------- |
 | 仪表盘     | <img src="docs/images/web-dashboard.jpg" alt="仪表盘" />       |
 | 班级管理   | <img src="docs/images/web-classes.jpg" alt="班级管理" />       |
 | 学生管理   | <img src="docs/images/web-students.jpg" alt="学生管理" />      |
@@ -119,7 +108,6 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 | 作业发布   | <img src="docs/images/web-homeworks.jpg" alt="作业发布" />     |
 | 通知发布   | <img src="docs/images/web-notifications.jpg" alt="通知发布" /> |
 | 成绩录入   | <img src="docs/images/web-grades.jpg" alt="成绩录入" />        |
-| ClassIsland 联动 | <img src="docs/images/web-integrations.jpg" alt="ClassIsland 联动" /> |
 | 数据库管理 | <img src="docs/images/web-database.jpg" alt="数据库管理" />    |
 
 </details>
@@ -132,7 +120,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 <summary>展开其余页面……</summary>
 
 | 页面                    | 截图                                                                       |
-| --- | --- |
+| ----------------------- | -------------------------------------------------------------------------- |
 | 作业看板                | <img src="docs/images/client-homeworks.png" alt="作业看板" />              |
 | 通知                    | <img src="docs/images/client-notifications.png" alt="通知" />              |
 | 成绩                    | <img src="docs/images/client-grades.png" alt="成绩" />                     |
@@ -144,7 +132,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 ### 灵动岛
 
 | 形态               | 截图                                                                    | 说明                                            |
-| --- | --- | --- |
+| ------------------ | ----------------------------------------------------------------------- | ----------------------------------------------- |
 | 新消息胶囊         | <img src="docs/images/island-4-pill.png" alt="新消息胶囊" />            | 非上课时段直接出现，点一下展开                  |
 | 点开后的详情       | <img src="docs/images/island-5-clicked.png" alt="详情卡" />             | 标题、内容、时间 + 打开应用 / 标为已读 / 知道了 |
 | 多条消息列表       | <img src="docs/images/island-9-list.png" alt="多条消息列表" />          | 按重要程度排序，默认显示三条                    |
@@ -159,7 +147,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 <summary>展开……</summary>
 
 | 场景     | 截图                                                                     |
-| --- | --- |
+| -------- | ------------------------------------------------------------------------ |
 | 仪表盘   | <img src="docs/images/mobile-dashboard.jpg" alt="手机 · 仪表盘" />       |
 | 通知发布 | <img src="docs/images/mobile-notifications.jpg" alt="手机 · 通知发布" /> |
 
@@ -168,10 +156,9 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
 ## 开始使用
 
 | 装在哪                  | 装什么                                      | 从 Releases 里拿                                                            |
-| ----------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- |
+| ----------------------- | ------------------------------------------- | --------------------------------------------------------------------------- |
 | 教师的电脑 / 学校服务器 | **服务端**（内含 Web 管理端与 Node 运行时） | `ClassHelper-<版本>-x64-server-setup.exe`                                   |
 | 教室机器 / 学生电脑     | **学生客户端**                              | `ClassHelper-<版本>-x64-client-setup.exe`，或 `-client-portable.exe` 免安装 |
-| 教室机器的 ClassIsland  | **联动插件**                                      | `ClassHelper.ClassIslandPlugin.cipx`                                         |
 
 也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑：
 选一个版本，四个包排成四张卡，文件名、体积与 SHA256 清单都在那儿 ——
@@ -199,11 +186,10 @@ curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/Love
 ## 开发
 
 | 层         | 选型                                                                |
-| -------------- | ------------------------------------------------------------------------ |
+| ---------- | ------------------------------------------------------------------- |
 | 后端       | Node.js ≥ 20.19 + Express 5 + Prisma 7（SQLite / MySQL）+ Socket.IO |
 | Web 管理端 | Vue 3 + Vite + Element Plus + Pinia                                 |
 | 桌面客户端 | Electron 44 + Vue 3 + IndexedDB 离线缓存（含独立的灵动岛渲染进程）  |
-| ClassIsland 插件 | .NET 8 / C# + Avalonia（ClassIsland 插件 API 2.0）                      |
 | 共享契约   | `packages/shared`：类型、常量、权限矩阵、动效令牌                   |
 
 ```bash
@@ -219,13 +205,13 @@ pnpm dev                                               # 后端 4000 + Web 端 5
 `pnpm db:seed` 会写一套演示数据（1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩）：
 
 | 角色                       | 账号          | 密码         |
-| -------------- | --------------- | ------------ |
+| -------------------------- | ------------- | ------------ |
 | 管理员                     | `admin`       | `admin123`   |
 | 教师                       | `teacher1`    | `teacher123` |
 | ClassHelper 班级端（班级） | 班级码 `G101` | `123456`     |
 
-- [AGENTS.md](AGENTS.md) —— 工程约定与本机踩坑，**改代码前先读它**
+- [AGENTS.md](AGENTS.md) —— 工程约定与开发环境注意事项，**改代码前先读它**
-- [docs/reference.md](docs/reference.md) —— 完整参考（功能行为、接口、验收记录）
+- [docs/reference.md](docs/reference.md) —— 功能章节与源码入口索引
 - [docs/dev/architecture.md](docs/dev/architecture.md) —— 架构总览
 
 ## 致谢
@@ -239,3 +225,10 @@ pnpm dev                                               # 后端 4000 + Web 端 5
 如果这个项目对你有帮助，欢迎点亮 Star ⭐
 
 </div>
+
+### 客户端维护
+
+支持远程关机、重启、注销与锁屏（管理端确认下发，客户端执行并回执），可查看最近一次执行结果。
+统一更新支持立即安装、放学后安装或空闲时安装，支持取消下发。
+管理员与教师的默认权限组均可自定义；管理员保留权限管理和系统管理入口。
+课件共享：教师可上传教学文件到服务端，按日期与类型归档，仅向本人授课班级开放或推送；班级客户端支持课件目录、离线补收，以及灵动岛传输进度。使用说明见 [课件上传与传输](docs/app/courseware.md)。

deploy/bootstrap-env.cjs

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

deploy/classhelper

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

deploy/docker-compose.sqlite.yml

@@ -23,7 +23,7 @@ services:
       context: ..
       dockerfile: deploy/Dockerfile
       target: runtime
-    image: classhelper-server:${APP_VERSION:-1.3.1}
+    image: classhelper-server:${APP_VERSION:-1.4.2}
     restart: unless-stopped
     environment:
       NODE_ENV: production

deploy/docker-compose.yml

@@ -60,7 +60,7 @@ services:
       context: ..
       dockerfile: deploy/Dockerfile
       target: runtime
-    image: classhelper-server:${APP_VERSION:-1.3.1}
+    image: classhelper-server:${APP_VERSION:-1.4.2}
     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/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,6 +1,6 @@
 {
   "name": "classhelper-server-runtime",
-  "version": "1.3.1",
+  "version": "1.4.2",
   "private": true,
   "type": "module",
   "description": "ClassHelper 服务端运行时（安装包 / 容器内置）",

deploy/tools/admin-cli.mjs

@@ -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();
     }
   }

docs/app/appearance.md

@@ -79,18 +79,20 @@ beUI 的组件本身是 React，用不到这里，但它的动效语言与框架
 两端各有一个 `prefers-reduced-motion` 的全局降级块，把动画压到 1ms ——
 **是压短而不是删掉**（`transition: none` 会让依赖 `transitionend` 的逻辑失灵）。
 
-唯一的例外是**加载指示旋**：它是放慢而不是停，停掉会让界面看起来像卡死。
+主窗口中的例外是**加载指示旋**：它是放慢而不是停，停掉会让界面看起来像卡死。
+
+灵动岛使用独立动画控制，应用内开关优先，具体见[灵动岛](island.md)。
 
 ## 客户端设置页
 
-「设置」是一个可展开的分组，六个子页各有自己的路由：
+「设置」是可展开分组，常用子页如下；开发者模式还提供开发者页，自定义岛编辑为灵动岛子路由：
 
 | 子页   | 内容                                                                          |
 | ------ | ----------------------------------------------------------------------------- |
 | 通用   | 服务器连接、离线缓存、作业录入短语、使用引导                                  |
 | 外观   | 浅色 / 深色                                                                   |
 | 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝（详见[灵动岛](island.md)） |
-| 提醒   | 通知显示在哪一端                                                              |
+| 提醒   | 本机课程等提醒开关与行为                                                      |
 | 账号   | 当前班级信息、退出登录                                                        |
 | 关于   | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢                   |
 

docs/app/calls.md

@@ -1,57 +1,22 @@
 ---
 title: 叫人
-description: 老师点名让学生过来：普通与紧急两档、快捷短语、谁能叫谁，以及它在教室里的表现。
+description: 点名、优先级、可见范围和客户端展示。
 ---
 
 # 叫人
 
-「叫人」是老师点名让某位同学来一趟 —— 它**不是**一条普通通知，因为它有一个明确的收件人和一个明确的动作
+在 Web“通知发布 → 叫人”选学生，填写事由或选择快捷短语，需 call:create 和班级范围权限。
-（学生会点「收到」）。
+可调用的学生必须属于相应在读班级且未转出；岗位范围、任课或班主任关系由服务端检查。
+学生没有账号，无法以个人身份调用接口。
 
-## 在哪发
+| 级别     | 落库优先级 | 经典 fixed 展示                                                    |
+| -------- | ---------- | ------------------------------------------------------------------ |
+| 普通叫人 | HIGH       | 胶囊可点击，上课也允许主动查看；不自动展开打断课堂，下课可自动展开 |
+| 紧急叫人 | URGENT     | 上课也立即展开，收起后仍可主动再打开                               |
 
-| 入口            | 谁能用       |
+自定义 custom 是常驻模式，两种叫人都先提示铃铛，由用户主动查看；详见[通知与提醒](notifications.md)。
-| --------------- | ------------ |
+卡片内容包括被叫学生、教师和事由，“收到”复用通知已读机制。
-| 通知发布 → 叫人 | 教师、管理员 |
+自定义消息优先于快捷短语，消息长度以接口 schema 校验为准。
-| 学生管理 → 叫人 | 管理员       |
 
-学生管理页是管理员专属，但班主任与科任老师同样需要叫人，所以给老师留的入口在「通知发布 → 叫人」。
+`POST /api/calls` 保存为 Notification，带本地所属日期；随后发送 notification:new 班级广播和 call:new 班级会话定向事件。
-
+定向主体是班级会话，学生本身没有 Socket 房间；双播按消息 id 合并去重。
-## 两档
-
-| 级别         | 落库级别 | ClassHelper 班级端行为                                                                                            |
-| ------------ | -------- | ----------------------------------------------------------------------------------------------------- |
-| **普通叫人** | `HIGH`   | 课间先显示「叫人」胶囊，点击展开；**上课时段只进队列、不打断课堂**，下课后自动弹出详情（90 秒后收起） |
-| **紧急叫人** | `URGENT` | **无视上课时段立即展开**，上课时被收起后仍保留胶囊、可再次点开                                        |
-
-两档的卡片都是「请 XXX 同学找 XXX 老师」+ 具体事由，徽标是「叫人」，按钮是「收到」
-（复用通知的已读机制）。
-
-> **是否立即展开只由 `priority` 决定**，与普通通知共用同一条排队 / 隐藏 / 下课弹出路径。
-
-## 怎么说
-
-两种输入方式，**自定义消息优先于快捷短语**：
-
-- **快捷短语**（8 条，点击选中、再点取消）：请到办公室找我 / 请到讲台找我 / 请到实验室找我 /
-  请到门卫处找我 / 请带上作业本找我 / 请带上试卷找我 / 请到教室门口等我 / 请马上来一趟；
-- **自定义消息**：最长 200 字，例如「带上昨天的数学作业到办公室」。
-
-## 谁能叫谁
-
-| 角色   | 限制                                                       |
-| ------ | ---------------------------------------------------------- |
-| 学生   | 调用被拒（403）                                            |
-| 教师   | 只能叫**自己班级**的学生；跨班、或学生不在本班 → 400 / 403 |
-| 管理员 | 任意班级                                                   |
-
-## 服务端做了什么
-
-`POST /api/calls`（教师 / 管理员）→ `urgent: true` 落库成 `URGENT`，否则 `HIGH`，
-然后广播两个事件：
-
-- `notification:new` 到班级房间（通知中心与灵动岛都靠它）；
-- `call:new` 定向到被叫学生 / 班级设备。
-
-如果教室的「通知显示位置」不是"只在 ClassHelper"，这条叫人也会推给 ClassIsland，
-教室大屏一并播报。

docs/app/classes.md

@@ -1,98 +1,67 @@
 ---
 title: 班级、学生与教师
-description: 班级账号、学生名单、班主任与各科任课老师，以及"谁能看什么、谁能改什么"。
+description: 名单、班级会话、任课关系与年度升级。
 ---
 
 # 班级、学生与教师
 
-## 班级账号：ClassHelper 班级端的身份
+## 班级账号
 
-学生**没有个人账号**。一台教室机器用一个**班级账号**登录：
+教室客户端使用班级码和班级密码登录，形成 CLASS_DEVICE 会话，主体是班级。
+班级码保存时统一大写；管理员在“班级管理”维护班级码、密码与班主任。
+班级端的已读、作业完成等操作代表全班，学生没有个人登录账号。
+客户端没有修改密码入口；员工本人改密码在 Web 顶栏菜单。
 
-```
+班级名由入学年份和班号组成，例如“2026级1班”；年级独立保存，学年升级时班名不随之改写。
-班级码（例如 G203） + 班级密码  →  这台机器代表"高二(3)班"
+班主任可以暂空，新学年自动创建的高一班级仅有骨架，需要管理员后续分配教师。
-```
 
-登录之后，这台机器上的「已读 / 完成 / 未交」都是**代全班**操作的；它看到的是本班的数据。
+## 学生名单
 
-班级码是管理员在「班级管理」里设的（新建时自动生成，可以改成好记的）。
+Web 统一从“学生管理”查看和维护名单；旧 `/roster` 地址转到同一页面，不再提供重复菜单。班级详情中的名单与课程按当前班级的生效范围展示维护入口，任课关系本身不授予跨班名单、课程或班级设置管理权。
-校验时会统一按大写比对（码存大写）。
 
-> 班级密码在新建班级时由 `.env` 的 `DEFAULT_CLASS_PASSWORD` 决定初始值，
+Student 存学号、姓名、班级、性别、家长电话和状态，没有密码或角色字段。
-> 之后由管理员在「班级管理 → 修改班级账号」维护。
+学号为必填唯一标识，格式为 1–32 位字母、数字或 . _ -；不会自动生成登录名。
->
+具有名单管理键的管理员、本班班主任或全校名单范围的授权员工管理学生；只读账号按名单读取键和范围查看历史。
-> **客户端没有改密码入口**，这是刻意移除的：教室机器上误改班级密码会让别的机器登录不了。
+名单表格导入要求 import:students、roster:manage 和对应班级范围；学号查重在 Student 表完成，不当成 User 用户名。
-> 教师 / 管理员本人改密码在 Web 端顶栏头像菜单里。
+调班保留历史内容原归属；转出独立记账并从现行业务名单过滤，学号不可复用。
 
-## 学生
+## 教师与科目
 
-**学生管理**（仅管理员）→ 新建 / 导入名单。
+教师使用工号和密码登录，管理入口受 teacher:read/teacher:manage 等功能权限控制。
+教师名单导入还要求管理员身份和相应导入权限。班主任关系在 Class.teacherId；
+科任关系唯一存于 Course(classId, name, teacherId)，分配任课关系由班级管理权限及服务端断言限制。
+班主任不任教某科就不能修改该科作业/成绩；科任老师有相应权限时可以管理自己任教科目。
 
-学生记录**只是名单**：成绩、未交名单、叫人、已读记录都按名单记录，所以名单不全这几项就不准。
+删除教师前，服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件；仍有业务内容则返回冲突，避免级联丢失。
+教师本人改密码、管理员修改教师密码、班级账号密码是不同入口；学生没有密码接口。
 
-| 项目     | 说明                                                                                 |
+## 权限、学年与归档
-| -------- | ------------------------------------------------------------------------------------ |
-| 用户名   | `^[A-Za-z0-9_.-]{3,32}$`；单个新建时自动生成                                         |
-| 密码     | **没有密码概念**。学生的 `passwordHash` 是空串占位，不能登录，也没有任何重置密码接口 |
-| 所属班级 | 一个学生属于一个主班级                                                               |
 
-> 学生**不是账号**（`Student` 表里没有密码、没有角色），拿学号去登录只会得到 401 ——
+管理员固定拥有全部能力；教师按岗位模板及每项分配的范围获得能力，未显式分配时使用教师默认模板与固定任教范围。
-> 否则"密码错(401)"和"密码对但学生账号已停用(403)"的差异会把学生账号密码变成可离线验证的预言机。
+范围不代替科目写权限，详见[角色与权限](../dev/permissions.md)。
+“学期周次”只维护教学周与日期区间；年度轨道、执行计划与补跑统一在管理员专用的“学年升级”页维护。
+学期周数受全校可配置上限约束，默认上限 30、允许 1–60，见[课表](schedules.md)。
+学年升级按计划时间运行，执行前保存快照，以年份幂等；启动发现漏跑需管理员预览补跑。
+默认高中轨道按高一、高二、高三排列，毕业学段归档，其余升一级；也可配置其他轨道。新班不复制任课关系。归档页查看届别历史与转出记录，
+不再通过手动创建归档来代替年度升级。撤回转出由 roster:manage 控制，原班归档后可指定其他在读班。
 
-## 教师
+## 学生生命周期
 
-| 能力                 | 在哪                                             | 谁能做        |
+资料编辑仅修改学号、姓名、性别与家长电话，不接受状态或班级字段；旧客户端发送这两项会收到 400 和专用接口提示。
-| -------------------- | ------------------------------------------------ | ------------- |
+默认名单只显示未归档的 active；状态筛选可查看 inactive、transferred、graduated，“包含归档”另行控制归档标记。
-| 新建 / 编辑 / 删除   | 「教师管理」                                     | **仅管理员**  |
-| 导入名单（xlsx/csv） | 「教师管理 → 导入名单」                          | **仅管理员**  |
-| 重置密码             | 「教师管理」（可指定新密码，留空用默认初始密码） | **仅管理员**  |
-| 加进某个班           | 班级详情 → 任课老师（班级 + 科目 + 教师）        | 管理员        |
-| 换班主任             | 班级详情顶部「更换班主任」                       | **仅管理员**  |
 
-> **教师录入只有管理员能做**：`/api/teachers` 整组接口都是 `requireRole('ADMIN')`，教师调用返回 403。
+调班、转出、转入、复学、撤回与移出班级均在一个事务内修改学生并写历史，包含批次、学年、原新班级与年级、来源去向学校、操作人和备注。
-> 前端也只在管理员登录时显示这个菜单项。
+调班需同时覆盖源班与目标班；跨年级须管理员勾选允许跨年级并填写备注。目标班必须在读。
+转出保留原班及业务历史，只接受在读或停用学生。转入支持新建学号或选择转出/停用学生，毕业或归档学生不能通过名单入口复活。
+撤回转出可选择另一个在读班，原历史保留。默认删除动作改为停用；硬删除另须管理员确认且无成绩、作业、已读或历史。
 
-### 删除教师有护栏
+## 升级预览与执行
 
-下面四种情况一律拒绝（409），因为删账号会级联删掉他在各班发过的内容：
+“学年升级”页面独立要求 promotion:manage，全校范围。先保存轨道、有序年级、起始班数、执行时间、开学日和周次重置策略，再预览逐班影响。
+预览包含在读/停用/转出人数、新班码、周次删除行数、阻断和警告、计划哈希。未知年级、缺失届别、重复班号、已有届别档案或新班码冲突会阻断执行。
+执行需确认学年和预览哈希；业务或配置变化后必须重新预览。未来学年禁止执行，过去学年仅 ADMIN 明确补跑。
 
-1. 他还是某个班的**班主任**；
+毕业班所有学生挂届别：在读转毕业，转出和停用保留状态；非毕业班只升到下一学段并清本班开学日覆盖。
-2. 名下有**课程**；
+新班只有骨架，开学日取计划值（未配置时为执行学年 9 月 1 日）。保留周次时，旧逐周区间会继续覆盖新学年，页面会警告。
-3. 有**任课关系**（`Course.teacherId === 他`）；
+同年执行幂等，执行记录显示操作人、快照路径、SHA256、明细与错误。快照失败不升级，失败事务回滚后可修正重试。
-4. **发布过作业或通知**。
+撤销归档只清标记并将毕业生恢复在读，转出/停用不变；不回滚年级、不删除新班、不恢复已清空周次，整学年恢复需管理员手工使用快照。
-
-（后两项曾经漏检，会静默删掉该教师发过的作业与通知。）
-
-## 角色与可见范围
-
-班级内的角色由「账号角色 + 与该班级的关系」共同决定：
-
-| 角色               | 怎么判定                       | 可见范围                   |
-| ------------------ | ------------------------------ | -------------------------- |
-| `ADMIN` 管理员     | `User.role = ADMIN`            | 全部班级                   |
-| 班主任 `HEAD`      | `Class.teacherId === 当前用户` | 本班                       |
-| 科任老师 `SUBJECT` | 该班 `Course.teacherId` 有当前用户 | 被任课的班级            |
-| 学生 `STUDENT`     | `User.classId` / 班级账号      | 自己的班级（只读业务数据） |
-
-### 权限矩阵（摘要）
-
-| 操作                                 | 管理员 |    班主任    | 科任老师 |
-| ------------------------------------ | :----: | :----------: | :------: |
-| 班级创建 / 修改 / 删除               |   ✅   |      ❌      |    ❌    |
-| 分配班主任与科任老师                 |   ✅   |      ❌      |    ❌    |
-| 学生名单管理（增删 / 导入）          |   ✅   |      ❌      |    ❌    |
-| 教师录入（新建 / 导入 / 改密码）     |   ✅   |      ❌      |    ❌    |
-| 数据库管理（备份 / 导入导出 / 切换） |   ✅   |      ❌      |    ❌    |
-| 课表管理（增删改 / 导入）            |   ✅   | ✅（仅本班） |    ❌    |
-| 布置作业                             |   ✅   |      ✅      |    ✅    |
-| 叫人                                 |   ✅   |      ✅      |    ✅    |
-| 发布通知                             |   ✅   |      ✅      |    ✅    |
-| 成绩录入 / 修改 / 导入（仅本班）     |   ✅   | ✅（仅本班） |    ❌    |
-| 维护班级密码                         |   ✅   |      ❌      |    ❌    |
-
-完整矩阵与实现见[角色与权限](../dev/permissions.md)。
-
-## 学期周数
-
-每个班有自己的学期周数（`Class.termWeeks`，默认 20，上限 30），**只有管理员**能改。
-它决定"现在是第几教学周"，见[课表](schedules.md)。

docs/app/courseware.md

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

docs/app/grades.md

@@ -1,56 +1,48 @@
 ---
 title: 成绩
-description: 成绩录入与导入、等级与得分率、ClassHelper 班级端看到的全班总览。
+description: 录入、按学号查询、排名与关闭个人查询后的集体分析。
 ---
 
 # 成绩
 
-## 三种录入方式
+Web 管理端支持单条、批量和表格导入成绩；记录通过 Grade.studentId 关联学生名单。
+科目来自班级课程与共享科目目录，分数、总分和等级按录入规则校验。
+成绩写入需 grade:write 或相应导入权限，并通过班级和科目检查：
+管理员可管理，教师只能编辑自己任课科目，无科目内容按班主任规则；班级端不能写成绩。
+表格导入另有管理员/本班班主任门槛，班主任也只能导入符合科目权限的行；它与单条/批量录入的准入不同。
 
-Web 管理端「成绩录入」页：
+## 查看、排名与隐私
 
-| 方式     | 适合                              | 说明                                                             |
+班级客户端可显示本班考试、成绩总览、等级分布，以及按学号查询明细。
-| -------- | --------------------------------- | ---------------------------------------------------------------- |
+是否允许读取个人数据由 Class.studentGradeQueryEnabled 控制，班级端只读该设置。
-| 单条录入 | 个别缺漏补录                      | 选学生、科目、考试名称、分数、总分                               |
-| 批量录入 | 一次录一个班的某一科              | 一屏列出全班学生，逐个填分                                       |
-| 导入表格 | 已经有 Excel 的（期中期末最常见） | 支持列名同义词映射、先预览再提交，见[表格与课表导入](imports.md) |
 
-**科目**下拉是全校统一的 18 科目录；选中一个该班还没有的科目时，前端会自动为该班建同名课程，
+| 状态         | 班级端可读取内容                                                     |
-不用先去把科目建一遍。
+| ------------ | -------------------------------------------------------------------- |
+| 个人查询开启 | 本班原始成绩、个人明细、考试及排名，仍检查班级归属                   |
+| 个人查询关闭 | 页面可打开，只返回服务端集体聚合；个人明细、原始全班成绩和排名被拒绝 |
 
-## 谁能录
+聚合对少于 5 名学生的样本、稀疏分段及补集抑制，不提供最高/最低分。
+客户端不会先拿个人成绩再做隐藏或聚合；教师/管理员按自身权限读取，不受班级端个人查询开关限制。
 
-| 角色            | 权限                                   |
+考试“是否计入总分”属于 Exam，教师在管理端设置，客户端只展示。
-| --------------- | -------------------------------------- |
+同一学生同一科多条成绩取最高分，排名并列用 1、2、2、4；总分只在开启时显示。
-| 管理员          | ✅ 全部班级                            |
+图表使用本地 HTML/CSS/SVG 组件。
-| **本班班主任**  | ✅ 仅本班（录入 / 修改 / 删除 / 导入） |
-| 科任老师        | ❌ 403                                 |
-| 学生 / 班级账号 | ❌ 只能看                              |
 
-权限在**服务层**兜底，前端只是按同一份矩阵隐藏按钮。
+## 接口入口
 
-## 学生看到的是什么
+以下省略 /api 前缀，详情与参数以 grades.module.ts、grades.schemas.ts 为准。
 
-ClassHelper 班级端（教室机器）用的是**班级账号**，所以它看到的不是"我的成绩"，而是**全班成绩总览**：
+| 方法与路径                                            | 用途                                               |
+| ----------------------------------------------------- | -------------------------------------------------- |
+| 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，事件载荷同样须遵守个人数据保护，客户端按需重新读取。
-- 柱状图；
-- 等级分布；
-- 最近更新。
-
-图表是自研的轻量组件（柱状图是纯 HTML/CSS，折线图是 SVG），项目里**不引图表库**。
-
-> 学生没有个人账号，所以系统里不存在"某个学生登录后看自己的成绩"这条路径。
-> 成绩记录本身是按学生名单存的（`Grade.userId`），只是入口统一在班级账号上。
-
-## 接口
-
-| 方法           | 路径                                           | 权限                        |
-| -------------- | ---------------------------------------------- | --------------------------- |
-| GET            | `/grades/my`                                   | 登录（班级会话 → 全班总览） |
-| GET            | `/grades?classId=&courseId=&userId=&examName=` | 教师 / 管理员               |
-| GET            | `/grades/stats?classId=&courseId=&examName=`   | 教师 / 管理员               |
-| POST           | `/grades`、`/grades/bulk`                      | 班主任 / 管理员             |
-| PATCH / DELETE | `/grades/:id`                                  | 班主任 / 管理员             |
-
-写入后会广播 `grade:updated`，客户端立刻刷新。

docs/app/homeworks.md

@@ -84,8 +84,8 @@ Web 端作业详情抽屉里同样可看可改。
 发布 / 修改 / 删除作业会分别广播：
 
 | 事件               | 客户端反应                                          |
-| ------------------ | ------------------------------------- |
+| ------------------ | --------------------------------------------------- |
-| `homework:new`     | 作业列表刷新 + 灵动岛弹「新作业」胶囊 |
+| `homework:new`     | 列表刷新；经典岛显示胶囊/课堂暂存，自定义岛提示铃铛 |
 | `homework:updated` | 刷新；带 `deleted: true` 表示删除                   |
 | `homework:status`  | 完成状态变化时刷新统计                              |
 

docs/app/imports.md

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

docs/app/index.md

@@ -9,10 +9,11 @@ description: ClassHelper每一项功能怎么用：课表、作业、通知、
 很多"看起来像故障"的现象其实是设计行为，下面每一页都会点出来。
 
 | 页面                              | 讲什么                                                     |
-| --------------------------------- | ------------------------------------------------------ |
+| --------------------------------- | ---------------------------------------------------------- |
 | [课表](schedules.md)              | 周视图与「今天」时间轴、单双周、学期周数、课表来源         |
+| [课件](courseware.md)             | 上传、班级可见范围、推送与逐设备接收                       |
 | [作业](homeworks.md)              | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单     |
-| [通知与提醒](notifications.md)    | 三档优先级、上课时段策略、二次确认、已读与红点         |
+| [通知与提醒](notifications.md)    | 四档优先级与两种岛模式、上课时段策略、二次确认、已读与红点 |
 | [叫人](calls.md)                  | 普通叫人与紧急叫人的差别、快捷短语、谁能叫谁               |
 | [成绩](grades.md)                 | 录入方式、导入、等级分布、学生看到的是什么                 |
 | [班级、学生与教师](classes.md)    | 班级账号、名单、班主任与各科任课老师、谁看得见什么         |
@@ -22,16 +23,16 @@ description: ClassHelper每一项功能怎么用：课表、作业、通知、
 
 ## 贯穿所有功能的三条规则
 
-**一、角色决定可见范围。** 同一个页面，管理员、班主任、科任老师看到的数据与能点的按钮都不一样。
+**一、权限与范围共同决定可见内容。** 同一个页面，管理员、班主任、科任老师看到的数据与能点的按钮都不一样。
 前端会按权限隐藏入口，但**真正拦人的是服务端**——直接调接口一样会被拒。完整矩阵在
 [角色与权限](../dev/permissions.md)。
 
-**二、上课时段不打扰课堂。** 「上课时段」由课表实时判定，普通通知与普通叫人只进队列、下课补弹；
+**二、课堂提醒遵循本机布局规则。** 经典模式普通通知暂存到下课，普通叫人保留可点胶囊；
-紧急通知与紧急叫人才会立刻打断。规则只有一份，客户端与 ClassIsland 都遵守它。
+紧急通知与紧急叫人立即展开；自定义常驻模式先显示铃铛，由用户主动查看。
 细节见[通知与提醒](notifications.md)。
 
-**三、实时推送只走班级房间。** 老师一发内容，服务端写库后按班级房间广播，客户端立刻更新，
+**三、实时广播配合恢复读取。** 老师发布后服务端按班级等房间广播，客户端刷新；断线恢复重新拉取。
-不靠轮询。教室机器断线重连后会自动补上漏掉的数据，灵动岛也会把上课期间暂存的通知补弹出来。
+设备心跳和课件补领另有轮询机制，普通通知课堂暂存由客户端处理。
 
 ## 两端的差异
 
@@ -40,7 +41,7 @@ description: ClassHelper每一项功能怎么用：课表、作业、通知、
 | 事情       | Web 管理端（老师）              | 桌面客户端（教室机器）                                    |
 | ---------- | ------------------------------- | --------------------------------------------------------- |
 | 作业       | 发布 / 编辑 / 删除 / 看未交名单 | 看作业 + **录入作业** + 勾未交名单，不显示"完成 / 待完成" |
-| 成绩       | 录入 / 导入 / 改 / 删，带统计   | 只看全班总览                                              |
+| 成绩       | 录入 / 导入 / 改 / 删，带统计   | 按班级开关看个人数据或集体分析                            |
 | 课表       | 排课、导入、改                  | 只看（周视图 + 今天时间轴）                               |
 | 通知       | 发布 / 删除 / 看已读            | 看、标为已读                                              |
 | 班级与人员 | 管理员可管                      | 只能看本班                                                |

docs/app/island.md

@@ -1,121 +1,79 @@
 ---
 title: 灵动岛
-description: 桌面客户端的通知浮窗：胶囊与卡片、多条通知的竖排列表、停靠与外观、触摸屏下的行为。
+description: 经典提醒、自定义常驻方案、课程与课件传输。
 ---
 
 # 灵动岛
 
-灵动岛是桌面客户端上那个独立于主窗口的浮窗：无边框、透明、置顶、不占任务栏。
+灵动岛是客户端的独立透明窗口，不占任务栏。设置中可选择经典 fixed 或自定义 custom，默认 fixed。
-它是「消息到达的第一现场」—— 老师发的内容先在岛上出现，学生点开才进主界面。
+自定义当前即常驻模式；旧 residentEnabled 字段只作兼容，不是另一个独立开关。
+两种布局共用一个原生窗口，切布局不会新开第二个岛。
 
-视觉参照 [WinIsland](https://github.com/WinIslandProject/WinIsland)：
+## 两种消息展示
-连续圆角（超椭圆）而不是 `border-radius`、纯黑 / 毛玻璃 / 主题色三种底、Apple 系统色强调色、
-6 个停靠位、可选的「空闲细缝」。逐项设计令牌见[灵动岛设计令牌](../dev/winisland-design-tokens.md)。
 
-## 各形态长什么样
+| 场景              | 经典 fixed                     | 自定义 custom              |
+| ----------------- | ------------------------------ | -------------------------- |
+| 空闲              | 默认隐藏，可选细缝             | 显示常态组件行             |
+| 课间普通通知/作业 | 胶囊，点击详情                 | 铃铛和未处理数量，点击查看 |
+| 课堂普通通知/作业 | 暂存，下课补弹                 | 铃铛提示，允许主动查看     |
+| 普通叫人          | 课堂也保留可点胶囊，不自动展开 | 铃铛提示，主动查看         |
+| 紧急通知/紧急叫人 | 无论课堂状态立即展开           | 铃铛提示，由用户主动展开   |
+| 无消息时点击      | 按经典空闲状态处理             | 展示方案的无通知展开内容   |
+| 处理完成          | 队列清空后隐藏或细缝           | 回到常态组件行             |
 
-| 形态                   | 截图                                                  | 说明                                              |
+多条消息按 id 去重，按优先级和时间排序；详情显示列表与“展开更多”，超出工作区提示到应用中操作。
-| ---------------------- | ----------------------------------------------------- | ------------------------------------------------- |
+“知道了/标为已读”按当前列表语义处理；本机刚录的作业通过指纹避免重复提醒自己。
-| 非上课时段的「新消息」 | ![新消息胶囊](../images/island-4-pill.png)            | 268×44，直接出现（无入场动画），点击后展开        |
+课堂发布紧急通知的二次确认是服务端规则，见[通知](notifications.md)，不因本机布局改变。
-| 点开后的详情卡         | ![点击后展开](../images/island-5-clicked.png)         | 标题 / 内容 / 时间 + 打开应用 / 标为已读 / 知道了 |
-| 下课后自动弹出         | ![下课后自动弹出](../images/island-2-after-class.png) | 上课期间暂存的通知，下课后自动弹出                |
-| 上课期间的紧急通知     | ![紧急通知立即展开](../images/island-3-urgent.png)    | 卡片**内部**红色光晕 + 紧急角标，无需点击         |
-| 新作业                 | ![新作业](../images/island-7-homework.png)            | 青蓝描边 + 书本图标                               |
-| 叫人                   | ![叫人](../images/island-8-call.png)                  | 琥珀金卡片 + 「叫人」徽标 + 「收到」按钮          |
 
-## 什么时候弹、弹成什么样
+经典布局的历史展示图（供外观参考，具体行为以上表和当前设置为准）：
 
-| 场景                              | 灵动岛行为                                                                                    |
+| 场景     | 展示图                                  |
-| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| -------- | --------------------------------------- |
-| 收到通知（非上课时段）            | 直接出现胶囊：`新消息 · 共 N 条` + 发送人 + `点击查看`                                        |
+| 经典胶囊 | ![胶囊](../images/island-4-pill.png)    |
-| 多条未处理消息                    | 胶囊标题汇总类型：`新消息：叫人/作业/通知（共 3 条）`，右侧带类型小标签                       |
+| 展开详情 | ![详情](../images/island-5-clicked.png) |
-| 点击胶囊（只有一条）              | 展开为**详情卡**：标题、内容、时间 + 三个按钮                                                 |
+| 紧急通知 | ![紧急](../images/island-3-urgent.png)  |
-| **点击胶囊（多条）**              | 展开为**竖排列表**，按重要程度排序（紧急 > 重要 > 普通 > 低，同级按时间新的在前）             |
-| **点「展开更多」**                | 把放得下的都铺出来；铺到工作区下沿还放不下时改成「更多请前往应用内操作」                      |
-| **多条时的「知道了 / 标为已读」** | 都是**整批**操作                                                                              |
-| 上课时段的**普通叫人**            | **不自动展开**（不打断课堂），但保留胶囊并**允许学生主动点开**；下课自动展开                  |
-| **紧急叫人**                      | 上课时段也立即展开，卡片是琥珀金 + 「叫人」徽标，按钮为「收到」                               |
-| 上课时段的普通通知                | **完全不显示**（窗口隐藏）并进队列；下课自动弹出详情 → 收起为胶囊                             |
-| 上课时段的紧急通知                | **无论是否上课立刻展开**，45 秒后收起                                                         |
-| 点击卡片空白处 / 屏幕任意位置     | 回缩为**胶囊**（不直接消失，仍可再次点开）                                                    |
-| **收起后胶囊常驻**                | 只要还有未处理通知，胶囊就不会消失；彻底消失只在「知道了 / 标为已读」、队列清空或进入上课时段 |
 
-> **本机刚录入的作业不会上岛** —— 自己通知自己没意义。
+## 编辑自定义方案
 
-## 多条通知时的排版
+“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
+页面上方排列当前组件，右上角选择配置方案；刷新图标重置当前方案，加号新建方案，文件夹菜单提供方案设置、复制、删除及 JSON 导入导出。
+下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器，并保留班级通知、作业和叫人组件。
+从组件库拖入上方的行或容器以添加，拖动已有组件调整顺序或跨行移动；也可点击组件库添加到选中的容器或当前行。
+分别编辑常态 rows 与无消息展开 expandedRows，点选组件打开内容、外观、尺寸与隐藏条件设置；行可以新增、排序、设为主要行或删除。
+“进入编辑模式”切换为实际内容预览，支持预览缩放；退出后回到组件标签排列。轮播和滚动容器在编辑时展示全部子组件，便于选择和排列。
+倒计时可指定目标名称与日期，也可按课表倒数至上课、下课或放学。
+天气简报需填写地点名称及经纬度，使用 [Open-Meteo](https://open-meteo.com/en/docs) 的天气数据，每 15 分钟更新；断网时保留本次客户端运行中的缓存并标明“缓存”。天气提示根据天气概况生成，不提供官方气象预警。
+方案保存到本机 config.json.islandLayout，不增加服务端同步。
+编辑预览不创建额外桌面窗口；打开编辑页不自动切布局，应用后启用自定义方案。
+保存按序进行，失败可重试，主题与关怀模式沿用客户端设置。
 
-这是最容易出问题的地方：卡片要长高，还得刚好放得下。规则是**主进程与渲染进程各算一次同一个数**
+## 外观、位置与输入
-（`islandListLayout()`，在 `@classhelper/shared` 里）：
 
-- 默认只显示前 `defaultVisibleRows`（3）条，下面是「展开更多（还有 N 条）」；
+经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距；自定义内容根据实际测量适配工作区。
-- 点开后铺到 `maxCardHeight` 为止，仍放不下的改成「更多请前往应用内操作」；
+自定义方案可配置缩放、圆角、颜色和行间距，默认值与范围在 shared/island-layout.ts。
-- `maxCardHeight` 是主进程按工作区 / 任务栏算出的**可用高度**，随状态下发。
+左右边距只在左/右停靠时生效，居中锚点仍在屏幕中线。
+触摸屏自动进入触摸模式，保留触摸命中和失焦宽限；鼠标模式按光标控制输入穿透。
+自定义常驻内容支持鼠标避让淡化及反转，交互入口、展开/编辑和触摸操作按实现暂停避让。
+应用内动画开关决定岛动画，不能用主窗口的减少动态效果说明替代岛自身规则。
 
-窗口的包围盒会**在卡片形变之前**先长高（这一步用户看不到），否则底部的按钮会被裁掉。
+经典几何与配色参考见[设计令牌](../dev/winisland-design-tokens.md)，实现入口见[当前实现约定](../dev/implementation.md)。
 
-## 外观设置
+## 课程与课件
 
-客户端「设置 → 灵动岛」：
+准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关，课程依据服务端解析后的课表。
 
-| 设置项          | 区间 / 取值                            | 默认                      |
+自定义常驻岛的「课程表」组件可选「当前时间点 / 下一节课 / 今日时间点」：
-| --------------- | -------------------------------------- | ------------------------- |
+「今日时间点」显示当天全部时间点，只有当前项展开显示起止时间，其余折叠只显示课程名；
-| 高度            | 36–72px                                | 44                        |
+课间休息与「默认隐藏」的上课时间点折叠时完全隐藏，轮到它们时才展开；分割线显示一条竖线，行动不显示。
-| 宽度            | 220–420px                              | 268                       |
+课中课程表不再常驻显示倒计时，只在最后一分钟由既有的「下课提醒」页显示「距下课还剩」；
-| 圆角            | 8–32px                                 | 20                        |
+倒计时阈值沿用本机提醒设置（默认 60 秒）。没有时间点数据时退回按课表条目显示课程。
-| 不透明度        | 40%–100%                               | 100%                      |
+经典 fixed 岛的课中提醒条保持原有倒计时行为。
-| **字号**        | 11–20px                                | 13                        |
-| 动画速度        | 0.5×–2×                                | 1×                        |
-| 主题色          | 取色器                                 | `#0a84ff`（Apple 系统蓝） |
-| **视觉风格**    | 纯黑 / 毛玻璃 / 主题色渐变             | 纯黑                      |
-| **显示位置**    | 顶部 / 底部 × 左 / 中 / 右（6 个锚点） | 顶部居中                  |
-| 左右 / 上下边距 | 0–200px / 0–160px                      | 都是 8px                  |
-| 跟随鼠标屏幕    | 开 / 关                                | 关                        |
-| 动画开关        | 开 / 关                                | 开                        |
-| 始终置顶        | 开 / 关                                | 开                        |
-| **空闲细缝**    | 开 / 关                                | 关                        |
 
-几个容易困惑的点：
+课件接收时显示文件名、类型、教师、字节和进度，覆盖当前固定/自定义内容；完成后校验 SHA256 并回执。
+客户端不会自动执行收到的文件，见[课件](courseware.md)。
 
-- **字号是"基础字号"**：岛内所有文本 = 基础字号 × 各自的排版系数（标题 1.08 / 正文 0.95 / 次要 0.78 /
+## 验证与排查
-  徽标 0.76 / 胶囊标题 0.92 ……），所以调一个滑块就能整体放大，比例不会乱。
-- **左右边距只在「左 / 右停靠」时生效**：默认是「顶部居中」，水平锚点就是屏幕中线，
-  这时调左右边距不会有任何变化 —— 设置页会把那个滑块置灰并写明原因。
-- **「毛玻璃」不是窗口材质**，是 CSS 半透明深色卡。用系统级背景材质（`setBackgroundMaterial`）
-  会在卡片外那一圈垫出一块浅色"白底面板"，而且**调用过一次就再也回不去逐像素透明**。
-- **「预览效果」**会本地推一条通知，立刻看到当前尺寸 / 配色 / 动画。预览是专用通道：
-  直接展开、失焦不收起、30 秒后自行消失。
 
-越界的值在**主进程**统一夹紧，配置填坏了也不会让布局错乱。
+默认 verify:desktop/verify:packaged 是后台快速检查，不显示岛或托盘。
-
+只有显式 --visual 或 verify:desktop:visual 才进行桌面像素、透明度、动画和截图验收。
-## 触摸屏（希沃白板等）
+若出现多岛，先确认是否存在用户实例与显式视觉验证实例；不要把默认后台冒烟解释成可见验证岛。
-
-触摸屏上灵动岛走的是**另一条命中链路**。
-
-原因：常规的命中判定有两条路径 ——渲染进程转发鼠标移动、主进程读系统光标位置 ——
-**两条都以"鼠标指针移动"为前提**。而手指触摸既不产生 `mousemove`、也不移动系统光标，
-窗口就会永远停在"穿透"状态，**手指点不开岛**。
-
-修法是：客户端检测到 `navigator.maxTouchPoints > 0` 后进入触摸模式，
-把窗口**贴合岛体**并**始终接收输入**（Windows 上 Electron 没有窗口区域能力，这是唯一可行的办法）。
-
-触摸模式下有三条额外的护栏，都是为了不闪、不裁：
-
-- **窗口可见期间只缩不放**（需要变小一律等窗口隐藏之后再做）；
-- 命中矩形按**窗口实际尺寸**算偏移；
-- 失焦宽限期放宽到 1200ms（触摸没有光标，"假失焦"会让刚展开的岛被缩回胶囊）。
-
-非触摸屏的机器**完全不走这条路**。
-
-## 鼠标穿透
-
-窗口是按最大形态创建的固定包围盒，比卡片大一圈。默认整块穿透，渲染层做命中测试，
-只在指针进入岛体时打开命中 —— 所以这个"大窗口"不会吞掉桌面上的点击。
-另有一层保险：主进程每 120ms 用系统光标位置校正一次命中。
-
-## 排查"闪一下"
-
-- **开合时底座闪一下**：卡片投影是常驻的 CSS `filter`，形态切换只改参数。
-  给元素增删 `filter` 会让 Chromium 重建渲染表面，首帧可能被当成空内容画出去。
-- **收回一瞬间闪一下**：多半是**自动化验证实例的叠影**，不是产品的问题 ——
-  冒烟会真的在屏幕上放一个灵动岛，如果它和你自己的客户端叠在一起，你看到的是两个窗口。
-  （验证实例的岛是洋红主题色，一眼可辨。）

docs/app/notifications.md

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

docs/app/schedules.md

@@ -1,82 +1,49 @@
 ---
 title: 课表
-description: 周课表与「今天」时间轴、单双周、学期周数、课表来源，以及上课时段是怎么判定的。
+description: 日课表、共享作息、轮换、临时换课和教学周。
 ---
 
 # 课表
 
-课表不只是"给学生们看看"的表格 —— **「上课时段」的判定完全基于它**。
+Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表，客户端提供“今天”时间轴和“本周”视图。
-课表排错，提醒就会在该弹的时候不弹。所以这一页值得读完。
+上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
 
-## 两个视图
+编辑工作区参照 [ClassIsland 档案编辑器](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/ProfileSettingsWindow.axaml) 的课表交互实现，作为管理端内的普通页面展示，沿用全站的导航、间距、控件及浅色/深色主题。顶部切换课表、时间表、科目和调课；课表页默认进入单表编辑：左侧按课表群分组的课表列表，中间逐节选择科目，右侧切换「科目 / 课表信息」。底部仍可切换列表、周和月视图。旧管理页地址 `/schedules` 自动进入同一页面，侧栏和顶部导航始终可用。
 
-| 视图           | 在哪                                      | 内容                                                     |
+点击每天列头的「新课表」选择时间表并创建日课表。周视图点击网格中的课时后可用右侧科目按钮快速填充，支持选择是否自动移动到下一节；方向键可移动焦点，Delete 可清空选中课程。课表名称、时间表、启用星期、轮换规则、生效周次与群组在右侧「课表信息」中维护。列表视图提供批量排课、复制粘贴、拖动交换课程等操作。
-| -------------- | ----------------------------------------- | -------------------------------------------------------- |
-| **周视图**     | Web 端「课表管理」、客户端「课表 → 本周」 | 节次 × 星期 的 7 列表格                                  |
-| **今天时间轴** | 客户端「课表 → 今天」                     | 大时钟 + 当前状态卡 + 时间轴（已结束 / 正在上 / 下一节） |
 
-「今天」时间轴是客户端默认打开的那一屏：
+时间表页采用 ClassIsland 式编辑器：左侧时间表列表（新建、复制、搜索），顶部按类型添加上课、课间休息、分割线、行动，中间可在列表视图与时间轴视图之间切换，右侧编辑选中时间点，左下设置默认上课/课间时长，右下缩放。时间轴视图可按分钟拖动时间点的开始/结束把柄，并按 1 分钟取整；列表视图可拖动排序。保存仍走页面顶部「保存」或 Ctrl+S；切周与实时刷新保留草稿，切换班级和离开页面时提醒未保存的修改。
 
-- **大时钟**：时:分（大字）+ 秒（小字），下面一行是日期 / 星期 / 第 N 教学周。
+上课时间点可以设置一个默认课程。日课表里**没有单独条目**的课时会回退到该默认课程；已有条目（包括显式空课）不会被覆盖。「覆盖现有课程」会把这门课写入所有引用该时间表的日课表。默认隐藏的上课时间点只在轮到时才在主界面显示；课间休息类型代表下课时间，折叠时完全隐藏，轮到它时才展开。
-- **当前状态卡**：「正在上 XXX」+ 时段地点 + **距下课 X 分钟**；没课时显示"今天的课都上完了"或"今天没有课程安排"。
-- **时间轴**：左侧时间栏（开始 / 结束）+ 竖向轨道与节点 + 右侧课卡。已结束的置灰、
-  正在上的用强调色实底 + 进度条 + 距下课倒计时、下一节用橙色标记 + "还有多久开始"。
 
-## 单双周
+完整档案可在页头「导入/导出」中导入或导出 JSON，保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航，点击日期后由服务端解析教学周并进入周视图。
 
-一门课可以设成**每周**（默认）、**单周**或**双周**。判定口径是 **第 1 周 = 单周**。
+## 日课表与时间表
 
-从 ClassIsland 导入时，`WeekCountDiv`（`0=每周 / 1=单周 / 2=双周`）会换算成这套 `ALL / ODD / EVEN`。
+时间表保存时间点：上课、课间、分割线、行动；日课表引用时间表，每节课程通过外键关联时间点。
-**3 周及以上的轮换没法用单双周表达**，导入时会给出 warning 并按"每周"处理 ——
+可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
-如果学校里真的是三周轮换，目前只能用两份课表 + 手工切换的方式绕过。
+时间点排序不会改变课程关联。行动配置当前保存数据，不执行外部动作。
 
-## 学期周数
+日课表按星期、周次范围和轮换规则启用，支持 1–9 周轮换；单双周是 2 周轮换的特例，第 1 教学周为单周。
+可以预定某天使用某张表，临时换课/叠加层保留原表。相同日期的最终启用选择由服务端唯一解析器完成。
 
-每个班有自己的**学期周数**（`Class.termWeeks`，默认 20，**上限 30**），只有管理员能改。
+## 教学周
 
-它决定三件事：课表的周次下拉能选到第几周、`weekEnd` 的默认值、以及"现在是第几教学周"。
+班级有自己的学期周数；全校上限由“学期周次”设置，默认 30、可设 1–60，班级不能超过该上限。
-周次换算的起点是服务端 `.env` 里的 `TERM_START_DATE`（当学期第 1 教学周的周一）。
+默认班级周数为 20。管理员可在界面修改全校开学日和逐周起止区间，班级可有独立设置。
+计算优先使用班级逐周区间、再全校区间；无适用区间时按开学日线性计算。
+开学日解析还会参考第 1 周起点，环境变量 TERM_START_DATE 是兜底，具体顺序见 `lib/term.ts`。
 
-> **`TERM_START_DATE` 设错，整套周次都错。** 它不在界面上改，要改 `.env` 后重启服务端。
+## 上课状态与提醒
-> 上限三处必须一致（`MAX_TERM_WEEK`、周次校验、班级设置），曾经出现过"班级能设到 40 周、
-> 而课表只到 30 周"的错位。
 
-## 上课时段是怎么判定的
+`GET /api/schedules/current?classId=<id>&at=<ISO时间>` 返回 inClass/current/next/week/serverTime 等状态；at 用于诊断。
+`/schedules` 是新模型的兼容门面，旧 Schedule 只保留迁移审计记录。
+经典岛普通通知上课暂存、下课补弹；普通叫人保留可点击胶囊，紧急消息立即展开。
+自定义常驻岛先显示铃铛，由用户主动查看。紧急通知在课堂发布仍需服务端二次确认。
 
-服务端有一个接口专门回答"这个班现在是不是在上课"：
+## 权限与导入
 
-```
+日课表写入需 schedule:write，并通过管理员或本班班主任检查；时间表写入需 timetable:manage。
-GET /api/schedules/current?classId=<班级 id>[&at=<ISO 时间>]
+离线导入完整 ClassIsland 档案可创建班级自有作息，不依赖在线联动插件。
-```
+完整导入保留 1–9 周轮换、空课、停用、群组和预定；旧预览界面的单双周展示不代表新模型只能表达双周。
-
+见[表格与课表导入](imports.md)。修改后广播 schedule:updated，客户端刷新。
-返回 `{ inClass, current, next, week, serverTime }`。`at` 参数可以覆盖判定时刻，用来联调与测试。
-
-判定结果被用在四处，规则完全一致：
-
-1. 客户端灵动岛：上课时段普通通知**不显示**（窗口直接隐藏）并进队列，下课自动补弹；
-2. ClassIsland 插件：同样暂存，下课后补弹；
-3. 服务端发布接口：上课时段发紧急通知会被拦（`409 URGENT_DURING_CLASS`），确认后放行；
-4. Web 端：提交紧急通知前先查一次状态，命中就弹全屏二次确认。
-
-## 课表的"来源"字段
-
-每一行课表都记着它是从哪来的：
-
-| 来源          | 什么时候产生                                   | 会被自动清理吗               |
-| ------------- | ---------------------------------------------- | ---------------------------- |
-| `manual`      | Web 端手工录入、从 ClassIsland JSON 一次性导入 | **不会**，永远保留           |
-| `classisland` | 教室插件上报同步过来的                         | 会——本次没再上报的行会被删掉 |
-
-这条规则解决了"老师在 ClassIsland 里删掉一节，小助手这边却永远留着"的幽灵课问题，
-同时保证老师在小助手这边手排的课不会被插件覆盖掉。
-
-> 去重键是「星期 + 开始时间 + 单双周」。如果老师手排的某一节恰好和上报的同一时间槽重合，
-> 那一行会被上报"收养"（保留原本的 `manual` 来源），下一次清理不会删它。
-
-## 排课 / 改课 / 导入
-
-- 手工排课在 **课表管理**（管理员 / 本班班主任）。科目下拉是全校统一的 18 科目录，
-  选中一个该班还没有的科目会自动建课。
-- 从 ClassIsland 档案导入最省事，课表、节次时间、单双周会一起进来，
-  见[表格与课表导入](imports.md)。
-- 课表变更后会广播 `schedule:updated`，客户端与灵动岛立刻刷新。

docs/app/toc.yml

@@ -4,6 +4,8 @@
   href: schedules.md
 - name: 作业
   href: homeworks.md
+- name: 课件上传与传输
+  href: courseware.md
 - name: 通知与提醒
   href: notifications.md
 - name: 叫人

docs/dev/api.md

@@ -1,138 +1,119 @@
 ---
 title: REST API
-description: ClassHelper后端全部接口一览：方法、路径、权限与说明。
+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`（设备接口也一样）；
+## 身份与班级
-- 统一响应体：`{ "success": true, "data": {}, "message": "" }`，错误为 `success: false` + `code`；
-- 除登录、健康检查与设备接口外，都需要 `Authorization: Bearer <token>`；
-- **ClassIsland 设备接口用 `X-ClassIsland-Token`**，不走 JWT（见[ClassIsland 插件](classisland-plugin.md)）；
-- 请求体校验走 zod（`middleware/validate.ts`），错误由 `middleware/error.ts` 统一映射。
 
-## 接口一览
+| 方法与路径（省略 /api）                                                 | 行为及边界                                                     |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
+| POST /auth/login、/auth/class-login                                     | 员工/班级登录，共享登录限流；学生无账号                        |
+| GET /auth/me；POST /auth/logout；PATCH /auth/password                   | 当前身份、退出、员工本人改密码                                 |
+| GET/POST /classes；GET/PATCH/DELETE /classes/:id                        | 班级查询/管理，读取 class:read；写入 class:manage 且仅管理员   |
+| PATCH /classes/:id/class-account、/classes/:id/head-teacher             | 班级凭据 class:account + 班主任；班主任分配仅管理员            |
+| PUT /classes/:id/subject-teachers                                       | 任课关系设置，Course 为唯一来源                                |
+| GET/PATCH /classes/:id/student-grade-query                              | 查看/修改班级个人成绩查询开关，班级端不能修改                  |
+| GET/POST /classes/:id/students；DELETE /classes/:id/students/:studentId | 本班名单及维护，受名单功能权限和班级关系约束                   |
+| /students、/teachers                                                    | 名单与账号 CRUD；读/写使用不同权限键，具体角色限制读取对应模块 |
+| POST /teachers/:id/reset-password                                       | 指定新密码或默认重置；学生无对应接口                           |
+| /permissions/me、/catalog、/groups、/users                              | 当前有效权限、目录、组与账号分组                               |
 
-| 方法                        | 路径                                                          | 权限                         | 说明                                                                           |
+## 教学与文件
-| --------------------------- | ------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------ |
-| POST                        | `/auth/login`                                                 | 公开                         | 登录（教师 / 管理员的**工号** + 密码）；学生不是账号，拿学号登录只会得到 401   |
-| POST                        | `/auth/class-login`                                           | 公开                         | **班级账号登录**：班级码 + 班级密码 → 班级会话                                 |
-| GET                         | `/auth/me`                                                    | 登录                         | 当前用户（学生附带班级 / 年级）                                                |
-| PATCH                       | `/auth/password`                                              | 登录                         | 修改自己的密码（班级会话 → 班级密码）                                          |
-| POST                        | `/auth/logout`                                                | 登录                         | 退出（无状态，客户端丢弃 token）                                               |
-| GET                         | `/permissions/me`                                             | 登录                         | 当前账号的生效权限（**无权限键**；班级端会话返回空集）                         |
-| GET                         | `/permissions/catalog`                                        | `permission:manage`          | 权限键目录（权限页整棵勾选树的唯一来源）                                       |
-| GET / POST                  | `/permissions/groups`                                         | `permission:manage`          | 权限组列表 / 新建                                                              |
-| PATCH / DELETE              | `/permissions/groups/:id`                                     | `permission:manage`          | 改名 / 改描述 / 整体替换权限键；内置组不可删                                   |
-| GET                         | `/permissions/users`                                          | `permission:manage`          | 成员列表（所属权限组 + 生效权限数量）                                          |
-| PUT                         | `/permissions/users/:id/groups`                               | `permission:manage`          | 整体替换某账号的权限组（空数组 = 回落角色默认模板）                            |
-| GET                         | `/classes`                                                    | 登录                         | 班级列表（按权限收敛）                                                         |
-| GET                         | `/classes/:id`                                                | 班级可见                     | 班级详情（学生 / 课程 / 班主任 / 各科任课老师）                                 |
-| POST                        | `/classes`                                                    | 管理员                       | 创建班级（自动生成班级码，可指定班主任）                                       |
-| PATCH / DELETE              | `/classes/:id`                                                | 管理员 / 教师                | 编辑 / 删除班级                                                                |
-| PATCH                       | `/classes/:id/class-account`                                  | 管理员                       | 设置 / 重置班级账号（班级码 + 班级密码）                                       |
-| PATCH                       | `/classes/:id/head-teacher`                                   | 管理员                       | 设置 / 更换班主任                                                              |
-| GET                         | `/classes/:id/classisland-status`                             | 班级可见                     | 本班 ClassIsland 联动状态（教室客户端设置页用）                                |
-| GET                         | `/classes/:id/notification-channel`                           | 班级可见                     | 读取「通知显示到哪个端」                                                       |
-| PATCH                       | `/classes/:id/notification-channel`                           | 班级账号 / 教师 / 管理员     | 设置「通知显示到哪个端」                                                       |
-| GET / POST                  | `/classes/:id/students`                                       | 班级可见 / ADMIN·TEACHER     | 学生名单 / 添加学生                                                            |
-| DELETE                      | `/classes/:id/students/:userId`                               | ADMIN·TEACHER                | 移出学生                                                                       |
-| PUT                         | `/classes/:id/subject-teachers`                               | ADMIN                        | 设置各科任课老师（班级 + 科目 + 教师）                                         |
-| GET / POST / PATCH / DELETE | `/courses`                                                    | 登录（写：班主任 / 管理员）  | 课程管理                                                                       |
-| GET                         | `/schedules?classId=&week=&dayOfWeek=`                        | 登录                         | 课表列表（`week` 过滤周次范围）                                                |
-| GET                         | `/schedules/grid?classId=&week=`                              | 登录                         | 周视图（7 列结构，供客户端直接渲染）                                           |
-| GET                         | `/schedules/current?classId=&at=`                             | 登录                         | 当前上课状态（`inClass` / `current` / `next`；`at` 为诊断用时间覆盖）          |
-| POST / PATCH / DELETE       | `/schedules[/:id]`                                            | 班主任 / 管理员              | 课表增删改（广播 `schedule:updated`）                                          |
-| GET                         | `/homeworks?classId=&courseId=&date=&pendingOnly=&keyword=`   | 登录                         | 作业列表（支持按所属日期；学生带完成状态，教师带完成人数）                     |
-| GET                         | `/homeworks/days?classId=&from=&to=`                          | 登录                         | 哪些天有作业（日期高亮）                                                       |
-| GET                         | `/homeworks/:id`                                              | 班级可见                     | 作业详情                                                                       |
-| POST                        | `/homeworks`                                                  | 教师 / 管理员 / **班级账号** | 发布作业（附 `assignDate`；班级账号用于教室机器录入，归属班主任）              |
-| PATCH / DELETE              | `/homeworks/:id`                                              | 教师 / 管理员                | 修改 / 删除（广播 `homework:new` / `homework:updated`）                        |
-| PATCH                       | `/homeworks/:id/status`                                       | 登录                         | 标记完成 / 取消（广播 `homework:status`）                                      |
-| GET / PATCH                 | `/homeworks/:id/submissions`                                  | 登录                         | 未交名单：读名单 / 回写全班完成状态                                            |
-| POST                        | `/homeworks/bulk`                                             | `homework:write`             | 一次给多个班级布置同一份作业（`subjectName` 跨班按名匹配科目；逐班结果）       |
-| GET                         | `/notifications?classId=&priority=&unreadOnly=&keyword=`      | 登录                         | 通知列表（带已读状态；另支持 `date` / `from` / `to` / `createdBy`）            |
-| GET                         | `/notifications/unread-count`                                 | 登录                         | 未读数（红点）                                                                 |
-| POST                        | `/notifications`                                              | 教师 / 管理员                | 发布通知（广播 `notification:new`）；上课时段发紧急通知需 `confirmDuringClass` |
-| POST                        | `/notifications/:id/read`、`/notifications/read-all`          | 登录                         | 标记已读（班级设备会写全班）                                                   |
-| DELETE                      | `/notifications/:id`                                          | 教师 / 管理员                | 删除通知                                                                       |
-| GET                         | `/notifications/days?classId=&from=&to=&createdBy=`           | 登录                         | 通知按天归档（日期 + 条数，日期取 `assignDate`）                               |
-| GET                         | `/notifications/creators?classId=&from=&to=&date=`            | 登录                         | 通知按发布人归档                                                               |
-| POST                        | `/notifications/bulk`                                         | `notification:publish`       | 一次给多个班级发同一条通知（逐班结果，**单班失败不影响整批**）                 |
-| POST                        | `/calls`                                                      | 教师 / 管理员                | **叫人**（`urgent` 决定 URGENT / HIGH；广播 `notification:new` 与 `call:new`） |
-| GET                         | `/grades/my`                                                  | 登录                         | 个人成绩（班级会话 → 全班总览）                                                |
-| GET                         | `/grades?classId=&courseId=&userId=&examName=`                | 教师 / 管理员                | 班级成绩                                                                       |
-| GET                         | `/grades/stats?classId=&courseId=&examName=`                  | 教师 / 管理员                | 等级分布 + 各课程平均得分率                                                    |
-| POST                        | `/grades`、`/grades/bulk`                                     | 班主任 / 管理员              | 单条 / 批量录入（广播 `grade:updated`）                                        |
-| PATCH / DELETE              | `/grades/:id`                                                 | 班主任 / 管理员              | 修改 / 删除成绩                                                                |
-| GET                         | `/students?classId=&keyword=`                                 | **管理员**                   | 学生名单                                                                       |
-| POST / PATCH / DELETE       | `/students[/:id]`                                             | **管理员**                   | 学生名单增删改（无密码概念；重置密码接口已下线 → 404）                         |
-| GET                         | `/teachers?keyword=`                                          | **管理员**                   | 教师列表                                                                       |
-| POST / PATCH / DELETE       | `/teachers[/:id]`                                             | **管理员**                   | 新建 / 编辑 / 删除教师账号                                                     |
-| POST                        | `/teachers/:id/reset-password`                                | **管理员**                   | 修改 / 重置教师密码（`newPassword` 可选，留空 = 默认初始密码）                 |
-| GET                         | `/dashboard/summary`、`/dashboard/term`                       | 登录                         | 仪表盘汇总 / 学期周次                                                          |
-| GET                         | `/imports/template?kind=&format=`                             | 管理员 / 班主任              | 导入模板下载（`csv` 走 JSON，`xlsx` 走二进制）                                 |
-| POST                        | `/imports/table/preview`                                      | 管理员 / 班主任              | 上传表格（base64）解析预览：列名 + 前 20 行 + 校验问题 + 建议映射              |
-| POST                        | `/imports/table/commit`                                       | 管理员 / 班主任              | 按字段映射与写入模式导入（成绩 / 学生名单 / 教师名单）                         |
-| POST                        | `/imports/time-layout/preview`                                | 管理员 / 本班班主任          | 解析 ClassIsland 时间配置 JSON（只解析不落库）                                 |
-| GET / POST / DELETE         | `/imports/time-layout[/:id]`                                  | 管理员 / 本班班主任          | 时间配置列表 / 导入（`replace` 覆盖、`merge` 合并）/ 删除                      |
-| POST                        | `/imports/class-plan/preview`、`/imports/class-plan`          | 管理员 / 本班班主任          | ClassIsland 课程表解析预览 / 导入（支持单双周）                                |
-| GET / POST / PATCH / DELETE | `/integrations/devices[/:id]`                                 | 管理员 / 教师                | ClassIsland 联动设备管理（令牌只存 sha256，令牌前缀用于人眼识别）              |
-| POST                        | `/integrations/devices/:id/token`                             | 管理员 / 教师                | 重置设备令牌（旧令牌立即失效，明文只返回一次）                                 |
-| POST                        | `/integrations/classisland/notify`                            | 管理员 / 教师                | 下发提醒到该班 ClassIsland 设备（广播 `classisland:notification`）             |
-| GET                         | `/database/status`                                            | **管理员**                   | 数据库状态（连接 / 版本 / 体积 / 23 张表行数 / 备份列表 / 定时配置）           |
-| POST                        | `/database/test-connection`                                   | **管理员**                   | 测试任意目标库连通性（provider 仅 sqlite / mysql）                             |
-| GET / POST                  | `/database/backups`                                           | **管理员**                   | 备份列表 / 立即备份（gzip JSON 快照，存 `<数据目录>/backups/`）                |
-| POST / DELETE               | `/database/backups/:name/restore` · `/database/backups/:name` | **管理员**                   | 从备份恢复（整库覆盖）/ 删除备份                                               |
-| GET                         | `/database/export`、`/database/sqlite-file`                   | **管理员**                   | 下载 JSON 快照 / 下载数据库文件（后者仅 SQLite）                               |
-| POST                        | `/database/import`                                            | **管理员**                   | 导入快照（base64，整库覆盖；可在 SQLite / MySQL 之间互迁）                     |
-| GET / PUT                   | `/database/backup-schedule`                                   | **管理员**                   | 定时备份配置（enabled / intervalHours / keepCount）                            |
-| POST / GET                  | `/database/switch`、`/database/switch/jobs/:id`               | **管理员**                   | **一键切换数据库**（异步任务）/ 轮询进度                                       |
-| POST                        | `/integrations/classisland/report`                            | **设备令牌**                 | 插件上报状态 + 课表 + 节次时间                                                 |
-| GET                         | `/integrations/classisland/pending`                           | **设备令牌**                 | 插件拉取尚未确认的提醒（离线期间老师发的通知，重连后补齐）                     |
-| POST                        | `/integrations/classisland/ack`                               | **设备令牌**                 | 插件确认提醒已弹出（确认后不再补发）                                           |
-| GET                         | `/integrations/classisland/class-plan`                        | **设备令牌**                 | 插件拉取本班课表（开启镜像时）用于写回 ClassIsland                             |
-| GET                         | `/update/check`                                               | 登录                         | 更新检查（服务端代查 GitHub 最新 Release；`?force=1` 绕过缓存仅管理员生效）    |
-| POST                        | `/clients/heartbeat`                                          | 登录                         | 客户端每 30 秒上报（**无权限键**）；返回更新目标 + 安装包信息 + 一条待执行命令 |
-| POST                        | `/clients/commands/:id/ack`                                   | 登录                         | 命令执行回执（**无权限键**，靠 body 的 `deviceKey` 校验归属，幂等）            |
-| POST                        | `/clients/commands`                                           | `remote:control`             | 下发远控命令（关机 / 重启 / 注销 / 锁屏；自动撤销该机更早的未回执命令）        |
-| GET                         | `/clients/devices?classId=`                                   | `client:manage`              | 客户端设备列表（版本 / 在线 / 待执行命令）                                     |
-| POST                        | `/clients/updates`                                            | `client:update-push`         | 统一下发客户端更新（按设备 / 班级 / 全部）                                     |
-| DELETE                      | `/clients/devices/:id`                                        | `client:manage`              | 移除设备记录（换机 / 旧机器清理）                                              |
-| GET                         | `/update/client/releases`                                     | `client:manage`              | 服务端已缓存了哪些客户端安装包                                                 |
-| POST                        | `/update/client/fetch`                                        | `client:update-push`         | 服务端代教室机器从 GitHub 下载安装包并登记 sha256 + size                        |
-| POST                        | `/update/client/releases`                                     | `client:update-push`         | 手工登记已放进磁盘的安装包（内网 / U 盘分发兜底）                              |
-| DELETE                      | `/update/client/releases/:version`                            | `client:update-push`         | 删除缓存的安装包（元数据 + 磁盘文件）                                          |
-| GET                         | `/update/client/download/:version`                            | 登录                         | 下载安装包（**故意不挂权限键**，班级端要能下；`res.download`）                 |
-| GET / PUT                   | `/ai/settings`                                                | `ai:manage`                  | 大模型设置（API Key 加密存储、**只进不出**，只回 `hasApiKey` / `keyHint`）     |
-| POST                        | `/ai/interpret`                                               | `ai:use`                     | 一句话解析（**只解析不落库**）；回 `action` / `params` / `preview` / `confidence` |
-| GET                         | `/ai/audit?limit=`                                            | `ai:manage`                  | 助手使用记录（每次解析写一条 `AiAudit`）                                       |
-| GET / PUT                   | `/system/settings`                                            | `system:manage`              | 系统设置（`developerMode`：开启后 500 响应带 `error.stack`）                   |
-| GET / PUT                   | `/system/autostart`                                           | `system:manage`              | 开机自启状态 / 开关（Windows 注册表 Run 项，Linux systemd 单元）               |
-| GET                         | `/system/diagnostics`                                         | `system:manage`              | 运行诊断（版本 / Node / 运行时长 / 数据目录 / 在线客户端数 / 已加载模块）      |
-| GET                         | `/health`                                                     | 公开                         | 健康检查（含版本号与已挂载模块）                                               |
 
-另有三个探针（不带 `/api` 前缀）：`/healthz`（存活）、`/readyz`（就绪）、以及 `/api/health`（详情）。
+| 路径/动作                                                                                                  | 行为及边界                                                                           |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| /courses                                                                                                   | 班级科目与任课关系                                                                   |
+| GET /schedules、/grid、/current、/active-week                                                              | 新关系模型的兼容投影，按班级范围读取                                                 |
+| POST/PATCH/DELETE /schedules[/:id]                                                                         | 兼容 CRUD，写新模型，不双写旧 Schedule                                               |
+| POST /schedules/swap、/overlay、/scheduled；GET /schedules/scheduled；DELETE /schedules/scheduled/:id      | 换课、临时层、预定                                                                   |
+| /time-layouts；POST /time-layouts/:id/clone、/:id/import                                                   | 时间表 CRUD/克隆/导入，写入 timetable:manage                                         |
+| /class-plans；PUT /class-plans/:id/entries；PATCH /class-plans/:id/enabled                                 | 日课表 CRUD、整表保存、启用，写入 schedule:write + 班主任/管理员                     |
+| POST /class-plans/:id/clone、/class-plans/import、/class-plans/import/profile；GET /class-plans/:id/export | 复制、导入导出及完整档案导入；导入另需 import:schedule                               |
+| /class-plan-groups；GET /class-plan-groups/selection；POST /class-plan-groups/select                       | 群组及当前/临时选择                                                                  |
+| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions                                                 | 作业、批量、完成与未交；员工功能键+科目检查，班级端可录作业                          |
+| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all                 | 通知、归档和已读；发布需 notification:publish，课堂紧急须确认                        |
+| POST /calls                                                                                                | 叫人，call:create + 范围检查                                                         |
+| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md)，查询列表参数用 studentId，写入仍按科目               |
+| /imports/template、/table/preview、/table/commit                                                           | 表格导入，按 kind 再检查对应导入键、管理键、班级和科目                               |
+| /imports/class-plan/preview、/imports/class-plan                                                           | 预览与提交均需 import:schedule + schedule:write；提交走关系化导入                    |
+| /imports/time-layout[/:id]、/time-layout/preview                                                           | 时间配置兼容入口，导入需 import:schedule + timetable:manage，删除需 timetable:manage |
+| GET /class-plans/profile?classId=                                                                          | 完整档案导出，按班级范围读取，保留时间点与课表关联                                   |
+| GET /courseware、/courseware/:id、/:id/download                                                            | 课件目录/详情/下载；员工需 courseware:read，班级端按可见范围                         |
+| POST /courseware/upload、/:id/push；PATCH /courseware/:id/visibility；DELETE /courseware/:id               | 写入 courseware:write + 员工身份；本人文件、任课班级与可见范围限制                   |
+| GET/POST /courseware/folders；PATCH /courseware/:id/folder                                                 | 员工 courseware:write；目录与课件均限本人                                            |
+| GET /courseware/transfers；POST /courseware/transfers/:id/ack                                              | 班级端补领、逐设备回执                                                               |
 
-## 几条容易踩的接口约定
+## 设备、系统与运维
 
-| 约定                                         | 说明                                                                                             |
+| 路径/动作                                                                                               | 行为及边界                                                                       |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| **`POST /homeworks` 故意不加 `requireRole`** | 权限判在 `homeworks.service.createHomework` 里（staff 或本班班级账号），因为教室机器也要能录作业 |
+| POST /clients/heartbeat、/clients/commands/:id/ack                                                      | 登录设备心跳/回执，校验 deviceKey 和归属                                         |
-| **班级账号的 `sub` 是班级 id**               | 写 `createdBy` 前要换成该班班主任，否则撞 `User` 外键                                            |
+| POST /clients/update-progress                                                                           | 设备上传下载、校验、等待、安装和失败状态，校验设备班级归属                       |
-| **登录限流挂在两个入口上**                   | `/auth/login` 与 `/auth/class-login` 都挂 `loginRateLimiter()`                                   |
+| GET /clients/devices；DELETE /clients/devices/:id                                                       | 设备读取/维护，分别检查功能键和范围                                              |
-| **角色判定在密码校验之前**                   | 否则"密码错 / 密码对但账号停用"的差异会把学生账号密码变成可离线验证的预言机                      |
+| POST /clients/commands                                                                                  | remote:control + 对应范围，白名单动作                                            |
-| **会渲染成链接的字段要校验 scheme**          | `Homework.attachmentUrl` 只允许 `http(s)://` 或站内相对路径                                      |
+| POST /clients/updates                                                                                   | client:update-push，安装策略 immediate/after-school/idle                         |
-| **表格导入 8MB ↔ 请求体 12MB**               | 文件以 base64 放进 JSON（约 4/3 倍），超限映射成 413 `IMPORT_TOO_LARGE`                          |
+| GET /update/check                                                                                       | 员工需 update:check；强制刷新另检查 update:force                                 |
-| **三个接口故意不挂权限键**                   | `/permissions/me`、`/clients/heartbeat`、`/update/client/download/:version` —— 前两者由班级端（`CLASS_DEVICE`，权限集为空）调用，下载接口要能装包；保护只有"已登录 + 限流" |
+| GET /update/client/releases                                                                             | 缓存版本读取，按路由允许的读取权限                                               |
-| **查询参数校验失败是 422**                   | `middleware/validate.ts` 的 zod 解析错误由错误中间件映射成 422 `VALIDATION_ERROR`（不是 400）   |
+| POST /update/client/fetch、/update/client/releases；DELETE /update/client/releases/:version             | 安装包写入口仅管理员 client:update                                               |
-| **批量发布逐班判定、不整批回滚**             | `/notifications/bulk` 与 `/homeworks/bulk` 的单班失败（403 越权 / `URGENT_DURING_CLASS`）不影响其它班，成功班照常落库并实时推送 |
+| GET /update/client/download/:version                                                                    | 本班 CLASS_DEVICE 或 client:read + 有效班级范围                                  |
-| **`/ai/interpret` 只解析不落库**             | 助手只回结构化参数与中文预览；落库由前端确认后调既有端点 —— 权限与上课时段保护都在那条路径上    |
+| /term；POST /term/auto；GET /term/holidays                                                              | 学期读取/编辑/假日建议，term:read/term:write                                     |
+| GET/PUT /term/promotion；POST /term/promotion/run                                                       | 升级计划与执行，promotion:manage + 全校范围，执行要求确认与计划哈希              |
+| /archives、/archives/transferred、/archives/transferred/:id/restore                                     | 历史归档需 archive:manage 全校范围；撤回转出需 roster:manage；不提供手动创建归档 |
+| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage；目标空库、快照及换库子进程保护                                  |
+| /system/settings、/autostart、/diagnostics                                                              | system:manage，非安装形态自启动返回不可用原因                                    |
+| /ai/settings、/interpret、/audit                                                                        | ai:manage/ai:use；只解析待确认动作，密钥只进不出                                 |
+| /dashboard/summary、/dashboard/term                                                                     | 按范围读取看板与周次                                                             |
 
-## 相关
+探针 /healthz 和 /readyz 不带 API 前缀；/api/health 提供版本与模块详情。
+课件上传是原始文件流，512 MB 限制独立于表格 JSON 的 12 MB 限制；metadata 走上传查询 schema。
+心跳 agentProtocol:2 使用统一响应 data，旧协议兼容字段只用于升级过渡。
+更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。
 
-- 实时事件见[实时事件（Socket.IO）](realtime.md)；
+## 权限治理与学生年度流程
-- 权限矩阵见[角色与权限](permissions.md)；
+
-- 数据模型见[数据模型](data-model.md)。
+| 方法与路径（省略 /api）                              | 参数与权限边界                                                                                                                          |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| GET /permissions/scopes                              | permission:manage；返回可选年级、部建议和计划年级                                                                                       |
+| GET /permissions/groups/:id/members                  | permission:manage；包含显式分组及角色默认回落的生效成员                                                                                 |
+| GET /permissions/audit?page=&pageSize=               | permission:manage；分页操作人、目标、前后 JSON，pageSize 最大 100                                                                       |
+| POST/PATCH/DELETE /permissions/groups[/:id]          | 仅 ADMIN；仅可分配键，范围校验，教师默认模板固定 TEACHING，内置组不可删                                                                 |
+| PUT /permissions/users/:id/groups                    | assignments 整体替换，每项 groupId/scope/scopeValue；兼容 groupIds 按建议范围分配；空数组恢复教师默认模板；ADMIN 不可分配               |
+| GET /students?status=&includeArchived=               | roster:read；默认 active，归档单独筛选；历史状态不会再被在读条件覆盖                                                                    |
+| POST /students                                       | roster:manage；仅 active/inactive，学号重复 409，班级不得归档                                                                           |
+| PATCH /students/:id                                  | roster:manage；仅资料字段；classId/status 明确返回 400                                                                                  |
+| POST /students/transfer                              | roster:manage；studentIds、toClassId（null 表示移出）、note；跨年级需 ADMIN、allowGradeChange=true 与备注                               |
+| POST /students/transfer-out                          | roster:manage；studentIds、note、toSchool；仅 active/inactive，毕业/归档/重复转出 409                                                   |
+| POST /students/transfer-in                           | roster:manage；指定 toClassId，新建用 studentNo/name，重入用 studentId；可传 fromSchool/note                                            |
+| POST /students/:id/restore                           | roster:manage；可传 toClassId/note；转出或停用恢复，原班归档时应另选在读班                                                              |
+| POST /archives/transferred/:id/restore               | 兼容同上，权限改为 roster:manage                                                                                                        |
+| DELETE /students/:id                                 | roster:manage；默认停用；hard=true&confirm=true 仅 ADMIN，存在业务或历史则 409                                                          |
+| GET /students/transfers；GET /students/:id/transfers | roster:read；不排除转出状态；支持 studentId/classId/batchId/academicYear 与分页                                                         |
+| GET/PUT /term/promotion                              | promotion:manage 全校范围；读取计划、执行时间、应执行学年与记录；保存兼容旧 month/day/hour/classCount，也接受 plan                      |
+| POST /term/promotion/preview                         | promotion:manage 全校范围；year；只读返回逐轨道逐班统计、阻断项、警告、新班码、周次影响、planHash                                       |
+| POST /term/promotion/run                             | promotion:manage 全校范围；year、planHash、confirm:true；过去学年还须 ADMIN + catchUp:true；未来年份 400；阻断或哈希变化 409 带 details |
+| POST /classes/promote                                | promotion:manage 与各目标范围；仅 classIds，不收自由 grade；从计划推导下一学段，毕业学段 409                                            |
+| PATCH /classes/:id                                   | 不再接受 grade，旧请求返回 400；改年级须走升级入口                                                                                      |
+| DELETE /archives/:id                                 | archive:manage 全校范围；仅撤销归档标记，保留转出与停用状态，不回滚年级、新班及周次                                                     |
+
+生命周期历史以 kind 为事实源，mode 为派生兼容字段；新响应另含 batchId、academicYear、fromGrade/toGrade、fromSchool/toSchool。
+归档详情含 inactive 列表、inactiveCount 和按学生去重的 transferInCount；升级记录含 operatorId/operatorName、detailsJson、snapshotSha256、error。
+所有学生与历史写入在同一事务，提交后再广播旧班与新班。班级详情只有持 roster:read 且在对应范围内的员工才能获得学生明细。
+
+## 分配级范围与班级设置
+
+`GET /permissions/catalog` 增加 meta（kind/risk/relation/allowedScopes）。模板 DTO 的 defaultScope/defaultScopeValue/defaultScopeLabel 及兼容 scope 字段都是建议范围；kind、inactiveKeys、warnings 展示模板类别和停用键。成员 DTO 的 assignments 是实际分配，groupIds 为派生值；ADMIN fixed=true。
+
+`GET /permissions/users/:id/effective` 仅 ADMIN，返回 permissions、entries（每键 scopes/classes/classCount）、conflicts、headOnlyKeys。可选 query assignments 为 JSON 数组，预览尚未保存的整体分配；预览与实际授权共用求值器。
+
+`PATCH /classes/:id/settings` 使用 class:settings + 本班班主任（ADMIN 例外）保存 termWeeks/termStartDate。管理员 `PATCH /classes/:id` 只接收 enrollmentYear/classIndex。`PATCH /classes/:id/class-account` 使用 class:account + 本班班主任。全局周次仅管理员，带 classId 的周次写走 class:settings + 班主任。时间表写入按存储 classId 分流，班级时间表需要 schedule:write + 班主任，全校时间表仅管理员。
+
+成绩 overview/collective/exams/ranking 显式检查 grade:read，班级端由服务断言限本班并执行查询开关。设备 heartbeat/update-progress/commands/:id/ack 仅接受绑定本班的 CLASS_DEVICE，不接受教师个人设备。
+
+`GET /permissions/me` 同时返回 classScopes、manageScopes、allScopeKeys，供 Web 按钮与班级选择器显示实际能力范围；manageScopes 对名单、日课表、导入和考试配置叠加班主任或显式组织范围规则。界面范围提示不替代服务端断言。

docs/dev/architecture.md

@@ -1,168 +1,79 @@
 ---
 title: 架构总览
-description: 目录结构、技术栈、模块化设计与几条贯穿全局的工程约定。
+description: 工作区结构、模块注册、共享契约与数据流。
 ---
 
 # 架构总览
 
-## 技术栈
+ClassHelper 是 pnpm workspace：Express/Prisma/Socket.IO 服务端、Vue Web 管理端、Electron 桌面客户端与共享包。
+依赖版本以根和各包的 `package.json`、`pnpm-lock.yaml` 为准。文档站和纯静态官网不在 workspace 内。
 
-| 层     | 选型                                                                 | 版本（`package.json` 实际声明）                            |
+## 目录与入口
-| ------ | -------------------------------------------------------------------- | ---------------------------------------------------------- |
-| 包管理 | pnpm workspace                                                       | 11.8.0                                                     |
-| 语言   | TypeScript                                                           | 5.9.3（`typescript-eslint` 要求 < 6.1，因此未用 7.x）      |
-| 后端   | Node.js + Express                                                    | ≥ 20.19 / 5.2                                              |
-| ORM    | Prisma + driver adapter                                              | 7.10（+ `@prisma/adapter-libsql`，切 MySQL 用 `-mariadb`） |
-| 实时   | Socket.IO                                                            | 4.8                                                        |
-| 认证   | jsonwebtoken + bcryptjs                                              | 9.0 / 3.0                                                  |
-| 校验   | zod                                                                  | 4.6                                                        |
-| Web 端 | Vue + Vite + Element Plus + Pinia + Vue Router + Axios               | 3.5 / 8.3 / 2.14 / 4.0 / 5.3 / 1.20                        |
-| 客户端 | Electron + Vue + Element Plus + Pinia + Socket.IO Client + IndexedDB | 44.3 / 3.5 / 2.14 / 4.0 / 4.8                              |
-| 插件   | .NET 8 / C# + Avalonia（ClassIsland 插件 API 2.0）                   | net8.0                                                     |
-| 打包   | electron-builder（nsis / portable）+ NSIS                            | 26.15                                                      |
-| 文档站 | docfx                                                                | 2.81                                                       |
 
-## 目录结构
+| 路径                                          | 职责                                        |
+| --------------------------------------------- | ------------------------------------------- |
+| `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 构建时拼接              |
 
-```
+## 模块与数据流
-class-helper/
-├── package.json                 # 根脚本（dev / build / db:* / verify:* / dist:* / docs:* / icons）
-├── pnpm-workspace.yaml          # workspace 定义 + allowBuilds（pnpm 11 依赖构建白名单）
-├── tsconfig.base.json           # 共享 TS 基础配置（ESM + NodeNext + strict）
-├── eslint.config.mjs            # ESLint 扁平配置（TS + Vue）
-├── .prettierrc.json             # 单引号 / 110 列 / LF / 尾逗号
-├── build/classhelper.{png,ico}  # **图标源**（设计导出、手工放入）；pnpm icons 从它派生其余全部图标
-├── scripts/
-│   ├── use-database.mjs         # SQLite ⇄ MySQL provider 切换助手
-│   ├── generate-icons.mjs       # 启动 Electron 跑 icons/render.cjs（= pnpm icons）
-│   ├── icons/render.cjs         # 把 classhelper.png 重采样成各端图标（CommonJS）
-│   ├── version.mjs              # 版本号单一来源的读写与一致性校验（= pnpm version:*）
-│   ├── dist-server.mjs          # 服务端 + Web 管理端打包（组装运行时 → NSIS 安装程序）
-│   ├── verify-packaged.mjs      # 对打包后 / 已安装的客户端 EXE 复跑冒烟
-│   ├── lib/                     # electron-env / node-runtime / smoke-class
-│   ├── nsis/server-installer.nsi# 安装程序脚本模板（版本号由 dist-server 注入）
-│   └── ui-smoke/                # Web 管理端 UI 真实点击回归（Electron 驱动）
-├── deploy/                      # 生产部署：Dockerfile / docker-compose{,.sqlite}.yml / nginx.conf
-│   ├── install.sh               # Linux 一键安装器（TUI；native/docker 双形态；自带 --check 体检）
-│   ├── classhelper              # 运维命令本体（软链 /usr/local/bin/classhelper）
-│   ├── verify-linux.sh          # Linux 安装/改密/备份/升级/回滚验收（自统计 N/N 项）
-│   ├── tools/admin-cli.mjs      # 离线账号工具（改密、列账号、SQLite 一致性快照）
-│   ├── classhelper.service      # systemd 单元模板
-│   └── package.runtime.json     # 运行时依赖清单（安装包 / 容器 / Linux 部署共用）
-├── docs/                        # **文档站**（docfx 项目，发布到 GitHub Pages）
-│   ├── docfx.json               # docfx 配置
-│   ├── toc.yml                  # 顶栏导航；各子目录各有一份 toc.yml 作为侧栏
-│   ├── index.md                 # 首页
-│   ├── get-started/ app/ management/ dev/   # 四个章节
-│   ├── templates/classhelper/   # docfx 模板覆盖（_master.tmpl + public/main.css + 图标）
-│   ├── images/                  # 展示图：文档站 / README / 官网共用的同一份（1× 逻辑像素）
-│   ├── screenshots/             # 回归测试留档的截图（island / client / web-mobile / classisland），页面不展示
-│   ├── build.mjs                # 构建入口（注入版本号与 404 的 base）
-│   ├── serve.mjs                # 本地预览（:5181）
-│   └── _site/                   # 构建产物（gitignore）
-├── website/                     # 产品官网（纯静态，无构建；node website/serve.mjs 本地预览）
-│   └── assets/{styles.css,motion.js,main.js,icon.png,shots/}
-└── packages/
-    ├── shared/                  # 三端共享：类型契约、常量、权限矩阵、动效令牌、工具函数
-    │   └── src/{types,constants,permissions,motion,island-layout,utils,index}.ts
-    ├── server/                  # 后端服务
-    │   ├── prisma/schema.prisma # 数据模型（24 个 model，只有一份，切库改 provider）
-    │   ├── prisma/migrations/   # 迁移历史（10 个）
-    │   ├── prisma/seed.ts       # 种子数据（会清空业务表后重建演示数据）
-    │   ├── scripts/             # verify-e2e.mjs / verify-classisland.mjs / apply-column-migrations.cjs
-    │   └── src/
-    │       ├── app.ts           # Express 装配（探针 + 限流 + 模块挂载 + 静态托管 + 兜底）
-    │       ├── index.ts         # 启动入口（自检 + HTTP + Socket.IO + 优雅退出）
-    │       ├── config/env.ts    # 环境变量校验（zod）+ 生产配置自检
-    │       ├── lib/             # access(RBAC) / snapshot(全库 JSON 快照) / db / db-bootstrap /
-    │       │                    #   session / web-static / http / jwt / logger / mappers / version …
-    │       ├── tools/apply-snapshot.ts  # 跨库迁移的子进程入口
-    │       ├── middleware/      # auth / error / validate / security(helmet + 限流 + 耗时日志)
-    │       ├── realtime/        # socket.ts（房间）+ bus.ts（事件总线）
-    │       └── modules/         # 15 个功能模块 + registry.ts（模块注册表）
-    ├── classisland-plugin/      # ClassIsland 联动插件（.NET 8 / C#，独立于 pnpm workspace）
-    │   ├── manifest.yml
-    │   ├── src/Plugin.cs
-    │   ├── src/Services/        # BridgeService / ScheduleMapper / ClassPlanWriter /
-    │   │                        #   ClassHelperNotificationProvider
-    │   ├── src/Views/           # BridgeSettingsPage.axaml（Avalonia 设置页）
-    │   └── src/Interop/ClassHelperClient.cs   # HTTP 客户端 + 逐字段对齐服务端 zod 的 DTO
-    ├── web-admin/               # Web 管理端（Vue 3 + Vite + Element Plus + PWA）
-    │   └── src/{api,stores,router,layouts,views,components,composables,styles}
-    └── desktop-client/          # 桌面客户端（Electron + Vue 3）
-        ├── electron-builder.yml
-        ├── scripts/{build-main,dev,smoke,dist-win,check-bundle-secrets}.mjs
-        └── src/
-            ├── main/            # 主进程：窗口 / 单实例 / 配置持久化 / 托盘 / 灵动岛 / 冒烟
-            ├── preload/         # contextBridge 安全桥（index.ts + island.ts）
-            ├── island/          # 灵动岛渲染进程（独立透明置顶窗口）
-            ├── types/desktop.d.ts   # 主进程 ↔ 渲染进程契约
-            └── renderer/        # 渲染进程：api / stores / cache / router / views / island
-```
 
-## 模块化设计
+功能模块使用 `*.module.ts` 路由、`*.schemas.ts` 校验、`*.service.ts` 业务；新增/下线改 `registry.ts`。
+注册表包含教学业务、课件、日课表/时间表/群组、权限、客户端、系统、AI、升级和数据管理模块。
+路由与模块总数直接读取注册表，不在文档复制另一份数组。
 
-后端每个功能是一个独立目录，统一契约：
+教师在 Web 提交 → 服务端校验权限、班级和科目范围 → 写数据库 → 事件总线按房间广播 → Web/客户端刷新。
+客户端先维护 IndexedDB 缓存，断网读取缓存；主窗口通过 preload 与主进程通信，主进程管理唯一原生岛窗口。
+课件先流式上传到服务端文件目录，再由客户端下载、验摘要并独立回执。
 
-```ts
+客户端统一更新由服务端缓存安装包、校验设备权限并通过心跳下发。客户端下载并校验 SHA256 后，
-// packages/server/src/modules/registry.ts（当前 21 个模块）
+把安装交给独立的 Windows 原生助手；助手从本机 `updates` 目录运行，再次验包并确认就绪，
-export const apiModules: ApiModule[] = [
+主进程复核更新策略后才退出。助手等待旧进程结束、执行安装并检查安装版的新版本及启动状态，
-  authModule,
+失败写入 `install-result.json` 并尝试恢复客户端；成功仍以新版心跳为最终回执。
-  aiModule, // 大模型助手（只解析不落库，见 docs/dev/api.md）
+排障日志为同目录下的 `install-helper.log`。Windows 构建使用系统 .NET Framework 编译器生成助手，
-  classesModule,
+教室机运行时不需要安装开发工具；助手与安装包均随客户端构建，不能只替换主进程 JS。
-  coursesModule,
-  schedulesModule,
-  homeworksModule,
-  notificationsModule,
-  callsModule,
-  importsModule,
-  integrationsModule,
-  gradesModule,
-  studentsModule,
-  teachersModule,
-  archivesModule,
-  termModule,
-  dashboardModule,
-  databaseModule, // 数据库管理（仅管理员）
-  updateModule, // 更新检查 + 客户端安装包缓存与统一下发
-  permissionsModule, // 权限组管理
-  clientsModule, // 客户端设备心跳 / 远控命令
-  systemModule, // 开发者模式 / 开机自启 / 运行诊断
-].filter((module) => module.enabled !== false);
-```
 
-- **新增功能**：新建 `modules/<name>/`（`*.schemas.ts` 校验、`*.service.ts` 业务、`*.module.ts` 路由），
+更新专项验证使用 `pnpm verify:update-download`、Windows 下的 `pnpm verify:update-installer`。
-  在 registry 里加一行即可，`app.ts` 不用改；
+显式执行 `pnpm verify:client-update:real` 会创建临时数据库、班级和独立应用标识，真实安装并升级
-- **下线功能**：删掉那一行，或把 `enabled` 置为 `false`，接口立即从路由表消失；
+测试副本，再卸载测试安装，报告保存在 `.cache/client-update-real/`；它不属于普通冒烟，
-- **实时推送解耦**：业务模块只调 `realtime/bus.ts` 的 `emitToClass/emitToUser`，不直接依赖 Socket.IO 实例；
+不会使用真实班级或桌面自动化，也不修改根版本号。
-- **共享契约**：所有 DTO 与类型集中在 `@classhelper/shared`（改完要 `pnpm build:shared`），三端共用。
+传入 `--portable --unicode-paths --prefix-version` 可覆盖便携运行转安装版、中文空格路径和带 `v` 的目标版本号。
 
-## 几条贯穿全局的硬约定
+## 工程边界
 
-这些都是踩过坑之后固化下来的，改代码前值得先看（完整版在 `AGENTS.md`）：
+- 三端契约只放 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)。
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| **统一响应与校验**           | 用 `lib/http.ts` 的 `sendOk/sendCreated`，用 `middleware/validate.ts` 挂 zod，错误交给 `middleware/error.ts` |
-| **功能级准入看权限键**       | 路由挂 `requirePermission('…')` / `requireAnyPermission(…)`，角色只是默认模板（`ROLE_DEFAULT_PERMISSIONS`）—— 见 `docs/dev/permissions.md` |
-| **权限判在服务层**           | 权限组只管功能级；班级维度与科目维度仍用 `lib/access.ts` 的断言（`assertCanManageSubjectContent` 等），**权限组不可覆盖** —— 前端隐藏 ≠ 权限 |
-| **周一为新一周的第一天**     | 周次口径唯一：`resolveCurrentWeek(TERM_START_DATE, now, MAX_TERM_WEEK)`                                      |
-| **作业按 `assignDate` 归类** | 用 `createdAt`（UTC）会在晚上把作业算到第二天                                                                |
-| **新增实时事件要改三处**     | 服务端 bus/socket、Web 端订阅、客户端订阅（灵动岛也依赖）                                                    |
-| **跨桥接只传纯数据**         | 传 Vue 的 `ref.value` 会在进入 preload 之前就抛 `could not be cloned`                                        |
-| **桌面端产物里不得有凭据**   | asar 可直接解包；构建有 `check-bundle-secrets` 门禁                                                          |
-| **图标只有一个图形源**       | 别改 `scripts/icons/` 的派生逻辑，换图标就换 `build/classhelper.{png,ico}`                                   |
-| **前端不写死颜色**           | 深色主题靠语义令牌，写死的颜色在深色下会露馅                                                                 |
 
-## 本地开发
+## 开发启动
 
 ```bash
 pnpm install
-cp packages/server/.env.example packages/server/.env   # 至少改 JWT_SECRET
+# 复制 packages/server/.env.example 为 .env，并配置独立 JWT_SECRET 与数据库
-pnpm db:generate && pnpm --filter @classhelper/server db:deploy
+pnpm db:generate
-pnpm build:shared        # 必须先构建 shared，否则后续全部 ERR_MODULE_NOT_FOUND
+pnpm --filter @classhelper/server db:deploy
-pnpm db:seed             # 演示数据（会清空业务表）
+pnpm build:shared
-pnpm dev                 # shared watch + 后端 4000 + Web 端 5173
+# 只有明确需要重建演示数据时才运行 pnpm db:seed（会清空业务表）
+pnpm dev
 ```
 
-常用命令与端口见[安装服务端](../get-started/server.md)；验收脚本见[验收与测试](testing.md)。
+后端 4000、Web dev 5173、桌面 dev 5174、官网 5180、文档预览 5181。
+生产服务端托管已构建的 Web 管理端；详见[安装服务端](../get-started/server.md)和[验收](testing.md)。

docs/dev/classisland-plugin.md

@@ -1,146 +0,0 @@
----
-title: ClassIsland 插件
-description: 联动插件的契约、镜像为什么要带节次时间、上课时段暂存，以及部署与调试。
----
-
-# ClassIsland 插件
-
-源码在 `packages/classisland-plugin/`，是一个 **.NET 8 / C#** 的 ClassIsland 插件
-（ClassIsland 插件 API 2.0）。它**独立于 pnpm workspace**，不参与 `pnpm install`。
-
-## 三条链路
-
-```
-ClassIsland（教室机器）
-    │  ① 上报：状态 + 课表 + 节次时间（每次上报顺带取回一条待弹提醒）
-    ▼
-/api/integrations/classisland/report      ← X-ClassIsland-Token（设备令牌，非 JWT）
-    │
-    │  ② 下发：老师在 Web 端发提醒 → 落库 → 插件下次上报时取回 → ClassIsland 全屏弹出 → ack
-    ▼
-/api/integrations/classisland/pending、/ack
-
-    │  ③ 镜像（可选）：服务端把本班课表下发，插件在 ClassIsland 里新建一份档案课表
-    ▼
-/api/integrations/classisland/class-plan
-```
-
-## 为什么走 HTTP 而不是 IPC
-
-ClassIsland 的跨进程 IPC 数据质量不足以还原课表。插件内部**直接读**
-`ILessonsService`（课程状态）与 `IProfileService`（档案课表）最准。
-
-与后端之间用「**上报即拉取**」：每次上报的返回值里顺带带一条待弹出的提醒 ——
-插件因此**不需要 WebSocket 依赖**，故障面更小，而且**上报间隔本身就是心跳**。
-
-提醒是**轮询取回**的（默认最多 10 秒延迟，设置页「提醒轮询间隔」可调到 5 秒）。
-
-## 设备令牌
-
-- 令牌是**设备级**的，不是用户级；
-- 插件在本机保存明文，服务端只存 **sha256** 与一个前缀提示（`chci_xxxxxxxx`）用于人眼识别；
-- 同一班级下按 `deviceKey`（机器码）唯一 —— 插件重装后带同一 `deviceKey` 会**自动重绑**到原记录，
-  不会在设备列表里堆重复项；
-- 关闭设备的「启用」开关后，该设备的上报与下发一律 403。
-
-## 提醒的排队规则
-
-| 提醒类型                                               | 上课时段                     | 下课 / 放学 |
-| ------------------------------------------------------ | ---------------------------- | ----------- |
-| 通知类（`kind=notification`：通知发布页 / 联动页下发） | **暂存不弹**                 | 自动补弹    |
-| 主动通知：紧急提醒、**叫人**（`kind=call`）            | **立刻弹**（老师正在等学生） | 立刻弹      |
-
-插件侧的实现在 `ClassHelperNotificationProvider`（`_deferred` + `FlushDeferred`，订阅课程事件）；
-客户端侧的实现在 `renderer/island/bridge.ts`。**改这条规则要两端一起改。**
-
-暂存期间**不回执**，所以服务端会一直保留着待提醒；`ClassIslandPush.expiresAt` 到期后不再补发
-（避免学生几天后突然弹出旧提醒）。
-
-## 镜像：为什么必须带 `startTime` / `endTime`
-
-ClassIsland 的 `ClassPlan.Classes[i]` **强制与时间表里第 i 个 `TimeType == 0`（上课）的时间点对齐**。
-
-所以镜像下发时，每一条课目都要带上自己的 `startTime` / `endTime`。
-
-> **少一个时间点，整份课表就会错位** —— 而且表现为"课表看着有内容、每节课都对不上"，
-> 极难排查。这是插件契约里最容易踩的坑。
-
-另外镜像进 ClassIsland 的课表还要**带课间**：每两节之间补一段（上一节下课 → 下一节上课），
-**最后一节之后不补**（放学）。实现见 `ClassPlanWriter.BuildTimeLayout`（自己按课目时间算），
-服务端合成节次时间表用的是同一口径。
-
-## 上报课表：单向还是双向
-
-**双向对齐**。插件每次全量上报时，服务端只清理「`source='classisland'` 且本次未再上报」的行：
-
-- 老师在 ClassIsland 里删掉 / 挪动一节 → 小助手这边跟着同步；
-- 老师在小助手这边手排的课 → **一律不删**。
-
-merge 的去重键是「星期 + 开始时间 + 单双周」。导入时**不要覆盖 `weekStart` / `weekEnd`** ——
-插件上报契约里没有周次范围，硬写"整学期"会把老师设的「第 1~10 周」抹掉。
-
-## 单双周的映射
-
-ClassIsland 的 `WeekCountDiv` / `WeekCountDivTotal` ⇄ 本项目的 `ALL / ODD / EVEN`，
-走 `@classhelper/shared` 的 `weekParityFromDiv` / `weekDivFromParity` ——
-**服务端与插件共用同一份语义**，两边不会各算各的。
-
-## 代理：本地地址强制直连
-
-`ClassHelperClient` 里有一个 `LocalAwareProxy`：对本地 / 内网地址**强制直连**，
-不走系统代理。
-
-原因：教室机器上如果开了系统代理，填好令牌后表现为"立刻 HTTP 404"（其实是代理返回的错误页）。
-`pnpm verify:classisland-plugin` 有 4 项断言盯着这段逻辑，别删。
-
-## 构建、打包与验收
-
-```bash
-pnpm build:classisland-plugin    # 编译（.NET 8；缓存与临时目录自动指到仓库内 .cache/）
-pnpm dist:classisland-plugin     # 打包 .cipx 并归集到 releases/classisland-plugin/<版本>/
-pnpm verify:classisland-plugin   # 静态契约校验（不需要 .NET，不需要服务端）
-```
-
-`verify:classisland-plugin` 会逐项校验：清单一致性、注册完整性、
-**C# DTO ↔ 服务端 zod 与路由的字段对齐**，以及已修复坑的护栏。
-
-### 那个预期内的编译警告
-
-全量编译会有 **1 个警告 `AVLN3001`**：设置页只有 DI 构造函数、没有公开无参构造。
-本插件走的是编译期 XAML + ClassIsland 的 DI 实例化，**加个无参构造反而会把 DI 弄坏**。
-别为了消警告去改它。
-
-## 部署到教室机器
-
-```powershell
-# 1) 完全退出 ClassIsland（它会锁住 DLL）
-Get-Process ClassIsland.Desktop | Stop-Process -Force
-# 2) 覆盖插件 DLL（**不要覆盖 Settings.json**，那里存着服务器地址与设备令牌）
-Copy-Item packages\classisland-plugin\bin\Release\ClassHelper.ClassIslandPlugin.dll `
-          D:\Classisland\data\Plugins\classhelper.classisland.bridge\ -Force
-# 3) 重新启动
-Start-Process D:\Classisland\ClassIsland.exe -WorkingDirectory D:\Classisland
-```
-
-改配置要在 **ClassIsland 退出时**改：运行中改会被内存里的副本随时回写覆盖。
-
-### 读日志要用 GBK
-
-.NET 的控制台输出是**系统 ANSI（GBK）**编码。用 UTF-8 读会变成乱码，
-**中文关键字一条都搜不到**（只能搜到 ASCII 的类名）：
-
-```powershell
-[System.IO.File]::ReadAllLines($path, [System.Text.Encoding]::GetEncoding(936))
-```
-
-日志文件被运行中的进程占用时，先 `Copy-Item` 一份再读。
-
-## 真机验收链路
-
-`pnpm verify:classisland`（需要后端在跑）会真的走一遍：设备令牌 → 上报 → 提醒下发与回执 →
-镜像契约 → 幽灵行清理。
-
-> 这个脚本开头会先**抽干本班的历史积压提醒**。因为待提醒接口是「本班全部未确认提醒，
-> 按时间升序取前 20 条」，而其他冒烟会真的往演示班发通知 —— 攒够 20 条之后，
-> 本脚本刚发的提醒会被挤出窗口，表现为"待提醒里找不到刚发的那条"，跟代码对不对毫无关系。
-> **别把那个 drain 删掉。**

docs/dev/data-model.md

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

docs/dev/implementation.md

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

docs/dev/index.md

@@ -8,12 +8,11 @@ description: ClassHelper的架构、接口、数据模型、权限、动效层
 ClassHelper是一个 **pnpm monorepo**，一份代码产出四个交付物：
 
 | 交付物     | 位置                      | 形态                                                            |
-| -------------------- | ----------------------------- | --------------------------------------------------------------- |
+| ---------- | ------------------------- | --------------------------------------------------------------- |
 | 后端服务   | `packages/server`         | Express 5 + Prisma 7 + Socket.IO，接口前缀 `/api`               |
 | Web 管理端 | `packages/web-admin`      | Vue 3 + Vite + Element Plus（教师 / 管理员用，PWA 可安装）      |
 | 桌面客户端 | `packages/desktop-client` | Electron + Vue 3（ClassHelper 班级端 / 教室机器，含灵动岛浮窗） |
 | 共享契约   | `packages/shared`         | 三端共用的类型 / 常量 / 权限 / 工具函数                         |
-| ClassIsland 联动插件 | `packages/classisland-plugin` | .NET 8 / C#（**独立于 pnpm workspace**，不参与 `pnpm install`） |
 
 核心链路：
 
@@ -26,7 +25,6 @@ ClassHelper是一个 **pnpm monorepo**，一份代码产出四个交付物：
         ▼
  Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI（含灵动岛）
 
-ClassIsland（教室机器）──► 联动插件 ──► /api/integrations/classisland/*（设备令牌鉴权）
                                   ▲                          │
                                   └──── 老师下发的提醒 ◄──────┘
 ```
@@ -36,20 +34,18 @@ ClassIsland（教室机器）──► 联动插件 ──► /api/integrations/
 | 页面                                         | 内容                                             |
 | -------------------------------------------- | ------------------------------------------------ |
 | [架构总览](architecture.md)                  | 目录结构、技术栈、模块化设计、几条贯穿全局的约定 |
-| [REST API](api.md)                           | 全部接口一览（方法 / 路径 / 权限）               |
+| [REST API](api.md)                           | 接口分组、常用路径与权限边界                     |
 | [实时事件（Socket.IO）](realtime.md)         | 事件清单、房间规则、新增事件要改哪三处           |
-| [数据模型](data-model.md)                    | 24 张表、迁移历史、跨库约定                      |
+| [数据模型](data-model.md)                    | 模型职责、迁移与快照边界                         |
 | [角色与权限](permissions.md)                 | 权限矩阵与实现位置                               |
 | [动效层与主题](motion.md)                    | beUI 令牌、CSS `linear()` 弹簧、深色主题         |
-| [ClassIsland 插件](classisland-plugin.md)    | 插件契约、镜像为什么要带 `startTime`、部署与调试 |
 | [灵动岛设计令牌](winisland-design-tokens.md) | 岛逐项的几何 / 配色 / 排版 token                 |
-| [验收与测试](testing.md)                     | 五套验收脚本怎么跑、哪些用例是脆弱的             |
+| [验收与测试](testing.md)                     | 隔离验收、后台冒烟与显式视觉模式                 |
 | [版本迭代与发布](release.md)                 | 改版本号、出安装包、发 Release 的完整流程        |
 
 ## 仓库里另外两份文档
 
-- **[完整参考](../reference.md)** —— 产品说明书 + 验收对照表（原 README 全文），
+- **[功能与源码索引](../reference.md)** —— 各帮助章节与源码入口的统一索引；功能行为在对应章节维护，按源码核验。
-  功能行为的**权威来源**；仓库首页那份 README 是精简后的门面页，细节都在这里。
 - **[`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md)** ——
-  写给 AI 编码代理的工程约定与本机踩坑记录，**改代码前必读**。
+  工程约定与开发环境注意事项，**改代码前必读**。里面每一条硬约定都对应一处容易踩空的地方，
-  里面每一条硬约定都对应一次真实的翻车，比代码注释更值得先看一遍。
+  规则与实际实现冲突时应查源码并同步修正。

docs/dev/motion.md

@@ -69,15 +69,13 @@ DOM 注入与 Vue 组合式函数在两端各自的 `composables/motion.ts` 里
 | 页面内容              | `.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 规则不直接替代岛自身设置。
-所以岛用 `--ch-ease-out` 这类单调曲线，壳的物理仍归它自己的 `src/island/spring.ts`（WinIsland 移植）。
-**不要拿 beUI 的 `SPRING_*` 去换**。
 
 另外岛的 `:hover` 规则必须关在 `@media (hover: hover) and (pointer: fine)` 里 ——
 教室触摸屏的"幽灵 hover"会让点过「知道了」的按钮永远高亮。

docs/dev/permissions.md

@@ -1,158 +1,76 @@
 ---
 title: 角色与权限
-description: 权限矩阵、科目维度的收口规则，以及"前端隐藏 ≠ 权限"这条纪律。
+description: 能力目录、岗位模板、分配范围与业务关系的授权契约。
 ---
 
 # 角色与权限
 
-## 矩阵在哪
+授权依次检查能力、该能力的数据范围、数据行上的业务关系。服务端统一入口为 `lib/authz/`，路由预检不能替代服务断言。共享目录 `PERMISSION_META` 提供分类、风险、关系提示、合法范围、标签和默认角色；完整键目录读取源码，不在文档维护固定数量。
 
-**唯一一份**在 `packages/shared/src/permissions.ts`：
+## 身份与模板
 
-- 后端 `lib/access.ts` 复用它做断言；
+| 主体                 | 生效能力                                           |
-- 两端前端用它隐藏入口；
+| -------------------- | -------------------------------------------------- |
-- 验收脚本按它逐条断言。
+| ADMIN                | 固定拥有全部目录键及全校范围，忽略权限组           |
+| TEACHER              | 显式分配模板的可分配能力并集；管理员专用键永久无效 |
+| 未显式分配的 TEACHER | 数据库教师默认模板与固定 TEACHING 范围             |
+| CLASS_DEVICE         | 空集；接口明确允许班级端并校验本班关系             |
 
-所以不存在"前端一套后端一套"。改权限就改这一个文件（改完记得 `pnpm build:shared`）。
+学生是 Student 名单记录，没有账号。HEAD/SUBJECT 是班主任和科任关系，级长/部长是岗位模板，不增加 User.role。权限管理只允许 ADMIN；旧 ADMIN 默认模板保留存储但隐藏、忽略。
 
-## 角色判定
+`PermissionGroup` 保存能力和新分配的建议范围，`UserPermissionGroup` 保存实际 `scope/scopeValue`。模板改建议范围不会改变已有分配；模板改能力会影响其成员。同一模板可分配不同范围，多条分配按键取并集。空分配恢复默认模板，界面不会将未分组成员自动转换成显式默认组。
 
-角色只有三种，**没有 `STUDENT`** —— 学生不是账号（见[数据模型](data-model.md)）。
+## 能力目录与范围
-班级内的角色由「账号角色 + 与该班级的关系」共同决定：
 
-| 角色                        | 判定方式                                   | 可见范围                             |
+能力分为管理员专用、班级级、组织只读。管理员专用能力包括组织与账号维护、权限/系统/数据库、全局周次、全校时间表、升级归档、安装包管理等；具体清单以 `PERMISSION_META.kind` 为准。`teacher:read` 和 `update:check` 为组织只读，忽略班级范围。其余班级级能力按分配范围求值。
-| --------------------------- | ------------------------------------------ | ------------------------------------ |
-| `ADMIN` 管理员              | `User.role = ADMIN`                        | 全部班级                             |
-| 班主任 `HEAD`               | `Class.teacherId === 当前用户`             | 本班                                 |
-| 科任老师 `SUBJECT`          | 该班存在 `Course.teacherId === 当前用户`   | 被任课的班级                         |
-| `CLASS_DEVICE` 班级端       | 班级码 + 班级密码登录（`classSession`）    | 本班（代全班读写个人数据）           |
-| `NONE`                      | 与这个班没有任何关系                       | 什么都看不到                         |
 
-判定函数是 `resolveClassRole()`。「科任」的判定源是 **`Course`**（班级 + 科目 + 教师），
+| 范围     | 语义                       |
-不是那张已经没有的 `ClassTeacher` 协作表。
+| -------- | -------------------------- |
+| TEACHING | 本人担任班主任或任课的班级 |
+| HEAD     | 仅本人担任班主任的班级     |
+| GRADE    | 指定一个年级               |
+| DIVISION | 指定多个年级               |
+| ALL      | 全校                       |
 
-## 权限矩阵
+`parsePermissionScope` 统一校验范围。GRADE/DIVISION 必须选择已有年级或升级计划中的年级，范围值按逗号分隔、去重排序；其余范围值必须为空串。旧 SELF_CLASS 仅在迁移和旧快照恢复中映射为 TEACHING/HEAD，不是运行时枚举。
 
-| 操作                                                     | 管理员 |    班主任    | 科任老师 | 班级端 |
+`loadAuthPrincipal` 在请求主体上缓存只读能力和分配快照，没有可变的“当前权限键”。`classIdsFor(user, key)` 和 `classWhere(user, key)` 强制传键，无键或无授权返回空集合；不会合并其他能力的范围。`classWhere` 过滤 Class 表主键，下游子表使用明确的 classId 条件。
-| -------------------------------------------------------- | :----: | :----------: | :------: | :----: |
-| 班级创建 / 修改 / 删除                                   |   ✅   |      ❌      |    ❌    |   ❌   |
-| 分配班主任与各科任课老师                                 |   ✅   |      ❌      |    ❌    |   ❌   |
-| 学生名单管理（增删 / 导入 / 调班 / 转出）                |   ✅   | ✅（仅本班） |    ❌    |   ❌   |
-| 教师录入（新建 / 导入名单 / 修改密码）                   |   ✅   |      ❌      |    ❌    |   ❌   |
-| 毕业归档 / 学年升级 / 学期周次                           |   ✅   |      ❌      |    ❌    |   ❌   |
-| 数据库管理（备份 / 导入导出 / 一键切换）                 |   ✅   |      ❌      |    ❌    |   ❌   |
-| 课表管理（增删改 / 时间配置导入）                        |   ✅   | ✅（仅本班） |    ❌    |   ❌   |
-| 布置作业（**自己任教的科目**）                           |   ✅   | ✅（本班）   |    ✅    |   ✅   |
-| 叫人 / 发布通知                                          |   ✅   |      ✅      |    ✅    |   ✅   |
-| 成绩录入 / 修改 / 导入（**自己任教的科目**）             |   ✅   | ✅（本班）   |    ✅    |   ❌   |
-| 查看本班成绩汇总                                         |   ✅   |      ✅      |    ✅    |   ✅   |
-| 按学号查询学生成绩明细                                   |   ✅   |      ✅      |    ✅    | 需班级开关 |
-| 查看 ClassHelper 班级端在线状态                          |   ✅   |      ✅      |    ✅    |   ❌   |
-| 班级密码 / 班级码维护（`PATCH /classes/:id/class-account`） |   ✅   |      ❌      |    ❌    |   ❌   |
 
-## 科目维度的收口（本次重构的核心规则）
+## 关系与写入
 
-作业与成绩不是"凡是能进这个班就能改"，而是**再按科目收一道**：
+| 操作                                          | 功能与关系                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------------------- |
+| 建班/删班/届别班号、班主任/任课分配、教师账号 | 管理员专用，记录审计；最后一个管理员不可降级或删除                               |
+| 班级账号                                      | class:account + 本班班主任，管理员例外；班级码只给班主任或管理员                 |
+| 班级学期设置/班级周次                         | class:settings + 本班班主任，管理员例外                                          |
+| 名单、日课表与课程写入                        | 对应写键；TEACHING/HEAD 要求班主任，显式年级/部/全校范围允许范围内维护           |
+| 学生/课表导入                                 | 导入键与相应写键同时满足；先校验全部班级再写，学生及任课导入使用事务             |
+| 班级时间表写入                                | schedule:write + 本班班主任；按存储 classId 校验，所有引用班级也要校验           |
+| 全校时间表、全局周次                          | 管理员；班级设置使用独立接口                                                     |
+| 作业/成绩写入                                 | assertContentWrite；有科目要求该科任教，无科目要求班主任；原科目与目标科目都检查 |
+| 作业提交/未交名单                             | homework:write + 同样的科目关系；班级端明确允许本班作业                          |
+| 通知/叫人                                     | 发布能力和范围，再检查班主任/任课关系；班级端限本班                              |
+| 通知删除                                      | notification:delete + 发布者/班主任/管理员                                       |
+| 课件                                          | 本人文件、对应功能范围与本人授课班级共同约束，不赋予班主任同事文件访问权         |
 
-| 情形                                    | 谁可以写                                   |
+ALL 也不能替代班主任、任课、发布者关系，只有 ADMIN 无条件绕过关系。班级端可代录作业，不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接，不能因事务路径省略授权。
-| --------------------------------------- | ------------------------------------------ |
-| 管理员                                  | 全部                                       |
-| 挂了科目（`courseId` 有值）             | **该科的任课老师**（`Course.teacherId`）   |
-| 没挂科目（`courseId` 为空）             | 本班**班主任**                             |
-| ClassHelper 班级端                      | 只有**作业**可以（老师在教室随手录一条）；**成绩不给** |
 
-于是：班主任若不教这一科，就改不了这一科的作业与成绩 —— 这正是需求
+成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后，本班设备仍可获得集体聚合，个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护，服务端执行稀疏样本和补集抑制。
-「班主任不自动拥有所有科目作业成绩编辑权，只有同时是该科科任老师时才有该科权限」。
 
-实现在 `lib/access.ts` 的 **`assertCanManageSubjectContent(user, classId, courseId, action, { allowClassDevice })`**，
+## 实时与设备
-作业 / 成绩 / 叫人三处写入统一走它。
 
-## 权限键与权限组（2026-10 起：权限组驱动，角色只是默认模板）
+班级房间为 `class:{id}:{channel}`，事件映射见 `SOCKET_EVENT_CHANNELS`。班级端加入本班全部通道；教师按各域读键及范围加入，core 由 class:read/schedule:read 决定。显式订阅再次校验通道，握手与 HTTP 共用数据库身份加载；权限/账号变更断开旧订阅。
 
-从权限组重构开始，**功能级准入不再看角色，而看权限键**：键目录同样是
+心跳、进度和命令回执只接受 CLASS_DEVICE，deviceKey 必须属于会话班级。远控只排队允许的系统指令，自动化始终假执行。安装包登记/删除使用管理员 client:update；班级推送使用 client:update-push。下载要求本班班级端或有范围的 client:read。版本与文件名在请求校验和路径构造两处拒绝不安全路径段。
-`packages/shared/src/permissions.ts` 的 `PERMISSION_KEYS`（39 个，形如 `domain:action`，
-中文名在 `PERMISSION_LABELS`、分组在 `PERMISSION_CATEGORIES`）。路由上挂的是
 
-```ts
+## 权限页与审计
-requirePermission('notification:publish')      // 需要全部列出的键
-requireAnyPermission('grade:write', 'grade:import')  // 有任意一个即可
-```
 
-**生效规则（四句话）**：
+权限页默认展示成员与范围，每条分配独立选择范围，保存前预览新增/移除能力、每键合并范围、班级列表、混合范围提示、班主任专属提示和风险标记。模板页仅提供可分配能力，旧管理员键显示为停用。组织只读能力标注“不限班级”。路由用 `meta.permission` 检查读取能力；维护页面额外用 `meta.menuActions` 声明可执行动作，动作须在至少一个可读班级生效才显示侧栏、搜索及页签，有部分功能可操作就保留入口。`permissions/me.actionScopes` 结合范围和班主任、任课、发布者关系提供动作班级；班级管理动作另用 `manageScopes`。纯查看页面按读取能力展示，服务端始终做最终判定。
 
-| 账号                                    | 有效权限                                                       |
+学期周次维护入口要求全校周次写能力或至少一个可维护的本班设置范围。非全校维护者进入后默认选择可编辑班级，仍可切换查看授权范围内的其他班级。
-| --------------------------------------- | -------------------------------------------------------------- |
-| `ADMIN`                                 | 全集；其中 `permission:manage` / `system:manage` **不可被剥夺** |
-| `CLASS_DEVICE`（班级端）                | 空集，**不受任何分组影响**（它的能力来自班级维度断言）          |
-| 被分配了权限分组                        | 分组键的**并集**（可以比角色默认更少 —— 这就是"能收权"）        |
-| 没有被分配任何分组                      | 回落到角色默认模板 `defaultPermissionsForRole(role)`            |
 
-默认模板逐条镜像重构前的 `requireRole`，所以"不动分组"= 行为与以前完全一致。
+目录、模板、成员、分配预览和审计的公开契约见[API](api.md)。模板/分配和账号敏感操作写入 PermissionAudit；审计不保存密码明文或哈希。迁移与快照兼容见[数据模型](data-model.md)。
-实现见 `packages/server/src/lib/permissions.ts` 的 `loadEffectivePermissions()`：它**每个请求实时查库**
-（不缓存），因此管理员改完分组**立刻生效**，不需要等令牌过期 —— 与下面「鉴权中间件会回查数据库」是同一个理由。
 
-**管理接口**（`packages/server/src/modules/permissions/`）：
+## 验证
 
-| 方法与路径                        | 权限要求             | 说明                                                     |
+`pnpm check:authz` 扫描旧授权符号和缺少显式键的查询，并接入 lint。`pnpm verify:authz` 使用临时 SQLite 验证接管班级、管理员提权、跨键借范围、科目改挂、跨班时间表/周次/导入、成绩隐私、通道订阅、设备冒用和旧快照等攻击场景。其他专项回归保留生命周期、课表、课件、设备与升级覆盖。验证不触及真实班级、不访问外网、不执行系统指令。
-| --------------------------------- | -------------------- | -------------------------------------------------------- |
-| `GET /api/permissions/me`         | 登录即可             | 当前账号的有效权限与来源（前端据此显示/隐藏入口）        |
-| `GET /api/permissions/catalog`    | `permission:manage`  | 全部权限键（含中文名、分类、默认角色、不可移除标记）     |
-| `GET/POST /api/permissions/groups`、`PATCH/DELETE /groups/:id` | `permission:manage` | 分组 CRUD；内置分组（`builtin=true`）可改不可删 |
-| `GET /api/permissions/users`、`PUT /api/permissions/users/:id/groups` | `permission:manage` | 成员列表与「整组替换」式分配；拒绝给 ADMIN / CLASS_DEVICE 分配 |
-
-**一条不能松的边界**：权限组只管**功能/路由级**准入；**班级维度的科目规则不可被权限组覆盖**。
-换句话说，给某人授了 `homework:write` 只代表"他能进布置作业这条路由"，
-**具体到哪个班、哪个科目**仍然由 `assertCanManageSubjectContent` 判（下一节）。
-否则「班主任能布置别人科目的作业」这个老 bug 会从权限组这条新路重新长出来。
-
-## 实现要点
-
-**路由级只做权限过滤**：`requirePermission('…')`（需要列出的键全有）或
-`requireAnyPermission('…')`（任意一个即可）。改造前这里是 `requireRole('ADMIN','TEACHER')`，
-按键目录里的 `PERMISSION_DEFAULT_ROLES` 逐条映射过来，因此**默认行为没有变化**。
-403 的文案会直接点名缺哪个键：「当前账号缺少「X」权限，请联系管理员在「权限组」里分配」。
-
-**班级维度的判断在服务层**：`src/lib/access.ts` 提供
-
-```
-assertCanManageClasses    / assertCanAssignTeachers / assertCanManageRoster
-assertCanManageSchedule   / assertCanPublishNotification
-assertCanManageGrades     / assertCanManageSubjectContent
-```
-
-**列表数据用 `resolveClassScope()` 收敛**（`classId in [...]`），单条接口直接断言；
-越权一律 403。
-
-**鉴权中间件会回查数据库**（`middleware/auth.ts`）：JWT 校验之后重新读一次账号，
-所以改了角色 / 班级关系会**立即生效**，不用等令牌过期。班级端会话则回查 `Class` 表。
-
-**班级端的成绩查询开关**：`Class.studentGradeQueryEnabled`（默认开启）。
-关闭后班级端调 `GET /grades/student/:studentNo` 一律 403，教师端不受影响 ——
-这就是需求「是否允许学生通过班级端查看本人明细，由教师或管理员开关控制」。
-
-## 前端隐藏 ≠ 权限
-
-前端的隐藏只是"别让人看见入口"：
-
-- 教师登录时侧边栏不显示「班级管理 / 学生管理 / 教师管理 / 毕业归档 / 学期周次 / 数据库管理 / 权限组 / 客户端设备」；
-- 课表页的增删改按钮只对「管理员或本班班主任」显示；
-- 成绩页的录入 / 删除按钮对教师显示（科任也能用，**具体到某一条由后端按科目判定**）。
-
-**门控怎么写的**：路由 `meta.roles` 做粗筛（角色），`meta.permission` 做细筛（权限键）——
-`packages/web-admin/src/router/index.ts` 的 `beforeEach` 会 `await auth.ensurePermissions()`
-再问 `auth.can(key)`（管理员短路为 true），不通过就 **fail-closed** 回仪表盘；
-侧栏菜单项同理带 `permission` 字段（`AdminLayout.vue` 的 `visibleMenuItems`）。
-`auth.ensurePermissions()` 读的就是 `GET /api/permissions/me`。
-
-但这些页面**直接输网址也进不去**（路由 `meta.roles` 会把非管理员挡回仪表盘），
-而且**所有写入请求服务端都会再断言一次**。绕过菜单、绕过前端，一样 403。
-
-> 新增视图时别忘了两处：路由的 `meta.roles` + 服务层对应 service 里的 `assertCanXxx`。
-> 只做其中一个都等于没做。
-
-## 学生没有账号的两个反向约束
-
-1. **学生不能登录，而且根本不存在可以登录的学生账号**。`User` 表里没有学生行，
-   拿学号当账号登录只会得到 401（"工号或密码错误"），连"这个学号存在吗"都探测不出来。
-2. **学生没有任何密码接口**。`POST /students/:id/reset-password` 已删除（调用返回 404），
-   新建学生也不设密码 —— `Student` 表里压根没有那一列。

docs/dev/realtime.md

@@ -1,81 +1,52 @@
 ---
 title: 实时事件（Socket.IO）
-description: 事件清单、房间规则，以及新增一个实时事件要同时改哪三处。
+description: 实际事件与房间、断线恢复和客户端提醒分工。
 ---
 
 # 实时事件（Socket.IO）
 
-## 连接
+连接使用 `io(url, { auth: { token } })`，服务端握手校验 JWT 并与 HTTP 共用数据库身份加载。
+事件与房间定义在 shared 的 `constants.ts`，载荷类型在 shared 的 `types.ts`，以这些契约和发送点为准。
 
-```ts
+## 房间与定向推送
-io(url, { auth: { token } }); // 握手阶段用 JWT 鉴权
-```
 
-客户端断线由 Socket.IO 自动重连。教室机器断线期间的变更，重连后靠各页重新拉取补齐
+| 房间                      | 作用                                               |
-（客户端在检测到服务器恢复时会触发 `onServerRecovered`）；**灵动岛的上课时段暂存通知**由服务端保留、
+| ------------------------- | -------------------------------------------------- |
-下课后补发，不依赖重连。
+| class:{classId}:{channel} | 某班级对应读域的业务广播                           |
+| session:{id}              | 会话定向名；员工 id 为账号 id，班级端 id 为班级 id |
+| role:{role}               | 角色房间名，定义在共享常量                         |
+| teacher:{id}              | 教师房间名，定义在共享常量                         |
+| students                  | 班级端连接的广播房间，代表全班，不是个人学生账号   |
+| teachers                  | 教师和管理员连接的广播房间                         |
 
-## 事件清单
+`realtime/socket.ts` 按域加入授权班级房间，并加入 session/role 与 students/teachers 房间；connected 载荷列出实际已加入房间。
+业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。
+叫人记录属于班级通知，并发送班级广播与班级会话定向事件；学生本身没有连接和个人房间。
 
-事件名定义在 `@classhelper/shared` 的 `SOCKET_EVENTS` —— **不要手写字符串**。
+## 主要事件
 
-| 事件                                  | 方向            | 载荷                                             |
+| 事件                                              | 内容                                                       |
-| ------------------------------------- | --------------- | ------------------------------------------------ |
+| ------------------------------------------------- | ---------------------------------------------------------- |
-| `connected`                           | 服务端 → 客户端 | `{ userId, role, rooms }`                        |
+| connected                                         | `{ sessionId, role, rooms }`                               |
-| `notification:new`                    | 服务端 → 客户端 | `NotificationDto`                                |
+| notification:new / notification:deleted           | 通知新增/撤回；客户端同步列表、缓存和岛队列                |
-| `homework:new`                        | 服务端 → 客户端 | `HomeworkDto`                                    |
+| homework:new / homework:updated / homework:status | 作业新增、修改/删除与完成状态                              |
-| `homework:updated`                    | 服务端 → 客户端 | `HomeworkDto & { deleted?: boolean }`            |
+| grade:updated                                     | 成绩变化通知；载荷按范围与隐私规则发送，客户端按需重新读取 |
-| `homework:status`                     | 服务端 → 客户端 | `HomeworkStatusDto & { classId }`                |
+| schedule:updated / class:updated                  | 课表/班级变化，重新加载对应数据                            |
-| `grade:updated`                       | 服务端 → 客户端 | `GradeDto`                                       |
+| courseware:changed                                | 课件列表/可见范围/推送变化，触发客户端检查                 |
-| `schedule:updated`                    | 服务端 → 客户端 | `{ classId, action, schedule? }`                 |
+| client:release-progress                           | 服务端缓存客户端安装包的进度                               |
-| `class:updated`                       | 服务端 → 客户端 | `{ classId, action }`                            |
+| call:new                                          | 叫人内容，与 notification:new 按同 id 合并去重             |
-| `call:new`                            | 服务端 → 客户端 | 叫人消息（定向到 `user:{studentId}` / 班级设备） |
+| class:join / class:leave / ping                   | 客户端订阅/离开班级、探活；join 重新校验范围               |
-| `classisland:state`                   | 服务端 → 客户端 | `ClassIslandStateEvent`（教室现在上什么课）      |
-| `classisland:notification`            | 服务端 → 客户端 | `ClassIslandNotificationEvent`（提醒已下发）     |
-| `class:join` / `class:leave` / `ping` | 客户端 → 服务端 | 手动订阅班级（服务端二次校验权限）               |
 
-## 房间规则
+事件没有持久离线消息队列保证。重连后由页面和恢复钩子重新拉取业务数据。
+普通通知上课暂存是客户端岛控制器的本机行为，服务端仍即时落库广播；
+断线通知补弹由客户端未读读取逻辑处理，课件未收任务由服务端保存、客户端心跳补领。
+经典/自定义模式的展示差异见[通知与提醒](../app/notifications.md)。
 
-房间名定义在 `SOCKET_ROOMS`：
+## 修改事件
 
-| 房间                  | 谁在里面                          |
+同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。
-| --------------------- | --------------------------------- |
+不要手写事件名；只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。
-| `class:{classId}`     | 这个班的所有在线端                |
-| `user:{userId}`       | 某个用户自己的连接                |
-| `teacher:{teacherId}` | 某个教师                          |
-| `role:{role}`         | 某一角色（`ADMIN` / `TEACHER` …） |
-| `students`            | 全部 ClassHelper 班级端连接                    |
-| `teachers`            | 全部教师端连接                    |
 
-服务端通过 `realtime/bus.ts` 的 `emitToClass` / `emitToUser` 发事件 ——
+## 读域订阅
-**业务模块不直接依赖 Socket.IO 实例**，只依赖事件总线。
 
-## 新增一个实时事件要改三处
+现行班级房间为 `class:{id}:{channel}`。channel 为 core/homework/notification/grade/courseware，事件映射来自 shared 的 SOCKET_EVENT_CHANNELS。旧 `class:{id}` 仅保留兼容名称，生产不订阅。班级端加入本班全部域；教师按对应读键和分配范围加入。`class:join` 接受旧 classId 字符串或 `{classId, channels}`，后者逐通道校验，有任一无权则拒绝整次请求。握手回查账号与角色，权限变更断开旧订阅。
-
-```
-① 服务端    shared/src/constants.ts 的 SOCKET_EVENTS 加常量
-            → business service 调 bus.emitToXxx(...)
-            → realtime/socket.ts 房间映射（如果需要新房间）
-② Web 端    web-admin/src/stores/realtime.ts 订阅
-③ 客户端    desktop-client/src/renderer/stores/realtime.ts 订阅
-            → 灵动岛也依赖它（renderer/island/bridge.ts）
-```
-
-**只改服务端不会报错**，只是前端静静地不更新 —— 所以这三处必须一起改。
-事件名一律取自共享常量，不要手写字符串（拼错一个字就是一个静默失效）。
-
-## 事件到达之后发生什么
-
-以通知为例：
-
-```
-服务端写库 → bus.emitToClass(classId, notification:new)
-   ├─► Web 端 stores/realtime.ts  → 通知列表刷新
-   └─► 客户端 stores/realtime.ts  → 更新内存状态 + 写回 IndexedDB
-                                    └─► island/bridge.ts → pushNotificationToIsland()
-                                          └─► 主进程 IslandController 决定：隐藏 / 胶囊 / 详情
-                                                └─► 灵动岛渲染进程 IslandApp.vue
-```
-
-上课时段的取舍（隐藏还是立即展开）由主进程的 `IslandController` 按当前上课状态决定，
-见[通知与提醒](../app/notifications.md)与[灵动岛](../app/island.md)。

docs/dev/release.md

@@ -1,245 +1,83 @@
 ---
 title: 版本迭代与发布
-description: 改版本号、跑验收、打安装包、发 GitHub Release、发布文档站——一次完整发布的命令清单。
+description: 版本单一来源、本地与发布文件名、验证和发布同步。
 ---
 
 # 版本迭代与发布
 
-## 一条总原则
+日常文档/代码维护不自动改版本。版本唯一修改入口是 scripts/version.mjs；先执行 pnpm version:check。
+正式新发布执行 pnpm version:bump patch|minor|major，指定固定版本的本地重构建保持版本不变。
+版本落点由脚本清单决定，不另维护“文件数/落点数”。
 
-> **版本号按「发布」迭代，不按「提交」迭代。**
+## 构建与验证
-
-日常的 `feat` / `fix` 提交**不动版本号**。只有当你要产出一批安装包、在 GitHub 上开一个 Release 时，
-才走一次完整的版本迭代。理由很实际：安装包、`.cipx`、Docker 镜像 tag、文档站的版本徽标、
-更新检查接口全都按版本号对齐；每次提交都动它，等于每天都在发版，用户那边的「检查更新」就废了。
-
-| 算一次发布                              | 不算                         |
-| --------------------------------------- | ---------------------------- |
-| 攒够一批功能 / 修好一个用户能感知的 bug | 改注释、改文档、重构、加测试 |
-| 要给别人一份新安装包                    | 只在自己机器上跑             |
-| 插件单独发补丁（只动插件第 4 段版本号） | —                            |
-
-## 每次发版必须一起交付的四样东西
-
-打安装包只是其中一件。**少一样都算「发到一半」**：
-
-| #  | 交付物            | 落在哪                                                             | 怎么做                                                       |
-| -- | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
-| ①  | **更新日志**      | GitHub Release 的正文                                               | 手写，草稿放 `releases/ReleaseNotes-<版本>.md`，用 `--notes-file` 发布。别只挂自动生成的列表 |
-| ②  | **Linux 服务端包** | Release 上的 `classhelper-server-linux-x64-<版本>.tar.gz`           | tag 推上去由 CI 构建；**推完去 Actions 确认没红**（见第 7 步）  |
-| ③  | **文档**          | `docs/reference.md`（功能说明 + 验收对照表）与相关章节                | 新增功能补对应小节；改交付形态一并改第 2 章 / 第 7 章          |
-| ④  | **官网与 README** | `website/index.html`、`website/download.html`、`README.md`          | 新功能补进官网功能块与 README 功能清单；版本号由脚本覆盖       |
-
-更新日志的骨架（照 1.2.0 / 1.3.0 那两份写）：
-**一句话定位 → 分节讲功能 → ⚠️ 升级须知（含会自动应用的迁移）→ 验收表 → 产物表**。
-验收表里**只写真跑过的数字**，没跑就直说没跑，不要照抄上一版的。
-
-## 版本号写在哪（14 处 / 12 个文件）
-
-同一个版本号分散在 14 个落点上，**手工改必然漏一处**，而漏掉的那处不会报错：
-
-| 文件                                                             | 内容                               |
-| ---------------------------------------------------------------- | ---------------------------------- |
-| `package.json`                                                   | 单一来源（服务端运行时读它）       |
-| `packages/{shared,server,web-admin,desktop-client}/package.json` | 各包的版本                         |
-| `deploy/package.runtime.json`                                    | 安装包 / 容器里的运行时依赖清单    |
-| `deploy/docker-compose.yml`、`docker-compose.sqlite.yml`         | 镜像 tag 的默认值                  |
-| `packages/classisland-plugin/manifest.yml`                       | 插件清单（四段：`x.y.z.0`）        |
-| `packages/classisland-plugin/src/Services/BridgeService.cs`      | 插件上报的 `PluginVersion` 常量    |
-| `website/index.html` × 3                                         | 官网顶栏徽标 / 首屏芯片 / 页脚     |
-| `website/download.html`（`<meta name="ch-version">`）            | 下载页读不到版本清单时的兜底版本号 |
-
-最后两行值得单独说：官网是**纯静态站、没有构建步骤**，没有哪段代码会去读 `package.json`，
-所以那几处只能靠脚本一起改 —— 漏了的话首页会一直挂着旧版本号（而那是别人看到的第一眼），
-下载页则会给离线访客一串指向**不存在版本**的直链。
-
-所以**改版本号的唯一入口是脚本**：
-
-```bash
-pnpm version:check              # 逐处列出并比对，不一致 exit 1
-pnpm version:bump patch         # 1.1.2 → 1.1.3
-pnpm version:bump minor         # 1.1.2 → 1.2.0
-pnpm version:bump major         # 1.1.2 → 2.0.0
-pnpm version:check              # 再确认一次
-```
-
-脚本按表逐个改写，**任何一处没匹配到或匹配到多处就直接失败退出**，不做"尽力而为"的部分改写。
-
-> 插件版本是 **四段** `x.y.z.0`：前三段跟产品版本走，第 4 段留给"只改插件、不动产品版本"的补丁发布。
-> `--bump` / `--set` 会把第 4 段归零；要单独发插件补丁就手工改那两处（清单 + `BridgeService.cs`）。
-
-## 一次完整的发布
-
-下面这一串命令就是全部流程，逐条照抄即可。
-
-### 1. 改版本号
 
 ```bash
 pnpm version:check
-pnpm version:bump patch
-```
-
-### 2. 本地体检
-
-```bash
 pnpm lint
 pnpm typecheck
 pnpm check:icons
-pnpm docs:check                 # 文档站构建（警告即失败）
+pnpm docs:check
-```
-
-### 3. 跑验收
-
-```bash
-pnpm dev:server                 # 另开一个终端跑着
-
 pnpm verify:e2e
-pnpm verify:classisland
+pnpm verify:v14
-pnpm verify:classisland-plugin
+pnpm verify:courseware
-
+pnpm build:desktop
-pnpm build:desktop && pnpm verify:desktop
+pnpm verify:desktop
-pnpm build && pnpm verify:web
+pnpm --filter @classhelper/web-admin build
+pnpm verify:web:isolated
+pnpm dist:all
+pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe" --offline
 ```
 
-哪一项红了先看[验收与测试](testing.md)的「失败时先别改代码」——
+以上按发布改动范围执行；显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
-里面列了几个已知脆弱的用例，它们红不代表代码坏了。
+完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本，最新包核验完成后按用户要求清理旧归档。
+2026-10-18 工作区清理后，1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
 
-### 4. 打安装包
+## 产物与文件名
+
+| 本地构建产物                                                                | GitHub Release 上传名                      |
+| --------------------------------------------------------------------------- | ------------------------------------------ |
+| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-setup.exe              | ClassHelper-<版本>-x64-client-setup.exe    |
+| releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe           | ClassHelper-<版本>-x64-client-portable.exe |
+| releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe       | ClassHelper-<版本>-x64-server-setup.exe    |
+| releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz | 同名                                       |
+
+Windows 服务端安装包只携带配置占位符，首次安装时生成独立的 JWT 密钥；覆盖升级保留原有 `.env`。`pnpm verify:server-bootstrap` 验证密钥独立性和配置保留，打包后还需在解包副本中复验。
+
+Linux 还需同名 .tar.gz.sha256。正式 Linux 包在 Linux runner 运行 pnpm dist:server:linux；
+Windows 上的交叉构建仅作验证，可能缺目标平台的 Prisma engine。
+构建中间物可再生成，不将 win-unpacked、server staging 或解包副本当交付物保留。
+
+## 更新日志与校验
+
+releases/ReleaseNotes-<版本>.md 维护本批包的功能、升级须知、实际验证范围与文件清单。
+它描述该构建批次，不能把之后的源码功能写成旧包已经包含。
+SHA256SUMS-<版本>.txt 用上传名记录各文件哈希；本地查验必须先按上表映射，不能因为本地文件没带 client/server 后缀就判断丢包。
+可在 PowerShell 对 client/server 安装包运行 Get-FileHash -Algorithm SHA256，将三项实际结果按上传名写入清单。
+不要仅对客户端目录做重定向而漏掉服务端；Linux 行待 CI 完成后同步。
+
+## 发布同步
+
+完成验证和本地更新日志后，检查 diff，按用户授权提交和推送 master；不要把其他未完成改动一并提交。
+将三个 Windows 包复制到独立的 .cache/release-staging/<版本>/，使用上传名，避免通配符混入别的版本。
+先准备当前 Windows SHA256 清单并随 Release 上传。创建 Release 时显式 --target master 或明确提交，说明用 --notes-file。
+ClassIsland 插件已退役，不再上传插件资产。
 
 ```bash
-pnpm dist:all                   # = dist:server + dist:win + dist:classisland-plugin
+# <版本> 和提交均替换为本次实际值
+gh release create v<版本> --target master --title "ClassHelper v<版本>" --notes-file releases/ReleaseNotes-<版本>.md
+gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256SUMS-<版本>.txt
 ```
 
-产物落在 `releases/<组件>/<版本>/`：`安装包/`（交付物）、`构建中间/`（可重新生成）。
+推送 v* tag 触发 release-linux-server.yml，按 tag 检出，在 Ubuntu 构建并上传 Linux 包、独立 .sha256，合并跨组件清单。
-**没有免安装目录** —— 组装/解包出来的那一份是中间物，打包脚本用完就删（见仓库根 `AGENTS.md` §4
+等待 Actions 成功，再下载 Linux 文件和最终 SHA256SUMS 同步回本地；检查清单的 Windows 行仍与本次文件一致。
-「交付产物归集」）。
+如需重跑，可手动运行该 workflow，指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
 
-打完之后**对打包副本再验一次**（开发产物通过 ≠ 用户机器上的副本通过）：
+官网和文档站由 pages.yml 拼装同一个站点：官网根、文档 /docs/。文档版本徽标读根 package.json，
+官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线，分别确认结果。
+官网行为变化同步 README 与相应帮助章节，功能索引放[源码索引](../reference.md)。
 
-```bash
+## 已发布版本与回滚
-# 默认指向装好的客户端；推荐直接拿刚打出来的便携版单文件当被测副本
-pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版本>-x64-portable.exe"
-```
 
-> Linux 包**只能在 Linux 上构建**（依赖是平台相关的），所以不在这条命令里 ——
+已公开且用户安装的版本建议发补丁版本修复，避免同号不同内容使更新缓存/忽略版本与摘要失配。
-> 它由 GitHub Actions 出，见第 7 步。
+用户明确要求固定版本重构建时，按要求保持版本，并清楚区分本地包和远端资产；不自动改远端 tag/Release。
-
+仅说明或文档错误直接修改说明/文档；线上故障按对应部署形态从完整备份恢复。
-### 5. 生成跨组件哈希清单
-
-`releases/SHA256SUMS-<版本>.txt` 是**人读的**（表头 + 体积 + 说明），由发布流程维护，
-本地只写 Windows 与插件那几行：
-
-```bash
-cd releases/client/<版本>/安装包 && sha256sum *.exe > ../../../SHA256SUMS-<版本>.txt  # 按实际文件名整理
-```
-
-（Linux 那一行由 CI 在第 7 步里**合并**进去，不要手工写。）
-
-### 6. 提交并推上去
-
-```bash
-git add -A
-git commit -m "chore(release): 1.1.3"
-git push origin master
-```
-
-提交信息用 Conventional Commits + 模块 scope，描述写中文，可多 scope，例如
-`fix(island): 胶囊"点不动"的根因——窗口必须始终可激活`。
-
-### 7. 开 Release
-
-上传前先把产物改成 ASCII 名 —— 构建产物是中文名，Release 上的名字是给别人看、要贴进脚本的：
-
-```bash
-V=1.1.3
-mkdir -p .cache/release-staging
-cp "releases/client/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-client-setup.exe"
-cp "releases/client/$V/安装包/"*-x64-portable.exe ".cache/release-staging/ClassHelper-$V-x64-client-portable.exe"
-cp "releases/server/$V/安装包/"*-x64-setup.exe    ".cache/release-staging/ClassHelper-$V-x64-server-setup.exe"
-cp "releases/classisland-plugin/$V/安装包/ClassHelper.ClassIslandPlugin.cipx" .cache/release-staging/
-
-gh release create v$V --title "ClassHelper v$V（<一句话定位>）" --notes-file "releases/ReleaseNotes-$V.md"
-gh release upload v$V .cache/release-staging/* "releases/SHA256SUMS-$V.txt" --clobber
-```
-
-| 构建产物                    | Release 上的名字                             |
-| --------------------------- | -------------------------------------------- |
-| `<客户端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-client-setup.exe`    |
-| `<客户端>-x64-portable.exe` | `ClassHelper-<版本>-x64-client-portable.exe` |
-| `<服务端>-x64-setup.exe`    | `ClassHelper-<版本>-x64-server-setup.exe`    |
-
-这三个名字是**外部契约**：README 的「开始使用」表、官网下载页读不到版本清单时拼的兜底直链，
-都按它们写；改名要三处一起改。
-
-`gh release create` 会**创建 tag 并推送**，这一步会自动触发
-[`release-linux-server.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/release-linux-server.yml)
-构建 Linux 包（ubuntu runner）。它跑完之后会：
-
-1. 把 `classhelper-server-linux-x64-<版本>.tar.gz` 与 `.sha256` 挂到 Release 上；
-2. **把 Linux 那一行合并进** `SHA256SUMS-<版本>.txt`（保留 Windows / 插件那几行）。
-
-> **顺序很重要**：Linux workflow 是在最后一步才去合并 SHA256SUMS 的，
-> 所以第 5 步那份清单必须**先上传**。万一手速反了（workflow 先跑完、你后上传），
-> 重新跑一次 `gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true` 就能把那一行补回来。
-
-想手动触发（比如只需要重出 Linux 包）：
-
-```bash
-gh workflow run release-linux-server.yml -f tag=v1.1.3 -f attach=true
-```
-
-> **CI 是按 tag 的 ref 检出源码的。** 发完版又发现构建脚本（或任何影响出包的代码）要修时，
-> **光推 master 不够** —— CI 仍会拿旧 tag 的源码跑，得把 tag 挪到修复后的提交：
-> `git tag -f v<版本> <提交> && git push --force origin v<版本>`，tag 一变会自动重跑。
-> 1.3.0 实测踩过：tag 指的那个提交里打包脚本有个 bug，CI 红了、Release 上少一个 Linux 包，
-> 而本地 `pnpm dist:server` 一直是绿的（Windows 侧走另一条分支）。
->
-> 另外，本页第 8 步的「官网与文档站」是**另一条**流水线（master 推送触发）——
-> 它绿不代表 Linux 包出来了，推完 tag 要去 `gh run list --limit 5` 看一眼。
-
-### 8. 官网与文档站
-
-**不用做任何事。** 推送 master 时只要 `website/**`、`docs/**`、`scripts/build-pages.mjs` 或
-`package.json` 变过，
-[`pages.yml`](https://github.com/LoveChengke/classhelper/blob/master/.github/workflows/pages.yml)
-就会把两者构建成**同一个** GitHub Pages 站点发出去：
-
-```
-https://lovechengke.github.io/ClassHelper/          ← 官网
-https://lovechengke.github.io/ClassHelper/docs/     ← 文档站
-```
-
-（一个仓库在 Pages 上只有一个站点，所以是拼在一起发的 —— 官网在根、文档站在 `/docs/` 下。）
-
-文档站顶栏的版本徽标取自根 `package.json`，所以第 1 步改完就跟着变了；
-官网首屏那排芯片、顶栏徽标与页脚里的版本号，以及下载页那个兜底版本号，
-也都是**由 `pnpm version:bump` 一起改的**（它们是那 14 个落点里的四个）。
-
-> 官网的「立即下载」会跳到 `/download.html`，那一页的版本清单是**当场**从 GitHub Releases 读的
-> （读不到才退回上面那个兜底版本号），所以发完 Release 不用重新部署那一页 —— 但**兜底值要跟着发版一起改**，
-> 不然离线访客点到的就是旧版本的直链。
-
-### 9. 检查
-
-- [ ] Release 页面上四个组件都在，`SHA256SUMS-<版本>.txt` 里 Windows / 插件 / Linux 三种行齐全；
-- [ ] 文档站能打开，顶栏版本号是新版；
-- [ ] 装一台机器试一遍（或至少跑 `pnpm verify:packaged`）。
-
-## 回滚
-
-发布出去之后发现严重问题：
-
-| 情形                        | 做法                                                                                                                    |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| 只是文档 / Release 说明写错 | 直接改 Release 说明或重发文档站（`gh workflow run docs.yml`）                                                           |
-| 二进制有问题                | 删掉 Release 与 tag（`gh release delete v1.1.3 --cleanup-tag`），修完重新发；**不要**拿同一个版本号发第二次内容不同的包 |
-| 用户已经装了                | 发一个**新版本号**（`pnpm version:bump patch`）修复，不要原地改                                                         |
-
-> 已经发出去的版本号**不要复用**：客户端把它记进「忽略此版本」，服务端与 Web 端各有 30 分钟缓存，
-> 同号换内容会让"检查更新"永久失灵。
-
-## 相关
-
-- 文档站本身怎么写的 → [架构总览的目录结构](architecture.md)
-- 验收脚本与脆弱用例 → [验收与测试](testing.md)
-- 各形态升级的**用户侧**步骤 → [更新与升级](../management/upgrade.md)

docs/dev/testing.md

@@ -1,122 +1,76 @@
 ---
 title: 验收与测试
-description: 五套验收脚本怎么跑、覆盖什么、哪些用例是脆弱的，以及怎么判断失败是不是真回归。
+description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
 ---
 
 # 验收与测试
 
-这个仓库的验收方式是**跑真东西**：真的起后端、真的开 Electron 窗口、真的点击菜单、
+按改动范围选择验证；数量和结果读取本次输出，不沿用历史报告数字。
-真的发一条通知。不是单元测试，是端到端回归。
+默认客户端冒烟为后台快速模式；动画、透明度、桌面截图必须显式视觉模式。
 
-## 五套脚本
+## 命令与前置条件
 
-| 命令                             | 覆盖                                                                             | 需要什么                    |
+| 命令                                             | 覆盖/前置条件                                                                |
-| -------------------------------- | -------------------------------------------------------------------------------- | --------------------------- |
+| ------------------------------------------------ | ---------------------------------------------------------------------------- |
-| `pnpm verify:e2e`                | 后端 + 实时推送 + RBAC 越权 + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查 | **后端已启动**              |
+| pnpm lint / pnpm typecheck / pnpm check:icons    | 静态检查；typecheck 会先构建 shared                                          |
-| `pnpm verify:web`                | Web 管理端真实点击回归（Electron 驱动）                                          | 后端已启动 + Web 产物已构建 |
+| pnpm docs:check                                  | docfx 严格构建，需 .NET SDK 与 docfx                                         |
-| `pnpm verify:desktop`            | 客户端冒烟（Electron，无人工点击）                                               | 已构建的客户端产物          |
+| pnpm verify:e2e                                  | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务            |
-| `pnpm verify:packaged`           | 对**打包后 / 已安装**的客户端 EXE 复跑同一套冒烟（`--exe` 指定路径）             | 打包产物                    |
+| pnpm verify:web:isolated                         | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物                         |
-| `pnpm verify:classisland`        | 设备令牌 / 上报 / 提醒下发与回执 / 镜像契约 / 幽灵行清理                         | 后端已启动                  |
+| pnpm verify:web                                  | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务                |
-| `pnpm verify:classisland-plugin` | 插件静态契约（清单一致性 / 注册完整性 / C# DTO ↔ 服务端 zod 与路由）             | 不需要 .NET，也不需要后端   |
+| pnpm verify:lifecycle                            | 临时 SQLite 验证权限治理、事务故障回滚、状态机、历史、多轨道、计划哈希和快照 |
+| pnpm verify:v14                                  | 临时库验证关系课表、周次、范围、隐私与升级等                                 |
+| pnpm verify:courseware                           | 临时库和文件目录的课件专项，不向真实班级推送                                 |
+| pnpm verify:client-agent                         | 假系统适配器验证命令、回执和更新策略                                         |
+| pnpm verify:client-migrations                    | 临时旧库验证迁移、联动退役与默认组持久化                                     |
+| pnpm verify:review-client                        | 无窗口逻辑回归                                                               |
+| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数                    |
+| pnpm verify:desktop                              | 先 pnpm build:desktop；隐藏快速检查，独立 userData                           |
+| pnpm verify:desktop:online                       | 显式联网，需要测试管理员并创建临时教师/班级                                  |
+| pnpm verify:desktop:visual                       | 显式使用桌面，完整岛几何/动画/透明度/截图检查                                |
+| pnpm verify:packaged --exe <客户端EXE>           | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面                   |
 
-条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`），**文档里不写死容易过期的总数** ——
+联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
-每次跑完看脚本输出。
+开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
+不得回退到真实班级、重置真实密码或向真实班级发测试通知；远控与安装器使用假执行器。
+桌面进程超时和失败日志先定位，不能因为一个历史脆弱用例名称就断言当前失败必然正常。
 
-另外三套是"门禁"而不是验收：`pnpm typecheck`、`pnpm lint`、`pnpm check:icons`。
+## 常用检查顺序
-
-### 一次完整的交付前检查
 
 ```bash
-pnpm lint                # ESLint，0 error 是底线
+pnpm lint
-pnpm typecheck           # 全仓库类型检查（含 vue-tsc）
+pnpm typecheck
-
+pnpm check:icons
-pnpm dev:server          # 另开一个终端
+pnpm docs:check
 pnpm verify:e2e
-pnpm verify:classisland
+pnpm verify:v14
-pnpm verify:classisland-plugin
+pnpm verify:lifecycle
-
+pnpm verify:client-migrations
-pnpm build:desktop && pnpm verify:desktop
+pnpm verify:courseware
-pnpm build && pnpm verify:web
+pnpm build:desktop
+pnpm verify:desktop
+pnpm --filter @classhelper/web-admin build
+pnpm verify:web:isolated
 ```
 
-改动涉及打包/交付形态时，再加 `pnpm dist:all` 与
+仅文档修改只需格式、链接与 docs:check；不因此重打包或占用桌面。
-`pnpm verify:packaged --exe "<客户端路径>"`（**开发产物通过不等于用户机器上的副本通过**）。
+改打包/运行时裁剪还要构建实际副本并跑 packaged；Linux 交付修改需 Linux 真机/CI 验证和 bash 语法检查。
 
-## 失败时先别改代码
+## 故障定位
 
-下面这些用例**不是回归**，遇到时先看条件。完整清单在 `AGENTS.md` 的「已知脆弱用例」表。
+- 临时服务失败查 .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 缺失时先补前置构建。
 
-| 用例                                                      | 触发条件                                                                                                                                         |
+## 截图
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `verify:desktop`「真实通知链路」「灵动岛标为已读」等 3 项 | 要求**当前不在上课时段**。种子课表恰有课正在进行时，客户端会**正确地**把普通通知暂存到下课 —— 这三项就会红（日志里会写 `客户端判定上课中=true`） |
-| `verify:e2e`「上课状态接口（at=周一 08:10）」             | 种子把周一第 1 节限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`.env` 的 `TERM_START_DATE` 对齐即可全绿                                        |
-| `verify:web`「课表科目为全校统一目录」                    | 种子给每个班建满了全部科目，下拉里就没有可自动建课的「统一科目」分组                                                                             |
-| `verify:desktop`「课表今天时间轴」                        | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤                                                                                       |
-| `verify:desktop`「作业看板全屏自适应」                    | 演示数据某天有 6 条长作业、而冒烟窗口只有约 543px 高时，缩放被下限 0.45 钳住 → 必然溢出                                                          |
-| 岛交互 / 岛动画 / 岛截图留档                              | **AI 会话里会间歇性失败**：置顶透明小窗的 rAF 被限流、形变采样抓不到帧。**先原样重跑一次再动手改**                                               |
 
-## 大面积报「登录失败 / 401」时
+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 通过表述为动画/透明度已验证。
 
-先核对本机 `teacher1` 的密码 —— 本机实测可能被改成了 `123456`，不是种子默认的 `teacher123`
+权限与年度流程回归入口为 `scripts/verify-lifecycle.mjs`，为子进程指定临时库与测试密钥，不使用业务 .env 的登录凭据。
-（原因是「修改密码」弹窗留空会落到默认初始密码）。**处理方式是用环境变量传实际凭据，不要去改数据。**
+旧库升级脚本动态读取最新迁移，另建重构前夹具校验 ADMIN 默认组补键、历史 kind 映射、空组保留及重复启动。
-
+事务回滚用 SQLite 触发器模拟历史写入失败，不能通过删除断言或放宽状态规则通过测试。
-两个演示账号的口令**不一定一起漂**，所以不能简单地全局替换。
-
-| 脚本              | 覆盖凭据的方式                                                                                                                |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `verify:desktop`  | `set "ELECTRON_SMOKE_USER=teacher1" && set "ELECTRON_SMOKE_PASSWORD=123456" && pnpm verify:desktop`                           |
-| `verify:packaged` | 同上（`ELECTRON_SMOKE_*`）                                                                                                    |
-| `verify:web`      | `set "UI_SMOKE_USER=teacher1" && set "UI_SMOKE_PASS=123456" && pnpm verify:web`（另有 `UI_SMOKE_ADMIN*`）                     |
-| `verify:e2e`      | **不支持环境变量**，需用临时副本替换（且副本必须放在 `packages/server/scripts/` 里，否则 `import 'socket.io-client'` 会失败） |
-
-## 冒烟会真的动你的屏幕
-
-`verify:web` / `verify:desktop` / `verify:packaged` 会**真的弹窗口**、真的发通知、真的移动鼠标：
-
-- 跑的时候别动键鼠；
-- 验证实例的灵动岛是**洋红主题色**（`#e91e8c`），一眼可以与你自己客户端那个区分开。
-  两条反馈里的"屏幕上出现了第二个灵动岛""点它反应不对"都源于这个叠影；
-- 冒烟会往演示班发几条「张老师 · _自检_」通知，用完即删；中途被 kill 会留下残条。
-
-## 截图留档
-
-截图分两套，各管一件事：
-
-| 目录                | 谁在用                                                      | 谁产出                                                                |
-| ------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
-| `docs/images/`      | **文档站、README、官网用的是同一份图**，页面上展示的都是它  | `capture-shots.mjs`（Web / 手机）+ 客户端冒烟（客户端 / 灵动岛）      |
-| `docs/screenshots/` | 回归留档，页面不展示；`verify:*` 的像素级断言比对的就是它们 | 各冒烟脚本自动写入（island / client / web-mobile / classisland 四组） |
-
-**展示图重新采集**（保证文档站与 README、官网用的是同一份图）：
-
-```bash
-pnpm dev:server                                                                    # 后端同时托管 Web 管理端
-CAPTURE_OUT=docs/images,website/assets/shots node website/tools/capture-shots.mjs  # → web-*.jpg / mobile-*.jpg
-
-# 客户端与灵动岛走的是冒烟脚本。它除了正片，还会顺手落一份「岛外留白对照图」
-# （*-window.png / *-backdrop.png），所以先落到临时目录，再挑要用的拷进去。
-ISLAND_SHOTS_DIR="$PWD/.cache/shots" ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/shots" \
-ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
-ELECTRON_SMOKE_USER=teacher1 ELECTRON_SMOKE_PASSWORD=123456 \
-  node packages/desktop-client/scripts/smoke.mjs
-cp .cache/shots/{island-*,client-*}.png docs/images/
-rm -f docs/images/*-window.png docs/images/*-backdrop.png
-cp docs/images/{island-*,client-*}.png website/assets/shots/       # 官网那份保持同步
-```
-
-**回归留档重新采集**（同一套冒烟，把输出指到留档目录）：
-
-```bash
-pnpm dev:server
-ISLAND_SHOTS_DIR="$PWD/.cache/island-shots" \
-ELECTRON_CLIENT_SHOTS_DIR="$PWD/.cache/client-shots" \
-ELECTRON_SMOKE_ISLAND_ACCENT='#0a84ff' ELECTRON_SMOKE_ISLAND_STYLE=black \
-ELECTRON_SMOKE_USER=teacher1 ELECTRON_SMOKE_PASSWORD=123456 \
-  node packages/desktop-client/scripts/smoke.mjs
-```
-
-> 展示图都是**逻辑像素 1×**（灵动岛的 268×44、424×230 就是这个数，不再乘 2），
-> 页面按原始尺寸显示即可 —— 换图时别顺手放大，否则整页的尺寸对不上。
-> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
-> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
-> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。

docs/dev/toc.yml

@@ -12,11 +12,12 @@
   href: permissions.md
 - name: 动效层与主题
   href: motion.md
-- name: ClassIsland 插件
-  href: classisland-plugin.md
 - name: 灵动岛设计令牌
   href: winisland-design-tokens.md
 - name: 验收与测试
   href: testing.md
 - name: 版本迭代与发布
   href: release.md
+
+- name: 当前实现约定
+  href: implementation.md

docs/dev/winisland-design-tokens.md

@@ -1,593 +1,59 @@
-# WinIsland 视觉设计系统（Design Token 规格）
+---
-
+title: 灵动岛设计令牌
-来源：`D:\classhelper\.cache\winisland-ref\WinIsland-master`（只读 checkout）。
+description: 本地经典/自定义岛的几何、外观与动画入口。
-所有数值均取自代码常量，标注了「常量名 = 值 @ 文件」。未在代码中找到的项明确写「未找到」。
-
-关键前提：**岛内所有几何尺寸都乘以 `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 两个状态的尺寸
+经典岛以 WinIsland 的连续圆角和形变为设计参考，自定义组件行以 ClassIsland 为参考。
+当前数值与行为以本仓库 shared 常量和渲染实现为准；本页不把上游音乐/歌词/媒体功能列为 ClassHelper 功能。
 
-| 项       | 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`）：
+| 来源                                                 | 内容                                                  |
+| ---------------------------------------------------- | ----------------------------------------------------- |
+| 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         | 经典底色、文字、图形与状态样式                        |
 
-```rust
+classic 的 black/glass/tinted 是本地 CSS 外观；glass 使用半透明色，不采样桌面模糊。
-pub(crate) fn expanded_island_radius(w: f32, h: f32, scale: f32) -> f32 {
+不要对透明岛调用 setBackgroundMaterial：系统材质作用于整窗矩形，可能破坏逐像素透明。
-    (48.0 * scale).min(w / 2.0).min(h / 2.0).max(0.0)
+投影常驻，只随形态改参数，避免切换 filter 创建合成表面的闪帧。
-}
+默认停靠中线不受左右边距影响，只有左/右停靠使用水平边距。
-```
 
-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）
+CLASSISLAND_ISLAND_METRICS 位于 shared/src/island-layout.ts：
 
-`src/window/app/layout.rs` `compute_lyric_target_width()`：
+| 参数                    | 本地值               |
+| ----------------------- | -------------------- |
+| 单行基准高度 / 水平留白 | 40 / 12 px           |
+| 次要/正文/强调/大字号   | 14 / 16 / 18 / 20 px |
+| 默认缩放 / 范围         | 1 / 0.75–2.5         |
+| 默认圆角 / 最大         | 8 / 20 px            |
+| 默认不透明度 / 行距     | 0.5 / 5 px           |
+| 鼠标避让淡化比例        | 0.05                 |
 
-- 无媒体 / 不在播放态：宽 = `base_width` = **120**
+方案有常态 rows 和无通知展开 expandedRows，运行时由 CustomIslandRuntime.vue 测量自然内容，
-- 有媒体但无歌词：宽 = `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`：
+经典与自定义岛的形变都使用 src/island/spring.ts 的 SpringValue；默认 stiffness=0.10、damping=0.68，
+换向保留部分动量，按剩余距离限速并钳制过冲。不同用途可能覆盖 snapThreshold 等参数，以调用点为准。
+这是独立的帧积分，不等同于主窗口 shared/motion.ts 的 CSS 弹簧。
+应用内动画开关、原生窗口可见性与文档可见性控制运行时动画和静止落定。
 
-- `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)`
+视觉验收必须显式 --visual；本页数值不代表本次已完成像素验收。
-- 单侧扩展宽：`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 | 宽                                         | 高                                        | 圆角             | 来源                                                                                                    |
+外观范围改 shared，经典样式改 classic-island.css，自定义样式改 custom-runtime.css 和 custom-island.css，
-| ------- | ------------------------------------------ | ----------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
+原生窗口与命中改 main/island.ts。组件结构/设置改 shared/island-layout.ts 并同步编辑器和运行时。
-| 通知    | `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`） |
+展示行为见[灵动岛](../app/island.md)，测试见[验收与测试](testing.md)。
-| 音量    | `(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
-
----
-
-## 附：ClassHelper实际采纳了哪些（本次重写对照表）
-
-| 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/**`                                                                     | 业务不同（我们做通知/作业/叫人/紧急）                                                                                              | —                                               |

docs/faq.md

@@ -7,24 +7,6 @@ description: 装不上、连不上、改了不生效——最常被问到的那
 
 ## 安装与启动
 
-### 客户端装不上 / 便捷版双击没反应 / 应用一闪就没了
-
-**现象**：安装程序报「拒绝访问」，便捷版双击毫无反应，装上了也启动即退且不写日志
-（退出码 `0x80000003`）。
-
-**原因**：交付物被打了 **Low 完整性标签**。带 Low 标签的 exe 会被 Windows 降级运行：
-写不进 `%LOCALAPPDATA%` / `%TEMP%`；即使装上，Chromium 的子进程（完整性更低）也读不到这些文件而秒崩。
-
-**处置**：从 [Releases](https://github.com/LoveChengke/classhelper/releases) 下载的官方包不受影响
-（打包脚本收尾会自动修正标签）。自己构建时如果碰到，用：
-
-```cmd
-icacls <产物目录> /setintegritylevel Medium /T /C
-```
-
-判据是 `icacls <exe> | findstr Mandatory` 里出现 `Low`。
-另外**别把安装测试装进仓库目录里** —— 在那里又会继承 Low。
-
 ### 双击客户端"点了没反应"
 
 **关窗只是隐藏到托盘，进程还在。** 再双击 EXE 会被单实例锁秒退（看起来像没反应），
@@ -46,7 +28,7 @@ icacls <产物目录> /setintegritylevel Medium /T /C
 1. 服务器地址要填**局域网 IP**（`http://192.168.1.10:4000`），不要写 `localhost`（那是客户端自己）；
 2. 服务器防火墙放行 **4000**；
 3. 服务器上如果开了系统代理，内网地址可能被代理接管 —— 浏览器与客户端**不会**自动绕过
-   （只有 ClassIsland 插件对本地 / 内网做了强制直连）；
+   请在系统代理中为内网服务端设置绕过规则；
 4. 在服务器本机 `curl.exe --noproxy '*' http://127.0.0.1:4000/healthz` 是不是 200？
 
 ### 页面能打开，但接口全 401
@@ -66,8 +48,8 @@ icacls <产物目录> /setintegritylevel Medium /T /C
 
 ### 上课时段发的通知学生看不到
 
-**这是设计行为。** 上课时段普通通知只进队列、不打断课堂，**下课自动补弹**。
+**经典模式的设计行为如此。** 上课时段普通通知暂存，下课补弹；自定义常驻模式先提示铃铛。
-紧急通知与叫人则立刻弹。规则见[通知与提醒](app/notifications.md)。
+经典模式紧急消息立即展开，普通叫人保留可点击胶囊；自定义常驻模式先提示铃铛，主动查看。规则见[通知与提醒](app/notifications.md)。
 
 ### 老师说发了通知，教室机器上什么都没弹
 
@@ -75,13 +57,13 @@ icacls <产物目录> /setintegritylevel Medium /T /C
 
 1. 客户端顶栏的实时通道是不是"已连接"？
 2. 现在是上课时段吗？（同上，是设计行为）
-3. 教室客户端的「设置 → 提醒」是不是设成了"只在 ClassIsland 上弹"？那样客户端只进通知中心。
+3. 确认客户端登录的是这条通知对应的班级。
 4. 反向代理放行 `/socket.io/` 的 WebSocket 升级了吗？
 
 ### 屏幕上出现了第二个灵动岛，点它反应不对
 
-那是**自动化验证实例**的岛 —— `pnpm verify:desktop` / `verify:packaged` 会真的在屏幕上放一个，
+先确认是否有人显式运行了 `verify:desktop:visual` 或 `verify:packaged --visual`；视觉实例由脚本控制，会自行开合。
-而且它归脚本控制，会自己展开 / 收起 / 消失。验证实例的岛是**洋红主题色**，一眼可辨。
+默认 `verify:desktop` / `verify:packaged` 是后台快速检查，不创建可见岛或托盘。
 
 ### 灵动岛上的文字往右跳一下再缩回
 
@@ -105,7 +87,7 @@ icacls <产物目录> /setintegritylevel Medium /T /C
 ### 学生登录不了
 
 **学生没有个人账号。** ClassHelper 班级端统一用**班级码 + 班级密码**登录（见[装 ClassHelper 班级端](get-started/client.md)）。
-用学生用户名去登录一定会失败，这是设计。
+用学生学号去登录会失败，这是设计。
 
 ### 客户端里找不到"修改密码"
 
@@ -148,8 +130,8 @@ Linux 上跑 `sudo classhelper doctor` 有专门一条断言盯着这个软链
 
 ## 还没解决？
 
-- 开发环境的坑（命令、代理与 TLS、完整性标签、ClassIsland 路径与日志编码……）
+- **开发与构建环境**的问题（命令、代理、TLS 与日志编码等）
-  都记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
+  记在仓库的 [`AGENTS.md`](https://github.com/LoveChengke/classhelper/blob/master/AGENTS.md) 里；
 - 功能行为的权威说明在[完整参考](reference.md)；
 - 都不是的话，去 [Issues](https://github.com/LoveChengke/classhelper/issues) 提一个，
   附上版本号（Web 端顶栏 / 客户端「设置 → 关于」里都有）和日志。

docs/get-started/classisland.md

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

docs/get-started/client.md

@@ -13,9 +13,9 @@ description: 在教室机器上安装 ClassHelper桌面客户端，用班级码
 从 [Releases](https://github.com/LoveChengke/classhelper/releases) 取：
 
 | 产物                                                                  | 用途                                       |
-| ------------------------------------ | ------------------------------------------ |
+| --------------------------------------------------------------------- | ------------------------------------------ |
-| `ClassHelper-<版本>-x64-setup.exe`    | 安装包（约 98 MB），装到本机并建快捷方式   |
+| `ClassHelper-<版本>-x64-client-setup.exe`（本地构建名不带 client）    | 安装包（约 98 MB），装到本机并建快捷方式   |
-| `ClassHelper-<版本>-x64-portable.exe` | 单文件便携版，双击即用，适合不改动机房机器 |
+| `ClassHelper-<版本>-x64-client-portable.exe`（本地构建名不带 client） | 单文件便携版，双击即用，适合不改动机房机器 |
 
 要自己打：
 
@@ -23,9 +23,7 @@ description: 在教室机器上安装 ClassHelper桌面客户端，用班级码
 pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的解包目录）
 ```
 
-> **装不上 / 双击没反应 / 一闪就没**（报 `0x80000003`）通常不是产物坏了，而是交付物被打了
+> **双击没反应？** 关窗只是隐藏到托盘，进程还在，再双击会因单实例锁秒退 —— 先从托盘右键退出。
-> Low 完整性标签。打包脚本收尾已自动修正；从 Release 下载的包不受影响。
-> 另外：关窗是隐藏到托盘，进程还在，再双击会因单实例锁秒退 —— 先从托盘退出。
 
 ## 2. 登录
 
@@ -52,15 +50,16 @@ pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的
 
 ## 4. 认一认主界面
 
-左侧是四个一级项（**课表 / 作业 / 通知 / 成绩**）加上一个可展开的**设置**分组，
+左侧是业务项（**课表 / 作业 / 通知 / 课件 / 成绩**）加上一个可展开的**设置**分组，
 顶部汉堡按钮把整栏收成 64px 的图标导轨（折叠状态会记住）。「通知」项上有未读红点。
 
 | 页面 | 一句话                                                         |
 | ---- | -------------------------------------------------------------- |
 | 课表 | 周视图 + 「今天」时间轴（大时钟 / 正在上什么 / 下一节）        |
 | 作业 | 看板模式（按科目卡片、可全屏）/ 列表模式；教室机器还能录入作业 |
+| 课件 | 查看本班可见文件、下载和打开本地文件夹                         |
 | 通知 | 未读红点、优先级标签、点开自动标为已读                         |
-| 成绩 | 班级账号看到的是全班总览（表格 + 柱状图 + 等级分布）           |
+| 成绩 | 个人查询开启时看本班成绩，关闭后只看服务端集体分析             |
 | 设置 | 通用 / 外观 / 灵动岛 / 提醒 / 账号 / 关于，六个子页            |
 
 细节见[应用帮助](../app/index.md)。
@@ -73,17 +72,25 @@ pnpm dist:win     # 安装包 + 便携版（两个都是成品，没有中间的
 2. **调灵动岛** —— 设置 → 灵动岛：高度、宽度、字号、主题色、停靠位置、视觉风格。
    讲台机器上通常把字号调大一点、位置放到顶部居中。
    触摸屏（希沃白板等）走的是另一套命中逻辑，客户端会自动识别，不用手动开。
-3. **选提醒弹在哪端** —— 设置 → 提醒：`ClassHelper 与 ClassIsland 都弹` / 只在客户端 / 只在 ClassIsland。
+3. **查看提醒规则** —— 设置 → 提醒维护本机课程等提醒设置；经典通知模式上课暂存普通消息，
-   这个选择会同步到班级记录，服务端据此决定要不要推 ClassIsland。
+   自定义常驻模式提示铃铛并主动查看。规则保存在本机，服务端仍即时广播。
 
 ## 6. 确认实时链路是通的
 
-在 Web 管理端给这个班发一条普通通知，教室机器上应该几秒内出现灵动岛胶囊。如果没有：
+在隔离测试服务中给临时验证班级发一条普通通知，经典岛课间应出现胶囊，自定义常驻岛应出现铃铛数量提示。如果没有：
 
 - 客户端顶栏的实时通道状态是不是"已连接"？
-- 现在是上课时段吗？上课时段的普通通知**只进队列、下课才弹**，这是设计行为，不是故障。
+- 现在是上课时段吗？经典模式普通通知上课暂存；自定义常驻模式看铃铛并主动展开。
 - 服务器与教室机器之间能互相 ping 通吗？防火墙放行 4000 了吗？
 
 排查清单见[常见问题](../faq.md)。
 
-下一步（可选）：[接入 ClassIsland](classisland.md)。
+## 7. 接收统一更新
+
+管理员在设备管理中缓存并推送客户端安装包，客户端会后台下载、校验文件，再按立即、放学后或空闲策略安装。
+关闭本机自动更新后，不会执行服务端下发的安装。安装助手未能就绪时，旧客户端会继续运行并显示失败原因。
+
+服务端下发的是安装版：便携运行的客户端接收更新后转为安装版，原便携文件不会原地替换，后续请使用安装版入口。
+新版重新连接服务端后，设备管理中的更新状态才会变为完成。
+
+已发布旧版若在拉起安装器时失败，需要先手动安装 1.4.2 以获得新的安装助手；服务端推送安装包不能替换旧客户端中已经损坏的交接逻辑。

docs/get-started/first-content.md

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

docs/get-started/index.md

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

docs/get-started/requirements.md

@@ -7,17 +7,17 @@ description: ClassHelper 服务端、Web 管理端、桌面客户端的运行环
 
 ## 服务端
 
-服务端的安装包**自带 Node 运行时**，目标机器不需要另外装 Node.js，也不需要数据库软件
+Windows 服务端安装包自带 Node；Linux 包不内置 Node，一键安装器检测或安装兼容运行时。
-（默认用内嵌的 SQLite）。
+默认使用内嵌 SQLite，无需另装数据库服务；MySQL 形态需可用数据库。
 
 | 项目     | 要求                                                                       |
-| -------- | --------------------------------------------------------------------------- |
+| -------- | -------------------------------------------------------------------------- |
 | 操作系统 | Windows 10 / 11 / Server 2016+（x64）；Linux（glibc 2.28+，见下）；Docker  |
 | 内存     | 512 MB 起步，2 GB 以上更稳（Node + SQLite 常驻约 120–200 MB）              |
-| 磁盘     | 程序约 340 MB（免安装目录）/ 安装后约 400 MB；数据按班级量增长，通常几十 MB |
+| 磁盘     | 预留程序、数据库、备份和课件文件空间；课件最多 512 MB/文件，按实际使用增长 |
 | CPU      | 任意 x64；不需要独显                                                       |
 
-**Linux 的 glibc 要求**：内置的 Node 官方 linux-x64 构建要求 glibc ≥ 2.28。
+**Linux 的运行时要求**：安装器下载的官方 Node linux-x64 运行时通常要求 glibc ≥ 2.28。
 CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体（尽力而为，未做长期验证）。
 判据：
 
@@ -25,8 +25,8 @@ CentOS 7 是 2.17，一键安装器会检测并自动换成 `-glibc-217` 变体
 ldd --version | head -1
 ```
 
-**外网**：服务端只在「检查更新」时访问 GitHub，且失败是设计内的结果（返回"查不到"，不报错）。
+**外网**：更新检查/下载安装包、假日建议和配置的在线 AI 服务等功能可能访问外网。
-内网机器可以完全不连通外网。
+基础教学业务可在内网运行；使用离线包、手工周次和 mock/关闭在线 AI，相关联网失败按接口返回原因处理。
 
 ## Web 管理端
 
@@ -64,9 +64,8 @@ ldd --version | head -1
 | 教室机器 / 老师电脑也要用 | 客户端与管理端填服务器的**局域网 IP**（如 `http://192.168.1.10:4000`），防火墙放行 4000 |
 | 公网访问                  | 前面加 Nginx / Caddy 反代并启用 HTTPS，见[生产部署指南](../management/production.md)    |
 
-> **别用代理**。本机自测时用 `curl.exe --noproxy '*'`，PowerShell 用 `-NoProxy`；
+> **别用代理**。自测时用 `curl.exe --noproxy '*'`，PowerShell 用 `-NoProxy`；
-> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。插件里对本地 / 内网地址做了强制直连，
+> 教室机器上如果开了系统代理，填服务端地址后可能拿到代理返回的 404。请检查系统代理绕过列表是否包含服务端的局域网地址。
-> 但浏览器与客户端本身不会绕过。
 
 ## 卸载 / 重置
 

docs/get-started/setup-class.md

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

docs/get-started/toc.yml

@@ -10,7 +10,5 @@
   href: setup-class.md
 - name: 装 ClassHelper 班级端
   href: client.md
-- name: 接入 ClassIsland
-  href: classisland.md
 - name: 发布第一条内容
   href: first-content.md

docs/get-started/web-admin.md

@@ -1,58 +1,38 @@
 ---
 title: 认识 Web 管理端
-description: 登录 ClassHelper Web 管理端，认一认 12 个页面、新手引导与手机端布局。
+description: 登录、菜单分组、权限与移动布局。
 ---
 
 # 认识 Web 管理端
 
-Web 管理端不用装：服务端起来之后，浏览器打开 `http://<服务器地址>:4000/` 就是它。
+服务端启动后，用浏览器打开 http://<服务器地址>:4000/，教师或管理员以工号和密码登录。
+学生无个人账号，教室客户端使用[班级登录](client.md)。新安装按部署配置创建初始管理员，首次使用后修改初始密码。
 
-## 登录
+## 菜单与权限
 
-用**教师 / 管理员账号**登录（用户名 + 密码）。学生没有个人账号，学生那一端走
+侧栏按以下分组组织，具体页面由路由权限筛选，并支持浅色/深色和关怀模式。
-[班级码 + 班级密码](client.md)，见[班级、学生与教师](../app/classes.md)。
 
-- 新装的服务端只有安装时创建的那一个管理员账号。**第一次登录后请立刻在顶栏头像菜单 → 修改密码里改掉它。**
+| 分组       | 主要页面                                                     |
-- 登录页**不含任何演示内容**（没有"点击填充示例账号"之类的按钮），也不会提示种子口令。
+| ---------- | ------------------------------------------------------------ |
-- 连不上服务器时页面会直接失败，不会静默重试 —— 先确认服务端在跑、端口对、没走代理。
+| 工作台     | 仪表盘、AI 助手                                              |
+| 教学事务   | 课表、时间表与日课表编辑、作业、通知、课件、成绩             |
+| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、学年升级、毕业归档 |
+| 设备运维   | 客户端在线状态、命令、更新与安装策略                         |
+| 系统管理   | 权限组、系统设置、大模型设置、数据库管理                     |
 
-## 界面
+班级、学生、学期周次、学年升级和归档页面按各自生效权限开放；教师管理和数据库页面仍保留角色门槛。
+名单、教学页与设备页还按对应数据范围开放，写按钮需额外管理键。
+每次操作服务端继续校验，不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
+顶栏提供本人密码、使用引导、检查更新与退出等入口。
 
-布局沿用 1Panel 那一套：左边固定深色侧边栏，右边浅灰底 + 白色圆角卡片。
+## 引导与手机
 
-| 页面             | 干什么                                         | 谁能进                 |
+首次登录展示使用引导，完成/跳过后记住；可从顶栏“使用引导”重看。
-| ---------------- | ---------------------------------------------- | ---------------------- |
+小屏侧栏收进抽屉，表格在卡片内横向滚动；支持安装 PWA，需要 HTTPS 或 localhost 安全上下文。
-| 仪表盘           | 全校 / 本班的汇总数字与最近动态                | 所有登录用户           |
+同局域网手机填写服务器局域网地址，不用 localhost；公网反代见[生产部署](../management/production.md)。
-| 课表管理         | 排课、导入 ClassIsland 课表、节次时间          | 管理员、本班班主任     |
-| 作业发布         | 发作业、按天查看、看未交名单                   | 教师、管理员、班级账号 |
-| 通知发布         | 发通知、发叫人                                 | 教师、管理员           |
-| 成绩录入         | 单条 / 批量录成绩、导入表格、看统计            | 管理员、本班班主任     |
-| ClassIsland 联动 | 接入教室设备、下发提醒、看实时状态、开镜像     | 管理员、教师           |
-| 班级管理         | 建班级、换班主任、改班级账号                   | **仅管理员**           |
-| 学生管理         | 学生名单增删、导入                             | **仅管理员**           |
-| 教师管理         | 教师账号增删改、导入名单、重置密码             | **仅管理员**           |
-| 数据库管理       | 备份 / 恢复、导出导入、一键切换 SQLite ⇄ MySQL | **仅管理员**           |
-| 检查更新         | 顶栏头像菜单里，查 GitHub 上有没有新版本       | 所有登录用户           |
-
-> **前端隐藏 ≠ 权限**。上面这张表只是"入口藏不藏"，每一条写入请求服务端都会再判一次
-> （见[角色与权限](../dev/permissions.md)）。直接输网址绕过菜单，一样会被挡回仪表盘。
-
-## 第一次登录的引导
-
-首次登录进入主布局后会自动弹一次聚焦式引导，依次指出：侧边菜单 → 实时通道状态 → 账号菜单 → 完成。
-走完或跳过（右上角 × 或 Esc）都记作"已看过"，之后不再自动弹。
-
-想重看：**右上角头像菜单 →「使用引导」**。
-
-## 手机 / 平板
-
-| 屏幕宽度  | 布局                                                   |
-| --------- | ------------------------------------------------------ |
-| > 992px   | 常驻 210px 深色侧边栏 + 顶栏显示连接状态与实时事件计数 |
-| 769–992px | 保留侧边栏，内容区内边距压缩                           |
-| ≤ 768px   | 侧边栏收进抽屉，顶栏汉堡按钮唤出；表格在卡片内横向滚动 |
-
-手机上（与电脑同一局域网）用 `http://<主机IP>:4000` 打开，可以「添加到主屏幕」当 App 用（PWA）。
-做成 HTTPS 之后 PWA 才能完全离线化，见[生产部署指南](../management/production.md)。
 
 下一步：[建班级、排课表](setup-class.md)。
+
+权限页选组会替代角色默认模板，保存前可查看新增/移除权限与影响成员；保留默认能力时同时选择同角色默认组。
+名单页默认在读，历史状态与包含归档分开筛选；资料编辑、调班、转出、转入/复学各有专用入口。
+学年升级先保存计划、预览阻断项和周次影响，再输入学年确认执行；执行记录保留快照与 SHA256。

docs/index.md

@@ -5,22 +5,21 @@ description: ClassHelper（Class Helper）的官方文档：安装部署、功
 
 # ClassHelper文档
 
-ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统。**一份代码，四个交付物**：
+ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统。**一份代码，三个交付物**：
-装在服务器上的后端、给老师用的 Web 管理端、装在教室机器的桌面客户端（ClassHelper 班级端 / 教室大屏），
+装在服务器上的后端、给老师用的 Web 管理端、装在教室机器的桌面客户端（ClassHelper 班级端 / 教室大屏）。
-以及装在 [ClassIsland](https://classisland.tech) 上的联动插件。
 
 <p class="ch-tagline">
-老师发一条通知，教室那台机器上的灵动岛和 ClassIsland 会同时弹出来；学生打开客户端就能看到当天的课表和作业。
+老师发一条通知，教室那台机器上的客户端和灵动岛会实时显示；学生打开客户端就能看到当天的课表和作业。
 </p>
 
 <div class="ch-cards">
   <a class="ch-card" href="get-started/index.md">
     <span class="ch-card-title">第一次装</span>
-    <span class="ch-card-desc">从零把服务端、管理端、ClassHelper 班级端和 ClassIsland 插件跑起来，大约半小时。</span>
+    <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>
+    <span class="ch-card-desc">课表、作业、通知、叫人、课件、成绩、灵动岛的使用说明。</span>
   </a>
   <a class="ch-card" href="management/index.md">
     <span class="ch-card-title">负责运维</span>
@@ -54,11 +53,10 @@ ClassHelper（Class Helper）是给中小学班级用的一套信息管理系统
 
 ## 这套系统的三件事
 
-**一、老师发，教室弹。** Web 端发布的内容通过 Socket.IO 按班级房间广播，客户端与灵动岛实时更新；
+**一、老师发，教室弹。** Web 端发布的内容通过 Socket.IO 按班级房间广播，客户端与灵动岛实时更新。
-落到 ClassIsland 上的那部分走设备令牌的独立通道，走 HTTP 上报，不依赖教室机器的网络环境有多好。
 
-**二、上课时段不打扰。** 「上课时段」由课表实时判定，普通通知只进队列、下课自动补弹，
+**二、课堂提醒有明确规则。** 经典岛普通通知暂存到下课，普通叫人保留可点胶囊，紧急消息立即展开；
-紧急通知和叫人则立刻弹出来 —— 服务端强制拦截，绕开界面直接调接口一样会被拦。
+自定义常驻岛先显示铃铛，由用户主动查看。课堂发布紧急通知还需服务端确认。
 
 **三、离线可用。** 客户端先写 IndexedDB，断网时回退缓存并在顶部提示；
 恢复连接后自动重新拉取，教室网络抖一下不会让大屏变白。

docs/management/database.md

@@ -5,14 +5,14 @@ description: 备份与恢复、导出导入、定时备份，以及 Web 管理
 
 # 数据库管理
 
-Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可见**，后端同样 `requireRole('ADMIN')`），
+Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可见**，接口要求 `database:manage`），
 把过去要手工做的数据库运维都收进了界面。
 
 ## 它能做什么
 
 | 能力         | 说明                                                                                                                                                   |
 | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、23 张表的行数、连接串（MySQL 密码脱敏）                                                  |
+| 连接状态检测 | 当前类型（SQLite / MySQL）、连通性与延迟、引擎版本、数据体积、快照清单中各表的行数、连接串（MySQL 密码脱敏）                                           |
 | 连接测试     | 对任意目标库试连（切换前的第一步）                                                                                                                     |
 | **一键切换** | SQLite ⇄ MySQL：自动「备份当前库 → 改写 schema provider → 生成客户端 / 建表 → 子进程迁移全部数据 → 改写 `.env`」，异步任务带步骤进度，**失败自动回滚** |
 | 备份 / 恢复  | gzip JSON 快照存在 `<数据目录>/backups/`；手动备份 / 从备份恢复（整库覆盖）/ 删除                                                                      |
@@ -23,12 +23,12 @@ Web 管理端有一个「数据库管理」页（`/database`，**仅管理员可
 
 **备份、导入导出、跨库迁移共用同一种「JSON 快照」**：
 
-- 23 张表按**拓扑序**导出；
+- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出；
-- 恢复时临时**关闭外键检查** —— 因为 `User.classId → Class` 与 `Class.teacherId → User`
+- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联，表清单与恢复顺序由 `lib/snapshot.ts` 统一维护；
-  是**互相引用**的，任何排序都会被其中一侧卡死；
 - 分批 `createMany` 写入。
 
-因此**任意一份备份都能恢复回任意一种受支持的数据库**（SQLite 备份可以恢复进 MySQL，反之亦然）。
+相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复；格式与缺失表由快照校验器检查。
+课件元数据包含在快照中，文件实体不包含，完整备份需另带 `data/courseware` 或 COURSEWARE_DIR 指定目录。
 
 MySQL 的连接测试 / 建表 / 写入依赖随包内置的 `@prisma/adapter-mariadb`，不需要额外安装。
 

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 上构建。
+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 是连接串                     |
@@ -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 反代 |
@@ -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 登录，改一次密码再登录
-# ② ClassHelper 班级端客户端填 http://<IP>:4000 用班级码 G101/123456 登录，收到一条老师发的通知
+# ② 在隔离测试服务创建临时教师和班级，用其班级凭据登录客户端，验证提醒后清理临时数据
 # ③ 重跑安装器（幂等性）：sudo bash /tmp/install.sh --yes --package <同一个包>
 #    期望：配置与数据保留、JWT_SECRET 不变（已登录用户不被踢下线）
 # ④ 卸载：sudo classhelper uninstall --yes

docs/management/mysql.md

@@ -1,134 +1,47 @@
+---
+title: MySQL 切换指南
+description: 通过快照和受支持的换库流程切换 SQLite/MySQL，保留迁移历史。
+---
+
 # MySQL 切换指南
 
-本项目默认使用 **SQLite（libSQL 内嵌模式）** 跑本地开发，数据模型与访问层已按
+默认数据库为 SQLite，服务端也支持 MySQL/MariaDB。唯一 schema 为 packages/server/prisma/schema.prisma；
-MySQL 兼容方式设计，可平滑切换到云端 MySQL / MariaDB 统一存储。
+Prisma 通过 libSQL 或 MariaDB driver adapter 访问，两种适配器已随运行时依赖内置。
+角色、优先级等以 String 加 API 校验存储，不用 Prisma enum 或 @db.*。
 
-## 为什么默认是 SQLite
+## 已有数据的切换
 
-- 本地零依赖即可跑通全部功能（无需安装数据库服务）
+管理员在“数据库管理 → 一键切换数据库”填写**空目标库**连接串，并完成界面确认。
-- `schema.prisma` 刻意只使用跨库通用类型
+还须 database:manage；页面和具体接口各自检查权限。
-  （`String` / `Int` / `Float` / `Boolean` / `DateTime`，无 `enum`、无 `@db.*` 原生类型）
 
-## 设计上的兼容约定
+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 也应指定新空文件，不能删除正在使用的数据库。
-| 不使用 Prisma `enum`                  | 角色（`ADMIN/TEACHER/STUDENT`）与优先级（`LOW/NORMAL/HIGH/URGENT`）以 `String` 存储，由 zod 在 API 层校验，两种数据库行为完全一致 |
+旧源库请保留到验证完成。课件实体不在 JSON 内，换主机时需另复制文件目录，见[课件](../app/courseware.md)。
-| 主键为 `String @default(cuid())`      | 不依赖自增，便于多端离线生成与合并                                                                                                |
-| 时间统一 `DateTime`                   | 由应用层与驱动适配器负责时区，不使用数据库原生时间函数                                                                            |
-| 唯一约束仅使用 `@@unique` / `@unique` | SQLite 与 MySQL 语义一致                                                                                                          |
-| 级联删除使用 Prisma 的 `onDelete`     | 由 Prisma 生成对应外键动作                                                                                                        |
 
-## 切换到 MySQL
+## 源码开发与配置
 
-### 方式一：Web 管理端「数据库管理 → 一键切换」（推荐，v1.0.0 新增）
+scripts/use-database.mjs 只切换 schema provider，不迁移数据、不改 .env、不替代完整换库流程。
-
+如果只准备一个全新的开发环境，可用 pnpm db:switch:mysql，再配置独立空库并生成客户端；
-管理员在 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` 换成云数据库内网/公网地址；
+SQLite 迁移目录属于仓库升级历史，不要为了切库删除它，也不要对已有数据运行 db:seed/db:reset。
-> 生产环境请同时修改 `JWT_SECRET` 与 `CORS_ORIGIN`。
+SQLite SQL 不直接应用到 MySQL；换库流程基于当前 schema 建表，保留原迁移用于 SQLite 升级。
+Prisma Client 与实际 provider 必须一致；切换后未重启时旧进程仍连接旧库。
 
-#### 4. 重建迁移并生成客户端
+## 部署核验
 
-SQLite 与 MySQL 的 DDL 方言不同，**必须重新生成迁移文件**：
+确认新库连接、表行数、班级登录、课表和成绩读取；保留切换前快照。
-
+生产凭据放 .env 或部署密钥中，不提交 Git。完整备份和各形态命令见[数据库管理](database.md)。
-```bash
+Linux 正式包应在 Linux 构建，否则 Prisma engine 可能是宿主平台版本，见[Linux 部署](linux-deploy.md)。
-# 删除 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/management/production.md

@@ -2,12 +2,12 @@
 
 本文档覆盖三种上线形态，按适用场景选择：
 
-| 形态                  | 适用场景                                     | 产物                                                     | 本机验证情况                           |
+| 形态                  | 适用场景                                      | 产物                                                                                                                     | 验证状态                                                 |
-| --------------------- | -------------------------------------------- | -------------------------------------------------------- | -------------------------------------- |
+| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
-| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）     | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe` | ✅ 已完整实测（静默安装/启停/卸载/UI） |
+| **A. Windows 安装包** | 学校机房、教师办公电脑（单机即完整系统）      | `releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe`                                                  | ✅ 已验证（静默安装 / 启停 / 卸载 / UI）                 |
-| **B. Docker + MySQL** | 云服务器、多终端共享一套数据（推荐长期方案） | `deploy/Dockerfile` + `deploy/docker-compose.yml`        | ⚠️ 文件已提供，本机无 Docker 未实测    |
+| **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，实机验收见 [linux-deploy.md](linux-deploy.md) §10 |
+| **C. Linux 原生部署** | 已有 Linux 服务器（systemd，SQLite 或 MySQL） | [`deploy/install.sh`](https://github.com/LoveChengke/classhelper/blob/master/deploy/install.sh) + `classhelper` 运维命令 | ⚠️ 实机验收清单见 [linux-deploy.md](linux-deploy.md) §10 |
-| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义           | 在仓库里构建后直接跑（见第四节）                          | ✅ 已实测（163 项端到端）    |
+| **D. 手动部署**       | 已有 Node 环境的服务器、需要自定义            | 在仓库里构建后直接跑（见第四节）                                                                                         | ✅ 已验证（端到端验收通过）                              |
 
 ---
 
@@ -59,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
@@ -101,8 +101,8 @@ uninstall-service.cmd   :: 删除计划任务
 
 ## 二、Docker + MySQL（形态 B，云部署推荐）
 
-> 本机没有 Docker，因此这套文件未在本机实测；结构经过与已验证的产物对照（依赖清单、
+> 这套文件与已验证的产物结构一致（依赖清单、目录布局、迁移方式与服务端完全相同），
-> 目录布局、迁移方式与服务端完全一致）。
+> 但**尚未在真实 Docker 环境跑过**。第一次上线请先在测试机走一遍。
 
 ```bash
 cp deploy/.env.example deploy/.env
@@ -207,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）                  |
@@ -273,7 +273,6 @@ sudo bash /tmp/verify-linux.sh --full --package /tmp/classhelper-server-linux-x6
 升级与回滚整条链路，末尾打印 `=== 结果：N/N 项通过 ===`。逐条清单见
 [linux-deploy.md](linux-deploy.md) 第 10 节。
 
-
 ---
 
 ## 四、手动部署（形态 D）
@@ -309,13 +308,13 @@ pnpm --filter @classhelper/server start      # 或 node packages/server/dist/ind
 ## 五、环境变量清单
 
 | 变量                                                | 默认                   | 说明                                                        |
-| --------------------------------------------------- | ---------------------- | --------------------------------------------------------- |
+| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
 | `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 空库时自动执行随包迁移并创建管理员                 |
+| `AUTO_MIGRATE`                                      | `false`                | SQLite 启动时补跑随包迁移，空库另创建管理员                 |
-| `JWT_SECRET`                                        | —                      | **必填**，≥32 位；生产环境仍为示例值会拒绝启动            |
+| `JWT_SECRET`                                        | —                      | **必填**，至少 16 位；生产需 ≥32 位且拒绝示例密钥           |
 | `JWT_EXPIRES_IN`                                    | `7d`                   | 令牌有效期                                                  |
 | `CORS_ORIGIN`                                       | `*`                    | 允许来源，多个用逗号分隔；生产建议写具体域名                |
 | `TRUST_PROXY`                                       | `false`                | 反向代理层数（Nginx 填 `1`），影响限流与日志中的真实 IP     |
@@ -326,7 +325,8 @@ pnpm --filter @classhelper/server start      # 或 node packages/server/dist/ind
 | `LOG_LEVEL`                                         | `info`                 | `debug` / `info` / `warn` / `error`                         |
 | `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`   | 空库首启动创建的管理员                                      |
 
 ---
@@ -354,6 +354,8 @@ pnpm --filter @classhelper/server start      # 或 node packages/server/dist/ind
 | 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 安全清单（上线前逐项确认）
@@ -392,7 +394,7 @@ pnpm --filter @classhelper/server start      # 或 node packages/server/dist/ind
 
 ## 八、性能与容量参考
 
-- 单机 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/upgrade.md

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

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/**',

package.json

@@ -1,6 +1,6 @@
 {
   "name": "class-helper",
-  "version": "1.3.1",
+  "version": "1.4.2",
   "private": true,
   "description": "ClassHelper - 班级信息管理系统（Web 管理端 + 后端服务 + 桌面客户端）",
   "packageManager": "pnpm@11.8.0",
@@ -15,10 +15,9 @@
     "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 .",
+    "lint": "node scripts/check-authz.mjs && eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write \"**/*.{ts,js,mjs,cjs,vue,json,md,yaml,yml,css,scss,html}\"",
     "format:check": "prettier --check \"**/*.{ts,js,mjs,cjs,vue,json,md,yaml,yml,css,scss,html}\"",
@@ -29,12 +28,22 @@
     "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:lifecycle": "node scripts/verify-lifecycle.mjs",
+    "verify:client-agent": "node scripts/verify-client-agent.mjs",
+    "verify:update-download": "node scripts/verify-update-download.mjs",
+    "verify:update-installer": "node scripts/verify-update-installer.mjs",
+    "verify:client-update:real": "node scripts/verify-client-update-real.mjs --real-install",
+    "verify:review-client": "node scripts/verify-review-client.mjs",
+    "verify:review-api": "node scripts/verify-e2e-isolated.mjs --review-api",
+    "verify:clients-api": "node scripts/verify-e2e-isolated.mjs --clients-api",
+    "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",
@@ -46,8 +55,12 @@
     "dist:win": "pnpm --filter @classhelper/desktop-client dist:win",
     "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",
-    "dist:all": "pnpm dist:server && pnpm dist:win && pnpm dist:classisland-plugin"
+    "verify:desktop:visual": "node packages/desktop-client/scripts/smoke.mjs --visual",
+    "verify:desktop:online": "node packages/desktop-client/scripts/smoke.mjs --online",
+    "verify:authz": "node scripts/verify-authz.mjs",
+    "check:authz": "node scripts/check-authz.mjs",
+    "verify:server-bootstrap": "node scripts/verify-server-bootstrap.mjs"
   },
   "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 @@
-# ClassHelper 联动插件
-
-把 [ClassIsland](https://classisland.tech) 与 [ClassHelper](https://github.com/LoveChengke/ClassHelper) 连起来：
-让 ClassHelper**读到教室真实的课表与上课状态**，也让老师的提醒**在教室的 ClassIsland 上弹出来**。
-
-## 它能做什么
-
-| 方向                             | 说明                                                                                                        |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| ClassIsland → ClassHelper         | 上报课表与节次时间、上报上课状态（当前科目 / 下一节 / 本节起止时间）                                        |
-| ClassHelper → ClassIsland         | 老师在 Web 端下发提醒 → 教室的 ClassIsland 上**全屏弹出**（可语音朗读），播完回执、不重复弹                 |
-| ClassHelper → ClassIsland（可选） | 把 ClassHelper上排好的课表**镜像**回 ClassIsland（新建 `ClassHelper-<班级名>` 档案课表，不改动老师原有的课表） |
-
-## 安装
-
-1. 把插件放进 ClassIsland 的插件目录，二选一：
-   - 用打包好的 `ClassHelper.ClassIslandPlugin.cipx`：ClassIsland →「设置 → 插件 → 从文件安装」；
-   - 或直接把 `ClassHelper.ClassIslandPlugin/` 目录（含 `manifest.yml` 与 dll）丢进插件目录
-     （Windows 默认 `%APPDATA%\ClassIsland\Plugins`，便携版在安装目录下的 `Plugins`）。
-2. 重启 ClassIsland，在「设置 → 插件」里确认「ClassHelper 联动」已启用。
-3. 打开「设置 → ClassHelper 联动」，填入：
-   - **服务器地址**：ClassHelper后端地址，例如 `http://127.0.0.1:4000`；
-   - **设备令牌**：在 ClassHelper Web 端「ClassIsland 联动」页面为本班新建一台设备后复制（形如 `chci_...`，只显示一次）。
-4. 点「立即上报」验证连接状态；状态卡片显示「已连接」即接入成功。
-
-## 配置项（全部在「设置 → ClassHelper 联动」里）
-
-| 配置项                       | 说明                                                                                               |
-| ---------------------------- | -------------------------------------------------------------------------------------------------- |
-| 服务器地址                   | ClassHelper后端地址（含端口；末尾斜杠与多余的 `/api` 后缀都会被自动容错）                           |
-| 设备令牌                     | 由 Web 端「ClassIsland 联动」页生成；服务端只存 sha256，明文只在页面上出现一次                     |
-| 上报课表到 ClassHelper         | 把 ClassIsland 里**已启用**的课表同步过去（合并写入：同星期同时间更新，不产生重复行）              |
-| 把班级课表镜像回 ClassIsland | 反方向同步，新建带前缀的档案课表；关闭后仍会照常上报「现在上什么课」                               |
-| 自动上报                     | 启动 / 课程事件（上课、下课、放学、状态变化）/ 定时各上报一次；关闭后只能用「立即上报」手动触发    |
-| 上报间隔（秒）               | 定时上报间隔，最小 15 秒，教室机器建议 60 秒                                                       |
-| 接收 ClassHelper提醒           | **本机总闸**：关掉后本机忽略老师下发的提醒（提醒仍留在班级通知中心）                               |
-| 语音朗读                     | 是否允许本机朗读（老师下发时也勾了「语音朗读」才会念，两个条件都满足才出声）                       |
-| 默认显示时长（秒）           | 老师未指定时长时用这个值；单条提醒可以在 Web 端单独指定更长的时长                                  |
-| 提醒轮询间隔（秒）           | **老师按下发送 → 教室弹出之间的最大延迟**（插件不持有长连接，是轮询取回的），默认 10 秒、最小 5 秒 |
-| 显示调试信息                 | 展开设备标识、与服务端的时钟差、配置目录等，排查「为什么同步不上」时打开                           |
-
-设置保存在 `<插件配置目录>/Settings.json`（随 ClassIsland 档案备份走，升级插件不丢）。
-改动即时生效 —— 改地址 / 令牌 / 间隔会立刻重建上报定时器，不需要重启 ClassIsland。
-
-> **上课时段策略（与 ClassHelper 客户端同一套规则）**：
-> 上课时段里，通知类提醒会**先暂存、下课后自动补弹**；**紧急提醒**与**叫人**属于「主动通知」，立刻弹。
-> 暂存期间不回执，服务端会保留这条待提醒。
-
-> **课间**：镜像回 ClassIsland 的课表会自动补上课间 —— **每两节之间**一段
-> （上一节下课 → 下一节上课），**最后一节之后不补**（放学）。课间由插件按课目时间算出来，
-> 不依赖 ClassHelper那边是否维护节次时间表，因此 ClassIsland 档案里一定有完整作息。
-
-> **两个方向各自需要的开关**：
->
-> - 服务端 → ClassIsland（镜像课表）：插件「把班级课表镜像回 ClassIsland」**且** Web 端该设备「镜像课表」都打开；
-> - ClassIsland → 服务端（上报课表）：插件「上报课表到 ClassHelper」打开；
->   关着时是正常行为（日志会写「仅状态（本机「上报课表到 ClassHelper」开关已关闭）」），不是上报失败；
-> - ClassIsland 里一张课表都没有时不会上报课表（日志会写「ClassIsland 里没有**启用的课表**」）。
-
-> **提醒到底会不会弹，取决于两个开关：**
->
-> 1. 教室机器的 **ClassHelper 客户端**在「设置 → 通知显示位置」里选了「只在 ClassHelper 客户端弹」时，
->    服务端根本不会推过来（此时本插件收不到东西，属正常）；
-> 2. 本插件的「接收 ClassHelper提醒」关掉时，即使推过来也不弹。
->
-> 两者都开着，提醒才会在 ClassIsland 上出现。
-
-## 工作原理（为什么这么写）
-
-- **不用跨进程 IPC，插件内直接读课程服务**：ClassIsland 的 IPC 暴露的是缓存数据，不足以还原课表；
-  插件直接读 `ILessonsService`（当前科目 / 状态 / 时间点）与 `IProfileService`（档案里的课表、时间表、科目），
-  拿到的才是「教室此刻真实的状态」。
-- **「上报即拉取」，不引入 Socket 依赖**：每次上报的返回值里会顺带带一条「尚未确认的提醒」，
-  插件收到就交给提醒提供方显示；应用启动时额外拉一次 `pending`，
-  补上「教室机器关机期间老师发的通知」。上报间隔本身就是心跳，插件因此少一个长连接故障面。
-- **提醒必须由「提醒提供方」发出**：只有通过 `NotificationProviderBase` 发出的提醒，
-  才会走 ClassIsland 主界面的全屏特效 / 语音 / 音效那一整套流程，因此插件注册了
-  「ClassHelper提醒」提供方（可以在 ClassIsland 的「提醒」设置里整体开关它）。
-- **回执时机 = 真的播完**：回执挂在提醒的 `Completed` / `Canceled` 上，
-  中途退出 ClassIsland 不会回执，下次上报会重发 —— 既不静默丢提醒，也不会重复弹。
-- **镜像时重建时间点**：ClassIsland 的 `ClassPlan.Classes[i]` 必须与时间表里
-  **第 i 个 `TimeType == 0`（上课）的时间点**一一对应，
-  因此镜像接口为每条课目带上 `startTime` / `endTime`，插件据此重建时间表
-  （课间点从服务端的时间表里按起始时刻对齐）。少一个时间点，整份课表就会错位。
-- **单双周口径与三端一致**：`WeekCountDiv/WeekCountDivTotal` ⇄ `ALL/ODD/EVEN`
-  与 `@classhelper/shared` 的 `weekParityFromDiv` / `weekDivFromParity` 互逆；
-  3 周及以上的轮换本系统无法表达，会降级为「每周」并在日志里提示。
-- **非破坏性**：镜像只创建 / 更新名字以 `ClassHelper-` 开头的课表与时间表；
-  老师手动建的课表不删不改名，同一星期已有启用课表时会在日志里给出重叠提示。
-
-## 上机联调记录（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`（响应不是 ClassHelper的标准格式）**
-这台机器上的**系统代理拦了内网请求**。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 小时后过期，避免教室机器一开机弹出一堆旧通知。
-
-**课表上报了但 ClassHelper上没变化**
-确认插件设置里打开了「上报课表到服务端」，且 Web 端该设备的「回传课表」开关也是允许状态。
-
-**镜像开关打开了，但 ClassIsland 的课表没变**
-镜像需要 Web 端该设备开启「镜像课表」且班级里已有课表；插件只在**上报时**顺路拉取镜像，
-所以打开开关后点一下「立即上报」或等一个上报间隔即可。镜像不会覆盖老师原有的课表。
-
-## 许可
-
-与 ClassHelper仓库一致。

packages/classisland-plugin/manifest.yml

@@ -1,19 +0,0 @@
-# ClassHelper ClassIsland 联动插件 —— 清单文件
-#
-# 字段说明见 https://docs.classisland.tech/dev/plugins/create-project/
-# apiVersion 指向 ClassIsland 2.0.0.0：本插件只用到 2.0 就有的插件 / 提醒 / 课程服务 API。
-
-id: classhelper.classisland.bridge
-name: ClassHelper 联动
-description: |-
-  把 ClassIsland 的课表与上课状态同步到 ClassHelper，并在 ClassIsland 上显示老师下发的提醒。
-  功能：
-  1. 上报当前课表与节次时间（ClassHelper Web 端与桌面客户端据此显示课程）；
-  2. 上报"正在上哪节课 / 下一节是什么 / 还有多久下课"的实时状态；
-  3. 接收老师在 ClassHelper上发布的提醒，在 ClassIsland 上全屏弹出（支持语音朗读）；
-  4. 可选：把 ClassHelper上排好的课表镜像回 ClassIsland。
-entranceAssembly: 'ClassHelper.ClassIslandPlugin.dll'
-url: https://github.com/LoveChengke/ClassHelper
-version: 1.3.1.0
-apiVersion: 2.0.0.0
-author: ClassHelper

packages/classisland-plugin/scripts/build.mjs

@@ -1,168 +0,0 @@
-/**
- * ClassIsland 联动插件构建脚本：`pnpm build:classisland-plugin` / `pnpm dist:classisland-plugin`
- *
- * 用法：
- *   node scripts/build.mjs              # Release 构建，产物在 packages/classisland-plugin/bin/Release
- *   node scripts/build.mjs --cipx       # 追加打包 .cipx 并归集到 releases/classisland-plugin/<版本>/
- *   额外参数会原样透传给 `dotnet build`（例如 `-p:ClassIslandPluginSdkVersion=2.1.1.1`）
- *
- * 为什么需要这层包装（本机踩过的坑，写在这里免得换台机器又踩一遍）：
- *   1. `dotnet` 默认把 NuGet 缓存与临时文件写在 C 盘（`%USERPROFILE%\.nuget`、`%TEMP%`），
- *      本机 C 盘紧张时会直接构建失败。这里统一改到仓库内 `.cache/`（已 gitignore）。
- *   2. 插件包（.cipx）的最后一步要调 PowerShell 生成哈希清单，SDK 默认用 `pwsh`；
- *      没有 pwsh 的机器会失败，因此这里探测一次并显式传给 MSBuild。
- *   3. 构建完顺手校验"清单 / 程序集 / 版本号"三者一致，避免打出装不上的包。
- */
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const pluginDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const repoRoot = path.resolve(pluginDir, '..', '..');
-const cacheDir = path.join(repoRoot, '.cache');
-const releasesRoot = path.join(repoRoot, 'releases', 'classisland-plugin');
-
-const argv = process.argv.slice(2);
-const withCipx = argv.includes('--cipx');
-/** `--` 之后的参数原样透传给 dotnet build；其余以 - 开头的参数同样透传 */
-const passthrough = argv.filter((item) => item !== '--cipx' && item !== '--');
-
-const log = (message) => console.log(`[classisland-plugin] ${message}`);
-
-/* ------------------------------------------------------------ 1. 环境准备 */
-
-const env = { ...process.env };
-for (const sub of ['nuget', 'tmp', 'dotnet-home']) {
-  fs.mkdirSync(path.join(cacheDir, sub), { recursive: true });
-}
-const setDefault = (key, value) => {
-  if (!env[key]) env[key] = value;
-};
-setDefault('NUGET_PACKAGES', path.join(cacheDir, 'nuget'));
-setDefault('TEMP', path.join(cacheDir, 'tmp'));
-setDefault('TMP', env.TEMP);
-setDefault('DOTNET_CLI_HOME', path.join(cacheDir, 'dotnet-home'));
-env.DOTNET_NOLOGO = '1';
-env.DOTNET_CLI_TELEMETRY_OPTOUT = '1';
-
-/** 可执行文件探测：先看显式配置，再问 PATH，最后试常见安装路径 */
-function resolveExecutable(envKey, names, fallbacks) {
-  const candidates = [];
-  if (env[envKey]) candidates.push(env[envKey]);
-  const finder = process.platform === 'win32' ? 'where' : 'which';
-  for (const name of names) {
-    const found = spawnSync(finder, [name], { encoding: 'utf8', env });
-    if (found.status === 0) {
-      for (const line of String(found.stdout ?? '').split(/\r?\n/)) candidates.push(line.trim());
-    }
-  }
-  candidates.push(...fallbacks);
-  for (const candidate of candidates) {
-    if (!candidate) continue;
-    try {
-      if (fs.statSync(candidate).isFile()) return candidate;
-    } catch {
-      /* 继续试下一个 */
-    }
-  }
-  return null;
-}
-
-const dotnet = resolveExecutable(
-  'DOTNET_EXE',
-  ['dotnet'],
-  process.platform === 'win32'
-    ? [path.join(env.ProgramFiles ?? 'C:\\Program Files', 'dotnet', 'dotnet.exe')]
-    : ['/usr/local/bin/dotnet', '/usr/bin/dotnet'],
-);
-if (!dotnet) {
-  throw new Error('未找到 dotnet SDK（需要 .NET 8 SDK）。安装后用 DOTNET_EXE 指定完整路径。');
-}
-
-const powerShell = resolveExecutable(
-  'POWERSHELL_EXE',
-  ['pwsh', 'powershell'],
-  process.platform === 'win32'
-    ? [path.join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')]
-    : [],
-);
-
-/* ------------------------------------------------------------ 2. 构建 */
-
-const buildArgs = ['build', '-c', 'Release'];
-if (withCipx) {
-  buildArgs.push('-p:CreateCipx=true');
-  // SDK 的 cipx 目标默认调 pwsh；这里按探测结果显式指定，避免"没有 pwsh 就打包失败"
-  if (powerShell) buildArgs.push(`-p:PowershellBinaryName=${powerShell}`);
-}
-buildArgs.push(...passthrough);
-
-log(`dotnet build（缓存目录 ${path.relative(repoRoot, cacheDir)}）`);
-const build = spawnSync(dotnet, buildArgs, { cwd: pluginDir, stdio: 'inherit', env });
-if (build.error) throw new Error(`无法启动 dotnet：${build.error.message}`);
-if (build.status !== 0) throw new Error(`dotnet build 失败（退出码 ${build.status}）`);
-
-/* ------------------------------------------------------------ 3. 产物自检 */
-
-const outputDir = path.join(pluginDir, 'bin', 'Release');
-const manifestPath = path.join(outputDir, 'manifest.yml');
-const assemblyPath = path.join(outputDir, 'ClassHelper.ClassIslandPlugin.dll');
-
-for (const required of [manifestPath, assemblyPath, path.join(outputDir, 'icon.png')]) {
-  if (!fs.existsSync(required)) {
-    throw new Error(`构建产物缺少 ${path.relative(pluginDir, required)}，ClassIsland 会加载失败`);
-  }
-}
-
-const manifest = fs.readFileSync(manifestPath, 'utf8');
-// prettier 会把 YAML 字符串统一成单引号，因此两种引号都要能剥掉
-const entrance = /^entranceAssembly:\s*(.+?)\s*$/m.exec(manifest)?.[1]?.replace(/^['"]|['"]$/g, '');
-if (entrance !== path.basename(assemblyPath)) {
-  throw new Error(
-    `manifest.yml 的 entranceAssembly（${entrance}）与程序集（${path.basename(assemblyPath)}）不一致`,
-  );
-}
-const manifestVersion = /^version:\s*([\d.]+)/m.exec(manifest)?.[1];
-const bridgeSource = fs.readFileSync(path.join(pluginDir, 'src', 'Services', 'BridgeService.cs'), 'utf8');
-const codeVersion = /PluginVersion = "([\d.]+)"/.exec(bridgeSource)?.[1];
-if (!manifestVersion || manifestVersion !== codeVersion) {
-  throw new Error(
-    `版本号不一致：manifest.yml=${manifestVersion ?? '缺失'}，BridgeService.cs=${codeVersion ?? '缺失'}`,
-  );
-}
-log(`产物自检通过（版本 ${manifestVersion}，入口程序集 ${entrance}）`);
-
-/* ------------------------------------------------------------ 4. 打包归集 */
-
-if (!withCipx) {
-  log('完成。加 --cipx 可同时打包成 ClassIsland 插件包（.cipx）');
-  process.exit(0);
-}
-
-const cipxDir = path.join(pluginDir, 'cipx');
-const cipxFile = path.join(cipxDir, 'ClassHelper.ClassIslandPlugin.cipx');
-if (!fs.existsSync(cipxFile)) {
-  throw new Error(`未生成插件包：${path.relative(pluginDir, cipxFile)}`);
-}
-
-// 归集到 releases/classisland-plugin/<版本>/（与客户端、服务端交付产物同一约定；releases/ 不入库）。
-// 只清理**当前版本**目录，历史版本原样保留 —— 原先这里是 rmSync 整个组件目录，重打一次就把
-// 上一版的留档抹掉了（插件版本是四段 <产品版本>.0，目录名取前三段与产品版本对齐）。
-// 产物只有 `安装包/*.cipx` + `checksums.md`：**.cipx 本身就是个 zip**，解压即用的那份
-// 「免安装目录」与它内容完全一样，纯属重复留档，已不再产出。
-const pluginVersion = manifestVersion.split('.').slice(0, 3).join('.');
-const versionDir = path.join(releasesRoot, pluginVersion);
-const installerDir = path.join(versionDir, '安装包');
-fs.rmSync(installerDir, { recursive: true, force: true });
-fs.rmSync(path.join(versionDir, '免安装'), { recursive: true, force: true });
-fs.mkdirSync(installerDir, { recursive: true });
-
-for (const file of fs.readdirSync(cipxDir)) {
-  // .cipx 是插件包本体，校验清单跟着版本目录走
-  const to = file.toLowerCase().endsWith('.cipx') ? installerDir : versionDir;
-  fs.copyFileSync(path.join(cipxDir, file), path.join(to, file));
-}
-
-log(`插件包已归集到 ${path.relative(repoRoot, versionDir)}`);
-for (const file of fs.readdirSync(installerDir)) log(`  安装包/${file}`);

packages/classisland-plugin/scripts/verify.mjs

@@ -1,405 +0,0 @@
-/**
- * ClassIsland 联动插件静态校验：`pnpm verify:classisland-plugin`
- *
- * 为什么是"静态"校验：插件要跑起来必须有 ClassIsland 本体，而本机（以及 CI）都没有，
- * 所以这里校验"装不上 / 对不上"的那几类问题 —— 它们不需要运行就能发现：
- *
- *   1. 清单三件套一致性：manifest.yml ↔ csproj ↔ 代码里的版本号；
- *   2. 注册完整性：插件入口、提醒提供方、设置页是否都挂上了（挂漏了功能会"静默消失"）；
- *   3. **接口契约**：C# DTO 的 JSON 字段名 ↔ 服务端路由 / 请求字段，
- *      这类错误（比如 dayOfWeek 写成 dayofweek）在运行时只会表现为"上报成功但课表是空的"，
- *      最难排查，所以专门盯住。
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const pluginDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const repoRoot = path.resolve(pluginDir, '..', '..');
-
-const results = [];
-const check = (name, ok, detail = '') => results.push({ name, ok: Boolean(ok), detail });
-const read = (relative) => fs.readFileSync(path.join(pluginDir, relative), 'utf8');
-const readRepo = (relative) => fs.readFileSync(path.join(repoRoot, relative), 'utf8');
-
-const manifest = read('manifest.yml');
-const csproj = read('ClassHelper.ClassIslandPlugin.csproj');
-const pluginSource = read('src/Plugin.cs');
-const providerSource = read('src/Services/ClassHelperNotificationProvider.cs');
-const bridgeSource = read('src/Services/BridgeService.cs');
-const clientSource = read('src/Interop/ClassHelperClient.cs');
-const settingsPageSource = read('src/Views/BridgeSettingsPage.axaml.cs');
-const settingsPageXaml = read('src/Views/BridgeSettingsPage.axaml');
-const mapperSource = read('src/Services/ScheduleMapper.cs');
-const writerSource = read('src/Services/ClassPlanWriter.cs');
-const settingsSource = read('src/Models/PluginSettings.cs');
-const serverModule = readRepo('packages/server/src/modules/integrations/integrations.module.ts');
-const serverSchemas = readRepo('packages/server/src/modules/integrations/integrations.schemas.ts');
-const serverService = readRepo('packages/server/src/modules/integrations/integrations.service.ts');
-const sharedTypes = readRepo('packages/shared/src/types.ts');
-const sharedConstants = readRepo('packages/shared/src/constants.ts');
-
-/* ------------------------------------------------------------ 1. 清单一致性 */
-
-/** 取 YAML 里某个顶层字段的值（prettier 会把字符串统一成单引号，两种引号都要能剥掉） */
-function field(name) {
-  const raw = new RegExp('^' + name + ':\\s*(.+?)\\s*$', 'm').exec(manifest)?.[1];
-  return raw?.replace(/^['"]|['"]$/g, '');
-}
-
-check('manifest.yml 有插件 id', Boolean(field('id')));
-check('manifest.yml 声明了入口程序集', Boolean(field('entranceAssembly')));
-check('manifest.yml 声明了 apiVersion', /\d+\.\d+\.\d+\.\d+/.test(field('apiVersion') ?? ''));
-
-const assemblyName = /<AssemblyName>([^<]+)<\/AssemblyName>/.exec(csproj)?.[1];
-check(
-  'entranceAssembly 与 csproj 的 AssemblyName 一致',
-  field('entranceAssembly') === assemblyName + '.dll',
-  'entranceAssembly=' + field('entranceAssembly') + ' AssemblyName=' + assemblyName,
-);
-
-const manifestVersion = field('version');
-const codeVersion = /PluginVersion = "([\d.]+)"/.exec(bridgeSource)?.[1];
-check(
-  '插件版本号在清单与代码里一致',
-  Boolean(manifestVersion) && manifestVersion === codeVersion,
-  'manifest=' + manifestVersion + ' code=' + codeVersion,
-);
-
-check(
-  '图标与自述文件按清单约定命名（icon.png / README.md）',
-  fs.existsSync(path.join(pluginDir, 'icon.png')) && fs.existsSync(path.join(pluginDir, 'README.md')),
-);
-
-/* ------------------------------------------------------------ 2. 注册完整性 */
-
-check(
-  '插件入口带 [PluginEntrance] 且继承 PluginBase',
-  /\[PluginEntrance\]/.test(pluginSource) && /:\s*PluginBase/.test(pluginSource),
-);
-check(
-  '初始化时注册了提醒提供方',
-  /AddNotificationProvider<\s*ClassHelperNotificationProvider\s*>/.test(pluginSource),
-);
-check('初始化时注册了设置页', /AddSettingsPage<\s*BridgeSettingsPage\s*>/.test(pluginSource));
-check('初始化时把联动服务注册为单例', /AddSingleton<\s*BridgeService\s*>/.test(pluginSource));
-check('应用启动后才接课程服务（不能更早）', /AppStarted/.test(pluginSource));
-check(
-  '设置以 JSON 持久化到插件配置目录',
-  /PluginConfigFolder/.test(pluginSource) && /Settings\.json/.test(pluginSource),
-);
-
-const providerGuid = /ProviderGuidValue = "([0-9A-Fa-f-]{36})"/.exec(providerSource)?.[1];
-check('提醒提供方声明了合法 GUID', Boolean(providerGuid));
-check(
-  '提醒提供方属性引用同一个 GUID 常量',
-  /NotificationProviderInfo\(\s*ProviderGuidValue/.test(providerSource),
-);
-check(
-  '提醒提供方会在播完后回执给服务端',
-  /Completed/.test(providerSource) && /AckAsync/.test(providerSource),
-);
-
-check(
-  '设置页带 [SettingsPageInfo] 且声明了页面 id',
-  /\[SettingsPageInfo\(/.test(settingsPageSource) && /"ClassHelper 联动"/.test(settingsPageSource),
-);
-check(
-  '设置页 XAML 的 x:Class 与代码后置类一致',
-  settingsPageXaml.includes('x:Class="ClassHelper.ClassIslandPlugin.Views.BridgeSettingsPage"') &&
-    /namespace ClassHelper\.ClassIslandPlugin\.Views;/.test(settingsPageSource),
-);
-check('设置页 XAML 继承 ClassIsland 的设置页基类', /SettingsPageBase/.test(settingsPageXaml));
-
-/* ------------------------------------------------------------ 3. 接口契约 */
-
-// 3.1 路由：插件调用的路径必须都在服务端注册过
-const clientPaths = [...clientSource.matchAll(/"(\/classisland\/[a-z-]+)"/g)].map((item) => item[1]);
-const registeredPaths = new Set(
-  [...serverModule.matchAll(/router\.(?:get|post|patch|delete)\(\s*'(\/classisland\/[a-z-]+)'/g)].map(
-    (item) => item[1],
-  ),
-);
-for (const route of [
-  '/classisland/report',
-  '/classisland/pending',
-  '/classisland/ack',
-  '/classisland/class-plan',
-]) {
-  check('服务端注册了 ' + route, registeredPaths.has(route));
-}
-check(
-  '插件调用的路由都存在于服务端',
-  clientPaths.length > 0 && clientPaths.every((item) => registeredPaths.has(item)),
-  '插件调用=[' + clientPaths.join(',') + ']',
-);
-check('插件把接口前缀拼成 /api/integrations', clientSource.includes('/api/integrations'));
-check('插件用设备令牌头鉴权', clientSource.includes('X-ClassIsland-Token'));
-
-// 3.2 上报请求字段：服务端 zod schema 里出现的字段名，插件必须真的会发
-const reportBlock = /export const classIslandReportSchema[\s\S]*?\n\}\);/.exec(serverSchemas)?.[0] ?? '';
-const requestFields = [
-  'pluginVersion',
-  'classIslandVersion',
-  'state',
-  'schedule',
-  'timeLayout',
-  'inClass',
-  'subject',
-  'nextSubject',
-  'timeState',
-  'periodStart',
-  'periodEnd',
-  'classPlanLoaded',
-  'clientTime',
-  'mode',
-  'entries',
-  'items',
-];
-const missingRequestFields = requestFields.filter(
-  (name) => reportBlock.includes(name) && !new RegExp('\\b' + name + '\\b').test(clientSource),
-);
-check(
-  '上报请求字段都出现在插件 DTO 里',
-  missingRequestFields.length === 0,
-  missingRequestFields.length > 0 ? '缺少=' + missingRequestFields.join(',') : '',
-);
-
-// 3.3 课表条目字段：这些是"上报成功但课表为空"的典型来源
-const entrySchema = /export const reportScheduleEntrySchema[\s\S]*?\n\}\);/.exec(serverSchemas)?.[0] ?? '';
-const entryFields = [
-  'dayOfWeek',
-  'startTime',
-  'endTime',
-  'subject',
-  'teacherName',
-  'weekParity',
-  'weekCountDiv',
-  'weekCountDivTotal',
-  'planName',
-];
-const csharpJsonNames = new Set(
-  [...clientSource.matchAll(/\[JsonPropertyName\("([^"]+)"\)\]/g)].map((item) => item[1]),
-);
-const missingEntryFields = entryFields.filter(
-  (name) => entrySchema.includes(name) && !csharpJsonNames.has(name),
-);
-check(
-  '课表条目字段服务端 zod 与插件 DTO 对齐',
-  missingEntryFields.length === 0,
-  missingEntryFields.length > 0 ? '插件缺少=' + missingEntryFields.join(',') : '',
-);
-
-// 3.4 插件 DTO 里的 JSON 字段名必须能在共享契约里找到（防错拼）
-const knownLocalOnly = new Set(['data', 'success', 'message', 'code']);
-const unknownJsonNames = [...csharpJsonNames].filter((name) => {
-  if (knownLocalOnly.has(name)) return false;
-  return !new RegExp('\\b' + name + '\\b').test(sharedTypes);
-});
-check(
-  '插件 DTO 的 JSON 字段名都能在 @classhelper/shared 里找到',
-  unknownJsonNames.length === 0,
-  unknownJsonNames.length > 0 ? '疑似拼写错误=' + unknownJsonNames.join(',') : '',
-);
-
-// 3.5 课表镜像：服务端给了 Classes[i] 对齐所需的时间，插件必须读
-for (const name of ['startTime', 'endTime', 'timeLayouts', 'profileName', 'weekDay', 'weekCountDivTotal']) {
-  check('镜像契约字段 ' + name + ' 在插件侧存在', csharpJsonNames.has(name));
-}
-
-// 3.6 提醒下发字段（Web 端 → 服务端 → 插件）
-const notifySchema = /export const sendNotificationSchema[\s\S]*?\n\}\);/.exec(serverSchemas)?.[0] ?? '';
-for (const name of [
-  'classId',
-  'title',
-  'content',
-  'durationSeconds',
-  'speech',
-  'speechContent',
-  'saveToNotifications',
-  'priority',
-]) {
-  check('下发提醒字段 ' + name + ' 在服务端 schema 里', notifySchema.includes(name));
-}
-check(
-  '提醒时长有上界（避免老师发出永不消失的提醒）',
-  /CLASSISLAND_NOTIFICATION_MAX_DURATION/.test(serverSchemas) &&
-    /CLASSISLAND_NOTIFICATION_MAX_DURATION/.test(sharedConstants),
-);
-
-// 3.7 实时事件：Web 端订阅的事件名必须在共享契约里声明过
-check(
-  '共享契约声明了 classisland 实时事件',
-  sharedTypes.includes("'classisland:state'") && sharedTypes.includes("'classisland:notification'"),
-);
-check(
-  '服务端广播事件名取自共享常量（不是手写字符串）',
-  /SOCKET_EVENTS\.classislandState/.test(serverService),
-);
-
-// 3.8 网络层：教室机器（以及开发机）常配了系统代理，而 Windows 的代理设置默认连 127.0.0.1
-//     也会走代理，表现为"填了令牌立刻 HTTP 404"（其实是代理自己的错误页，跟本服务无关）。
-//     插件必须对本地/内网地址绕开系统代理，否则内网部署必然失败。
-check(
-  'HttpClient 显式配置代理（不裸用默认行为）',
-  /SocketsHttpHandler\s*\{[^}]*Proxy\s*=/.test(clientSource),
-);
-check(
-  '本地/内网地址绕开系统代理',
-  /class LocalAwareProxy/.test(clientSource) && /IsBypassed\(Uri host\)/.test(clientSource),
-);
-check(
-  '代理判定覆盖回环与内网网段',
-  /IsLoopback/.test(clientSource) &&
-    /10\.0\.0\.0\/8/.test(clientSource) &&
-    /192\.168\.0\.0\/16/.test(clientSource),
-);
-check('失败信息带上请求 URL（便于定位代理/网关拦截）', /request\.RequestUri/.test(clientSource));
-
-// 3.10 课表同步方向（2026-10-11 定稿）：**两个方向都只由 Web 端的一次性动作触发**。
-//      2026-10-06 曾经把它做成"服务端 → 教室自动下发 + 本机两个开关"，但默认 15 秒一轮的
-//      自动上传 + 自动镜像会让服务端与教室里的课表每 15 秒互相覆盖一次，老师看到的是
-//      "课表被反复删改"（2026-10-11 实测）。现在本机没有任何"一直同步"的开关：
-//        · 教室 → 服务端：`scheduleRequested` 一次性待办（Web 端「从教室机器获取课表」）
-//        · 服务端 → 教室：`mirrorRequested` 一次性待办（Web 端「下发课表到教室」，强制替换）
-//      这几条盯着新契约，别删。
-check(
-  '课表两个方向都改为按需：本机不再有「自动回传 / 自动镜像」开关',
-  !/_uploadSchedule/.test(settingsSource) && !/_mirrorSchedule/.test(settingsSource),
-);
-check(
-  '定时上报只报运行状态，课表仅在服务端显式请求时上传',
-  /var uploadSchedule = forceSchedule;/.test(bridgeSource),
-);
-check(
-  '响应 DTO 里有 scheduleRequested / mirrorRequested（两个方向的一次性待办）',
-  /scheduleRequested/.test(clientSource) && /mirrorRequested/.test(clientSource),
-);
-check(
-  '收到 scheduleRequested 会补发一次带课表的上报（且不受本机自动上报开关限制）',
-  /ScheduleRequested\s*==\s*true/.test(bridgeSource) &&
-    /forceSchedule:\s*true/.test(bridgeSource),
-);
-check(
-  '只有收到 mirrorRequested 才镜像（不再跟着每一次上报走）',
-  /MirrorRequested\s*==\s*true/.test(bridgeSource),
-);
-check(
-  '镜像写入是「强制替换」（停用冲突的旧课表，而不是只留一条警告）',
-  /Apply\(profile, plan, force: true\)/.test(bridgeSource) &&
-    /IsEnabled = false/.test(writerSource),
-);
-check(
-  '补发课表发生在镜像之前（顺序反了会把刚拿到的课表盖掉）',
-  bridgeSource.indexOf('ScheduleRequested == true') < bridgeSource.indexOf('MirrorScheduleAsync()'),
-);
-check(
-  '课表拉取 DTO 带 weekRanges（管理员逐周配的学期周次区间）',
-  /weekRanges/.test(clientSource) && /TermWeekRangeDto/.test(clientSource),
-);
-
-// 3.9 提醒显示链路：下面几条全是"在真机上跑出来的"，回归时别删
-check(
-  '提醒在 UI 线程构造并显示（否则 Avalonia 直接抛 Call from invalid thread）',
-  providerSource.includes('Dispatcher.UIThread.Post'),
-);
-check(
-  '同一条提醒在播放期间按 id 去重（否则轮询会让它反复弹）',
-  providerSource.includes('_playing') && providerSource.includes('HashSet<string>'),
-);
-check(
-  '不再自造图标串（用模板默认图标，紧急用滚动文本表达）',
-  // 不再给 CreateTwoIconsMask 传 leftIcon（自造图标串会踩格式/字形坑）
-  !providerSource.includes('leftIcon') && providerSource.includes('CreateRollingTextContent'),
-);
-check(
-  'ClassIsland 的占位科目（Subject.Fallback）折算成"没有科目"',
-  mapperSource.includes('Subject.Fallback'),
-);
-check(
-  '上课时段暂存非主动通知（与客户端灵动岛同一套规则）',
-  providerSource.includes('_deferred') &&
-    providerSource.includes('IsImmediate') &&
-    providerSource.includes('FlushDeferred') &&
-    providerSource.includes('OnBreakingTime'),
-);
-check(
-  '主动通知（紧急 / 叫人）上课时段也立即弹',
-  providerSource.includes("\"call\"") && providerSource.includes('notification.Urgent'),
-);
-check(
-  '「上报课表」开关关闭时会在日志里说明（避免被当成"上报失败"）',
-  bridgeSource.includes('上报课表到 ClassHelper') && bridgeSource.includes('开关已关闭'),
-);
-check(
-  '提醒轮询独立于上报间隔（老师发完通知不必等一个上报周期）',
-  settingsSource.includes('NotificationPollSeconds') &&
-    bridgeSource.includes('_notifyTimer') &&
-    bridgeSource.includes('NotificationPollSeconds'),
-);
-
-/* ------------------------------------------------------------ 8. 回归护栏：本次修复过的坑 */
-
-check(
-  '课表配对用原始 TimeType==0 列表，**不用** ValidTimeLayoutItems（后者会剔除被停用的节次，导致整份课表错位）',
-  // 只查代码形态（`.Count`），因为源码注释里特意点名了这个属性来说明"为什么不能用它"
-  mapperSource.includes('classPoints[index]') && !mapperSource.includes('.ValidTimeLayoutItems.Count'),
-);
-check(
-  '上报字段按服务端 zod 上限截断（一个超长名字会让整批上报 400，连状态与心跳一起丢掉）',
-  mapperSource.includes('Truncate(') &&
-    mapperSource.includes('SubjectMaxLength') &&
-    mapperSource.includes('PlanNameMaxLength'),
-);
-check(
-  '课表镜像在 UI 线程改写档案（线程池上改 Observable 集合会与落盘并发，可能写坏档案）',
-  bridgeSource.includes('Dispatcher.UIThread.InvokeAsync') && bridgeSource.includes('SaveProfile()'),
-);
-check(
-  '镜像内容未变化时跳过（否则每次上报都重建课表并全量落盘）',
-  bridgeSource.includes('_lastMirrorSignature') && bridgeSource.includes('MirrorSignature('),
-);
-check(
-  '上报异常有 catch（fire-and-forget 的异常会被静默吞掉）',
-  bridgeSource.includes('catch (Exception exception)') && bridgeSource.includes('上报异常'),
-);
-check(
-  '镜像前过滤时间非法的条目（避免档案里出现 00:00 的课次，且必须与 Classes 同步过滤）',
-  read('src/Services/ClassPlanWriter.cs').includes('IsValidTime'),
-);
-check(
-  '上报体带上 deviceKey，且服务端 schema 也声明了该字段（回填机器码的契约两端一致）',
-  clientSource.includes('"deviceKey"') && serverSchemas.includes('deviceKey:'),
-);
-check(
-  '2xx 但不是本服务响应体时给出原因（而不是"成功但无数据 + 空消息"），并限制响应体大小',
-  clientSource.includes('响应不是 ClassHelper的标准格式') &&
-    clientSource.includes('MaxResponseContentBufferSize'),
-);
-check(
-  '提醒提供方惰性获取课程服务并重试（拿不到服务时"上课暂存"会永久失效且静默）',
-  providerSource.includes('EnsureLessons') && providerSource.includes('_lessonsHooked'),
-);
-check(
-  '设置落盘先写临时文件再原子替换（逐字符写盘 + 截断式写入会留下坏 JSON）',
-  pluginSource.includes('File.Move(temp, path, overwrite: true)'),
-);
-check(
-  '服务器地址只接受 http/https（裸 Uri.TryCreate 会放过 file:// / ftp://）',
-  settingsSource.includes('TryGetServerUri') && settingsSource.includes('UriSchemeHttp'),
-);
-
-/* ------------------------------------------------------------ 结果 */
-
-const failed = results.filter((item) => !item.ok);
-for (const item of results) {
-  console.log((item.ok ? '√ ' : '× ') + item.name + (item.detail ? '　（' + item.detail + '）' : ''));
-}
-console.log('');
-console.log(
-  'ClassIsland 联动插件静态校验：' + (results.length - failed.length) + '/' + results.length + ' 项通过',
-);
-if (failed.length > 0) {
-  console.log('未通过：\n  - ' + failed.map((item) => item.name).join('\n  - '));
-  process.exit(1);
-}

packages/classisland-plugin/src/Interop/ClassHelperClient.cs

@@ -1,485 +0,0 @@
-using System.Net;
-using System.Net.Http;
-using System.Net.Sockets;
-using System.Net.Http.Headers;
-using System.Net.Http.Json;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using ClassHelper.ClassIslandPlugin.Models;
-
-namespace ClassHelper.ClassIslandPlugin.Interop;
-
-/* ---------------------------------------------------------------- 服务端契约（与 packages/shared 保持一致） */
-
-/// <summary>插件上报的课表条目。</summary>
-public class ScheduleEntryDto
-{
-    [JsonPropertyName("dayOfWeek")] public int DayOfWeek { get; set; }
-    [JsonPropertyName("startTime")] public string StartTime { get; set; } = "";
-    [JsonPropertyName("endTime")] public string EndTime { get; set; } = "";
-    [JsonPropertyName("subject")] public string Subject { get; set; } = "";
-    [JsonPropertyName("teacherName")] public string? TeacherName { get; set; }
-    /// <summary>ALL / ODD / EVEN；留空则由服务端按 weekCountDiv 推导。</summary>
-    [JsonPropertyName("weekParity")] public string? WeekParity { get; set; }
-    [JsonPropertyName("weekCountDiv")] public int WeekCountDiv { get; set; }
-    [JsonPropertyName("weekCountDivTotal")] public int WeekCountDivTotal { get; set; }
-    [JsonPropertyName("planName")] public string? PlanName { get; set; }
-}
-
-/// <summary>插件上报的节次时间。</summary>
-public class TimeLayoutItemDto
-{
-    [JsonPropertyName("index")] public int Index { get; set; }
-    [JsonPropertyName("name")] public string Name { get; set; } = "";
-    [JsonPropertyName("startTime")] public string StartTime { get; set; } = "";
-    [JsonPropertyName("endTime")] public string EndTime { get; set; } = "";
-    /// <summary>class / break / divider / action</summary>
-    [JsonPropertyName("type")] public string Type { get; set; } = "class";
-    [JsonPropertyName("skipped")] public bool Skipped { get; set; }
-}
-
-/// <summary>本机运行状态快照。</summary>
-public class StateDto
-{
-    [JsonPropertyName("inClass")] public bool InClass { get; set; }
-    [JsonPropertyName("subject")] public string? Subject { get; set; }
-    [JsonPropertyName("nextSubject")] public string? NextSubject { get; set; }
-    [JsonPropertyName("timeState")] public string? TimeState { get; set; }
-    [JsonPropertyName("periodStart")] public string? PeriodStart { get; set; }
-    [JsonPropertyName("periodEnd")] public string? PeriodEnd { get; set; }
-    [JsonPropertyName("week")] public int? Week { get; set; }
-    [JsonPropertyName("classPlanLoaded")] public bool ClassPlanLoaded { get; set; }
-    [JsonPropertyName("clientTime")] public string ClientTime { get; set; } = "";
-}
-
-public class SchedulePayloadDto
-{
-    [JsonPropertyName("mode")] public string Mode { get; set; } = "merge";
-    [JsonPropertyName("entries")] public List<ScheduleEntryDto> Entries { get; set; } = new();
-}
-
-public class TimeLayoutPayloadDto
-{
-    [JsonPropertyName("name")] public string Name { get; set; } = "ClassIsland 时间表";
-    [JsonPropertyName("mode")] public string Mode { get; set; } = "replace";
-    [JsonPropertyName("items")] public List<TimeLayoutItemDto> Items { get; set; } = new();
-}
-
-public class ReportRequestDto
-{
-    [JsonPropertyName("pluginVersion")] public string PluginVersion { get; set; } = "";
-    [JsonPropertyName("classIslandVersion")] public string ClassIslandVersion { get; set; } = "";
-    /// <summary>本机机器码：设备创建时服务端还不知道它，靠这里回填（见服务端 syncDeviceKey）。</summary>
-    [JsonPropertyName("deviceKey")] public string DeviceKey { get; set; } = "";
-    [JsonPropertyName("state")] public StateDto? State { get; set; }
-    [JsonPropertyName("schedule")] public SchedulePayloadDto? Schedule { get; set; }
-    [JsonPropertyName("timeLayout")] public TimeLayoutPayloadDto? TimeLayout { get; set; }
-}
-
-public class ReportSettingsDto
-{
-    [JsonPropertyName("mirrorScheduleToClassIsland")] public bool MirrorScheduleToClassIsland { get; set; }
-    [JsonPropertyName("enabled")] public bool Enabled { get; set; }
-
-    /// <summary>
-    /// 服务端请求**立刻上报一次课表**（老师在 Web 端点了「从教室机器获取课表」）。
-    ///
-    /// 它与本机的「上报课表到 ClassHelper」开关无关：那个开关管的是"要不要**自动**回传"，
-    /// 现在是默认关闭的；而这是一次显式的人工请求，看到就要照做。
-    /// </summary>
-    [JsonPropertyName("scheduleRequested")] public bool ScheduleRequested { get; set; }
-
-    /// <summary>
-    /// 服务端请求**下发一次课表到教室**（老师在 Web 端点了「下发课表到教室」）。
-    ///
-    /// 与 <see cref="ScheduleRequested"/> 反方向，同样是一次性待办：看到就拉本班课表并
-    /// **强制替换**写进 ClassIsland；拉取成功时由服务端清除标记。
-    /// 没有"后台定时镜像"那条路径了 —— 那会让教室课表被反复重写（见 BridgeService 的说明）。
-    /// </summary>
-    [JsonPropertyName("mirrorRequested")] public bool MirrorRequested { get; set; }
-}
-
-public class ReportResultDto
-{
-    [JsonPropertyName("scheduleApplied")] public bool ScheduleApplied { get; set; }
-    [JsonPropertyName("scheduleCreated")] public int ScheduleCreated { get; set; }
-    [JsonPropertyName("scheduleUpdated")] public int ScheduleUpdated { get; set; }
-    [JsonPropertyName("courses")] public List<string> Courses { get; set; } = new();
-    [JsonPropertyName("timeLayoutApplied")] public bool TimeLayoutApplied { get; set; }
-    [JsonPropertyName("week")] public int Week { get; set; }
-    [JsonPropertyName("serverTime")] public string ServerTime { get; set; } = "";
-    [JsonPropertyName("settings")] public ReportSettingsDto? Settings { get; set; }
-    [JsonPropertyName("pendingNotification")] public PushNotificationDto? PendingNotification { get; set; }
-}
-
-/// <summary>服务端下发的提醒。</summary>
-public class PushNotificationDto
-{
-    [JsonPropertyName("id")] public string Id { get; set; } = "";
-    [JsonPropertyName("title")] public string Title { get; set; } = "";
-    [JsonPropertyName("content")] public string Content { get; set; } = "";
-    [JsonPropertyName("durationSeconds")] public int DurationSeconds { get; set; } = 8;
-    [JsonPropertyName("speechContent")] public string? SpeechContent { get; set; }
-    [JsonPropertyName("createdAt")] public string CreatedAt { get; set; } = "";
-    [JsonPropertyName("urgent")] public bool Urgent { get; set; }
-
-    /// <summary>提醒类型：notification（默认）/ call（叫人，算"主动通知"，上课时段也立刻弹）</summary>
-    [JsonPropertyName("kind")] public string? Kind { get; set; }
-    [JsonPropertyName("classId")] public string ClassId { get; set; } = "";
-    [JsonPropertyName("className")] public string? ClassName { get; set; }
-    [JsonPropertyName("teacherName")] public string? TeacherName { get; set; }
-}
-
-public class PendingResultDto
-{
-    [JsonPropertyName("notifications")] public List<PushNotificationDto> Notifications { get; set; } = new();
-    [JsonPropertyName("serverTime")] public string ServerTime { get; set; } = "";
-    [JsonPropertyName("week")] public int Week { get; set; }
-}
-
-/* ---------------------------------------------------------------- 课表镜像（服务端 → ClassIsland） */
-
-public class ClassPlanEntryMirrorDto
-{
-    [JsonPropertyName("weekDay")] public int WeekDay { get; set; }
-    [JsonPropertyName("weekCountDiv")] public int WeekCountDiv { get; set; }
-    [JsonPropertyName("weekCountDivTotal")] public int WeekCountDivTotal { get; set; }
-    [JsonPropertyName("subject")] public string Subject { get; set; } = "";
-    [JsonPropertyName("teacherName")] public string? TeacherName { get; set; }
-    /// <summary>起止时间（HH:mm）。Classes[i] 必须与第 i 个上课时间点对齐，靠它重建时间表。</summary>
-    [JsonPropertyName("startTime")] public string StartTime { get; set; } = "";
-    [JsonPropertyName("endTime")] public string EndTime { get; set; } = "";
-    [JsonPropertyName("timeLayoutId")] public string TimeLayoutId { get; set; } = "";
-}
-
-public class TimeLayoutMirrorDto
-{
-    [JsonPropertyName("id")] public string Id { get; set; } = "";
-    [JsonPropertyName("name")] public string Name { get; set; } = "";
-    [JsonPropertyName("layouts")] public List<TimeLayoutItemMirrorDto> Layouts { get; set; } = new();
-}
-
-public class TimeLayoutItemMirrorDto
-{
-    [JsonPropertyName("startTime")] public string StartTime { get; set; } = "";
-    [JsonPropertyName("endTime")] public string EndTime { get; set; } = "";
-    [JsonPropertyName("timeType")] public int TimeType { get; set; }
-}
-
-public class ClassPlanMirrorDto
-{
-    [JsonPropertyName("entries")] public List<ClassPlanEntryMirrorDto> Entries { get; set; } = new();
-    [JsonPropertyName("timeLayouts")] public List<TimeLayoutMirrorDto> TimeLayouts { get; set; } = new();
-    [JsonPropertyName("profileName")] public string ProfileName { get; set; } = "";
-    [JsonPropertyName("termStartDate")] public string TermStartDate { get; set; } = "";
-}
-
-/// <summary>服务端逐周配的学期周次区间（管理员在「学期周次」里维护）。</summary>
-public class TermWeekRangeDto
-{
-    [JsonPropertyName("weekNumber")] public int WeekNumber { get; set; }
-    /// <summary>YYYY-MM-DD</summary>
-    [JsonPropertyName("startDate")] public string StartDate { get; set; } = "";
-    /// <summary>YYYY-MM-DD</summary>
-    [JsonPropertyName("endDate")] public string EndDate { get; set; } = "";
-}
-
-public class PullResultDto
-{
-    [JsonPropertyName("classPlan")] public ClassPlanMirrorDto? ClassPlan { get; set; }
-    [JsonPropertyName("week")] public int Week { get; set; }
-
-    /// <summary>
-    /// 学期逐周区间；空 = 服务端只按学期开始日期线性推算。
-    ///
-    /// ClassIsland 自身只认"教学周序号 + 单双周"，没有"按日期区间定义某一周"的模型
-    /// （本机装的 2.1.0.1 没有该字段），所以这份区间在插件侧只用于：
-    /// 1) 校正"现在是第几周"（调休会让线性推算整体错位）；
-    /// 2) 在设置页里显示教室这台机器当前处在哪一段日期区间，方便老师核对。
-    /// 课表本身的周次口径仍由 <see cref="ClassPlanMirrorDto.TermStartDate"/> 与单双周表达。
-    /// </summary>
-    [JsonPropertyName("weekRanges")] public List<TermWeekRangeDto> WeekRanges { get; set; } = new();
-
-    [JsonPropertyName("serverTime")] public string ServerTime { get; set; } = "";
-}
-
-/* ---------------------------------------------------------------- 统一响应体 */
-
-internal class ApiEnvelope<T>
-{
-    [JsonPropertyName("success")] public bool Success { get; set; }
-    [JsonPropertyName("data")] public T? Data { get; set; }
-    [JsonPropertyName("message")] public string Message { get; set; } = "";
-    [JsonPropertyName("code")] public string? Code { get; set; }
-}
-
-/// <summary>调用 ClassHelper后端的结果（不抛异常，便于设置页展示原因）。</summary>
-public class ApiCallResult
-{
-    public bool Ok { get; init; }
-    public string Message { get; init; } = "";
-    public bool NetworkError { get; init; }
-
-    public static ApiCallResult Success(string message) => new() { Ok = true, Message = message };
-    public static ApiCallResult Failure(string message) => new() { Ok = false, Message = message };
-    public static ApiCallResult Offline(string message) => new() { Ok = false, Message = message, NetworkError = true };
-}
-
-/// <summary>
-/// ClassHelper后端客户端。
-///
-/// 只用 <see cref="HttpClient"/> + System.Text.Json：不引入额外依赖包，
-/// 避免插件加载时因为"插件程序集隔离"缺少依赖而无法启动
-/// （见 https://docs.classisland.tech/dev/plugins/basics.html 的程序集隔离说明）。
-/// </summary>
-public sealed class ClassHelperClient : IDisposable
-{
-    /// <summary>
-    /// 单次请求超时。教室机器可能是内网慢链路，但也不该卡住上报线程太久。
-    /// </summary>
-    private static readonly TimeSpan Timeout = TimeSpan.FromSeconds(12);
-
-    /// <summary>
-    /// 响应体上限（4MB）。默认是 2GB —— 服务器地址填错（指到一个会吐大页面的地址）时，
-    /// 一次请求就能在 12 秒内把内存吃光。
-    /// </summary>
-    private const long MaxResponseBytes = 4 * 1024 * 1024;
-
-    private static readonly JsonSerializerOptions JsonOptions = new()
-    {
-        PropertyNameCaseInsensitive = true,
-        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
-        Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
-    };
-
-    /// <summary>
-    /// 与 ClassHelper通信的 HttpClient。
-    ///
-    /// **必须显式处理代理**：教室机器（以及开发机）常常配了系统代理，
-    /// 而 Windows 的代理设置默认连 `127.0.0.1` 也会走代理 —— 于是"填写令牌后立刻 HTTP 404"，
-    /// 那个 404 其实是**代理自己的错误页**，跟本服务毫无关系。
-    /// 因此这里用 <see cref="LocalAwareProxy"/>：本地/内网地址直连，公网地址照旧走系统代理。
-    /// </summary>
-    private readonly HttpClient _http = new(new SocketsHttpHandler { Proxy = new LocalAwareProxy() })
-    {
-        Timeout = Timeout,
-        MaxResponseContentBufferSize = MaxResponseBytes,
-    };
-
-    public string LastError { get; private set; } = "";
-    public DateTimeOffset? LastSuccessAt { get; private set; }
-
-    /// <summary>
-    /// 包装系统代理：**本地/内网地址标记为"绕过"**，其余交给系统代理决定。
-    ///
-    /// 判定为本地/内网的情形：localhost、回环地址、IPv4/IPv6 私有段与链路本地段，
-    /// 以及不含点的主机名（`server` / `classhelper` 这类校内机器名，DNS 也可能解析不出来）。
-    /// 判定为公网时保持原行为，避免"云服务器 + 公司代理"这种场景被我们改坏。
-    /// </summary>
-    private sealed class LocalAwareProxy : IWebProxy
-    {
-        private readonly IWebProxy _inner = HttpClient.DefaultProxy;
-
-        // 只读透传即可：HttpClient.DefaultProxy 是全局单例，改它的凭据会波及宿主进程里的其它请求
-        public ICredentials? Credentials { get; set; }
-
-        public Uri? GetProxy(Uri destination) => _inner.GetProxy(destination);
-
-        public bool IsBypassed(Uri host) => IsLocalHost(host) || _inner.IsBypassed(host);
-
-        /// <summary>该地址是否属于"不该走代理"的本地/内网范围。</summary>
-        internal static bool IsLocalHost(Uri uri)
-        {
-            var host = uri.Host;
-            if (host.Equals("localhost", StringComparison.OrdinalIgnoreCase)) return true;
-            // 不含点的主机名（校内机器名）走直连：解析成内网 IP 的可能性远大于公网
-            if (!host.Contains('.')) return true;
-
-            if (!IPAddress.TryParse(host, out var address)) return false;
-            if (IPAddress.IsLoopback(address)) return true;
-
-            if (address.AddressFamily == AddressFamily.InterNetwork)
-            {
-                var bytes = address.GetAddressBytes();
-                return bytes[0] == 10                                            // 10.0.0.0/8
-                       || (bytes[0] == 172 && bytes[1] >= 16 && bytes[1] <= 31)  // 172.16.0.0/12
-                       || (bytes[0] == 192 && bytes[1] == 168)                   // 192.168.0.0/16
-                       || (bytes[0] == 169 && bytes[1] == 254);                  // 169.254.0.0/16（链路本地）
-            }
-
-            // IPv6：fc00::/7（唯一本地地址）与 fe80::/10（链路本地）
-            var first = address.GetAddressBytes()[0];
-            return (first & 0xFE) == 0xFC || (first & 0xC0) == 0x80;
-        }
-    }
-
-    /// <summary>拼接 API 地址，容忍用户填了带/不带末尾斜杠、甚至带 /api 后缀的地址。</summary>
-    private static string BuildUrl(string serverUrl, string path)
-    {
-        var baseUrl = (serverUrl ?? "").Trim().TrimEnd('/');
-        if (baseUrl.EndsWith("/api", StringComparison.OrdinalIgnoreCase))
-        {
-            baseUrl = baseUrl[..^4];
-        }
-        return $"{baseUrl}/api/integrations{path}";
-    }
-
-    private HttpRequestMessage BuildRequest(HttpMethod method, string serverUrl, string path, string token)
-    {
-        var request = new HttpRequestMessage(method, BuildUrl(serverUrl, path));
-        if (!string.IsNullOrWhiteSpace(token))
-        {
-            request.Headers.TryAddWithoutValidation("X-ClassIsland-Token", token);
-        }
-        return request;
-    }
-
-    private async Task<ApiEnvelope<T>?> SendAsync<T>(
-        HttpMethod method,
-        string serverUrl,
-        string path,
-        string token,
-        object? body,
-        CancellationToken cancellationToken)
-    {
-        try
-        {
-            using var request = BuildRequest(method, serverUrl, path, token);
-            if (body is not null)
-            {
-                var json = JsonSerializer.Serialize(body, JsonOptions);
-                request.Content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
-            }
-
-            using var response = await _http.SendAsync(request, cancellationToken).ConfigureAwait(false);
-            var text = await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-
-            ApiEnvelope<T>? envelope = null;
-            try
-            {
-                envelope = JsonSerializer.Deserialize<ApiEnvelope<T>>(text, JsonOptions);
-            }
-            catch (JsonException)
-            {
-                // 非 JSON 响应（例如被网关拦截）——交给下面的兜底分支
-            }
-
-            if (!response.IsSuccessStatusCode)
-            {
-                var message = envelope?.Message;
-                if (string.IsNullOrWhiteSpace(message))
-                {
-                    // 响应不是本服务的统一响应体：最常见的原因就是被系统代理 / 网关拦下来
-                    // （典型表现：HTTP 404 且 body 是一张 HTML 错误页）。把 URL 一起报出来，
-                    // 老师截图给我们就能一眼定位。
-                    message = envelope is null
-                        ? $"HTTP {(int)response.StatusCode}（{method.Method} {request.RequestUri}）——" +
-                          "响应不是 ClassHelper的标准格式，请检查服务器地址是否正确、" +
-                          "或该系统代理是否拦截了内网请求"
-                        : $"HTTP {(int)response.StatusCode}（{method.Method} {request.RequestUri}）";
-                }
-                LastError = message!;
-                return envelope ?? new ApiEnvelope<T> { Success = false, Message = message! };
-            }
-
-            if (envelope is null)
-            {
-                // 2xx 但响应不是本服务的统一响应体（网关/反代的 HTML 错误页、地址指到了别的服务等）。
-                // 必须留下原因：否则调用方拿到的是"成功但无数据 + 空错误消息"，
-                // 设置页显示"连接异常"却没有原因，与上面专门为代理错误页写的诊断自相矛盾。
-                LastError =
-                    $"HTTP {(int)response.StatusCode}（{method.Method} {request.RequestUri}）——" +
-                    "响应不是 ClassHelper的标准格式，请检查服务器地址是否正确，或该系统代理是否拦截了内网请求";
-                return new ApiEnvelope<T> { Success = false, Message = LastError };
-            }
-
-            LastError = "";
-            LastSuccessAt = DateTimeOffset.Now;
-            return envelope;
-        }
-        catch (TaskCanceledException) when (!cancellationToken.IsCancellationRequested)
-        {
-            LastError = "请求超时（请检查服务器地址与网络）";
-            return null;
-        }
-        catch (HttpRequestException exception)
-        {
-            LastError = $"无法连接 ClassHelper服务：{exception.Message}";
-            return null;
-        }
-        catch (Exception exception)
-        {
-            LastError = exception.Message;
-            return null;
-        }
-    }
-
-    /// <summary>上报状态 +（可选）课表。</summary>
-    public async Task<(ApiCallResult Result, ReportResultDto? Data)> ReportAsync(
-        PluginSettings settings,
-        ReportRequestDto payload,
-        CancellationToken cancellationToken)
-    {
-        var envelope = await SendAsync<ReportResultDto>(
-            HttpMethod.Post, settings.ServerUrl, "/classisland/report", settings.DeviceToken, payload, cancellationToken);
-        if (envelope is null)
-        {
-            return (ApiCallResult.Offline(LastError), null);
-        }
-        if (!envelope.Success || envelope.Data is null)
-        {
-            return (ApiCallResult.Failure(envelope.Message.Length > 0 ? envelope.Message : LastError), null);
-        }
-        return (ApiCallResult.Success(envelope.Message), envelope.Data);
-    }
-
-    /// <summary>拉取尚未确认的下发提醒（插件启动/重连时补齐）。</summary>
-    public async Task<(ApiCallResult Result, List<PushNotificationDto> Items)> PendingAsync(
-        PluginSettings settings,
-        CancellationToken cancellationToken)
-    {
-        var envelope = await SendAsync<PendingResultDto>(
-            HttpMethod.Get, settings.ServerUrl, "/classisland/pending", settings.DeviceToken, null, cancellationToken);
-        if (envelope is null) return (ApiCallResult.Offline(LastError), new List<PushNotificationDto>());
-        if (!envelope.Success || envelope.Data is null)
-        {
-            return (ApiCallResult.Failure(envelope.Message.Length > 0 ? envelope.Message : LastError),
-                new List<PushNotificationDto>());
-        }
-        return (ApiCallResult.Success(envelope.Message), envelope.Data.Notifications);
-    }
-
-    /// <summary>确认提醒已弹出（之后服务端不再补发）。</summary>
-    public async Task<ApiCallResult> AckAsync(PluginSettings settings, string id, CancellationToken cancellationToken)
-    {
-        var envelope = await SendAsync<JsonElement>(
-            HttpMethod.Post, settings.ServerUrl, "/classisland/ack", settings.DeviceToken, new { id }, cancellationToken);
-        if (envelope is null) return ApiCallResult.Offline(LastError);
-        return envelope.Success
-            ? ApiCallResult.Success("已确认")
-            : ApiCallResult.Failure(envelope.Message.Length > 0 ? envelope.Message : LastError);
-    }
-
-    /// <summary>拉取班级课表（用于镜像回 ClassIsland）。未开启镜像时服务端返回 data=null。</summary>
-    public async Task<(ApiCallResult Result, ClassPlanMirrorDto? Plan)> PullClassPlanAsync(
-        PluginSettings settings,
-        CancellationToken cancellationToken)
-    {
-        var envelope = await SendAsync<PullResultDto>(
-            HttpMethod.Get, settings.ServerUrl, "/classisland/class-plan", settings.DeviceToken, null, cancellationToken);
-        if (envelope is null) return (ApiCallResult.Offline(LastError), null);
-        if (!envelope.Success)
-        {
-            return (ApiCallResult.Failure(envelope.Message.Length > 0 ? envelope.Message : LastError), null);
-        }
-        if (envelope.Data?.ClassPlan is null)
-        {
-            return (ApiCallResult.Failure(envelope.Message.Length > 0
-                ? envelope.Message
-                : "该设备未开启「把班级课表镜像到 ClassIsland」"), null);
-        }
-        return (ApiCallResult.Success(envelope.Message), envelope.Data.ClassPlan);
-    }
-
-    public void Dispose() => _http.Dispose();
-}

packages/classisland-plugin/src/Models/PluginSettings.cs

@@ -1,159 +0,0 @@
-using CommunityToolkit.Mvvm.ComponentModel;
-
-namespace ClassHelper.ClassIslandPlugin.Models;
-
-/// <summary>
-/// 插件设置。
-///
-/// 存储由 ClassIsland 负责：插件入口把它保存在 <c>PluginConfigFolder/Settings.json</c>
-/// （**不要**放在插件安装目录，那里不会随档案备份、升级时还会被清掉）。
-/// 因此这里必须继承 <see cref="ObservableObject"/> 并让每个属性都走 <c>SetProperty</c>：
-/// ClassIsland 通过监听 <c>PropertyChanged</c> 来即时保存。
-/// </summary>
-public class PluginSettings : ObservableObject
-{
-    private string _serverUrl = "http://127.0.0.1:4000";
-    private string _deviceToken = "";
-    private string _deviceKey = "";
-    private bool _autoReport = true;
-    private int _reportIntervalSeconds = 60;
-    // 课表同步（2026-10-11 起）：**两个方向都只由 Web 端的一次性动作触发** ——
-    // 「从教室机器获取课表」与「下发课表到教室」，都走服务端的一个待办标记。
-    // 原先这里有两个开关（自动回传 / 自动镜像），默认 15 秒一轮，结果是服务端与教室里
-    // 的课表每 15 秒互相覆盖一次，老师看到的就是"课表被反复删改"。
-    // 定时上报现在**只报运行状态**（当前上什么课），不带课表。
-    private bool _receiveNotifications = true;
-    private int _notificationDurationSeconds = 8;
-    private int _notificationPollSeconds = 10;
-    private bool _speechEnabled = false;
-    private bool _showDebugInfo = false;
-
-    /// <summary>
-    /// ClassHelper后端地址，例如 <c>http://127.0.0.1:4000</c>。
-    /// </summary>
-    public string ServerUrl
-    {
-        get => _serverUrl;
-        set => SetProperty(ref _serverUrl, value);
-    }
-
-    /// <summary>
-    /// 设备令牌（形如 <c>chci_...</c>）：在 ClassHelper Web 端「ClassIsland 联动」页面生成。
-    /// </summary>
-    public string DeviceToken
-    {
-        get => _deviceToken;
-        // 在 setter 里就去掉首尾空白：粘贴令牌时带前导空格非常常见，
-        // 而 Normalize() 只在启动加载时跑一次 —— 运行期粘进来的脏值会让 IsConfigured
-        // 一直为 false，用户看着明明填好了却查不出原因。
-        set => SetProperty(ref _deviceToken, (value ?? "").Trim());
-    }
-
-    /// <summary>
-    /// 本机标识（首次生成后固定）：服务端据此把同一台机器识别为同一设备，重装插件不会产生重复设备。
-    /// </summary>
-    public string DeviceKey
-    {
-        get => _deviceKey;
-        set => SetProperty(ref _deviceKey, value);
-    }
-
-    /// <summary>
-    /// 是否自动上报：启动后、课表变化时、以及每隔 <see cref="ReportIntervalSeconds"/> 秒各上报一次。
-    /// </summary>
-    public bool AutoReport
-    {
-        get => _autoReport;
-        set => SetProperty(ref _autoReport, value);
-    }
-
-    /// <summary>
-    /// 定时上报间隔（秒），最小 15 秒。
-    /// </summary>
-    public int ReportIntervalSeconds
-    {
-        get => _reportIntervalSeconds;
-        set => SetProperty(ref _reportIntervalSeconds, Math.Clamp(value, 15, 3600));
-    }
-
-    /// <summary>
-    /// 是否接收老师在 ClassHelper上发布的提醒，并在 ClassIsland 上弹出。
-    /// </summary>
-    public bool ReceiveNotifications
-    {
-        get => _receiveNotifications;
-        set => SetProperty(ref _receiveNotifications, value);
-    }
-
-    /// <summary>
-    /// 提醒轮询间隔（秒），最小 5 秒。
-    ///
-    /// 插件与后端之间没有长连接（刻意不引入 Socket 依赖），提醒是"轮询取回"的，
-    /// 因此这个值就是**老师按下发送到教室弹出之间的最大延迟**。
-    /// 单独一个轻量轮询（只查待提醒，不上传课表）比把上报间隔改小划算得多。
-    /// </summary>
-    public int NotificationPollSeconds
-    {
-        get => _notificationPollSeconds;
-        set => SetProperty(ref _notificationPollSeconds, Math.Clamp(value, 5, 600));
-    }
-
-    /// <summary>
-    /// 默认提醒显示时长（秒）；老师在下发时可以单独指定更长的时长。
-    /// </summary>
-    public int NotificationDurationSeconds
-    {
-        get => _notificationDurationSeconds;
-        set => SetProperty(ref _notificationDurationSeconds, Math.Clamp(value, 1, 120));
-    }
-
-    /// <summary>
-    /// 提醒弹出时是否语音朗读（沿用 ClassIsland 的语音设置与语音提供方）。
-    /// </summary>
-    public bool SpeechEnabled
-    {
-        get => _speechEnabled;
-        set => SetProperty(ref _speechEnabled, value);
-    }
-
-    /// <summary>
-    /// 是否在设置页显示调试信息（最后一次上报结果、课表条目数等），排查问题时打开。
-    /// </summary>
-    public bool ShowDebugInfo
-    {
-        get => _showDebugInfo;
-        set => SetProperty(ref _showDebugInfo, value);
-    }
-
-    /// <summary>
-    /// 兼容旧配置：反序列化后把 DeviceKey 补齐（首次运行时由服务生成）。
-    /// </summary>
-    public void Normalize()
-    {
-        ServerUrl = (ServerUrl ?? "").Trim().TrimEnd('/');
-        DeviceToken = (DeviceToken ?? "").Trim();
-        DeviceKey = (DeviceKey ?? "").Trim();
-        ReportIntervalSeconds = Math.Clamp(ReportIntervalSeconds, 15, 3600);
-        NotificationDurationSeconds = Math.Clamp(NotificationDurationSeconds, 1, 120);
-        NotificationPollSeconds = Math.Clamp(NotificationPollSeconds, 5, 600);
-    }
-
-    /// <summary>是否已经配置好（地址 + 令牌都填了）。</summary>
-    public bool IsConfigured =>
-        TryGetServerUri(out _) && DeviceToken.StartsWith("chci_", StringComparison.Ordinal);
-
-    /// <summary>
-    /// 解析服务器地址，**只接受 http/https 绝对地址**。
-    ///
-    /// 不用裸的 `Uri.TryCreate(..., UriKind.Absolute)`：它会接受 `file://` / `ftp://`，
-    /// 那种地址会在发请求时抛一句难以理解的 NotSupportedException，用户根本猜不到是地址填错了。
-    /// </summary>
-    public bool TryGetServerUri(out Uri uri)
-    {
-        uri = null!;
-        if (!Uri.TryCreate((ServerUrl ?? "").Trim(), UriKind.Absolute, out var parsed)) return false;
-        if (parsed.Scheme != Uri.UriSchemeHttp && parsed.Scheme != Uri.UriSchemeHttps) return false;
-        uri = parsed;
-        return true;
-    }
-}

packages/classisland-plugin/src/Plugin.cs

@@ -1,171 +0,0 @@
-using System.Text.Json;
-using ClassHelper.ClassIslandPlugin.Models;
-using ClassHelper.ClassIslandPlugin.Services;
-using ClassHelper.ClassIslandPlugin.Views;
-using ClassIsland.Core;
-using ClassIsland.Core.Abstractions;
-using ClassIsland.Core.Abstractions.Services;
-using ClassIsland.Core.Attributes;
-using ClassIsland.Core.Extensions.Registry;
-using ClassIsland.Shared;
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Logging;
-
-namespace ClassHelper.ClassIslandPlugin;
-
-/// <summary>
-/// 插件入口。
-///
-/// 职责只有三件：读配置 → 注册扩展（提醒提供方 / 设置页 / 联动服务）→ 在应用启动后接上课程服务。
-/// 真正的联动逻辑都在 <see cref="BridgeService"/> 里，入口保持"看一眼就知道装了哪些东西"。
-/// </summary>
-[PluginEntrance]
-public class Plugin : PluginBase
-{
-    /// <summary>插件设置文件名。存在 <see cref="PluginBase.PluginConfigFolder"/> 下：随档案备份走，升级插件不丢。</summary>
-    private const string SettingsFileName = "Settings.json";
-
-    private static readonly JsonSerializerOptions JsonOptions = new()
-    {
-        WriteIndented = true,
-        Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
-    };
-
-    /// <summary>插件设置。注册成单例后，设置页与 <see cref="BridgeService"/> 拿到的是同一个对象。</summary>
-    public PluginSettings Settings { get; private set; } = new();
-
-    /// <summary>联动只接一次（AppStarted 与"运行中启用"两条路都会走到这里）</summary>
-    private bool _bridgeStarted;
-
-    public override void Initialize(HostBuilderContext context, IServiceCollection services)
-    {
-        Settings = LoadSettings();
-
-        // 设置页与联动服务共用一个实例：设置页改了值，服务立刻能看到（不需要重启 ClassIsland）
-        services.AddSingleton(Settings);
-        services.AddSingleton<BridgeService>();
-
-        services.AddSettingsPage<BridgeSettingsPage>();
-        services.AddNotificationProvider<ClassHelperNotificationProvider>();
-
-        // 初始化阶段课程服务还没准备好（它在主机启动流程里才被创建），
-        // 因此这里先挂一个"应用已启动"的回调，等到那时再取 ILessonsService 并开始上报。
-        var application = AppBase.Current;
-        if (application is null)
-        {
-            Logger?.LogError("ClassHelper 联动：拿不到 ClassIsland 应用实例，联动未启动");
-            return;
-        }
-
-        application.AppStarted += (_, _) => StartBridge();
-
-        // 插件是"运行中才被启用"时，AppStarted 早就过去了 —— 主窗口已经存在就直接接一次
-        if (application.MainWindow is not null) StartBridge();
-    }
-
-    private void StartBridge()
-    {
-        if (_bridgeStarted) return;
-        try
-        {
-            var lessons = IAppHost.TryGetService<ILessonsService>();
-            if (lessons is null)
-            {
-                Logger?.LogError("ClassHelper 联动：拿不到课程服务，联动已停用");
-                return;
-            }
-
-            var bridge = IAppHost.TryGetService<BridgeService>();
-            if (bridge is null)
-            {
-                Logger?.LogError("ClassHelper 联动：拿不到联动服务，联动已停用");
-                return;
-            }
-
-            _bridgeStarted = true;
-            bridge.Attach(lessons);
-            bridge.RestartTimer();
-            // 应用刚起来时还没有第一个上报点，先主动拉一次未弹出的提醒（离线期间老师发的通知）：
-            // 不这么做的话，最长要等一个上报间隔才会弹出来
-            _ = bridge.PullPendingAsync();
-            Logger?.LogInformation("ClassHelper 联动：已接入课程服务（服务器 {Server}）", Settings.ServerUrl);
-        }
-        catch (Exception exception)
-        {
-            // 联动失败绝不能把 ClassIsland 本体拖下水
-            Logger?.LogError(exception, "ClassHelper 联动：初始化联动服务失败");
-        }
-    }
-
-    private ILogger<Plugin>? Logger => IAppHost.TryGetService<ILogger<Plugin>>();
-
-    /// <summary>
-    /// 读取设置。首次运行时 <c>DeviceKey</c> 为空，这里补一个随机值并立即落盘 ——
-    /// 服务端用它把同一台机器识别为同一设备，重装插件不会堆出重复设备。
-    /// </summary>
-    private PluginSettings LoadSettings()
-    {
-        var path = Path.Combine(PluginConfigFolder, SettingsFileName);
-        var settings = new PluginSettings();
-        try
-        {
-            if (File.Exists(path))
-            {
-                var loaded = JsonSerializer.Deserialize<PluginSettings>(File.ReadAllText(path), JsonOptions);
-                if (loaded is not null) settings = loaded;
-            }
-        }
-        catch (Exception exception)
-        {
-            // 配置损坏不该拦住插件加载：用默认值继续，原文件保留供排查
-            IAppHost.TryGetService<ILogger<Plugin>>()?.LogWarning(exception,
-                "ClassHelper 联动：读取设置失败，已回退到默认设置（{Path}）", path);
-        }
-
-        var needGenerateKey = string.IsNullOrWhiteSpace(settings.DeviceKey);
-        settings.Normalize();
-        if (needGenerateKey)
-        {
-            // 机器名 + 随机短码：既是人眼可读的"这台机器"，又不会两台同名机器撞车。
-            // 注意长度：原先写的是 `[..Math.Min(24, machine.Length + 33)]`，而 machine.Length + 33
-            // 恒大于 24，所以实际**永远只取前 24 个字符** —— 机器名稍长就把随机段整个切掉，
-            // "同名机器不撞车"的保障就没了。这里改成"机器名按需截短 + 保留 8 位随机段"。
-            var machine = Environment.MachineName.ToLowerInvariant();
-            var suffix = Guid.NewGuid().ToString("N")[..8];
-            var maxMachineLength = Math.Max(4, 24 - suffix.Length - 1);
-            if (machine.Length > maxMachineLength) machine = machine[..maxMachineLength];
-            settings.DeviceKey = $"{machine}-{suffix}";
-        }
-
-        Settings = settings;
-        // 落盘：一是固定首次生成的 DeviceKey，二是把缺字段的旧配置补齐成完整文件
-        SaveSettings(settings, path);
-        // 设置变化时即时保存
-        settings.PropertyChanged += (_, _) => SaveSettings(settings, path);
-        return settings;
-    }
-
-    private static void SaveSettings(PluginSettings settings, string path)
-    {
-        try
-        {
-            var folder = Path.GetDirectoryName(path);
-            if (!string.IsNullOrEmpty(folder)) Directory.CreateDirectory(folder);
-            // 先写临时文件再原子替换。
-            //
-            // 设置页的地址/令牌输入框是 TwoWay 绑定（逐字符提交），直接 `File.WriteAllText`
-            // 会就地截断原文件；一旦此刻进程被杀或断电，留下的是半截 JSON，而 LoadSettings 的
-            // catch 会**静默回退到默认设置** —— 用户看到的是"令牌和地址莫名其妙没了"，
-            // 而且原文件已被覆盖，无从恢复。
-            var temp = path + ".tmp";
-            File.WriteAllText(temp, JsonSerializer.Serialize(settings, JsonOptions));
-            File.Move(temp, path, overwrite: true);
-        }
-        catch (Exception exception)
-        {
-            IAppHost.TryGetService<ILogger<Plugin>>()?.LogWarning(exception,
-                "ClassHelper 联动：保存设置失败（{Path}）", path);
-        }
-    }
-}

packages/classisland-plugin/src/Services/BridgeService.cs

@@ -1,647 +0,0 @@
-using System.ComponentModel;
-using System.Runtime.CompilerServices;
-using System.Text;
-using Avalonia.Threading;
-using ClassHelper.ClassIslandPlugin.Interop;
-using ClassHelper.ClassIslandPlugin.Models;
-using ClassIsland.Core;
-using ClassIsland.Core.Abstractions.Services;
-using ClassIsland.Core.Models.Notification;
-using ClassIsland.Shared;
-using Microsoft.Extensions.Logging;
-
-namespace ClassHelper.ClassIslandPlugin.Services;
-
-/// <summary>
-/// 联动主循环。三件事：
-/// 1. <b>上报</b>：应用启动后、课程事件（上课/下课/放学/状态变化）发生时、以及每 N 秒，
-///    把"当前上什么课"与（可选的）全量课表推给 ClassHelper；
-/// 2. <b>接收</b>：每次上报的返回值里带一条"尚未确认的下发提醒"，
-///    交给 <see cref="ClassHelperNotificationProvider"/> 在 ClassIsland 上弹出；
-/// 3. <b>镜像</b>：开启镜像开关时，把 ClassHelper上排好的课表写回 ClassIsland 档案。
-///
-/// 为什么用"上报即拉取"而不是长连接：
-/// 插件不需要额外的 Socket/WebSocket 依赖（避免程序集隔离带来的加载问题），
-/// 而教室机器的上报间隔本身就是心跳 —— 顺路把待提醒带回来，依赖更少、故障面更小。
-///
-/// 线程约定：HttpClient 回调在线程池上，因此所有跨线程可见的状态都用 <c>lock</c> 或
-/// 赋值引用（<c>string</c> / <c>int</c>）保护，属性变化通过 <see cref="PropertyChanged"/> 通知设置页。
-/// </summary>
-public sealed class BridgeService : INotifyPropertyChanged, IDisposable
-{
-    private readonly PluginSettings _settings;
-    private readonly ILogger<BridgeService> _logger;
-    private readonly ClassHelperClient _client = new();
-    private readonly object _gate = new();
-
-    private ILessonsService? _lessons;
-    private Timer? _timer;
-    private Timer? _notifyTimer;
-    private bool _disposed;
-    private bool _reporting;
-    private bool _pulling;
-    private bool _eventsHooked;
-    /// <summary>
-    /// 上次成功镜像的课表内容指纹。内容没变就完全跳过镜像：既省掉每分钟一次的全量重建 + 落盘，
-    /// 也把"跨线程改档案"的窗口从"每分钟一次"降回"只在课表真的变化时"。
-    /// </summary>
-    private volatile string? _lastMirrorSignature;
-
-    public BridgeService(PluginSettings settings, ILogger<BridgeService> logger)
-    {
-        _settings = settings;
-        _logger = logger;
-    }
-
-    public event PropertyChangedEventHandler? PropertyChanged;
-
-    /// <summary>上报结果变化时触发（设置页据此刷新）。</summary>
-    public event EventHandler? StateChanged;
-
-    /// <summary>需要把提醒丢给提醒提供方去显示。</summary>
-    public event EventHandler<PushNotificationDto>? NotificationReceived;
-
-    /* ---------------------------------------------------------------- 供设置页绑定的状态 */
-
-    private string _lastReportMessage = "尚未上报";
-
-    /// <summary>最近一次上报的结果描述。</summary>
-    public string LastReportMessage
-    {
-        get => _lastReportMessage;
-        private set => SetField(ref _lastReportMessage, value);
-    }
-
-    private bool _lastReportOk;
-    public bool LastReportOk
-    {
-        get => _lastReportOk;
-        private set => SetField(ref _lastReportOk, value);
-    }
-
-    private DateTimeOffset? _lastReportAt;
-    public DateTimeOffset? LastReportAt
-    {
-        get => _lastReportAt;
-        private set
-        {
-            if (SetField(ref _lastReportAt, value)) Raise(nameof(LastReportAtText));
-        }
-    }
-
-    /// <summary>供界面直接显示的"最后上报时间"。</summary>
-    public string LastReportAtText => LastReportAt is null
-        ? "从未"
-        : LastReportAt.Value.LocalDateTime.ToString("yyyy-MM-dd HH:mm:ss");
-
-    private int _lastScheduleEntryCount;
-    /// <summary>最近一次上报里的课表条目数。</summary>
-    public int LastScheduleEntryCount
-    {
-        get => _lastScheduleEntryCount;
-        private set => SetField(ref _lastScheduleEntryCount, value);
-    }
-
-    private int _lastTimeLayoutItemCount;
-    /// <summary>最近一次上报里的节次数量。</summary>
-    public int LastTimeLayoutItemCount
-    {
-        get => _lastTimeLayoutItemCount;
-        private set => SetField(ref _lastTimeLayoutItemCount, value);
-    }
-
-    private int? _lastServerWeek;
-    /// <summary>服务端返回的教学周。</summary>
-    public int? LastServerWeek
-    {
-        get => _lastServerWeek;
-        private set
-        {
-            if (SetField(ref _lastServerWeek, value)) Raise(nameof(ClientTimeOffsetText));
-        }
-    }
-
-    private int _notificationCount;
-    /// <summary>已弹出并回执的提醒数量。</summary>
-    public int NotificationCount
-    {
-        get => _notificationCount;
-        private set => SetField(ref _notificationCount, value);
-    }
-
-    private bool _busy;
-    /// <summary>是否正在上报（"立即上报"按钮据此禁用）。</summary>
-    public bool Busy
-    {
-        get => _busy;
-        private set => SetField(ref _busy, value);
-    }
-
-    private TimeSpan? _serverTimeOffset;
-    /// <summary>服务端与本机的时钟差（诊断用：差得多说明教室机器时间不对）。</summary>
-    public string ClientTimeOffsetText => _serverTimeOffset is null
-        ? "—"
-        : $"{_serverTimeOffset.Value.TotalSeconds:+0;-0;0} 秒";
-
-    /// <summary>当前配置是否完整（设置页据此提示"还没填令牌"）。</summary>
-    public bool IsConfigured => _settings.IsConfigured;
-
-    /// <summary>是否已接入课程服务（拿到 ILessonsService 才算真正跑起来）。</summary>
-    public bool IsAttached
-    {
-        get { lock (_gate) return _lessons is not null; }
-    }
-
-    /* ---------------------------------------------------------------- 生命周期 */
-
-    /// <summary>接入课程服务并订阅课程事件（由插件入口在 AppStarted 时调用）。</summary>
-    public void Attach(ILessonsService lessons)
-    {
-        lock (_gate)
-        {
-            _lessons = lessons;
-        }
-
-        if (!_eventsHooked)
-        {
-            // 上课 / 下课 / 放学 / 状态变化时立刻上报一次，不等到下一个定时点。
-            // 这些事件在 ClassIsland 的公开约定里是在**主线程**触发的，可以直接订阅。
-            lessons.OnClass += (_, _) => RequestReport("上课");
-            lessons.OnBreakingTime += (_, _) => RequestReport("下课");
-            lessons.OnAfterSchool += (_, _) => RequestReport("放学");
-            lessons.CurrentTimeStateChanged += (_, _) => RequestReport("状态变化");
-            _eventsHooked = true;
-        }
-
-        Raise(nameof(IsAttached));
-        _logger.LogInformation("ClassHelper 联动：已订阅课程事件");
-        RequestReport("应用启动");
-    }
-
-    /// <summary>按设置重建定时器（设置页改间隔后调用）。</summary>
-    public void RestartTimer()
-    {
-        lock (_gate)
-        {
-            _timer?.Dispose();
-            _timer = null;
-            _notifyTimer?.Dispose();
-            _notifyTimer = null;
-
-            if (!_settings.IsConfigured) return;
-
-            if (_settings.AutoReport)
-            {
-                var interval = TimeSpan.FromSeconds(Math.Clamp(_settings.ReportIntervalSeconds, 15, 3600));
-                _timer = new Timer(_ => RequestReport("定时"), null, interval, interval);
-            }
-
-            // 提醒单独用一个轻量轮询（只查待提醒，不上传课表）：
-            // 老师按下发送到教室弹出之间的延迟就是这个间隔，因此默认 10 秒，不跟随上报间隔。
-            if (_settings.ReceiveNotifications)
-            {
-                var poll = TimeSpan.FromSeconds(Math.Clamp(_settings.NotificationPollSeconds, 5, 600));
-                _notifyTimer = new Timer(_ => _ = PullPendingAsync(), null, poll, poll);
-            }
-        }
-    }
-
-    /// <summary>
-    /// 发起一次**仅状态**的上报（定时器与课程事件都走这里）。
-    ///
-    /// 刻意不带课表：课表只在服务端显式点「从教室机器获取课表」时上传（见 <see cref="ReportAsync"/>
-    /// 的 <c>forceSchedule</c>）。原先每次上报都带全量课表、默认 15 秒一次，服务端于是每 15 秒
-    /// merge + 清理一次幽灵行 —— 老师看到的就是"课表被反复删改"（2026-10-11 实测）。
-    /// </summary>
-    public void RequestReport(string reason)
-    {
-        _ = ReportAsync(reason, includeSchedule: false);
-    }
-
-    /// <summary>
-    /// 执行一次上报并返回是否真的发出去了。
-    /// <paramref name="includeSchedule"/> 为 true 时带上全量课表与节次时间。
-    /// </summary>
-    public async Task<bool> ReportAsync(string reason, bool includeSchedule = true, bool forceSchedule = false)
-    {
-        if (_disposed) return false;
-
-        ILessonsService? lessons;
-        lock (_gate) lessons = _lessons;
-        if (lessons is null) return false;
-
-        if (!_settings.IsConfigured)
-        {
-            SetState(false, "尚未配置服务器地址或设备令牌", 0, 0, null);
-            return false;
-        }
-
-        lock (_gate)
-        {
-            if (_reporting) return false;
-            _reporting = true;
-        }
-        Busy = true;
-
-        try
-        {
-            var profile = ResolveProfile();
-            var request = new ReportRequestDto
-            {
-                PluginVersion = PluginVersion,
-                ClassIslandVersion = SafeAppVersion(),
-                // 机器码：设备创建时服务端只能用 pending-… 占位，靠这里回填，Web 端设备列表才能与教室机器对上
-                DeviceKey = _settings.DeviceKey,
-                State = BuildState(lessons),
-            };
-
-            var entryCount = 0;
-            var layoutCount = 0;
-            // 课表**只在服务端显式请求时**上传：没有"本机自动回传"这条路径了
-            // （原先由本机 `UploadSchedule` 开关决定，默认开 + 定时 15 秒 = 服务端课表被反复 merge）。
-            // forceSchedule：服务端点了「从教室机器获取课表」，这是一次人工请求。
-            var uploadSchedule = forceSchedule;
-
-            if (includeSchedule && !uploadSchedule)
-            {
-                _logger.LogInformation("ClassHelper 联动：本次只上报运行状态；课表由 Web 端点「从教室机器获取课表」时才会拉取");
-            }
-
-            if (includeSchedule && uploadSchedule && profile is not null)
-            {
-                var entries = ScheduleMapper.MapAllClassPlans(profile, out var warnings);
-                foreach (var warning in warnings) _logger.LogWarning("ClassHelper 联动：{Warning}", warning);
-                entryCount = entries.Count;
-                request.Schedule = new SchedulePayloadDto { Mode = "merge", Entries = entries };
-                // 课表为空时不发（否则会把服务端已有课表"合并"成空），但**必须把原因写清楚**：
-                // 日志里只出现"仅状态"时，用户会以为上报失败，实际是 ClassIsland 里还没有课表。
-                if (entries.Count == 0)
-                {
-                    request.Schedule = null;
-                    _logger.LogWarning(
-                        "ClassHelper 联动：ClassIsland 里没有**启用的课表**（0 条），本次未上报课表。" +
-                        "请在 ClassIsland 里排好课表，或在 Web 端打开「镜像课表」由 ClassHelper下发一份");
-                }
-
-                var layout = ResolvePrimaryTimeLayout(profile);
-                if (layout is not null)
-                {
-                    var items = ScheduleMapper.MapTimeLayout(layout);
-                    layoutCount = items.Count;
-                    request.TimeLayout = new TimeLayoutPayloadDto
-                    {
-                        Name = ScheduleMapper.Truncate(
-                            string.IsNullOrWhiteSpace(layout.Name) ? "ClassIsland 时间表" : layout.Name,
-                            ScheduleMapper.PlanNameMaxLength)!,
-                        Mode = "replace",
-                        Items = items,
-                    };
-                }
-            }
-
-            var (result, data) = await _client.ReportAsync(_settings, request, CancellationToken.None)
-                .ConfigureAwait(false);
-            if (!result.Ok || data is null)
-            {
-                _logger.LogWarning("ClassHelper 联动上报失败（{Reason}）：{Message}", reason, result.Message);
-                SetState(false, result.Message, entryCount, layoutCount, null);
-                return false;
-            }
-
-            LastServerWeek = data.Week;
-            UpdateClockOffset(data.ServerTime);
-            if (data.ScheduleApplied)
-            {
-                _logger.LogInformation(
-                    "ClassHelper 联动：课表已同步（新增 {Created} / 更新 {Updated}）",
-                    data.ScheduleCreated, data.ScheduleUpdated);
-            }
-
-            var detail = entryCount > 0
-                ? $"课表 {entryCount} 节 / 节次 {layoutCount} 条"
-                : uploadSchedule
-                    ? "仅状态（ClassIsland 里还没有启用的课表）"
-                    : "仅状态（本机「上报课表到 ClassHelper」开关已关闭）";
-            SetState(true, $"上报成功（{reason}）：{detail}，服务端第 {data.Week} 周",
-                entryCount, layoutCount, data.Week);
-
-            // 顺路把"还没弹出过的"提醒带回来
-            var pending = data.PendingNotification;
-            if (pending is not null && _settings.ReceiveNotifications)
-            {
-                NotificationReceived?.Invoke(this, pending);
-            }
-
-            // 服务端请求"立刻上报一次课表"（老师在 Web 端点了「从教室机器获取课表」）。
-            // 放在镜像之前：先把教室的现状推上去，再做服务端→教室的镜像，顺序反了会把刚拿到的课表盖掉。
-            if (data.Settings?.ScheduleRequested == true && !uploadSchedule)
-            {
-                _logger.LogInformation("ClassHelper 联动：服务端请求立即上报课表，正在补发一次…");
-                _ = ReportAsync("服务端请求课表", includeSchedule: true, forceSchedule: true);
-            }
-
-            // 只有服务端点了「下发课表到教室」才镜像。原先跟着**每一次上报**走（本机 MirrorSchedule
-            // 开关 + 默认 15 秒周期），教室的课表被反复重写 —— 与服务端那边的 merge/清理叠在一起，
-            // 就是老师反馈的"课表一直在变"。现在是一次性待办，拉取成功由服务端清标记。
-            if (data.Settings?.MirrorRequested == true)
-            {
-                _logger.LogInformation("ClassHelper 联动：服务端请求下发课表，正在拉取并强制替换教室课表…");
-                await MirrorScheduleAsync().ConfigureAwait(false);
-            }
-
-            return true;
-        }
-        catch (Exception exception)
-        {
-            // ReportAsync 是通过 `_ = ReportAsync(reason)` 这种 fire-and-forget 方式发起的
-            // （事件回调与定时器都是），没有这个 catch，中途抛出的异常（例如跨线程改档案时的
-            // "Collection was modified"）会被 unobserved task 静默吞掉：日志里一条都没有，
-            // 而 LastReportMessage 还停在上一次的成功结果，用户以为一切正常。
-            _logger.LogError(exception, "ClassHelper 联动：上报异常（{Reason}）", reason);
-            SetState(false, $"上报异常：{exception.Message}", 0, 0, null);
-            return false;
-        }
-        finally
-        {
-            Busy = false;
-            lock (_gate) _reporting = false;
-        }
-    }
-
-    /// <summary>
-    /// 拉取本班尚未弹出过的提醒并逐条交给提醒提供方（用于"应用刚起来还没到第一个上报点"的场景）。
-    /// </summary>
-    public async Task PullPendingAsync()
-    {
-        if (_disposed) return;
-        if (!_settings.IsConfigured || !_settings.ReceiveNotifications) return;
-
-        // 轮询与"上报顺路拉取"可能同时到达：同一时刻只放一个请求过去
-        lock (_gate)
-        {
-            if (_pulling) return;
-            _pulling = true;
-        }
-
-        try
-        {
-            var (result, items) = await _client.PendingAsync(_settings, CancellationToken.None).ConfigureAwait(false);
-            if (!result.Ok)
-            {
-                _logger.LogInformation("ClassHelper 联动：拉取待提醒失败（{Message}）", result.Message);
-                return;
-            }
-
-            foreach (var item in items)
-            {
-                _logger.LogInformation("ClassHelper 联动：取到待弹出提醒「{Title}」（id={Id}）", item.Title, item.Id);
-                NotificationReceived?.Invoke(this, item);
-            }
-        }
-        finally
-        {
-            lock (_gate) _pulling = false;
-        }
-    }
-
-    /// <summary>把服务端的一条提醒标记为已弹出。</summary>
-    public async Task AckAsync(string id)
-    {
-        var result = await _client.AckAsync(_settings, id, CancellationToken.None).ConfigureAwait(false);
-        if (result.Ok)
-        {
-            NotificationCount += 1;
-            _logger.LogInformation("ClassHelper 联动：已确认提醒 {Id}", id);
-        }
-        else
-        {
-            // 回执失败无妨：服务端会按 24 小时有效期补发，最坏是重复弹一次
-            _logger.LogWarning("ClassHelper 联动：确认提醒失败 {Message}", result.Message);
-        }
-    }
-
-    /// <summary>把 ClassHelper上排好的课表写回 ClassIsland（新建带前缀的档案课表，不动老师原有的课表）。</summary>
-    public async Task MirrorScheduleAsync()
-    {
-        var profile = ResolveProfile();
-        if (profile is null) return;
-
-        var (result, plan) = await _client.PullClassPlanAsync(_settings, CancellationToken.None).ConfigureAwait(false);
-        if (!result.Ok || plan is null)
-        {
-            // 服务端在"镜像开关没开"时会返回 data=null —— 这不是错误，但要告诉用户去哪儿开
-            _logger.LogInformation(
-                "ClassHelper 联动：跳过课表镜像（{Message}）。" +
-                "需要在 Web 端「ClassIsland 联动」页给这台设备打开「镜像课表」，然后点一次「立即上报」或等下一个上报周期",
-                result.Message);
-            return;
-        }
-
-        // 内容没变就直接返回：上报是"启动 + 每个课程事件 + 每 N 秒"触发的，原先每次都要
-        // 重建全部课表对象并整体落盘 —— 无谓的网络/磁盘 I/O，还会把档案页刷得不停重绘。
-        var signature = MirrorSignature(plan);
-        if (signature == _lastMirrorSignature)
-        {
-            _logger.LogDebug("ClassHelper 联动：课表内容与上次一致，跳过镜像");
-            return;
-        }
-
-        try
-        {
-            // **必须在 UI 线程上改写档案**：ClassIsland 的档案是 ObservableDictionary /
-            // ObservableCollection，落盘是"属性变化即整体序列化 + FileStream 就地截断"。
-            // 而本方法是从线程池线程继续执行的（ReportAsync 里 ConfigureAwait(false) 之后，
-            // 定时器回调本就在线程池上），在线程池上改集合会与 UI 线程的保存/绑定并发：
-            // 轻则 InvalidOperationException（Collection was modified），重则两次写入互相截断，
-            // **把整个档案写成半截 JSON**（老师的课表/科目全丢，只能靠 .bak 兜底）。
-            var outcome = await Dispatcher.UIThread.InvokeAsync(() =>
-            {
-                var applied = ClassPlanWriter.Apply(profile, plan, force: true);
-                if (!applied.Applied)
-                {
-                    return applied;
-                }
-
-                // 改写的是 Profile 里的集合，ClassIsland 会靠 INotifyCollectionChanged 落盘；
-                // 这里显式 SaveProfile() 是为了"打开开关马上就能在课表里看到"，不用等下一次自动保存。
-                IAppHost.TryGetService<IProfileService>()?.SaveProfile();
-                return applied;
-            });
-
-            if (!outcome.Applied)
-            {
-                _logger.LogInformation("ClassHelper 联动：课表镜像未生效（{Reason}）",
-                    outcome.Warnings.FirstOrDefault() ?? "服务端课表为空");
-                return;
-            }
-
-            _lastMirrorSignature = signature;
-            _logger.LogInformation("ClassHelper 联动：已把班级课表写入 ClassIsland（{Plans}）",
-                string.Join("、", outcome.PlanNames.Select(name => $"「{name}」")));
-            foreach (var warning in outcome.Warnings)
-            {
-                _logger.LogWarning("ClassHelper 联动镜像提示：{Warning}", warning);
-            }
-        }
-        catch (Exception exception)
-        {
-            _logger.LogError(exception, "ClassHelper 联动：课表镜像失败");
-        }
-    }
-
-    /// <summary>镜像载荷的内容指纹（只用于"内容没变就跳过"，不参与任何业务判断）</summary>
-    private static string MirrorSignature(ClassPlanMirrorDto plan)
-    {
-        var builder = new StringBuilder();
-        foreach (var entry in plan.Entries)
-        {
-            builder.Append(entry.WeekDay).Append('|').Append(entry.WeekCountDiv).Append('|')
-                .Append(entry.WeekCountDivTotal).Append('|').Append(entry.Subject).Append('|')
-                .Append(entry.StartTime).Append('|').Append(entry.EndTime).Append(';');
-        }
-        foreach (var layout in plan.TimeLayouts)
-        {
-            builder.Append('#').Append(layout.Id).Append(':');
-            foreach (var item in layout.Layouts)
-            {
-                builder.Append(item.StartTime).Append('-').Append(item.EndTime).Append('@')
-                    .Append(item.TimeType).Append(',');
-            }
-        }
-        return builder.ToString();
-    }
-
-    /* ---------------------------------------------------------------- 内部实现 */
-
-    /// <summary>插件版本（与 manifest.yml / csproj 保持一致）。</summary>
-    private const string PluginVersion = "1.3.1.0";
-
-    /// <summary>ClassIsland 版本读不到时不该让上报失败（开发版可能为 null）。</summary>
-    private static string SafeAppVersion()
-    {
-        try
-        {
-            return AppBase.AppVersion ?? "";
-        }
-        catch
-        {
-            return "";
-        }
-    }
-
-    /// <summary>
-    /// 取得当前状态快照。
-    /// <c>CurrentTimeLayoutItem</c> 在"没有课表"时是 <see cref="ClassIsland.Shared.Models.Profile.TimeLayoutItem.Empty"/>，
-    /// 语义上等价于"没有节次"，因此要转成 null 而不是 00:00。
-    /// </summary>
-    private StateDto BuildState(ILessonsService lessons)
-    {
-        try
-        {
-            return ScheduleMapper.BuildState(lessons, LastServerWeek);
-        }
-        catch (Exception exception)
-        {
-            // 课程服务在"应用启动中/课表未加载"时可能抛异常，这里降级为只有心跳的上报
-            _logger.LogWarning(exception, "ClassHelper 联动：读取课程状态失败，本次只上报心跳");
-            return new StateDto { ClientTime = DateTimeOffset.Now.ToString("o") };
-        }
-    }
-
-    /// <summary>
-    /// 选一份"最有代表性"的时间表上报给 ClassHelper：**上课点最多的那一份**。
-    ///
-    /// 为什么不按"当前课表"选：镜像会给每个（星期 + 单双周）建一份时间表，
-    /// 于是"今天"那一份可能只有一两节课 —— 按当前课表选就会把只有一节的时间表报上去，
-    /// 服务端那边的节次时间表就退化了。取上课点最多的那份，得到的是完整作息。
-    /// 并列时优先"每周"型（单双周的两份内容一致，每周型更通用）。
-    /// </summary>
-    private static ClassIsland.Shared.Models.Profile.TimeLayout? ResolvePrimaryTimeLayout(
-        ClassIsland.Shared.Models.Profile.Profile profile)
-    {
-        if (profile.TimeLayouts.Count == 0) return null;
-
-        var best = profile.TimeLayouts
-            .Select(pair => (pair.Value, ClassPoints: pair.Value.Layouts.Count(item => item.TimeType == 0)))
-            .Where(item => item.ClassPoints > 0)
-            .OrderByDescending(item => item.ClassPoints)
-            .ToList();
-        if (best.Count > 0) return best[0].Value;
-
-        // 兜底：档案里被激活的时间表，最后才是任意一个
-        return profile.TimeLayouts.Values.FirstOrDefault(item => item.IsActivated)
-               ?? profile.TimeLayouts.Values.First();
-    }
-
-    private static ClassIsland.Shared.Models.Profile.ClassPlan? CurrentClassPlan(
-        ClassIsland.Shared.Models.Profile.Profile profile)
-    {
-        // 用课程服务拿"今天该上哪张课表"最准
-        try
-        {
-            var lessons = IAppHost.TryGetService<ILessonsService>();
-            return lessons?.CurrentClassPlan;
-        }
-        catch
-        {
-            return null;
-        }
-    }
-
-    private ClassIsland.Shared.Models.Profile.Profile? ResolveProfile()
-    {
-        try
-        {
-            // 档案由 ProfileService 持有；这里用 TryGetService 避免服务未注册时抛异常
-            return IAppHost.TryGetService<IProfileService>()?.Profile;
-        }
-        catch (Exception exception)
-        {
-            _logger.LogWarning(exception, "ClassHelper 联动：读取档案失败");
-            return null;
-        }
-    }
-
-    /// <summary>用服务端时间校准本机时钟差（只影响设置页展示，不改系统时间）。</summary>
-    private void UpdateClockOffset(string serverTime)
-    {
-        if (!DateTimeOffset.TryParse(serverTime, out var parsed)) return;
-        _serverTimeOffset = parsed - DateTimeOffset.Now;
-        Raise(nameof(ClientTimeOffsetText));
-    }
-
-    private void SetState(bool ok, string message, int entryCount, int layoutCount, int? week)
-    {
-        LastReportOk = ok;
-        LastReportMessage = message;
-        LastReportAt = DateTimeOffset.Now;
-        LastScheduleEntryCount = entryCount;
-        LastTimeLayoutItemCount = layoutCount;
-        if (week.HasValue) LastServerWeek = week;
-        StateChanged?.Invoke(this, EventArgs.Empty);
-    }
-
-    private void Raise(string propertyName) =>
-        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
-
-    private bool SetField<T>(ref T field, T value, [CallerMemberName] string? propertyName = null)
-    {
-        if (EqualityComparer<T>.Default.Equals(field, value)) return false;
-        field = value;
-        Raise(propertyName!);
-        return true;
-    }
-
-    public void Dispose()
-    {
-        _disposed = true;
-        lock (_gate)
-        {
-            _timer?.Dispose();
-            _timer = null;
-            _notifyTimer?.Dispose();
-            _notifyTimer = null;
-        }
-        _client.Dispose();
-    }
-}

packages/classisland-plugin/src/Services/ClassHelperNotificationProvider.cs

@@ -1,260 +0,0 @@
-using Avalonia.Threading;
-using ClassHelper.ClassIslandPlugin.Interop;
-using ClassHelper.ClassIslandPlugin.Models;
-using ClassIsland.Core.Abstractions.Services;
-using ClassIsland.Shared;
-using ClassIsland.Shared.Enums;
-using ClassIsland.Core.Abstractions.Services.NotificationProviders;
-using ClassIsland.Core.Attributes;
-using ClassIsland.Core.Models.Notification;
-using Microsoft.Extensions.Logging;
-
-namespace ClassHelper.ClassIslandPlugin.Services;
-
-/// <summary>
-/// 提醒提供方：把老师在 ClassHelper上发布的提醒显示到 ClassIsland 上。
-///
-/// 与 <see cref="BridgeService"/> 的分工：
-/// - <see cref="BridgeService"/> 负责"拉"（上报时顺路把待提醒带回来）与"回执"（ack）；
-/// - 本类只负责"显示"——提醒必须由提醒提供方发出，ClassIsland 才会走主界面的
-///   全屏特效 / 语音 / 音效那一整套流程。
-///
-/// 为什么不给这个提供方再配一套"提醒设置"：本插件的开关全在「ClassHelper 联动」设置页里，
-/// 再在「提醒」设置页放第二份开关只会让老师困惑（两处都能关，到底以哪个为准）。
-/// 因此这里用无设置的 <see cref="NotificationProviderBase"/>，读的是同一份 <see cref="PluginSettings"/>。
-/// </summary>
-// 第 3 个参数是 Fluent 图标字体里的字形字符（ClassIsland 内置提醒提供方用的也是字形字符，
-// 不是 "fluent(...)" 表达式）：E8BD 是喇叭字形。
-[NotificationProviderInfo(
-    ProviderGuidValue,
-    "ClassHelper提醒",
-    "\uE8BD",
-    "显示老师从 ClassHelper下发的提醒。")]
-public sealed class ClassHelperNotificationProvider : NotificationProviderBase
-{
-    /// <summary>
-    /// 提醒提供方 GUID（全局唯一，别改：改了等于换了一个提供方，用户原有的提醒设置会失联）。
-    /// 名字带 Value 后缀是为了不和基类的 <see cref="NotificationProviderBase.ProviderGuid"/> 属性撞名。
-    /// </summary>
-    public const string ProviderGuidValue = "7C4B1F6E-2A85-4A1F-9E3C-5B7D0C1A9E42";
-
-    private readonly BridgeService _bridge;
-    private readonly PluginSettings _settings;
-    private readonly ILogger<ClassHelperNotificationProvider> _logger;
-
-    /// <summary>
-    /// 正在播放（尚未回执）的提醒 id。
-    ///
-    /// 服务端在提醒被回执前会**一直**把它算作"待弹出"，而插件是按固定间隔轮询取回的，
-    /// 因此时长超过轮询间隔的提醒会被反复取到 —— 没有这层去重就会一遍遍重复弹。
-    /// 只有播完（或用户关掉）才从集合里移除，那一刻才回执。
-    /// </summary>
-    private readonly HashSet<string> _playing = new();
-
-    /// <summary>
-    /// 上课时段被暂存的提醒（与客户端灵动岛同一套规则）。
-    ///
-    /// 为什么要有它：老师在**上课时段**发通知，教室里正上着课，直接全屏弹会打断课堂。
-    /// 客户端的灵动岛就是"上课先收着、下课再弹"，ClassIsland 这侧必须一致，
-    /// 否则学生在客户端看不到、却在 ClassIsland 上被打断。
-    ///
-    /// 例外（"主动通知"）：紧急提醒与**叫人**，老师正在等学生，必须立刻弹。
-    /// </summary>
-    private readonly List<PushNotificationDto> _deferred = new();
-
-    private ILessonsService? _lessons;
-    private bool _lessonsHooked;
-
-    public ClassHelperNotificationProvider(
-        BridgeService bridge,
-        PluginSettings settings,
-        ILogger<ClassHelperNotificationProvider> logger)
-    {
-        _bridge = bridge;
-        _settings = settings;
-        _logger = logger;
-        _bridge.NotificationReceived += OnNotificationReceived;
-
-        // 尽力而为地先订阅一次；拿不到也没关系，后面每次需要判定时都会重试
-        // （本类的构造函数可能在课程服务建好之前就被 DI 调用）
-        EnsureLessons();
-    }
-
-    /// <summary>
-    /// 惰性获取课程服务并**只订阅一次**课程事件（下课后补弹上课时段暂存的提醒）。
-    ///
-    /// 为什么不能只在构造函数里订阅：提供方是随主机启动被构造的，而课程服务在启动流程里的
-    /// 创建时机并不固定。一旦构造函数里拿到 null，原先的实现既不重试、也不打日志，
-    /// 于是 `IsInClass()` 恒为 false —— "上课时段先暂存、下课再补弹"这条规则**永久失效**，
-    /// 老师在课上发的通知会直接全屏打断课堂，而且完全静默、无从排查。
-    /// </summary>
-    private void EnsureLessons()
-    {
-        if (_lessonsHooked) return;
-        try
-        {
-            _lessons = IAppHost.TryGetService<ILessonsService>();
-            if (_lessons is null) return;
-
-            _lessons.OnBreakingTime += (_, _) => Dispatcher.UIThread.Post(FlushDeferred);
-            _lessons.OnAfterSchool += (_, _) => Dispatcher.UIThread.Post(FlushDeferred);
-            _lessons.CurrentTimeStateChanged += (_, _) => Dispatcher.UIThread.Post(FlushDeferred);
-            _lessonsHooked = true;
-            _logger.LogInformation("ClassHelper 联动：提醒提供方已订阅课程事件（上课时段暂存、下课补弹）");
-        }
-        catch (Exception exception)
-        {
-            _logger.LogWarning(exception, "ClassHelper 联动：订阅课程事件失败，将在下次提醒时重试");
-        }
-    }
-
-    /// <summary>当前是否处于上课时段（读不到课程服务时按"不在上课"处理，宁可弹也不静默丢）</summary>
-    private bool IsInClass()
-    {
-        EnsureLessons();
-        try
-        {
-            return _lessons?.CurrentState == TimeState.OnClass;
-        }
-        catch
-        {
-            return false;
-        }
-    }
-
-    /// <summary>
-    /// 这条提醒是否必须立刻弹（"主动通知"）：
-    /// 紧急提醒，或叫人（老师正在等学生）。
-    /// </summary>
-    private static bool IsImmediate(PushNotificationDto notification) =>
-        notification.Urgent || string.Equals(notification.Kind, "call", StringComparison.OrdinalIgnoreCase);
-
-    /// <summary>下课后补弹暂存的提醒（按进入顺序）</summary>
-    private void FlushDeferred()
-    {
-        if (IsInClass()) return; // 还在上课（例如只是状态在 OnClass 内部变化）
-        if (_deferred.Count == 0) return;
-
-        var pending = _deferred.ToList();
-        _deferred.Clear();
-        _logger.LogInformation("ClassHelper 联动：下课了，补弹 {Count} 条上课时段暂存的提醒", pending.Count);
-        foreach (var item in pending) ShowOnUiThread(item);
-    }
-
-    private void OnNotificationReceived(object? sender, PushNotificationDto notification)
-    {
-        if (!_settings.ReceiveNotifications) return;
-        if (string.IsNullOrWhiteSpace(notification.Id)) return;
-
-        // 同一条提醒在播放期间会被后续轮询反复取回，这里按 id 去重（详见 _playing 的说明）
-        lock (_playing)
-        {
-            if (!_playing.Add(notification.Id))
-            {
-                _logger.LogDebug("ClassHelper 联动：提醒 {Id} 正在播放，跳过重复投递", notification.Id);
-                return;
-            }
-        }
-
-        // 必须切回 UI 线程：提醒内容里的图标、以及提醒主机本身都是 Avalonia 的 UI 对象，
-        // 而本方法是从上报回调（线程池）里被调用的 —— 在线程池上直接显示会静默失败/抛异常。
-        Dispatcher.UIThread.Post(() => ShowOnUiThread(notification));
-    }
-
-    private void ShowOnUiThread(PushNotificationDto notification)
-    {
-        try
-        {
-            // 上课时段：非"主动通知"先收着（与客户端灵动岛同一套规则），下课后补弹
-            if (IsInClass() && !IsImmediate(notification))
-            {
-                _deferred.Add(notification);
-                _logger.LogInformation("ClassHelper 联动：上课中，「{Title}」已暂存，下课后弹出", notification.Title);
-                return;
-            }
-
-            var request = BuildRequest(notification);
-            // 只有真正播完（或被用户关掉）才回执：中途退出 ClassIsland 时下次上报还会补发，不会静默丢失
-            AckWhenFinished(request, notification);
-            ShowNotification(request);
-            _logger.LogInformation("ClassHelper 联动：已弹出提醒「{Title}」（{Seconds} 秒）",
-                notification.Title, notification.DurationSeconds);
-        }
-        catch (Exception exception)
-        {
-            // 显示失败不能让 ClassIsland 崩掉：记日志，且**不回执**，服务端下次轮询还会重发。
-            // 同时要把 id 从"正在播放"里放出来，否则本次失败后再也不会重试。
-            lock (_playing) _playing.Remove(notification.Id);
-            _logger.LogError(exception, "ClassHelper 联动：显示提醒「{Title}」失败", notification.Title);
-        }
-    }
-
-    /// <summary>
-    /// 把服务端下发的提醒转成 ClassIsland 的提醒请求。
-    ///
-    /// 时长口径：老师指定的时长给**正文**（正文才是持续显示的那一段），遮罩只停留几秒 ——
-    /// 遮罩占满整个时长会把正文压没，不如"遮罩几秒 + 正文 N 秒"清楚。
-    /// </summary>
-    private NotificationRequest BuildRequest(PushNotificationDto notification)
-    {
-        var seconds = Math.Clamp(
-            notification.DurationSeconds > 0 ? notification.DurationSeconds : _settings.NotificationDurationSeconds,
-            1,
-            120);
-        var duration = TimeSpan.FromSeconds(seconds);
-        var maskDuration = TimeSpan.FromSeconds(Math.Min(notification.Urgent ? 5 : 3, seconds));
-
-        var title = string.IsNullOrWhiteSpace(notification.Title) ? "ClassHelper" : notification.Title;
-        var content = string.IsNullOrWhiteSpace(notification.Content) ? title : notification.Content;
-
-        // 语音：老师勾了朗读 + 本机允许朗读，两者都满足才念（本机开关是给学生机的总闸）
-        var speech = _settings.SpeechEnabled ? notification.SpeechContent : null;
-        var speechEnabled = !string.IsNullOrWhiteSpace(speech);
-
-        // 遮罩用双图标模板的**默认图标**：这两个图标由模板自己创建（LucideIconSource），
-        // 自己塞图标串很容易踩到"图标表达式格式不对/字形不存在"，没必要冒这个险。
-        var mask = NotificationContent.CreateTwoIconsMask(title, factory: content_ =>
-        {
-            content_.Duration = maskDuration;
-            content_.SpeechContent = speech ?? string.Empty;
-            // 没勾朗读时明确关掉，否则 ClassIsland 会按默认设置把标题也念出来
-            content_.IsSpeechEnabled = speechEnabled;
-        });
-
-        // 正文：普通提醒用静态文本；紧急提醒改用**滚动文本**（ClassIsland 自带的抢注意力模板），
-        // 这样"紧急"在视觉上真的有区别，而不是只靠一个可能不存在的图标。
-        NotificationContent overlay = notification.Urgent
-            ? NotificationContent.CreateRollingTextContent(content, factory: content_ =>
-            {
-                content_.Duration = duration;
-                content_.SpeechContent = speech ?? string.Empty;
-                content_.IsSpeechEnabled = speechEnabled;
-            })
-            : NotificationContent.CreateSimpleTextContent(content, factory: content_ =>
-            {
-                content_.Duration = duration;
-                content_.SpeechContent = speech ?? string.Empty;
-                content_.IsSpeechEnabled = speechEnabled;
-            });
-
-        return new NotificationRequest { MaskContent = mask, OverlayContent = overlay };
-    }
-
-    /// <summary>提醒播完 / 被关掉后回执给 ClassHelper，服务端不再补发。</summary>
-    private void AckWhenFinished(NotificationRequest request, PushNotificationDto notification)
-    {
-        void Handler(object? sender, EventArgs args)
-        {
-            request.Completed -= Handler;
-            request.Canceled -= Handler;
-
-            // 播完再放行：即使回执失败（例如断网）也移除，让后续轮询能重新投递一次，
-            // 避免"回执丢了 + 不再重试"把提醒彻底吞掉
-            lock (_playing) _playing.Remove(notification.Id);
-            _ = _bridge.AckAsync(notification.Id);
-        }
-
-        request.Completed += Handler;
-        request.Canceled += Handler;
-    }
-}

packages/classisland-plugin/src/Services/ClassPlanWriter.cs

@@ -1,299 +0,0 @@
-using System.Collections.ObjectModel;
-using ClassHelper.ClassIslandPlugin.Interop;
-using ClassIsland.Shared.Models.Profile;
-
-namespace ClassHelper.ClassIslandPlugin.Services;
-
-/// <summary>
-/// 把 ClassHelper拉回来的课表写进 ClassIsland 档案。
-///
-/// **核心约束**：ClassIsland 的一份 <see cref="ClassPlan"/> 只带**一个** <see cref="TimeRule"/>
-/// （即一个星期几 + 一个单双周相位），而 ClassHelper的课表同时覆盖 7 天与单双周。
-/// 因此这里把服务端的条目**按（星期几 + 单双周）分组**，每一组生成一份独立的档案课表。
-///
-/// **时间点的构造方式**：ClassIsland 的 <c>ClassPlan.Classes[i]</c> 必须与
-/// <c>TimeLayout.Layouts</c> 里第 i 个 <c>TimeType == 0</c>（上课）的点一一对应。
-/// 与其去"匹配服务端时间表里的时间点"（一旦对不齐整份课表就错位），
-/// 这里**按分组内的条目顺序直接重建时间点**：每条课目生成一个上课点，
-/// 并在其结束后接上服务端时间表里同一起始时刻的课间点。这样索引关系天然成立。
-///
-/// **非破坏性**：
-/// - 只创建/更新名字带 <see cref="PlanNamePrefix"/> 前缀的课表与时间表；
-/// - 老师手动建的课表一律不删除、不改名（同名星期的冲突会在日志里警告）；
-/// - 重复镜像时原地更新，不会越积越多。
-/// </summary>
-public static class ClassPlanWriter
-{
-    /// <summary>识别前缀：只有名字带此前缀的课表才由本插件创建与维护。</summary>
-    public const string PlanNamePrefix = "ClassHelper-";
-
-    /// <summary>时间表名字后缀。</summary>
-    public const string TimeLayoutNameSuffix = "（ClassHelper）";
-
-    /// <summary>一次镜像的结果（写入的课表名与冲突提示）。</summary>
-    public sealed class ApplyResult
-    {
-        public List<string> PlanNames { get; } = new();
-        public List<string> Warnings { get; } = new();
-        public bool Applied { get; set; }
-    }
-
-    /// <summary>
-    /// 应用服务端下发的课表。
-    /// </summary>
-    /// <param name="force">
-    /// 「强制更换课表」：同一星期几 + 同一单双周相位下老师还开着别的课表时，**停用**它们，
-    /// 让教室大屏立刻改成以 ClassHelper 下发的这份为准。
-    /// 由 Web 端的「下发课表到教室」按钮触发（服务端那个一次性待办）。
-    /// **只停用不删除** —— 课表内容原样留在档案里，老师随时能在 ClassIsland 里重新启用。
-    /// </param>
-    public static ApplyResult Apply(Profile profile, ClassPlanMirrorDto source, bool force = false)
-    {
-        var result = new ApplyResult();
-        if (source.Entries.Count == 0 || source.TimeLayouts.Count == 0)
-        {
-            result.Warnings.Add("服务端返回的课表为空，未改动 ClassIsland 档案");
-            return result;
-        }
-
-        var layout = source.TimeLayouts[0];
-
-        // 1) 补齐科目（同名的复用，避免每次镜像堆出新的 Subject）
-        EnsureSubjects(profile, source);
-
-        // 2) 按（星期几 + 单双周）分组，每组一份课表
-        var groups = source.Entries
-            .GroupBy(entry => new
-            {
-                entry.WeekDay,
-                entry.WeekCountDiv,
-                entry.WeekCountDivTotal,
-            })
-            .Select(group => new
-            {
-                group.Key.WeekDay,
-                group.Key.WeekCountDiv,
-                group.Key.WeekCountDivTotal,
-                // 时间点顺序 = 课表顺序：`Classes[i]` 靠这个顺序与上课时间点对齐，
-                // 「HH:mm」是定长字符串，字典序就是时间序
-                Entries = group.OrderBy(entry => entry.StartTime, StringComparer.Ordinal).ToList(),
-            })
-            .OrderBy(group => group.WeekDay)
-            .ToList();
-
-        foreach (var group in groups)
-        {
-            var planName = BuildPlanName(source.ProfileName, group.WeekDay, group.WeekCountDiv,
-                group.WeekCountDivTotal, groups.Count);
-
-            // 时间非法的条目必须**在这里**就整批丢掉：`Classes` 与时间表里的上课点必须等长且同序，
-            // 只在一处跳过会让整份课表错位。原先 ParseTime 把无法解析的值悄悄变成 00:00，
-            // 于是档案里凭空出现 00:00-00:00 的课次（时间轴显示与当前节次判断都会乱），还没有任何日志。
-            var usable = group.Entries
-                .Where(entry => IsValidTime(entry.StartTime) && IsValidTime(entry.EndTime))
-                .ToList();
-            if (usable.Count < group.Entries.Count)
-            {
-                result.Warnings.Add(
-                    $"「{planName}」有 {group.Entries.Count - usable.Count} 节的时间无法解析（需要 HH:mm），已跳过");
-            }
-            if (usable.Count == 0) continue;
-
-            var planId = FindPlanId(profile, planName);
-            var (timeLayoutId, timeLayout) = BuildTimeLayout(profile, planName, usable);
-
-            var plan = profile.ClassPlans.TryGetValue(planId, out var existing)
-                ? existing
-                : new ClassPlan();
-            plan.Name = planName;
-            plan.TimeLayoutId = timeLayoutId;
-            plan.TimeRule = new TimeRule
-            {
-                WeekDay = group.WeekDay,
-                WeekCountDiv = group.WeekCountDiv,
-                WeekCountDivTotal = group.WeekCountDivTotal,
-            };
-
-            // Classes[i] ↔ 第 i 个上课点：按分组内条目的时间顺序直接构造，索引天然一致
-            // ClassIsland 的 `ClassInfo.CurrentTimeLayoutItem` = CurrentTimeLayout 里第 Index 个上课点，
-            // 因此这里必须显式把 Index 与 CurrentTimeLayout 一起写上 —— 只在构造时依赖
-            // `RefreshClassesList()` 是不够的：更新已有课表时 `TimeLayouts` 引用没变，
-            // 档案不会重新触发刷新，课次就会停留在旧时间点上。
-            var classes = new ObservableCollection<ClassInfo>();
-            var index = 0;
-            foreach (var entry in usable)
-            {
-                var subjectId = profile.Subjects
-                    .FirstOrDefault(pair => pair.Value.Name == entry.Subject).Key;
-                classes.Add(new ClassInfo
-                {
-                    Index = index++,
-                    CurrentTimeLayout = timeLayout,
-                    SubjectId = subjectId,
-                    IsEnabled = true,
-                });
-            }
-            plan.Classes = classes;
-            plan.IsEnabled = true;
-            profile.ClassPlans[planId] = plan;
-            result.PlanNames.Add(planName);
-
-            // 冲突处理：同一星期几 + 同一单双周相位下老师还开着别的课表。
-            // ClassIsland 在同一个时间点上只会用一份**启用**的课表，所以"强制更换"就是把冲突的
-            // 那份停用 —— 教室大屏上立刻显示成 ClassHelper 下发的这一份。
-            var conflicts = profile.ClassPlans
-                .Where(pair => pair.Key != planId
-                               && pair.Value.IsEnabled
-                               && !pair.Value.Name.StartsWith(PlanNamePrefix, StringComparison.Ordinal)
-                               && pair.Value.TimeRule.WeekDay == group.WeekDay
-                               && pair.Value.TimeRule.WeekCountDivTotal == group.WeekCountDivTotal
-                               && pair.Value.TimeRule.WeekCountDiv == group.WeekCountDiv)
-                .ToList();
-            if (conflicts.Count > 0)
-            {
-                var names = string.Join("、", conflicts.Select(pair => pair.Value.Name));
-                if (force)
-                {
-                    foreach (var pair in conflicts) pair.Value.IsEnabled = false;
-                    result.Warnings.Add(
-                        $"星期 {group.WeekDay} 原有的课表（{names}）已停用，教室显示改以 ClassHelper 下发的课表为准" +
-                        "（只停用、未删除，可在 ClassIsland 的课表面板里重新启用）");
-                }
-                else
-                {
-                    result.Warnings.Add(
-                        $"星期 {group.WeekDay} 已有启用的课表（{names}），两者重叠时以 ClassHelper 同步的课表为准");
-                }
-            }
-        }
-
-        // 3) 停用上一次镜像留下来的、本次不再需要的课表（只动自己创建的）
-        var currentNames = new HashSet<string>(result.PlanNames);
-        foreach (var pair in profile.ClassPlans)
-        {
-            if (!pair.Value.Name.StartsWith(PlanNamePrefix, StringComparison.Ordinal)) continue;
-            if (currentNames.Contains(pair.Value.Name)) continue;
-            pair.Value.IsEnabled = false;
-        }
-
-        result.Applied = true;
-        return result;
-    }
-
-    private static void EnsureSubjects(Profile profile, ClassPlanMirrorDto source)
-    {
-        foreach (var name in source.Entries.Select(entry => entry.Subject).Distinct())
-        {
-            if (string.IsNullOrWhiteSpace(name)) continue;
-            if (profile.Subjects.Any(pair => pair.Value.Name == name)) continue;
-            profile.Subjects[Guid.NewGuid()] = new Subject { Name = name };
-        }
-    }
-
-    private static Guid FindPlanId(Profile profile, string planName)
-    {
-        var existing = profile.ClassPlans.FirstOrDefault(pair => pair.Value.Name == planName);
-        return existing.Key != Guid.Empty ? existing.Key : Guid.NewGuid();
-    }
-
-    /// <summary>
-    /// 按分组内的条目重建时间表：**每节课之间补一个课间**（最后一节之后不补）。
-    ///
-    /// 课间 = 「上一节下课」到「下一节上课」之间的那段空隙，直接由两条课目的时间算出来，
-    /// 不依赖服务端有没有给课间点 —— 这样无论 ClassHelper那边是否维护节次时间表，
-    /// ClassIsland 档案里的课表都会有一致的课间（需求：每节课的间隔都是课间，放学后除外）。
-    /// </summary>
-    private static (Guid Id, TimeLayout Layout) BuildTimeLayout(
-        Profile profile,
-        string planName,
-        IReadOnlyList<ClassPlanEntryMirrorDto> entries)
-    {
-        var layoutName = planName + TimeLayoutNameSuffix;
-        var existing = profile.TimeLayouts.FirstOrDefault(pair => pair.Value.Name == layoutName);
-        var id = existing.Key != Guid.Empty ? existing.Key : Guid.NewGuid();
-
-        var layout = new TimeLayout { Name = layoutName, IsActivated = true };
-        for (var index = 0; index < entries.Count; index++)
-        {
-            var entry = entries[index];
-            layout.Layouts.Add(new TimeLayoutItem
-            {
-                TimeType = 0, // 上课
-                StartTime = ParseTime(entry.StartTime),
-                EndTime = ParseTime(entry.EndTime),
-            });
-
-            // 课间：下一节开始晚于本节结束才有空隙；最后一节之后（放学）不插
-            if (index + 1 >= entries.Count) continue;
-            var next = entries[index + 1];
-            var breakStart = ParseTime(entry.EndTime);
-            var breakEnd = ParseTime(next.StartTime);
-            if (breakEnd <= breakStart) continue;
-
-            layout.Layouts.Add(new TimeLayoutItem
-            {
-                TimeType = 1, // 课间
-                StartTime = breakStart,
-                EndTime = breakEnd,
-            });
-        }
-
-        profile.TimeLayouts[id] = layout;
-        return (id, layout);
-    }
-
-    /// <summary>
-    /// 课表名：单组时用「ClassHelper-&lt;班级名&gt;」；多组时补上星期与单双周以免互相覆盖。
-    /// </summary>
-    private static string BuildPlanName(
-        string profileName,
-        int weekDay,
-        int weekCountDiv,
-        int weekCountDivTotal,
-        int groupCount)
-    {
-        var baseName = string.IsNullOrWhiteSpace(profileName) ? "ClassHelper课表" : profileName.Trim();
-        if (!baseName.StartsWith(PlanNamePrefix, StringComparison.Ordinal))
-        {
-            baseName = PlanNamePrefix + baseName;
-        }
-        if (groupCount <= 1) return baseName;
-
-        var weekday = weekDay switch
-        {
-            0 => "周日",
-            1 => "周一",
-            2 => "周二",
-            3 => "周三",
-            4 => "周四",
-            5 => "周五",
-            6 => "周六",
-            _ => $"星期{weekDay}",
-        };
-        var parity = weekCountDivTotal <= 1
-            ? "每周"
-            : $"第{weekCountDiv}/{weekCountDivTotal}周";
-        return $"{baseName} · {weekday} · {parity}";
-    }
-
-    /// <summary>"HH:mm" / "HH:mm:ss" → TimeSpan（解析失败回退到 0 点）。</summary>
-    private static TimeSpan ParseTime(string value)
-    {
-        return TimeSpan.TryParse(value, out var parsed) ? parsed : TimeSpan.Zero;
-    }
-
-    /// <summary>
-    /// 时间字符串是否可用（HH:mm / HH:mm:ss）。
-    ///
-    /// 服务端输出侧没有校验 `Schedule.startTime`（老数据/异常数据可能是空串），
-    /// 而 <see cref="ParseTime"/> 会把非法值变成 0 点 —— 因此调用方必须先用本方法过滤，
-    /// 并把 Classes 与时间表**同时**按过滤后的列表构造，保证索引仍然一致。
-    /// </summary>
-    private static bool IsValidTime(string? value)
-    {
-        if (string.IsNullOrWhiteSpace(value)) return false;
-        return TimeSpan.TryParse(value, out var parsed)
-               && parsed >= TimeSpan.Zero
-               && parsed < TimeSpan.FromDays(1);
-    }
-}

packages/classisland-plugin/src/Services/ScheduleMapper.cs

@@ -1,272 +0,0 @@
-using System.Collections.ObjectModel;
-using ClassHelper.ClassIslandPlugin.Interop;
-using ClassIsland.Core.Abstractions.Services;
-using ClassIsland.Shared;
-using ClassIsland.Shared.Enums;
-using ClassIsland.Shared.Models.Profile;
-
-namespace ClassHelper.ClassIslandPlugin.Services;
-
-/// <summary>
-/// 课表 / 状态 → 上报载荷 的换算层。
-///
-/// 这里集中全部"ClassIsland 口径 ↔ ClassHelper口径"的转换，保证只有一处需要跟着
-/// ClassIsland 的模型变化而修改：
-/// - 星期：ClassIsland <c>WeekDay</c> 是 0=周日、1=周一…6=周六；本系统是 1=周一…7=周日；
-/// - 单双周：ClassIsland <c>WeekCountDiv</c>/<c>WeekCountDivTotal</c>；本系统 ALL/ODD/EVEN；
-/// - 节次：ClassIsland <c>TimeLayoutItem.TimeType</c> 0=上课 1=课间 2=分割线 3=行动。
-/// </summary>
-public static class ScheduleMapper
-{
-    /// <summary>
-    /// ClassIsland 的 WeekDay（0=周日…6=周六）→ 本系统 dayOfWeek（1=周一…7=周日）。
-    /// </summary>
-    public static int ToServerDayOfWeek(int weekDay)
-    {
-        var normalized = ((weekDay % 7) + 7) % 7;
-        return normalized == 0 ? 7 : normalized;
-    }
-
-    /// <summary>
-    /// ClassIsland 的 WeekCountDiv/Total → 本系统单双周。
-    /// 与 <c>packages/shared/src/utils.ts</c> 的 <c>weekParityFromDiv</c> 完全一致：
-    /// 3 周及以上的循环本系统无法表达，降级为「每周」。
-    /// </summary>
-    public static string ToWeekParity(int weekCountDiv, int weekCountDivTotal)
-    {
-        if (weekCountDiv <= 0 || weekCountDivTotal <= 1) return "ALL";
-        var position = ((weekCountDiv - 1) % weekCountDivTotal) + 1;
-        if (weekCountDivTotal == 2) return position == 1 ? "ODD" : "EVEN";
-        return "ALL";
-    }
-
-    /// <summary>ClassIsland TimeType → 本系统节次类型。</summary>
-    public static string ToTimeLayoutType(int timeType) => timeType switch
-    {
-        1 => "break",
-        2 => "divider",
-        3 => "action",
-        _ => "class",
-    };
-
-    /// <summary>TimeSpan → "HH:mm"（跨天的时间点做钳制，避免出现 24:xx）。</summary>
-    public static string ToHhMm(TimeSpan time)
-    {
-        var totalMinutes = (int)Math.Round(time.TotalMinutes);
-        totalMinutes = Math.Clamp(totalMinutes, 0, 24 * 60 - 1);
-        return $"{totalMinutes / 60:D2}:{totalMinutes % 60:D2}";
-    }
-
-    /// <summary>
-    /// 把档案里的一张课表（ClassPlan）展开成"每个上课时间点一条"的课表条目。
-    ///
-    /// 与 ClassIsland 的语义严格对齐：<c>ClassPlan.Classes[i]</c> 对应
-    /// <c>TimeLayout.Layouts</c> 里**第 i 个 TimeType=0（上课）的点**，课间 / 分割线 / 行动不占位。
-    ///
-    /// **注意不要用 `plan.ValidTimeLayoutItems`**：它的口径与 `Classes` 不同 ——
-    /// `GetValidTimeLayoutItems()`（ClassIsland ClassPlan.cs）会正反两遍扫描，
-    /// 把 `ClassInfo.IsEnabled == false`（老师在课表编辑里"停用"这一节）的课**连同其后的课间**
-    /// 一起从结果里剔除；而 `RefreshClassesList()` 只按 `TimeType == 0` 的**总数**对齐
-    /// `Classes` 的长度，`ClassInfo.CurrentTimeLayoutItem` 也是按原始列表的第 `Index` 个取的。
-    /// 于是只要停用过任意一节，用 ValidTimeLayoutItems 配对就会让索引整体前移：
-    /// 第 i 节配上第 i+1 节的时间点、最后一节丢失，且 `Math.Min` 会把缺口静默吃掉 ——
-    /// 表现就是"课表看着有内容、每节课都对不上"，极难排查。
-    /// </summary>
-    public static List<ScheduleEntryDto> MapClassPlan(ClassPlan plan, Profile profile, out string? warning)
-    {
-        warning = null;
-        var entries = new List<ScheduleEntryDto>();
-
-        var timeLayout = ResolveTimeLayout(plan, profile);
-        if (timeLayout is null)
-        {
-            warning = $"课表「{plan.Name}」找不到对应的时间表，已跳过";
-            return entries;
-        }
-
-        // 只保留上课类型的时间点，顺序必须与 Classes 的索引一致（见上面注释）
-        var classPoints = timeLayout.Layouts.Where(item => item.TimeType == 0).ToList();
-
-        var weekDay = ToServerDayOfWeek(plan.TimeRule.WeekDay);
-        var parity = ToWeekParity(plan.TimeRule.WeekCountDiv, plan.TimeRule.WeekCountDivTotal);
-        if (plan.TimeRule.WeekCountDivTotal > 2)
-        {
-            warning = "存在 3 周以上的轮换课表，ClassHelper只支持单双周，已按「每周」处理";
-        }
-
-        var classes = plan.Classes;
-        var count = Math.Min(classes.Count, classPoints.Count);
-        for (var index = 0; index < count; index++)
-        {
-            var info = classes[index];
-            // 索引必须与 Classes 对齐：这里按下标取时间点，**不能**先用 Where 过滤再取
-            var point = classPoints[index];
-            if (info is null) continue;
-            // 老师停用的一节：本系统没有"停用"概念，不上报（否则 ClassHelper 班级端会看到一节实际上不上的课）
-            if (!info.IsEnabled) continue;
-
-            // 空课（未安排科目）不上报：服务端的科目是必填的，空课由课表里的缺席表达
-            var subject = ResolveSubjectName(info.SubjectId, profile);
-            if (string.IsNullOrWhiteSpace(subject)) continue;
-
-            entries.Add(new ScheduleEntryDto
-            {
-                DayOfWeek = weekDay,
-                StartTime = ToHhMm(point.StartTime),
-                EndTime = ToHhMm(point.EndTime),
-                // 服务端对这几个字段有 zod 长度上限，且是**整批**校验：一个超长名字会让整次上报
-                // 400，连"现在上什么课"的状态与心跳都不更新，Web 端把教室显示成离线。
-                Subject = Truncate(subject, SubjectMaxLength)!,
-                TeacherName = Truncate(ResolveSubjectTeacher(info.SubjectId, profile), NameMaxLength),
-                WeekParity = parity,
-                WeekCountDiv = plan.TimeRule.WeekCountDiv,
-                WeekCountDivTotal = plan.TimeRule.WeekCountDivTotal,
-                PlanName = Truncate(plan.Name, PlanNameMaxLength),
-            });
-        }
-
-        return entries;
-    }
-
-    /// <summary>服务端 zod 对各类名称的长度上限（超出会让整批上报 400，所以要截断） */
-    public const int SubjectMaxLength = 40;
-    public const int NameMaxLength = 40;
-    public const int PlanNameMaxLength = 60;
-
-    /// <summary>按服务端上限截断（null / 空串原样返回）</summary>
-    public static string? Truncate(string? value, int max)
-    {
-        if (string.IsNullOrEmpty(value)) return value;
-        var trimmed = value.Trim();
-        return trimmed.Length <= max ? trimmed : trimmed[..max];
-    }
-
-    /// <summary>把时间表（TimeLayout）转成本系统的节次时间配置。</summary>
-    public static List<TimeLayoutItemDto> MapTimeLayout(TimeLayout layout)
-    {
-        var items = new List<TimeLayoutItemDto>();
-        // ClassIsland 的上课时间点没有独立名称，这里按"它之前有几个上课点"编出"第 N 节"
-        var classPointIndex = 0;
-        for (var index = 0; index < layout.Layouts.Count; index++)
-        {
-            var point = layout.Layouts[index];
-            items.Add(new TimeLayoutItemDto
-            {
-                Index = index + 1,
-                // 节次名同样是服务端有上限的字段（max 40），超长会让整批上报失败
-                Name = Truncate(BuildTimePointName(point, ref classPointIndex), NameMaxLength)!,
-                StartTime = ToHhMm(point.StartTime),
-                EndTime = ToHhMm(point.EndTime),
-                Type = ToTimeLayoutType(point.TimeType),
-                Skipped = false,
-            });
-        }
-        return items;
-    }
-
-    /// <summary>
-    /// 节次名称：ClassIsland 只有课间有名字（BreakName），上课时间点没有独立名称，
-    /// 因此按类型生成"第 N 节 / 课间 / 分割线"，保证本系统的时间轴可读。
-    /// </summary>
-    private static string BuildTimePointName(TimeLayoutItem point, ref int classPointIndex)
-    {
-        switch (point.TimeType)
-        {
-            case 1:
-                return string.IsNullOrWhiteSpace(point.BreakName) ? "课间" : point.BreakName!;
-            case 2:
-                return "分割线";
-            case 3:
-                return "行动";
-            default:
-                classPointIndex++;
-                return $"第 {classPointIndex} 节";
-        }
-    }
-
-    /// <summary>取出课表使用的时间表：优先按 TimeLayoutId，其次用档案里第一个。</summary>
-    public static TimeLayout? ResolveTimeLayout(ClassPlan plan, Profile profile)
-    {
-        if (profile.TimeLayouts.Count == 0) return null;
-        if (plan.TimeLayoutId != Guid.Empty && profile.TimeLayouts.TryGetValue(plan.TimeLayoutId, out var byId))
-        {
-            return byId;
-        }
-        return plan.TimeLayout ?? profile.TimeLayouts.Values.FirstOrDefault();
-    }
-
-    /// <summary>科目名（找不到时返回空字符串，由调用方决定是否跳过）。</summary>
-    public static string? ResolveSubjectName(Guid subjectId, Profile profile)
-    {
-        if (subjectId == Guid.Empty) return null;
-        return profile.Subjects.TryGetValue(subjectId, out var subject) ? subject.Name : null;
-    }
-
-    /// <summary>科目任课老师（ClassIsland 在 Subject 上记录 TeacherName）。</summary>
-    public static string? ResolveSubjectTeacher(Guid subjectId, Profile profile)
-    {
-        if (subjectId == Guid.Empty) return null;
-        return profile.Subjects.TryGetValue(subjectId, out var subject) ? subject.TeacherName : null;
-    }
-
-    /// <summary>
-    /// 收集档案里今天（按当前周次与星期）应该上的课表，
-    /// 用于"只上报今天"这类轻量场景；当前实现为上报全部课表（服务端按周次并存）。
-    /// </summary>
-    public static List<ScheduleEntryDto> MapAllClassPlans(Profile profile, out List<string> warnings)
-    {
-        warnings = new List<string>();
-        var all = new List<ScheduleEntryDto>();
-        foreach (var plan in profile.ClassPlans.Values)
-        {
-            if (!plan.IsEnabled) continue;
-            if (plan.IsOverlay) continue; // 临时层课表不下发，避免把临时调整固化到班级课表
-            var entries = MapClassPlan(plan, profile, out var warning);
-            if (!string.IsNullOrWhiteSpace(warning) && !warnings.Contains(warning!))
-            {
-                warnings.Add(warning!);
-            }
-            all.AddRange(entries);
-        }
-        return all;
-    }
-
-    /// <summary>
-    /// 科目名归一化。
-    ///
-    /// 没有课表 / 没有当前科目时，ClassIsland 会把 <see cref="Subject.Fallback"/> 挂到
-    /// `CurrentSubject` / `NextClassSubject` 上（见 LessonsService：
-    /// `CurrentSubject = currentSubject ?? Subject.Fallback`），而它的名字就是占位符本身。
-    /// 直接上报会让 Web 端显示成"正在上 ???"，因此这里统一折算成"没有科目"。
-    /// </summary>
-    private static string? NormalizeSubjectName(Subject? subject)
-    {
-        if (subject is null) return null;
-        if (ReferenceEquals(subject, Subject.Fallback)) return null;
-
-        var name = subject.Name?.Trim();
-        if (string.IsNullOrEmpty(name)) return null;
-        // 兜底：万一拿到的是另一个同名占位符实例（不是同一个引用）
-        if (string.Equals(name, Subject.Fallback.Name, StringComparison.Ordinal)) return null;
-        return name;
-    }
-
-    /// <summary>当前状态快照：服务端据此在 Web 端展示"现在上什么课"。</summary>
-    public static StateDto BuildState(ILessonsService lessons, int? currentWeek)
-    {
-        var current = lessons.CurrentTimeLayoutItem;
-        var state = lessons.CurrentState;
-        return new StateDto
-        {
-            InClass = state == TimeState.OnClass,
-            Subject = NormalizeSubjectName(lessons.CurrentSubject),
-            NextSubject = NormalizeSubjectName(lessons.NextClassSubject),
-            TimeState = state.ToString(),
-            PeriodStart = current is null || current == TimeLayoutItem.Empty ? null : ToHhMm(current.StartTime),
-            PeriodEnd = current is null || current == TimeLayoutItem.Empty ? null : ToHhMm(current.EndTime),
-            Week = currentWeek,
-            ClassPlanLoaded = lessons.IsClassPlanLoaded,
-            ClientTime = DateTimeOffset.Now.ToString("o"),
-        };
-    }
-}

packages/classisland-plugin/src/Views/BridgeSettingsPage.axaml

@@ -1,150 +0,0 @@
-<controls:SettingsPageBase x:Class="ClassHelper.ClassIslandPlugin.Views.BridgeSettingsPage"
-      xmlns="https://github.com/avaloniaui"
-      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
-      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
-      xmlns:local="clr-namespace:ClassHelper.ClassIslandPlugin.Views"
-      xmlns:controls="clr-namespace:ClassIsland.Core.Abstractions.Controls;assembly=ClassIsland.Core"
-      xmlns:ci="clr-namespace:ClassIsland.Core.Controls;assembly=ClassIsland.Core"
-      xmlns:fa="clr-namespace:FluentAvalonia.UI.Controls;assembly=FluentAvalonia"
-      mc:Ignorable="d"
-      d:DesignHeight="450" d:DesignWidth="800"
-      d:DataContext="{d:DesignInstance local:BridgeSettingsPage}"
-      Loaded="OnLoaded"
-      Unloaded="OnUnloaded">
-    <ScrollViewer>
-        <StackPanel Classes="settings-container animated-intro" Spacing="0">
-            <!-- 连接 -->
-            <TextBlock Text="连接 ClassHelper"
-                       Theme="{StaticResource SubtitleTextBlockStyle}" />
-            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
-                       Text="填入 ClassHelper后端的地址与设备令牌。设备令牌在 ClassHelper Web 端「ClassIsland 联动」页面里为本班新建设备后生成，只显示一次。" />
-
-            <TextBox Watermark="http://127.0.0.1:4000"
-                     Text="{Binding Settings.ServerUrl, Mode=TwoWay}" />
-            <TextBox Margin="0 8 0 0"
-                     Watermark="chci_..."
-                     PasswordChar="●"
-                     Text="{Binding Settings.DeviceToken, Mode=TwoWay}" />
-            <!-- 令牌是设备级长期凭证（只有管理员在 Web 端重置才会失效），而 ClassIsland 的插件配置
-                 是明文 JSON 且会随档案备份/迁移一起被带走，所以这里明确提示用户别外传。 -->
-            <TextBlock Margin="0 6 0 0" TextWrapping="Wrap" Opacity="0.7"
-                       Text="令牌是这台教室机器的长期凭证（仅管理员在 Web 端重置才会失效），会明文保存在本机配置文件里并随 ClassIsland 档案备份一起复制，请不要外传或提交到版本库。" />
-
-            <StackPanel Orientation="Horizontal" Margin="0 12 0 0" Spacing="8">
-                <Button Content="立即上报" Command="{Binding ReportCommand}" IsEnabled="{Binding !Bridge.Busy}" />
-                <Button Content="检查连接" Command="{Binding TestCommand}" IsEnabled="{Binding !Bridge.Busy}" />
-                <Button Content="拉取待提醒" Command="{Binding PullCommand}" IsEnabled="{Binding !Bridge.Busy}" />
-                <Button Content="重建档案课表" Command="{Binding MirrorCommand}" IsEnabled="{Binding !Bridge.Busy}" />
-            </StackPanel>
-
-            <!-- 状态 -->
-            <Border Margin="0 16 0 0" Padding="12" CornerRadius="4"
-                    Background="{DynamicResource SystemFillColorNeutralBackgroundBrush}">
-                <StackPanel Spacing="4">
-                    <TextBlock Text="{Binding StatusText}" TextWrapping="Wrap" FontWeight="SemiBold" />
-                    <TextBlock Text="{Binding Bridge.LastReportMessage}" TextWrapping="Wrap" />
-                    <TextBlock Text="{Binding DetailText}" TextWrapping="Wrap" Opacity="0.8" />
-                </StackPanel>
-            </Border>
-
-            <!-- 同步 -->
-            <TextBlock Margin="0 24 0 0" Text="课表同步"
-                       Theme="{StaticResource SubtitleTextBlockStyle}" />
-            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
-                       Text="课表的两个方向都是按需的，由 Web 端「ClassIsland 联动」页的两个按钮触发，本机不再提供「一直同步」的开关：「从教室机器获取课表」把 ClassIsland 里启用的课表合并进 ClassHelper；「下发课表到教室」把 ClassHelper 排好的课表写回 ClassIsland，并把同一天同一单双周相位下冲突的旧课表停用（只停用、不删除，可在 ClassIsland 的课表面板里重新启用）。" />
-
-            <fa:SettingsExpander Header="自动上报"
-                                 Description="应用启动、课程事件以及每隔一段时间各上报一次**运行状态**（现在上什么课、ClassIsland 版本等）。课表不在这条路径上 —— 它只由 Web 端「从教室机器获取课表」按需拉取。关闭后只能用上面的「立即上报」手动触发。">
-                <fa:SettingsExpander.IconSource>
-                    <ci:FluentIconSource Glyph="&#xE895;" />
-                </fa:SettingsExpander.IconSource>
-                <fa:SettingsExpander.Footer>
-                    <ToggleSwitch IsChecked="{Binding Settings.AutoReport, Mode=TwoWay}" />
-                </fa:SettingsExpander.Footer>
-            </fa:SettingsExpander>
-
-            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
-                <StackPanel>
-                    <TextBlock Text="上报间隔（秒）" />
-                    <TextBlock Text="最小 15 秒；教室机器建议 60 秒。" Opacity="0.7" TextWrapping="Wrap" />
-                </StackPanel>
-                <NumericUpDown Grid.Column="1" Width="140"
-                               Minimum="15" Maximum="3600" Increment="15"
-                               FormatString="0"
-                               IsEnabled="{Binding Settings.AutoReport}"
-                               Value="{Binding Settings.ReportIntervalSeconds, Mode=TwoWay}" />
-            </Grid>
-
-            <!-- 提醒 -->
-            <TextBlock Margin="0 24 0 0" Text="提醒"
-                       Theme="{StaticResource SubtitleTextBlockStyle}" />
-            <TextBlock Margin="0 6 0 12" TextWrapping="Wrap"
-                       Text="老师在 ClassHelper上发布的提醒会以 ClassIsland 的全屏提醒呈现；未弹出的提醒在应用重开后会自动补发，确认弹出后不再重复。" />
-
-            <fa:SettingsExpander Header="接收 ClassHelper提醒"
-                                 Description="关闭后本机会忽略老师在 ClassHelper上发布的提醒（提醒仍会留在班级通知中心）。">
-                <fa:SettingsExpander.IconSource>
-                    <ci:FluentIconSource Glyph="&#xE8BD;" />
-                </fa:SettingsExpander.IconSource>
-                <fa:SettingsExpander.Footer>
-                    <ToggleSwitch IsChecked="{Binding Settings.ReceiveNotifications, Mode=TwoWay}" />
-                </fa:SettingsExpander.Footer>
-            </fa:SettingsExpander>
-
-            <fa:SettingsExpander Header="语音朗读"
-                                 Description="提醒弹出时按 ClassIsland 的语音设置为全机朗读提醒内容。">
-                <fa:SettingsExpander.IconSource>
-                    <ci:FluentIconSource Glyph="&#xE8D6;" />
-                </fa:SettingsExpander.IconSource>
-                <fa:SettingsExpander.Footer>
-                    <ToggleSwitch IsChecked="{Binding Settings.SpeechEnabled, Mode=TwoWay}" />
-                </fa:SettingsExpander.Footer>
-            </fa:SettingsExpander>
-
-            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
-                <StackPanel>
-                    <TextBlock Text="默认显示时长（秒）" />
-                    <TextBlock Text="老师在下发单条提醒时可以另外指定更长的时长。" Opacity="0.7" TextWrapping="Wrap" />
-                </StackPanel>
-                <NumericUpDown Grid.Column="1" Width="140"
-                               Minimum="1" Maximum="120" Increment="1"
-                               FormatString="0"
-                               Value="{Binding Settings.NotificationDurationSeconds, Mode=TwoWay}" />
-            </Grid>
-
-            <Grid Margin="0 8 0 0" ColumnDefinitions="*,Auto">
-                <StackPanel>
-                    <TextBlock Text="提醒轮询间隔（秒）" />
-                    <TextBlock Text="老师按下发送到教室弹出之间的最大延迟（插件不持有长连接，是轮询取回提醒）。默认 10 秒。"
-                               Opacity="0.7" TextWrapping="Wrap" />
-                </StackPanel>
-                <NumericUpDown Grid.Column="1" Width="140"
-                               Minimum="5" Maximum="600" Increment="5"
-                               FormatString="0"
-                               IsEnabled="{Binding Settings.ReceiveNotifications}"
-                               Value="{Binding Settings.NotificationPollSeconds, Mode=TwoWay}" />
-            </Grid>
-
-            <!-- 调试 -->
-            <TextBlock Margin="0 24 0 0" Text="调试"
-                       Theme="{StaticResource SubtitleTextBlockStyle}" />
-            <fa:SettingsExpander Header="显示调试信息"
-                                 Description="显示设备标识、时钟差等细节，排查「为什么同步不上」时打开。">
-                <fa:SettingsExpander.IconSource>
-                    <ci:FluentIconSource Glyph="&#xE7EF;" />
-                </fa:SettingsExpander.IconSource>
-                <fa:SettingsExpander.Footer>
-                    <ToggleSwitch IsChecked="{Binding Settings.ShowDebugInfo, Mode=TwoWay}" />
-                </fa:SettingsExpander.Footer>
-            </fa:SettingsExpander>
-
-            <StackPanel Margin="0 8 0 0" Spacing="2" IsVisible="{Binding Settings.ShowDebugInfo}">
-                <TextBlock Text="{Binding DebugText}" TextWrapping="Wrap" FontFamily="Consolas,monospace" />
-            </StackPanel>
-
-            <TextBlock Margin="0 24 0 0" Opacity="0.6" TextWrapping="Wrap"
-                       Text="提示：ClassHelper Web 端 →「ClassIsland 联动」可以新建/重置设备令牌、开关同步项，并实时看到本机当前上的课。" />
-        </StackPanel>
-    </ScrollViewer>
-</controls:SettingsPageBase>

packages/classisland-plugin/src/Views/BridgeSettingsPage.axaml.cs

@@ -1,198 +0,0 @@
-using System.ComponentModel;
-using System.Runtime.CompilerServices;
-using Avalonia.Threading;
-using ClassHelper.ClassIslandPlugin.Models;
-using ClassHelper.ClassIslandPlugin.Services;
-using ClassIsland.Core.Abstractions.Controls;
-using ClassIsland.Core.Attributes;
-using ClassIsland.Core.Enums.SettingsWindow;
-using CommunityToolkit.Mvvm.Input;
-
-namespace ClassHelper.ClassIslandPlugin.Views;
-
-/// <summary>
-/// 「ClassHelper 联动」设置页。
-///
-/// 页面上的绑定源就是本页自己（<c>DataContext = this</c>）：<see cref="Settings"/> 暴露全部配置项，
-/// <see cref="Bridge"/> 暴露运行状态。这样 XAML 里能直接写 <c>{Binding Settings.Xxx}</c>，
-/// 不需要再套一层 ViewModel，改配置项时也少一处"两边同步"的机会。
-/// </summary>
-// 图标用 Fluent 字体的码位（与 ClassIsland 内置设置页写法一致）：未选中/选中同一枚插头图标
-[SettingsPageInfo(
-    "classhelper.classisland.bridge.settings",
-    "ClassHelper 联动",
-    "\uE71B",
-    "\uE71B",
-    SettingsPageCategory.External)]
-public partial class BridgeSettingsPage : SettingsPageBase, INotifyPropertyChanged
-{
-    public BridgeSettingsPage(PluginSettings settings, BridgeService bridge)
-    {
-        Settings = settings;
-        Bridge = bridge;
-
-        ReportCommand = new AsyncRelayCommand(ReportAsync);
-        TestCommand = new AsyncRelayCommand(TestAsync);
-        PullCommand = new AsyncRelayCommand(PullAsync);
-        MirrorCommand = new AsyncRelayCommand(MirrorAsync);
-
-        InitializeComponent();
-        DataContext = this;
-        Raise(nameof(StatusText));
-    }
-
-    public PluginSettings Settings { get; }
-
-    public BridgeService Bridge { get; }
-
-    public IAsyncRelayCommand ReportCommand { get; }
-    public IAsyncRelayCommand TestCommand { get; }
-    public IAsyncRelayCommand PullCommand { get; }
-    public IAsyncRelayCommand MirrorCommand { get; }
-
-    private PropertyChangedEventHandler? _propertyChanged;
-
-    /// <summary>
-    /// 显式实现 <see cref="INotifyPropertyChanged"/>：<c>AvaloniaObject</c> 自带一个同名但类型不同的事件，
-    /// 直接声明会遮蔽基类成员。显式实现既不影响 Avalonia 的绑定查找（它按接口取），也不会有歧义。
-    /// </summary>
-    event PropertyChangedEventHandler? INotifyPropertyChanged.PropertyChanged
-    {
-        add => _propertyChanged += value;
-        remove => _propertyChanged -= value;
-    }
-
-    /* ---------------------------------------------------------------- 绑定用的展示文本 */
-
-    /// <summary>一句话结论：还没配 / 已配置 / 已连接 / 连接异常。</summary>
-    public string StatusText
-    {
-        get
-        {
-            if (!Settings.IsConfigured) return "尚未配置：请填写服务器地址与设备令牌";
-            if (!Bridge.IsAttached) return "已填写配置，等待 ClassIsland 课程服务就绪";
-            return Bridge.LastReportOk ? "已连接" : "连接异常";
-        }
-    }
-
-    public string DetailText
-    {
-        get
-        {
-            var week = Bridge.LastServerWeek?.ToString() ?? "—";
-            return $"最后上报：{Bridge.LastReportAtText}　教学周：{week}　" +
-                   $"课表 {Bridge.LastScheduleEntryCount} 节 / 节次 {Bridge.LastTimeLayoutItemCount} 条　" +
-                   $"已弹出提醒：{Bridge.NotificationCount} 条";
-        }
-    }
-
-    /// <summary>调试信息（设置页里打开"显示调试信息"才可见）。</summary>
-    public string DebugText
-    {
-        get
-        {
-            var lines = new List<string>
-            {
-                $"服务器地址：{(string.IsNullOrWhiteSpace(Settings.ServerUrl) ? "(未填)" : Settings.ServerUrl)}",
-                $"设备令牌：{(string.IsNullOrWhiteSpace(Settings.DeviceToken) ? "(未填)" : Mask(Settings.DeviceToken))}",
-                $"设备标识：{(string.IsNullOrWhiteSpace(Settings.DeviceKey) ? "(未生成)" : Settings.DeviceKey)}",
-                $"课程服务：{(Bridge.IsAttached ? "已接入" : "未接入")}",
-                $"与服务端时钟差：{Bridge.ClientTimeOffsetText}",
-                $"ClassIsland 版本：{SafeVersion()}",
-                $"配置目录：{PluginConfigFolder}",
-            };
-            return string.Join(Environment.NewLine, lines);
-        }
-    }
-
-    /// <summary>设置页所在的插件配置目录（从插件入口拿；拿不到时留空）。</summary>
-    private string PluginConfigFolder =>
-        ClassIsland.Shared.IAppHost.TryGetService<ClassIsland.Core.Abstractions.PluginBase>()?.PluginConfigFolder ?? "—";
-
-    private static string SafeVersion()
-    {
-        try { return ClassIsland.Core.AppBase.AppVersion ?? "—"; }
-        catch { return "—"; }
-    }
-
-    /// <summary>令牌只露头尾，避免设置页截图时把可用凭证泄露出去。</summary>
-    private static string Mask(string token) =>
-        token.Length <= 14 ? token : $"{token[..12]}…{token[^4..]}";
-
-    /* ---------------------------------------------------------------- 交互 */
-
-    private async Task ReportAsync()
-    {
-        await Bridge.ReportAsync("手动").ConfigureAwait(true);
-    }
-
-    /// <summary>不带课表上报一次：用来快速验证"地址 + 令牌"是否可用，不会因为课表为空而出错。</summary>
-    private async Task TestAsync()
-    {
-        await Bridge.ReportAsync("连接检查", includeSchedule: false).ConfigureAwait(true);
-    }
-
-    private async Task PullAsync()
-    {
-        await Bridge.PullPendingAsync().ConfigureAwait(true);
-    }
-
-    private async Task MirrorAsync()
-    {
-        await Bridge.MirrorScheduleAsync().ConfigureAwait(true);
-    }
-
-    private void OnSettingsChanged(object? sender, PropertyChangedEventArgs args)
-    {
-        // 影响上报链路的改动需要立刻重建定时器；纯界面项（如"显示调试信息"）不用管
-        if (args.PropertyName is nameof(PluginSettings.ServerUrl)
-            or nameof(PluginSettings.DeviceToken)
-            or nameof(PluginSettings.AutoReport)
-            or nameof(PluginSettings.ReportIntervalSeconds)
-            or nameof(PluginSettings.ReceiveNotifications)
-            or nameof(PluginSettings.NotificationPollSeconds))
-        {
-            Bridge.RestartTimer();
-        }
-
-        Raise(nameof(StatusText));
-        Raise(nameof(DebugText));
-    }
-
-    private void OnBridgeChanged(object? sender, PropertyChangedEventArgs args)
-    {
-        // Bridge 的属性变化可能来自线程池（HttpClient 回调），绑定必须在 UI 线程上更新
-        if (Dispatcher.UIThread.CheckAccess())
-        {
-            RaiseStateProperties();
-        }
-        else
-        {
-            Dispatcher.UIThread.Post(RaiseStateProperties);
-        }
-    }
-
-    private void RaiseStateProperties()
-    {
-        Raise(nameof(StatusText));
-        Raise(nameof(DetailText));
-        Raise(nameof(DebugText));
-    }
-
-    private void OnLoaded(object sender, Avalonia.Interactivity.RoutedEventArgs args)
-    {
-        // 改完地址/令牌/间隔要重建定时器，否则"改了设置但上报节奏还是旧的"
-        Settings.PropertyChanged += OnSettingsChanged;
-        // 运行状态（上一次上报结果 / 待弹出提醒数）变了要刷新状态卡片
-        Bridge.PropertyChanged += OnBridgeChanged;
-    }
-
-    private void OnUnloaded(object sender, Avalonia.Interactivity.RoutedEventArgs args)
-    {
-        Settings.PropertyChanged -= OnSettingsChanged;
-        Bridge.PropertyChanged -= OnBridgeChanged;
-    }
-
-    private void Raise([CallerMemberName] string? propertyName = null) =>
-        _propertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
-}

packages/desktop-client/native/update-helper.cs

@@ -0,0 +1,172 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Web.Script.Serialization;
+
+// 独立 WinExe：从 updates 目录运行，安装器覆盖应用时不会锁住安装目录。
+// 只接收主进程生成的清单；不接受任意命令或安装参数。
+internal static class UpdateHelper
+{
+    public sealed class Manifest
+    {
+        public string Attempt;
+        public int ParentId;
+        public string ParentExe;
+        public string Installer;
+        public string RestartExe;
+        public string Version;
+        public string ServerUrl;
+        public string Username;
+        public string Sha256;
+        public long Size;
+        public bool Portable;
+    }
+
+    private static readonly JavaScriptSerializer Json = new JavaScriptSerializer();
+    private static readonly Encoding Utf8 = new UTF8Encoding(false);
+    private static string directory;
+    private static string prefix;
+    private static Manifest manifest;
+    private static Process parent;
+    private static bool installerRunning;
+
+    [STAThread]
+    private static int Main(string[] args)
+    {
+        try
+        {
+            if (args.Length != 1) return 2;
+            var file = Path.GetFullPath(args[0]);
+            directory = Path.GetDirectoryName(file);
+            if (!String.Equals(Path.GetFileName(directory), "updates", StringComparison.OrdinalIgnoreCase)) return 2;
+            manifest = Json.Deserialize<Manifest>(File.ReadAllText(file, Utf8));
+            if (manifest == null || !Regex.IsMatch(manifest.Attempt ?? "", "^[0-9a-f-]{36}$")) return 2;
+            prefix = Path.Combine(directory, "install-" + manifest.Attempt);
+            if (!SamePath(file, prefix + ".json")) return 2;
+            Log("助手启动，目标版本 " + manifest.Version);
+            parent = Process.GetProcessById(manifest.ParentId);
+            if (!SamePath(parent.MainModule.FileName, manifest.ParentExe)) throw new Exception("旧进程身份不匹配");
+            var installer = Path.GetFullPath(manifest.Installer);
+            if (!SamePath(Path.GetDirectoryName(installer), directory) ||
+                !String.Equals(Path.GetExtension(installer), ".exe", StringComparison.OrdinalIgnoreCase) ||
+                (File.GetAttributes(installer) & FileAttributes.ReparsePoint) != 0)
+                throw new Exception("安装包不在受管理目录内");
+            if (!Regex.IsMatch(manifest.Sha256 ?? "", "^[0-9a-fA-F]{64}$")) throw new Exception("缺少有效安装包摘要");
+            if (manifest.Size <= 0 || new FileInfo(installer).Length != manifest.Size) throw new Exception("安装包长度不匹配");
+            using (var stream = File.OpenRead(installer))
+            using (var hash = SHA256.Create())
+            {
+                var actual = BitConverter.ToString(hash.ComputeHash(stream)).Replace("-", "");
+                if (!String.Equals(actual, manifest.Sha256, StringComparison.OrdinalIgnoreCase)) throw new Exception("安装包 SHA256 校验失败");
+            }
+            File.WriteAllText(prefix + ".ready", manifest.Attempt, Utf8);
+            Log("校验通过，等待主进程确认交接");
+            var deadline = DateTime.UtcNow.AddSeconds(30);
+            while (!File.Exists(prefix + ".start"))
+            {
+                if (File.Exists(prefix + ".cancel")) { Log("主进程取消交接"); return 0; }
+                if (parent.HasExited) throw new Exception("主进程在确认交接前退出");
+                if (DateTime.UtcNow >= deadline) throw new Exception("等待主进程确认超时");
+                Thread.Sleep(50);
+            }
+            if (File.ReadAllText(prefix + ".start", Utf8) != manifest.Attempt) throw new Exception("交接标识不匹配");
+            if (!parent.WaitForExit(60000)) throw new Exception("等待旧客户端退出超时");
+            Log("旧进程已退出，开始安装");
+            int exitCode;
+            using (var installerProcess = Process.Start(new ProcessStartInfo(installer, "/S --updated --force-run")
+            {
+                UseShellExecute = false,
+                CreateNoWindow = true,
+                WorkingDirectory = directory
+            }))
+            {
+                if (installerProcess == null) throw new Exception("安装器未能启动");
+                installerRunning = true;
+                if (!installerProcess.WaitForExit(10 * 60 * 1000)) throw new Exception("安装器执行超时，请查看安装日志");
+                installerRunning = false;
+                exitCode = installerProcess.ExitCode;
+            }
+            Log("安装器退出码：" + exitCode);
+            if (exitCode != 0) throw new Exception("安装器退出码：" + exitCode);
+            if (!manifest.Portable)
+            {
+                var expected = ParseVersion(manifest.Version);
+                var actual = ParseVersion(FileVersionInfo.GetVersionInfo(manifest.RestartExe).ProductVersion);
+                if (actual.CompareTo(expected) < 0) throw new Exception("安装器结束后客户端版本仍未更新");
+                // 安装器通常会启动新版；未启动时补启一次，避免留在“安装中”。
+                var startedAt = DateTime.UtcNow;
+                while (!IsClientRunning(manifest.RestartExe) && DateTime.UtcNow - startedAt < TimeSpan.FromSeconds(3)) Thread.Sleep(100);
+                if (!IsClientRunning(manifest.RestartExe)) RestartClient();
+            }
+            Result("installed", "", exitCode);
+            Log("安装交接完成，等待新版客户端心跳确认");
+            return 0;
+        }
+        catch (Exception error)
+        {
+            try { Log("更新失败：" + error.Message); Result("failed", error.Message, null); } catch { }
+            // 超时的安装器可能仍在替换文件，不可在它退出之前重新打开客户端。
+            try { if (!installerRunning && parent != null && parent.HasExited && manifest != null && File.Exists(manifest.RestartExe) && !IsClientRunning(manifest.RestartExe)) RestartClient(); }
+            catch (Exception restoreError) { try { Log("恢复客户端失败：" + restoreError.Message); } catch { } }
+            return 1;
+        }
+        finally
+        {
+            if (prefix != null) foreach (var suffix in new[] { ".ready", ".start", ".cancel", ".json" })
+                try { File.Delete(prefix + suffix); } catch { }
+            if (parent != null) parent.Dispose();
+        }
+    }
+
+    private static bool SamePath(string a, string b)
+    {
+        return String.Equals(Path.GetFullPath(a), Path.GetFullPath(b), StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static Version ParseVersion(string value)
+    {
+        Version version;
+        if (!Version.TryParse((value ?? "").Trim().TrimStart('v', 'V').Split('-', '+')[0], out version)) throw new Exception("无法识别客户端版本：" + value);
+        return version;
+    }
+
+    private static bool IsClientRunning(string exe)
+    {
+        foreach (var process in Process.GetProcessesByName(Path.GetFileNameWithoutExtension(exe)))
+        {
+            using (process) try { if (!process.HasExited && SamePath(process.MainModule.FileName, exe)) return true; } catch { }
+        }
+        return false;
+    }
+
+    private static void RestartClient()
+    {
+        Process.Start(new ProcessStartInfo(manifest.RestartExe, "--hidden")
+        {
+            UseShellExecute = false,
+            CreateNoWindow = true,
+            WorkingDirectory = Path.GetDirectoryName(manifest.RestartExe)
+        });
+        Log("已启动客户端");
+    }
+
+    private static void Log(string message)
+    {
+        if (directory != null) File.AppendAllText(Path.Combine(directory, "install-helper.log"), DateTime.UtcNow.ToString("o") + " " + message + Environment.NewLine, Utf8);
+    }
+
+    private static void Result(string stage, string error, int? exitCode)
+    {
+        if (manifest == null || prefix == null) return;
+        var value = new { version = manifest.Version, serverUrl = manifest.ServerUrl, username = manifest.Username, attempt = manifest.Attempt, stage = stage, error = error, installerExitCode = exitCode, at = DateTime.UtcNow.ToString("o") };
+        var target = Path.Combine(directory, "install-result.json");
+        var temp = prefix + ".result";
+        File.WriteAllText(temp, Json.Serialize(value), Utf8);
+        if (File.Exists(target)) File.Delete(target);
+        File.Move(temp, target);
+    }
+}

packages/desktop-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/desktop-client",
-  "version": "1.3.1",
+  "version": "1.4.2",
   "private": true,
   "description": "ClassHelper EXE 客户端（Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存）",
   "author": "Class Helper",

packages/desktop-client/scripts/build-main.mjs

@@ -6,8 +6,10 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
+import { buildUpdateHelper } from './build-update-helper.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+buildUpdateHelper(path.join(root, 'dist/main/update-helper.exe'));
 
 const shared = {
   bundle: true,

packages/desktop-client/scripts/build-update-helper.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+/** Windows 自带 .NET Framework 编译器；构建产物随客户端分发，不在教室机上编译。 */
+export function buildUpdateHelper(output) {
+  if (process.platform !== 'win32') return;
+  const framework = path.join(
+    process.env.SystemRoot ?? 'C:\\Windows',
+    'Microsoft.NET',
+    'Framework64',
+    'v4.0.30319',
+  );
+  const compiler = path.join(framework, 'csc.exe');
+  if (!fs.existsSync(compiler)) throw new Error('缺少 Windows .NET Framework 编译器，无法构建更新助手');
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  execFileSync(
+    compiler,
+    [
+      '/nologo',
+      '/target:winexe',
+      '/optimize+',
+      '/platform:anycpu',
+      `/reference:${path.join(framework, 'System.Web.Extensions.dll')}`,
+      `/out:${output}`,
+      fileURLToPath(new URL('../native/update-helper.cs', import.meta.url)),
+    ],
+    { stdio: 'pipe', windowsHide: true },
+  );
+}

packages/desktop-client/scripts/dist-win.mjs

@@ -136,7 +136,7 @@ function normalizeIntegrityLabel(dir) {
     run([dir, '/setintegritylevel', 'Medium', '/T', '/C']);
     console.log('[dist] 已把交付物完整性标签修正为 Medium：', dir);
   } catch (error) {
-    console.warn('[dist] 完整性标签修正失败（交付物可能装不上，见 AGENTS.md §7 第 7 条）：', error.message);
+    console.warn('[dist] 完整性标签修正失败（交付物可能装不上，见 AGENTS.md 的现行工程约定）：', error.message);
   }
   // 目录自身恢复为"继承父目录的 Low"，保证下次构建时带 Low 标签的 7za 仍能写进这个目录。
   // 宿主目录树本来就没有 Low 标签体系时，这一步会被系统拒绝（保持继承即可），属正常，不提示。

packages/desktop-client/scripts/smoke.mjs

@@ -9,10 +9,17 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { provisionSmokeClass } from '../../../scripts/lib/smoke-class.mjs';
 import { resolveElectronEnv, resolveElectronExecutable } from '../../../scripts/lib/electron-env.mjs';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const repoRoot = path.resolve(root, '..', '..');
+const startedAt = Date.now();
+const mode = process.argv.includes('--visual') ? 'visual' : (process.env.ELECTRON_SMOKE_MODE ?? 'quick');
+if (!['quick', 'visual'].includes(mode)) throw new Error('冒烟模式只能是 quick 或 visual');
+const resultFile =
+  process.env.ELECTRON_SMOKE_RESULT ?? path.join(repoRoot, '.cache', 'desktop-smoke-result.json');
+console.log(`[smoke] 模式：${mode === 'visual' ? '视觉验收（会使用桌面）' : '后台快速检查（不占用前台）'}`);
 const electronPath = resolveElectronExecutable(path.join(root, 'node_modules', 'electron'));
 const required = [path.join(root, 'dist/main/index.js'), path.join(root, 'dist/renderer/index.html')];
 const missing = required.filter((file) => !fs.existsSync(file));
@@ -37,124 +44,13 @@ try {
 }
 console.log(`[smoke] 独立配置目录：${profileDir}`);
 
-// 未显式指定时自动探测后端：可达则启用联网集成 + 侧边栏点击测试
+// 联网验收必须显式指定，避免自动碰到用户正在使用的实例。
-let online = process.env.ELECTRON_SMOKE_ONLINE;
+const online = process.argv.includes('--online') ? '1' : (process.env.ELECTRON_SMOKE_ONLINE ?? '0');
-if (online === undefined) {
-  online = '0';
-  try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 2500);
-    const response = await fetch('http://127.0.0.1:4000/api/health', { signal: controller.signal });
-    clearTimeout(timer);
-    online = response.ok ? '1' : '0';
-  } catch {
-    online = '0';
-  }
-  console.log(
-    online === '1'
-      ? '[smoke] 检测到后端在线，将执行联网集成与侧边栏点击测试'
-      : '[smoke] 后端未在线，仅执行本地检查（离线缓存/界面渲染）；如需联网测试请先启动 pnpm dev:server',
-  );
-}
-
-/**
- * 准备一个已知可用的班级账号（ClassHelper 班级端已改为班级码 + 班级密码登录）：
- * 用管理员账号登录 → 取第一个班级 → 先试"已知密码"（冒烟密码 / 种子默认 123456），
- * 命中就直接用、**不改动任何数据**；都不行才把该班重置成冒烟专用密码，
- * 并在脚本收尾时恢复为种子默认密码（避免把演示实例的 123456 悄悄改掉）。
- */
-async function provisionClassAccount() {
-  const base = process.env.ELECTRON_SMOKE_API ?? 'http://127.0.0.1:4000/api';
-  const username = process.env.ELECTRON_SMOKE_ADMIN ?? 'admin';
-  const adminPassword = process.env.ELECTRON_SMOKE_ADMIN_PASSWORD ?? 'admin123';
-  const password = process.env.ELECTRON_SMOKE_CLASS_PASSWORD ?? 'smoke123456';
-  const CANDIDATES = [...new Set([password, process.env.ELECTRON_SMOKE_SEED_PASSWORD ?? '123456'])];
-  const tryLogin = async (code, candidate) => {
-    const response = await fetch(`${base}/auth/class-login`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ code, password: candidate }),
-    });
-    return response.ok;
-  };
-  try {
-    const loginResponse = await fetch(`${base}/auth/login`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ username, password: adminPassword }),
-    });
-    const login = await loginResponse.json();
-    const token = login?.data?.token;
-    if (!token) return null;
-
-    const authHeaders = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
-    const classesResponse = await fetch(`${base}/classes`, { headers: authHeaders });
-    const classes = (await classesResponse.json())?.data ?? [];
-    const target = classes[0];
-    if (!target) return null;
-
-    // 冒烟**永不修改班级码**（班级码是给学生用的，不应被测试工具改写）：
-    // 只有"现有班级码 + 已知密码全部登录失败"时才重置密码，班级码原样保留。
-    const code = target.code;
-    if (!code) return null;
-
-    for (const candidate of CANDIDATES) {
-      if (await tryLogin(code, candidate)) return { code, password: candidate, className: target.name };
-    }
-
-    const patchResponse = await fetch(`${base}/classes/${target.id}/class-account`, {
-      method: 'PATCH',
-      headers: authHeaders,
-      body: JSON.stringify({ code, password }),
-    });
-    if (!patchResponse.ok) return null;
-
-    const patched = (await patchResponse.json())?.data;
-    // 记下"需要恢复"，脚本收尾时改回种子默认密码（已知密码都不通时无法得知原密码）
-    patchedAccount = { id: target.id, code: patched?.code ?? code, base, authHeaders };
-    console.log(
-      `[smoke] 已知密码均不可用，已把班级 ${target.name} 的密码临时重置为 ${password}` +
-        `（结束时恢复为 ${CANDIDATES[1]}）`,
-    );
-    return { code: patched?.code ?? code, password, className: target.name };
-  } catch {
-    return null;
-  }
-}
-
-/** 冒烟临时重置过的班级账号（结束时恢复） */
-let patchedAccount = null;
-
-/** 恢复被冒烟临时改过的班级密码（失败只告警，不影响冒烟结论） */
-async function restoreClassAccount() {
-  if (!patchedAccount) return;
-  try {
-    const response = await fetch(`${patchedAccount.base}/classes/${patchedAccount.id}/class-account`, {
-      method: 'PATCH',
-      headers: patchedAccount.authHeaders,
-      body: JSON.stringify({
-        code: patchedAccount.code,
-        password: process.env.ELECTRON_SMOKE_SEED_PASSWORD ?? '123456',
-      }),
-    });
-    console.log(
-      response.ok
-        ? '[smoke] 已恢复班级密码为种子默认 123456（冒烟不留副作用）'
-        : `[smoke] [WARN] 班级密码恢复失败：status=${response.status}，请到后台重新设置`,
-    );
-  } catch (error) {
-    console.log(`[smoke] [WARN] 班级密码恢复失败：${error?.message ?? error}`);
-  }
-}
-
 let classCredentials = null;
 if (online === '1') {
-  classCredentials = await provisionClassAccount();
+  classCredentials = await provisionSmokeClass();
-  console.log(
+  if (!classCredentials) throw new Error('无法建立独立验证班级，请检查测试服务端与管理员凭据');
-    classCredentials
+  console.log('[smoke] 已建立独立验证班级：' + classCredentials.code);
-      ? `[smoke] 班级账号就绪：${classCredentials.code}（${classCredentials.className}）`
-      : '[smoke] 未能准备班级账号，联网集成将使用种子默认凭据',
-  );
 }
 
 /** 启动一次冒烟（返回退出码） */
@@ -163,26 +59,49 @@ function launchSmoke(extraEnv) {
     const child = spawn(electronPath, ['.'], {
       cwd: root,
       stdio: 'inherit',
+      windowsHide: true,
       env: resolveElectronEnv({
         ELECTRON_SMOKE_TEST: '1',
+        ELECTRON_SMOKE_MODE: mode,
+        ELECTRON_SMOKE_RESULT: resultFile,
         ELECTRON_SMOKE_ONLINE: online,
         ELECTRON_SMOKE_PROFILE: profileDir,
         ELECTRON_SMOKE_CLASS_CODE: classCredentials?.code ?? '',
         ELECTRON_SMOKE_CLASS_PASSWORD: classCredentials?.password ?? '',
         // 教师凭据只从这里传入：主进程的冒烟代码从环境变量读，
         // 因此安装包（app.asar）里不会留下教师口令字面量（本脚本不进安装包）
-        ELECTRON_SMOKE_USER: process.env.ELECTRON_SMOKE_USER ?? 'teacher1',
+        ELECTRON_SMOKE_USER:
-        ELECTRON_SMOKE_PASSWORD: process.env.ELECTRON_SMOKE_PASSWORD ?? 'teacher123',
+          classCredentials?.teacherUsername ?? process.env.ELECTRON_SMOKE_USER ?? 'teacher1',
+        ELECTRON_SMOKE_PASSWORD:
+          classCredentials?.teacherPassword ?? process.env.ELECTRON_SMOKE_PASSWORD ?? 'teacher123',
+        ELECTRON_SMOKE_CLASS_ID: classCredentials?.classId ?? '',
         ...extraEnv,
       }),
     });
-    child.on('exit', (code) => resolve(code ?? 1));
+    const deadline = setTimeout(
+      () => {
+        console.error('[smoke] 超时，结束验证进程');
+        child.kill();
+        resolve(124);
+      },
+      // 快速套件已包含本地 HTTP、校验下载和布局编辑；保留冷启动余量，单项断言不放宽。
+      mode === 'visual' ? 360_000 : 90_000,
+    );
+    child.once('exit', (code) => {
+      clearTimeout(deadline);
+      resolve(code ?? 1);
+    });
+    child.once('error', (error) => {
+      clearTimeout(deadline);
+      console.error(error);
+      resolve(1);
+    });
   });
 }
 
 const code = await launchSmoke();
 console.log(`\n[smoke] Electron 退出，code=${code}`);
-await restoreClassAccount();
+await classCredentials?.cleanup();
 if (code !== 0) process.exit(code);
 
 /**
@@ -208,7 +127,11 @@ try {
 }
 
 console.log('\n[smoke] 二次启动校验（单实例锁 / 句柄是否已释放）...');
-const relaunchCode = await launchSmoke({ ELECTRON_SMOKE_ONLINE: '0', ELECTRON_SMOKE_RESULT: relaunchResult });
+const relaunchCode = await launchSmoke({
+  ELECTRON_SMOKE_ONLINE: '0',
+  ELECTRON_SMOKE_MODE: 'quick',
+  ELECTRON_SMOKE_RESULT: relaunchResult,
+});
 
 let relaunchPassed = 0;
 let relaunchTotal = 0;
@@ -232,4 +155,5 @@ try {
 } catch {
   // 二次启动可能又建了目录，删除失败不影响结论（首次删除已证明锁已释放）
 }
+console.log('[smoke] 总耗时：' + ((Date.now() - startedAt) / 1000).toFixed(1) + ' 秒');
 process.exit(resourcesOk ? 0 : 1);

packages/desktop-client/src/island/ClassicNotifications.vue

@@ -0,0 +1,234 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  PRIORITY_RANK,
+  PRIORITY_LABELS,
+  formatDate,
+  islandListLayout,
+  ISLAND_SIZE_DELTA,
+  type IslandState,
+  type IslandAppearance,
+  type IslandNotification,
+  type IslandNotificationKind,
+} from '@classhelper/shared';
+const props = defineProps<{ state: IslandState; appearance: IslandAppearance; maxHeight: number }>();
+const state = computed(() => props.state);
+const appearance = computed(() => props.appearance);
+const notification = computed(() => state.value.active);
+const isUrgent = computed(() => notification.value?.priority === 'URGENT');
+const isCall = computed(() => notification.value?.kind === 'call');
+const isHomework = computed(() => notification.value?.kind === 'homework');
+const pendingNotifications = computed(() =>
+  [
+    ...new Map(
+      [state.value.active, ...state.value.queued]
+        .filter((n): n is IslandNotification => !!n)
+        .map((n) => [n.id, n]),
+    ).values(),
+  ].sort(
+    (a, b) => PRIORITY_RANK[b.priority] - PRIORITY_RANK[a.priority] || b.createdAt.localeCompare(a.createdAt),
+  ),
+);
+const pendingCount = computed(() => pendingNotifications.value.length);
+const queueCount = computed(() => state.value.queued.length);
+const listLayout = computed(() =>
+  pendingCount.value < 2
+    ? null
+    : islandListLayout({
+        count: pendingCount.value,
+        fontSize: appearance.value.fontSize,
+        maxHeight: props.maxHeight,
+        expanded: state.value.listExpanded,
+      }),
+);
+const isListMode = computed(() => !!listLayout.value);
+const listItems = computed(() => pendingNotifications.value.slice(0, listLayout.value?.rows ?? 0));
+const hiddenCount = computed(() => pendingCount.value - listItems.value.length);
+const listHint = computed(() => listLayout.value?.hint);
+const size = computed(() => {
+  const extra = isCall.value
+    ? ISLAND_SIZE_DELTA.call
+    : isUrgent.value
+      ? ISLAND_SIZE_DELTA.urgent
+      : ISLAND_SIZE_DELTA.expanded;
+  return {
+    width: appearance.value.width + (isListMode.value ? ISLAND_SIZE_DELTA.expanded.width : extra.width),
+    height: listLayout.value?.height ?? appearance.value.height + extra.height,
+  };
+});
+const TYPE_ORDER: IslandNotificationKind[] = ['call', 'homework', 'notification'];
+const TYPE_LABELS = { call: '叫人', homework: '作业', notification: '通知' };
+const pendingTypes = computed(() =>
+  TYPE_ORDER.filter((k) => pendingNotifications.value.some((n) => (n.kind ?? 'notification') === k)).map(
+    (k) => TYPE_LABELS[k],
+  ),
+);
+function rowKind(n: IslandNotification) {
+  return n.kind ?? 'notification';
+}
+function rowBadgeText(n: IslandNotification) {
+  return n.kind === 'call' ? '叫人' : n.kind === 'homework' ? '新作业' : PRIORITY_LABELS[n.priority];
+}
+function rowBadgeClass(n: IslandNotification) {
+  return n.kind === 'call'
+    ? 'badge-call'
+    : n.kind === 'homework'
+      ? 'badge-homework'
+      : `badge-${n.priority.toLowerCase()}`;
+}
+function rowSubText(n: IslandNotification) {
+  return `${n.teacherName ? n.teacherName + ' · ' : ''}${formatDate(n.createdAt, true)}`;
+}
+const badgeText = computed(() => (notification.value ? rowBadgeText(notification.value) : '通知'));
+const badgeClass = computed(() => (notification.value ? rowBadgeClass(notification.value) : 'badge-normal'));
+const subtitle = computed(() => (notification.value ? rowSubText(notification.value) : ''));
+const callHint = computed(() => notification.value?.subtitle ?? '');
+const showAfterClassHint = computed(() => state.value.reason === 'after-class' && !state.value.inClass);
+const canMarkRead = computed(() => pendingNotifications.value.some((n) => n.kind !== 'homework'));
+function collapse() {
+  window.island?.sendAction('collapse');
+}
+function openApp() {
+  window.island?.sendAction('open-app');
+}
+function expandList() {
+  window.island?.sendAction('expand-list');
+}
+function dismiss() {
+  window.island?.sendAction(isListMode.value ? 'dismiss-all' : 'dismiss');
+}
+function markRead() {
+  window.island?.sendAction(isListMode.value ? 'mark-all-read' : 'mark-read', notification.value?.id);
+}
+</script>
+<template>
+  <span
+    class="expanded-layer classic-notifications"
+    :class="{ 'list-mode': isListMode }"
+    :style="{ width: `${size.width}px`, height: `${size.height}px` }"
+  >
+    <header class="head">
+      <span
+        class="head-icon"
+        :class="{ urgent: isUrgent, call: isCall, homework: isHomework, list: isListMode }"
+      >
+        <svg v-if="isHomework" viewBox="0 0 24 24" aria-hidden="true">
+          <path
+            fill="currentColor"
+            d="M6 3h9a3 3 0 0 1 3 3v13.5a.5.5 0 0 1-.75.43L15 18.5l-2.25 1.43a.5.5 0 0 1-.53 0L10 18.5l-2.25 1.43a.5.5 0 0 1-.53 0L5 18.5V5a2 2 0 0 1 1-2Zm2 4v1.6h7V7H8Zm0 3.4V12h7v-1.6H8Z"
+          />
+        </svg>
+        <svg v-else-if="isCall" viewBox="0 0 24 24" aria-hidden="true">
+          <path
+            fill="currentColor"
+            d="M4 10v4a1 1 0 0 0 1 1h2l4 3.5a1 1 0 0 0 1.65-.76V5.26A1 1 0 0 0 11 4.5L7 8H5a1 1 0 0 0-1 1Zm12.5-2.9a1 1 0 0 1 1.4.1 8 8 0 0 1 0 9.6 1 1 0 1 1-1.5-1.3 6 6 0 0 0 0-7 1 1 0 0 1 .1-1.4Z"
+          />
+        </svg>
+        <svg v-else viewBox="0 0 24 24" aria-hidden="true">
+          <path
+            fill="currentColor"
+            d="M12 2a6 6 0 0 0-6 6v3.1L4.6 14a1 1 0 0 0 .9 1.5h13a1 1 0 0 0 .9-1.5L18 11.1V8a6 6 0 0 0-6-6Zm0 20a3 3 0 0 0 3-2.6H9A3 3 0 0 0 12 22Z"
+          />
+        </svg>
+      </span>
+      <div class="head-meta">
+        <span class="badge" :class="isListMode ? 'badge-normal' : badgeClass">
+          {{ isListMode ? `共 ${pendingCount} 条` : badgeText }}
+        </span>
+        <template v-if="isListMode">
+          <span v-if="pendingTypes.length > 1" class="head-sub">{{ pendingTypes.join(' / ') }}</span>
+          <span v-else class="head-sub">按重要程度排列</span>
+        </template>
+        <template v-else>
+          <span v-if="isCall" class="live-dot call">老师正在等你</span>
+          <span v-else-if="isUrgent" class="live-dot">需立即查看</span>
+          <span v-else-if="showAfterClassHint" class="live-dot muted">下课后补发</span>
+          <span class="head-sub">{{ subtitle }}</span>
+        </template>
+      </div>
+      <button type="button" class="icon-btn" title="收起" @click.stop="collapse">
+        <svg viewBox="0 0 24 24" aria-hidden="true">
+          <path
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.4"
+            stroke-linecap="round"
+            d="m6 15 6-6 6 6"
+          />
+        </svg>
+      </button>
+    </header>
+
+    <!-- 多条消息：竖向排列，按重要程度排序，默认只显示前三条 -->
+    <template v-if="isListMode">
+      <h3 class="title">{{ pendingCount }} 条待处理通知</h3>
+      <div class="body list-body">
+        <button
+          v-for="item in listItems"
+          :key="item.id"
+          type="button"
+          class="list-row"
+          :title="`打开应用查看：${item.title}`"
+          @click.stop="openApp"
+        >
+          <span class="row-icon" :class="rowKind(item)">
+            <svg v-if="rowKind(item) === 'homework'" viewBox="0 0 24 24" aria-hidden="true">
+              <path
+                fill="currentColor"
+                d="M6 3h9a3 3 0 0 1 3 3v13.5a.5.5 0 0 1-.75.43L15 18.5l-2.25 1.43a.5.5 0 0 1-.53 0L10 18.5l-2.25 1.43a.5.5 0 0 1-.53 0L5 18.5V5a2 2 0 0 1 1-2Zm2 4v1.6h7V7H8Zm0 3.4V12h7v-1.6H8Z"
+              />
+            </svg>
+            <svg v-else-if="rowKind(item) === 'call'" viewBox="0 0 24 24" aria-hidden="true">
+              <path
+                fill="currentColor"
+                d="M4 10v4a1 1 0 0 0 1 1h2l4 3.5a1 1 0 0 0 1.65-.76V5.26A1 1 0 0 0 11 4.5L7 8H5a1 1 0 0 0-1 1Zm12.5-2.9a1 1 0 0 1 1.4.1 8 8 0 0 1 0 9.6 1 1 0 1 1-1.5-1.3 6 6 0 0 0 0-7 1 1 0 0 1 .1-1.4Z"
+              />
+            </svg>
+            <svg v-else viewBox="0 0 24 24" aria-hidden="true">
+              <path
+                fill="currentColor"
+                d="M12 2a6 6 0 0 0-6 6v3.1L4.6 14a1 1 0 0 0 .9 1.5h13a1 1 0 0 0 .9-1.5L18 11.1V8a6 6 0 0 0-6-6Zm0 20a3 3 0 0 0 3-2.6H9A3 3 0 0 0 12 22Z"
+              />
+            </svg>
+          </span>
+          <span class="row-text">
+            <span class="row-title">{{ item.title }}</span>
+            <span class="row-sub">{{ rowSubText(item) }}</span>
+          </span>
+          <span class="row-badge" :class="rowBadgeClass(item)">{{ rowBadgeText(item) }}</span>
+        </button>
+        <!-- 还有没显示出来的：能展开就"展开更多"，屏幕到任务栏了就只能去应用里看 -->
+        <div v-if="listHint" class="list-hint">
+          <button v-if="listHint === 'more'" type="button" class="more-btn" @click.stop="expandList">
+            展开更多（还有 {{ hiddenCount }} 条）
+          </button>
+          <span v-else class="more-app">更多请前往应用内操作</span>
+        </div>
+      </div>
+    </template>
+
+    <template v-else>
+      <h3 class="title">{{ notification?.title ?? '' }}</h3>
+      <div class="body">
+        <p class="content-text">{{ notification?.content ?? '' }}</p>
+        <p v-if="callHint" class="call-hint">{{ callHint }}</p>
+        <p v-else-if="notification?.subtitle" class="call-hint">{{ notification?.subtitle }}</p>
+      </div>
+    </template>
+
+    <!-- 一排按钮（多条消息时也是这一排）：展开态的操作都收在这里 -->
+    <footer class="foot">
+      <span v-if="isListMode" class="more">共 {{ pendingCount }} 条待处理</span>
+      <span v-else-if="queueCount > 0" class="more">还有 {{ queueCount }} 条通知</span>
+      <span v-else class="more muted">来自 ClassHelper</span>
+      <span class="actions">
+        <button type="button" class="ghost-btn" @click.stop="openApp">打开应用</button>
+        <button v-if="canMarkRead" type="button" class="ghost-btn" @click.stop="markRead">标为已读</button>
+        <button type="button" class="solid-btn" @click.stop="dismiss">
+          {{ isCall && !isListMode ? '收到' : '知道了' }}
+        </button>
+      </span>
+    </footer>
+  </span>
+</template>
+<style src="./classic-island.css"></style>

packages/desktop-client/src/island/ComponentIcon.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import type { IslandComponentKind } from '@classhelper/shared';
+defineProps<{ kind: IslandComponentKind }>();
+const paths: Record<IslandComponentKind, string> = {
+  clock: 'M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0ZM12 7v5l3 2',
+  weather:
+    'M16 12a4 4 0 1 1-8 0 4 4 0 0 1 8 0ZM12 2v2m0 16v2M2 12h2m16 0h2M5 5l1.5 1.5m11 11L19 19M5 19l1.5-1.5m11-11L19 5',
+  date: 'M6 5h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V7a2 2 0 0 1 2-2ZM8 3v4m8-4v4M4 10h16M8 14h2m4 0h2m-8 3h2',
+  schedule: 'M9 5h11M9 12h11M9 19h11M4 5h1m-1 7h1m-1 7h1',
+  countdown: 'M6 3h12M6 21h12M8 3v4l4 5-4 5v4m8-18v4l-4 5 4 5v4',
+  text: 'M6 3h12a3 3 0 0 1 3 3v12a3 3 0 0 1-3 3H6a3 3 0 0 1-3-3V6a3 3 0 0 1 3-3Zm1 5h10M7 12h7m-7 4h10',
+  separator: 'M12 4v16M5 8v8m14-8v8',
+  notification: 'M9 19a3 3 0 0 0 6 0M6 10a6 6 0 0 1 12 0v4l2 3H4l2-3v-4Z',
+  homework: 'M9 4H6a2 2 0 0 0-2 2v14h16V6a2 2 0 0 0-2-2h-3M9 3h6v4H9V3Zm-1 9h8m-8 4h5',
+  call: 'M4 10h4l6-5v14l-6-5H4v-4Zm13-2a6 6 0 0 1 0 8m3-11a10 10 0 0 1 0 14',
+  group: 'M3 5h18v14H3V5Zm4 4h4v6H7V9Zm8 0h2v6h-2V9Z',
+  stack: 'm12 3 9 5-9 5-9-5 9-5ZM3 12l9 5 9-5M3 16l9 5 9-5',
+  slide: 'M6 5h12v14H6V5ZM2 8v8m20-8v8m-12 7h4',
+  rolling: 'M3 8h17m-4-4 4 4-4 4M21 16H4m4-4-4 4 4 4',
+};
+</script>
+<template>
+  <svg
+    viewBox="0 0 24 24"
+    width="24"
+    height="24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path :d="paths[kind]" />
+  </svg>
+</template>

packages/desktop-client/src/island/ComponentNode.vue

@@ -0,0 +1,443 @@
+<script setup lang="ts">
+import { computed, type CSSProperties } from 'vue';
+import {
+  ISLAND_COMPONENT_LABELS,
+  resolveClassStatus,
+  type IslandComponentNode,
+  type IslandState,
+  type IslandTimePointDto,
+  type ScheduleDto,
+} from '@classhelper/shared';
+import WeatherBrief from './WeatherBrief.vue';
+const props = defineProps<{
+  node: IslandComponentNode;
+  state: IslandState;
+  now: number;
+  schedules: ScheduleDto[];
+  timePoints: IslandTimePointDto[];
+  editing: boolean;
+  selectedId: string;
+  alertNodeId: string;
+  parentHasWidth?: boolean;
+}>();
+const emit = defineEmits<{ select: [id: string]; drag: [event: PointerEvent, id: string] }>();
+function select(event: MouseEvent) {
+  if (!props.editing) return;
+  event.stopPropagation();
+  emit('select', props.node.id);
+}
+const container = computed(() => ['group', 'stack', 'slide', 'rolling'].includes(props.node.kind));
+const today = computed(() =>
+  props.schedules
+    .filter((s) => s.dayOfWeek === (new Date(props.now).getDay() || 7))
+    .sort((a, b) => a.startTime.localeCompare(b.startTime)),
+);
+const status = computed(() => resolveClassStatus(today.value, new Date(props.now)));
+const current = computed(() => today.value.find((s) => s.id === status.value.current?.scheduleId));
+const next = computed(() => today.value.find((s) => s.id === status.value.next?.scheduleId));
+function timeAt(time: string) {
+  const d = new Date(props.now);
+  const [h, m] = time.split(':').map(Number);
+  d.setHours(h!, m!, 0, 0);
+  return d.getTime();
+}
+/**
+ * 今天的时间点：优先用服务端下发的完整时间表（含课间/分割线/默认隐藏），
+ * 没有时回退到课表条目，保证旧服务端与离线缓存仍能显示课程。
+ */
+const dayPoints = computed<IslandTimePointDto[]>(() => {
+  const source = props.timePoints.length
+    ? props.timePoints
+    : today.value.map<IslandTimePointDto>((s) => ({
+        id: s.id,
+        timeType: 'LESSON',
+        name: '',
+        courseName: s.course?.name ?? null,
+        startTime: s.startTime,
+        endTime: s.endTime,
+        isHideDefault: false,
+      }));
+  return [...source].sort((a, b) => a.startTime.localeCompare(b.startTime));
+});
+const currentPoint = computed(
+  () =>
+    dayPoints.value.find(
+      (point) =>
+        point.timeType !== 'DIVIDER' &&
+        point.timeType !== 'ACTION' &&
+        props.now >= timeAt(point.startTime) &&
+        props.now < timeAt(point.endTime),
+    ) ?? null,
+);
+const currentLesson = computed(() => (currentPoint.value?.timeType === 'LESSON' ? currentPoint.value : null));
+/** 课程表组件按 ClassIsland 主界面的折叠/展开规则挑选时间点。 */
+const schedulePoints = computed<IslandTimePointDto[]>(() => {
+  const display = props.node.settings.display;
+  if (display === 'next')
+    return dayPoints.value
+      .filter((point) => point.timeType === 'LESSON' && timeAt(point.startTime) > props.now)
+      .slice(0, 1);
+  if (display === 'current') {
+    if (currentPoint.value) return [currentPoint.value];
+    return dayPoints.value
+      .filter((point) => point.timeType === 'LESSON' && timeAt(point.startTime) > props.now)
+      .slice(0, 1);
+  }
+  const visible = dayPoints.value.filter(
+    (point) =>
+      point.timeType === 'DIVIDER' ||
+      point.id === currentPoint.value?.id ||
+      (point.timeType === 'LESSON' && !point.isHideDefault),
+  );
+  const count = Math.max(1, props.node.settings.count);
+  if (visible.length <= count) return visible;
+  const index = visible.findIndex((point) => point.id === currentPoint.value?.id);
+  const start = Math.max(0, Math.min(index - Math.floor(count / 2), visible.length - count));
+  return visible.slice(start, start + count);
+});
+const elapsed = computed(() => {
+  const point = currentLesson.value;
+  if (!point) return 0;
+  const start = timeAt(point.startTime);
+  const end = timeAt(point.endTime);
+  return Math.max(0, Math.min(1, (props.now - start) / Math.max(1, end - start)));
+});
+const remaining = computed(() =>
+  currentLesson.value ? Math.max(0, Math.ceil((timeAt(currentLesson.value.endTime) - props.now) / 1000)) : 0,
+);
+const hidden = computed(
+  () =>
+    !props.editing &&
+    ((['notification', 'homework', 'call'].includes(props.node.kind) &&
+      (!props.state.active || props.state.mode === 'hidden' || props.node.id !== props.alertNodeId)) ||
+      props.node.advanced.hideRules.some(
+        (r) =>
+          (r === 'in-class' && props.state.inClass) ||
+          (r === 'no-message' && !props.state.active) ||
+          (r === 'no-class' && !currentLesson.value),
+      )),
+);
+const visibleChildren = computed(() =>
+  props.node.kind === 'slide' && !props.editing
+    ? props.node.children.filter(
+        (_, i) =>
+          i ===
+          Math.floor(props.now / (props.node.settings.interval * 1000)) %
+            Math.max(1, props.node.children.length),
+      )
+    : props.node.children,
+);
+const content = computed(() => {
+  const n = props.node,
+    d = new Date(props.now);
+  if (n.kind === 'date')
+    return d.toLocaleDateString('zh-CN', { month: 'long', day: 'numeric', weekday: 'long' });
+  if (n.kind === 'clock')
+    return d.toLocaleTimeString('zh-CN', {
+      hour: '2-digit',
+      minute: '2-digit',
+      ...(n.settings.seconds ? { second: '2-digit' } : {}),
+      hour12: n.settings.hour12,
+    });
+  if (n.kind === 'text')
+    return n.settings.template
+      ? n.settings.text
+          .replaceAll('{date}', d.toLocaleDateString('zh-CN'))
+          .replaceAll('{time}', d.toLocaleTimeString('zh-CN'))
+          .replaceAll('{course}', current.value?.course?.name || '暂无课程')
+      : n.settings.text;
+  if (n.kind === 'countdown') {
+    if (n.settings.target === 'date') {
+      if (!n.settings.targetDate) return '请设置目标日期';
+      const [year, month, day] = n.settings.targetDate.split('-').map(Number);
+      const days = Math.round(
+        (Date.UTC(year!, month! - 1, day!) - Date.UTC(d.getFullYear(), d.getMonth(), d.getDate())) / 86400000,
+      );
+      return days > 0
+        ? `距${n.settings.countdownTitle} ${days} 天`
+        : days === 0
+          ? `${n.settings.countdownTitle}就在今天`
+          : `${n.settings.countdownTitle}已过 ${-days} 天`;
+    }
+    const ending = n.settings.target === 'end' || (n.settings.target === 'auto' && !!current.value);
+    const time =
+      n.settings.target === 'school'
+        ? today.value.at(-1)?.endTime
+        : ending
+          ? current.value?.endTime
+          : next.value?.startTime;
+    if (!time) return '今日课程已结束';
+    const [h, m] = time.split(':').map(Number);
+    const end = new Date(d);
+    end.setHours(h!, m!, 0, 0);
+    const left = Math.max(0, Math.ceil((end.getTime() - props.now) / 1000));
+    return `${n.settings.target === 'school' ? '距放学' : ending ? '距下课' : '距上课'} ${Math.floor(left / 60)}:${String(left % 60).padStart(2, '0')}`;
+  }
+  return '';
+});
+const style = computed<CSSProperties>(() => {
+  const n = props.node,
+    a = n.appearance,
+    override = a.resourceOverridingEnabled;
+  const color =
+    a.background +
+    Math.round((a.customBackgroundOpacityEnabled ? a.backgroundOpacity : 1) * 255)
+      .toString(16)
+      .padStart(2, '0');
+  return {
+    opacity: a.opacity,
+    width: n.advanced.width ? `${n.advanced.width}px` : undefined,
+    maxWidth: n.advanced.maxWidth ? `${n.advanced.maxWidth}px` : undefined,
+    alignSelf: !props.parentHasWidth
+      ? undefined
+      : ({ stretch: 'stretch', start: 'flex-start', center: 'center', end: 'flex-end' } as const)[
+          n.advanced.align
+        ],
+    textAlign: n.advanced.align === 'start' ? 'start' : n.advanced.align === 'end' ? 'end' : 'center',
+    color: override && a.customForegroundEnabled ? a.foreground : undefined,
+    background: override && a.customBackgroundEnabled ? color : undefined,
+    borderRadius: override && a.customCornerRadiusEnabled ? `${a.cornerRadius}px` : undefined,
+    fontSize: override ? `${a.bodyFontSize}px` : undefined,
+    '--secondary': override ? `${a.secondaryFontSize}px` : undefined,
+    '--emphasized': override ? `${a.emphasizedFontSize}px` : undefined,
+    '--large': override ? `${a.largeFontSize}px` : undefined,
+    '--rolling-duration': `${Math.max(1, 200 / n.settings.speed)}s`,
+    flexDirection: container.value ? (n.settings.direction === 'vertical' ? 'column' : 'row') : undefined,
+    gap: container.value ? `${n.settings.gap}px` : undefined,
+    display: container.value ? 'flex' : undefined,
+  };
+});
+</script>
+<template>
+  <div
+    v-if="!hidden"
+    class="component-node"
+    :class="[{ selected: editing && selectedId === node.id, container, 'node-editing': editing }, node.kind]"
+    :style="style"
+    :data-node="node.id"
+    @click="select"
+  >
+    <button
+      v-if="editing"
+      class="node-handle"
+      :data-kind="node.kind"
+      aria-label="拖动组件"
+      @pointerdown.stop="emit('drag', $event, node.id)"
+    >
+      ⠿ {{ ISLAND_COMPONENT_LABELS[node.kind] }}
+    </button>
+    <template v-if="container">
+      <ComponentNode
+        v-for="child in visibleChildren"
+        :key="child.id"
+        :node="child"
+        :state="state"
+        :now="now"
+        :schedules="schedules"
+        :time-points="timePoints"
+        :editing="editing"
+        :selected-id="selectedId"
+        :alert-node-id="alertNodeId"
+        :parent-has-width="Boolean(node.advanced.width || node.advanced.maxWidth)"
+        @select="emit('select', $event)"
+        @drag="(e, id) => emit('drag', e, id)"
+      >
+        <template #alerts><slot name="alerts" /></template>
+      </ComponentNode>
+    </template>
+    <template v-else-if="node.kind === 'separator'"><span aria-hidden="true">│</span></template>
+    <WeatherBrief v-else-if="node.kind === 'weather'" :settings="node.settings" />
+    <template v-else-if="node.kind === 'schedule'">
+      <template v-for="p in schedulePoints" :key="p.id">
+        <span v-if="p.timeType === 'DIVIDER'" class="time-divider" aria-hidden="true">│</span>
+        <div
+          v-else
+          class="lesson-line"
+          :class="{ current: p.id === currentPoint?.id, break: p.timeType === 'BREAK' }"
+        >
+          <strong>{{ p.courseName || p.name || '—' }}</strong>
+          <small v-if="p.id === currentPoint?.id && node.settings.showPeriod" class="lesson-time">
+            {{ p.startTime }}–{{ p.endTime }}
+          </small>
+          <span
+            v-if="p.id === currentPoint?.id && p.timeType === 'LESSON' && node.settings.showProgress"
+            class="lesson-progress"
+            role="progressbar"
+            :aria-valuenow="Math.round(elapsed * 100)"
+            aria-valuemin="0"
+            aria-valuemax="100"
+            :aria-label="`${p.courseName || '课程'}课程进度，距下课${remaining}秒`"
+          >
+            <i :style="{ transform: `scaleX(${elapsed})` }" />
+          </span>
+        </div>
+      </template>
+      <span v-if="!schedulePoints.length">暂无课程</span>
+    </template>
+    <template v-else-if="['notification', 'homework', 'call'].includes(node.kind)">
+      <slot v-if="node.id === alertNodeId" name="alerts" />
+      <span v-else-if="editing">{{ ISLAND_COMPONENT_LABELS[node.kind] }}内容组件</span>
+    </template>
+    <span v-else :class="{ emphasized: node.kind === 'clock' || node.kind === 'countdown' }">
+      {{ content }}
+    </span>
+  </div>
+</template>
+<style scoped>
+.component-node {
+  min-width: 0;
+  overflow: hidden;
+  padding: 6px;
+  flex-shrink: 0;
+  position: relative;
+}
+.component-node:not(.node-editing) {
+  line-height: 1.4;
+}
+.clock {
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+.date,
+.countdown {
+  white-space: nowrap;
+}
+.schedule > .lesson-line {
+  position: relative;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  padding-bottom: 3px;
+}
+.lesson-line strong {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.lesson-line.current strong {
+  color: #fff;
+}
+.lesson-line.break {
+  opacity: 0.86;
+}
+.time-divider {
+  display: block;
+  width: 1px;
+  height: 18px;
+  overflow: hidden;
+  background: currentColor;
+  font-size: 0;
+  opacity: 0.25;
+}
+.lesson-time {
+  flex-shrink: 0;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+.lesson-progress {
+  position: absolute;
+  inset: auto 0 0;
+  height: 2px;
+  background: #ffffff24;
+  overflow: hidden;
+  border-radius: 1px;
+}
+.lesson-progress i {
+  display: block;
+  height: 100%;
+  background: var(--island-accent, #60a5fa);
+  transform-origin: left;
+  transition: transform 1s linear;
+}
+.schedule > .lesson-line + .lesson-line {
+  margin-top: 8px;
+}
+.separator > span {
+  display: block;
+  width: 1px;
+  height: 24px;
+  overflow: hidden;
+  background: currentColor;
+  font-size: 0;
+  opacity: 0.25;
+}
+.container {
+  align-items: center;
+}
+.stack {
+  flex-wrap: wrap;
+}
+.rolling {
+  overflow: hidden;
+}
+.rolling > :deep(.component-node) {
+  animation: rolling var(--rolling-duration) linear infinite;
+}
+.rolling.node-editing > :deep(.component-node) {
+  animation: none;
+}
+.selected {
+  outline: 2px solid #85aaff;
+  border-radius: 8px;
+  background: #759cff14;
+}
+.node-handle {
+  touch-action: none;
+  cursor: grab;
+  display: block;
+  font:
+    10px 'Microsoft YaHei',
+    sans-serif;
+  padding: 3px 6px;
+  border: 0;
+  border-radius: 4px;
+  min-height: 24px;
+  margin-bottom: 4px;
+  color: #ffffff80;
+  background: #ffffff0d;
+}
+.node-handle:hover {
+  background: #ffffff20;
+  color: #fff;
+}
+.notification,
+.homework,
+.call {
+  padding: 0;
+}
+.notification.node-editing,
+.homework.node-editing,
+.call.node-editing {
+  padding: 6px;
+  flex-basis: auto;
+}
+.node-editing {
+  cursor: pointer;
+}
+.node-editing:hover {
+  box-shadow: inset 0 0 0 1px #ffffff28;
+  border-radius: 8px;
+}
+small {
+  font-size: var(--secondary, 12px);
+  opacity: 0.7;
+}
+strong,
+.emphasized {
+  font-size: var(--emphasized, 20px);
+}
+.large {
+  font-size: var(--large, 28px);
+}
+@keyframes rolling {
+  from {
+    transform: translateX(30%);
+  }
+  to {
+    transform: translateX(-80%);
+  }
+}
+</style>

packages/desktop-client/src/island/CoursewareTransfer.vue

@@ -0,0 +1,132 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue';
+import {
+  COURSEWARE_CATEGORIES,
+  COURSEWARE_ISLAND_SIZE,
+  ISLAND_SHADOW_PAD,
+  type CoursewareTransfer,
+  type IslandAppearance,
+} from '@classhelper/shared';
+const props = defineProps<{ transfer: CoursewareTransfer; appearance: IslandAppearance }>();
+const card = ref<HTMLElement>();
+const style = computed(() => {
+  const position = props.appearance.position;
+  return {
+    width: `${COURSEWARE_ISLAND_SIZE.width}px`,
+    height: `${COURSEWARE_ISLAND_SIZE.height}px`,
+    [position.startsWith('bottom') ? 'bottom' : 'top']: `${ISLAND_SHADOW_PAD}px`,
+    ...(position.endsWith('left')
+      ? { left: `${ISLAND_SHADOW_PAD}px` }
+      : position.endsWith('right')
+        ? { right: `${ISLAND_SHADOW_PAD}px` }
+        : { left: '50%', transform: 'translateX(-50%)' }),
+    '--transfer-accent': props.appearance.accent,
+  };
+});
+const status = computed(
+  () =>
+    ({
+      downloading: '正在接收课件',
+      verifying: '正在校验文件',
+      completed: '课件接收完成',
+      failed: '课件接收失败',
+    })[props.transfer.stage],
+);
+function report() {
+  const rect = card.value?.getBoundingClientRect();
+  if (rect) window.island?.setHitRect({ x: rect.x, y: rect.y, width: rect.width, height: rect.height });
+}
+watch(
+  () => [props.appearance.position, props.transfer],
+  () => void nextTick(report),
+);
+onMounted(() => {
+  report();
+  window.addEventListener('resize', report);
+});
+onUnmounted(() => window.removeEventListener('resize', report));
+</script>
+<template>
+  <section ref="card" class="courseware-transfer" :style="style" aria-label="课件传输状态">
+    <header>
+      <span>{{ status }}</span>
+      <strong>{{ transfer.stage === 'failed' ? '失败' : `${transfer.progress}%` }}</strong>
+    </header>
+    <div class="filename" :title="transfer.name">{{ transfer.name }}</div>
+    <div class="metadata">
+      {{ COURSEWARE_CATEGORIES[transfer.category] }} · {{ transfer.teacherName || '教师' }}
+      <span>
+        {{ (transfer.receivedBytes / 1048576).toFixed(1) }} /
+        {{ (transfer.totalBytes / 1048576).toFixed(1) }} MB
+      </span>
+    </div>
+    <progress :value="transfer.progress" max="100" :aria-label="`${transfer.name} 传输进度`" />
+    <p v-if="transfer.error">{{ transfer.error }}</p>
+  </section>
+</template>
+<style scoped>
+.courseware-transfer {
+  position: fixed;
+  box-sizing: border-box;
+  padding: 17px 24px;
+  border-radius: 24px;
+  color: white;
+  background: rgba(20, 20, 24, 0.97);
+  box-shadow: 0 2px 8px #0004;
+  font:
+    13px/1.4 'Segoe UI',
+    'Microsoft YaHei',
+    sans-serif;
+  overflow: hidden;
+  pointer-events: none;
+}
+header,
+.metadata {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+}
+header {
+  color: #ffffffb8;
+  font-size: 12px;
+}
+header strong {
+  color: var(--transfer-accent);
+}
+.filename {
+  font-weight: 600;
+  font-size: 16px;
+  margin: 5px 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.metadata {
+  color: #ffffffb8;
+  font-size: 12px;
+}
+progress {
+  display: block;
+  width: 100%;
+  height: 5px;
+  margin-top: 11px;
+  border: 0;
+  border-radius: 8px;
+  overflow: hidden;
+  accent-color: var(--transfer-accent);
+}
+progress::-webkit-progress-bar {
+  background: #ffffff30;
+}
+progress::-webkit-progress-value {
+  background: var(--transfer-accent);
+}
+p {
+  margin: 3px 0;
+  font-size: 11px;
+  color: #ffb4ab;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+</style>

packages/desktop-client/src/island/CustomIslandRuntime.vue

@@ -0,0 +1,517 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, onUnmounted, ref, watch, type CSSProperties } from 'vue';
+import {
+  ISLAND_SHADOW_PAD,
+  PRIORITY_RANK,
+  type IslandAppearance,
+  type IslandLayoutSettings,
+  type IslandState,
+  type IslandTimePointDto,
+  type ScheduleDto,
+  type IslandLessonReminder,
+} from '@classhelper/shared';
+import ComponentNode from './ComponentNode.vue';
+import ComponentIcon from './ComponentIcon.vue';
+import ClassicNotifications from './ClassicNotifications.vue';
+import { squirclePath } from './squircle.js';
+import { SpringValue } from './spring.js';
+import LessonReminderContent from './LessonReminderContent.vue';
+
+const props = defineProps<{
+  settings: IslandLayoutSettings;
+  state: IslandState;
+  schedules: ScheduleDto[];
+  timePoints: IslandTimePointDto[];
+  appearance: IslandAppearance;
+  nativeVisible: boolean;
+}>();
+const scheme = computed(() => props.settings.schemes.find((s) => s.id === props.settings.activeSchemeId)!);
+const expanded = computed(() => props.state.mode === 'expanded');
+const lesson = computed(() => props.state.lessonReminder ?? null);
+const lastLesson = ref<IslandLessonReminder | null>(null);
+watch(
+  lesson,
+  (value) => {
+    if (value) lastLesson.value = value;
+  },
+  { immediate: true },
+);
+const messages = computed(() => {
+  const unique = new Map(
+    [props.state.active, ...props.state.queued].filter((n) => n !== null).map((n) => [n.id, n]),
+  );
+  return [...unique.values()].sort(
+    (a, b) =>
+      PRIORITY_RANK[b.priority] - PRIORITY_RANK[a.priority] ||
+      Date.parse(b.createdAt) - Date.parse(a.createdAt),
+  );
+});
+const shell = ref<HTMLElement>();
+const compact = ref<HTMLElement>();
+const details = ref<HTMLElement>();
+const lessonSource = ref<HTMLElement>();
+const now = ref(Date.now());
+const visible = ref(!document.hidden);
+const motion = computed(() => props.appearance.animations && visible.value && props.nativeVisible);
+const available = ref({ width: 940, height: 620 });
+const natural = ref({
+  compact: { width: 40, height: 40 },
+  details: { width: 280, height: 80 },
+  lesson: { width: 480, height: 40 },
+});
+const anchor = computed(() =>
+  props.appearance.position.endsWith('left')
+    ? 'left'
+    : props.appearance.position.endsWith('right')
+      ? 'right'
+      : 'center',
+);
+function fitted(size: { width: number; height: number }) {
+  // 以未变形内容测量；字体、配置缩放、行数和屏幕变化都参与适配，不从动画中的壳反推内容。
+  const scale = Math.min(
+    scheme.value.scale,
+    available.value.width / size.width,
+    available.value.height / size.height,
+  );
+  return { scale, width: Math.ceil(size.width * scale), height: Math.ceil(size.height * scale) };
+}
+const compactFit = computed(() => fitted(natural.value.compact));
+const detailsFit = computed(() => fitted(natural.value.details));
+const lessonFit = computed(() => fitted(natural.value.lesson));
+const fit = computed(() =>
+  lesson.value ? lessonFit.value : expanded.value ? detailsFit.value : compactFit.value,
+);
+const morph = ref({ width: 40, height: 40, radius: 20 });
+const springs = {
+  width: new SpringValue(40),
+  height: new SpringValue(40),
+  radius: new SpringValue(20),
+  content: new SpringValue(0, { snapThreshold: 0.001 }),
+  lesson: new SpringValue(0, { snapThreshold: 0.001 }),
+};
+// 与经典岛一致：常态内容先退净，展开内容按进度平方进入；反向收起沿同一条曲线返回。
+// 独立进度也保证两页尺寸相同时仍播放过渡，不能靠高度差推导。
+const progress = ref(0);
+const lessonProgress = ref(0);
+const compactAlpha = computed(() => Math.max(0, 1 - progress.value * 1.5) * (1 - lessonProgress.value));
+const detailsAlpha = computed(() => progress.value * progress.value * (1 - lessonProgress.value));
+const path = computed(() => squirclePath(morph.value.width, morph.value.height, morph.value.radius));
+const style = computed<CSSProperties>(() => ({
+  width: `${morph.value.width}px`,
+  height: `${morph.value.height}px`,
+  '--card-path': `path("${path.value}")`,
+  '--island-font': `${props.appearance.fontSize}px`,
+  '--island-accent': props.appearance.accent,
+  '--state-color':
+    props.state.active?.priority === 'URGENT'
+      ? '#ff453a'
+      : props.state.active?.kind === 'call'
+        ? '#ff9f0a'
+        : props.appearance.accent,
+  '--resident-background': 'var(--wn-bg)',
+  '--resident-radius': `${morph.value.radius}px`,
+  '--resident-scale': fit.value.scale,
+  '--custom-row-gap': `${scheme.value.spacing}px`,
+  '--resident-row-width': `${Math.max(60, available.value.width / scheme.value.scale - 58)}px`,
+  '--secondary': `${(props.appearance.fontSize / 13) * 14}px`,
+  '--emphasized': `${(props.appearance.fontSize / 13) * 18}px`,
+  '--large': `${(props.appearance.fontSize / 13) * 20}px`,
+  '--ci-body-font': `${(props.appearance.fontSize / 13) * 16}px`,
+  '--resident-fade-duration': motion.value ? `${200 / props.appearance.speed}ms` : '0ms',
+}));
+let morphFrame = 0;
+let morphFallback: ReturnType<typeof setTimeout> | undefined;
+function animate() {
+  const size = fit.value;
+  const radius = Math.min(
+    lesson.value ? 8 : expanded.value ? props.appearance.radius : scheme.value.radius,
+    size.width / 2,
+    size.height / 2,
+  );
+  const target = { width: size.width, height: size.height, radius };
+  const snap = () => {
+    cancelAnimationFrame(morphFrame);
+    morphFrame = 0;
+    clearTimeout(morphFallback);
+    for (const key of ['width', 'height', 'radius'] as const) springs[key].snap(target[key]);
+    springs.content.snap(expanded.value ? 1 : 0);
+    springs.lesson.snap(lesson.value ? 1 : 0);
+    progress.value = springs.content.value;
+    lessonProgress.value = springs.lesson.value;
+    morph.value = target;
+    void nextTick(reportHit);
+  };
+  // 应用内动画开关与经典岛保持一致；系统减少动态效果不能再次覆盖用户已开启的动画。
+  if (!motion.value) {
+    snap();
+    return;
+  }
+  for (const key of ['width', 'height', 'radius'] as const) springs[key].setTarget(target[key]);
+  springs.content.setTarget(expanded.value ? 1 : 0);
+  springs.lesson.setTarget(lesson.value ? 1 : 0);
+  clearTimeout(morphFallback);
+  morphFallback = setTimeout(snap, 1200 / props.appearance.speed);
+  if (morphFrame) return;
+  let last = performance.now();
+  const frame = (time: number) => {
+    const dt = (time - last) * props.appearance.speed;
+    last = time;
+    // 三个维度每帧都推进；不能用短路 || 导致后面的维度等宽度结束才开始。
+    const moving = Object.values(springs)
+      .map((s) => s.step(dt))
+      .some(Boolean);
+    morph.value = { width: springs.width.value, height: springs.height.value, radius: springs.radius.value };
+    progress.value = springs.content.value;
+    lessonProgress.value = springs.lesson.value;
+    if (moving) morphFrame = requestAnimationFrame(frame);
+    else {
+      morphFrame = 0;
+      clearTimeout(morphFallback);
+      void nextTick(reportHit);
+    }
+  };
+  morphFrame = requestAnimationFrame(frame);
+}
+function action(value: 'expand' | 'collapse' | 'expand-list' | 'dismiss-all' | 'mark-all-read' | 'open-app') {
+  window.island?.sendAction(value);
+}
+function open(event: Event) {
+  if (!expanded.value && !(event.target as HTMLElement).closest('button')) action('expand');
+}
+function key(event: KeyboardEvent) {
+  if (event.target === event.currentTarget && ['Enter', ' '].includes(event.key)) {
+    event.preventDefault();
+    action(expanded.value ? 'collapse' : 'expand');
+  }
+  if (event.key === 'Escape') action('collapse');
+}
+function pointer(event: PointerEvent) {
+  if (event.pointerType !== 'mouse') window.island?.noteResidentTouch();
+}
+let observer: ResizeObserver | undefined;
+let clock: ReturnType<typeof setInterval>;
+let hitFrame = 0;
+let hitUntil = 0;
+let hitTimer: ReturnType<typeof setTimeout> | undefined;
+let lastHit = '';
+function reportHit() {
+  const r = shell.value?.getBoundingClientRect();
+  if (!r) return;
+  const payload = { x: r.x, y: r.y, width: r.width, height: r.height };
+  const key = Object.values(payload).map(Math.round).join(',');
+  if (key !== lastHit) {
+    lastHit = key;
+    window.island?.setHitRect(payload);
+  }
+  const bell = !expanded.value ? shell.value?.querySelector('.resident-bell')?.getBoundingClientRect() : null;
+  window.island?.reportResidentControl(
+    bell ? { x: bell.x, y: bell.y, width: bell.width, height: bell.height } : null,
+  );
+}
+function trackHit() {
+  // 几何动画只在合成/渲染层播放；主进程只接收限流命中矩形，绝不据此改窗口大小。
+  if (!motion.value) {
+    reportHit();
+    return;
+  }
+  hitUntil = performance.now() + 600 / props.appearance.speed;
+  clearTimeout(hitTimer);
+  hitTimer = setTimeout(reportHit, 650 / props.appearance.speed);
+  if (hitFrame) return;
+  let last = 0;
+  const frame = (time: number) => {
+    if (time - last >= 60) {
+      reportHit();
+      last = time;
+    }
+    if (time < hitUntil) hitFrame = requestAnimationFrame(frame);
+    else {
+      hitFrame = 0;
+      reportHit();
+    }
+  };
+  hitFrame = requestAnimationFrame(frame);
+}
+let measuring = false;
+function measure() {
+  if (measuring) return;
+  measuring = true;
+  void nextTick(() => {
+    measuring = false;
+    if (!compact.value || !details.value) return;
+    const read = (element: HTMLElement) => ({
+      width: Math.max(40, element.offsetWidth),
+      height: Math.max(40, element.offsetHeight),
+    });
+    natural.value = {
+      compact: read(compact.value),
+      details: read(details.value),
+      lesson: lessonSource.value ? read(lessonSource.value) : natural.value.lesson,
+    };
+    void nextTick(() => {
+      window.island?.reportSize({ width: fit.value.width, height: fit.value.height });
+      trackHit();
+    });
+  });
+}
+function resizeCanvas(width = innerWidth, height = innerHeight) {
+  available.value = {
+    width: Math.max(40, Math.min(width, innerWidth) - 2 * ISLAND_SHADOW_PAD - 4),
+    height: Math.max(40, Math.min(height, innerHeight) - 2 * ISLAND_SHADOW_PAD - 4),
+  };
+  measure();
+}
+const resize = () => resizeCanvas();
+let stopViewport: (() => void) | undefined;
+function visibility() {
+  visible.value = !document.hidden;
+  resize();
+  void nextTick(reportHit);
+}
+// 不深度监听整份状态；只在目标内容/几何变化时测量，时钟每秒只改文本。
+watch(
+  [
+    expanded,
+    scheme,
+    lesson,
+    () => props.state.listExpanded,
+    messages,
+    () => props.timePoints,
+    () => Math.floor(now.value / 60_000),
+  ],
+  measure,
+  { deep: true, flush: 'post' },
+);
+watch(
+  [fit, motion, expanded, lesson, () => props.appearance.radius, () => props.appearance.speed],
+  () => {
+    animate();
+    trackHit();
+  },
+  { flush: 'post' },
+);
+watch(
+  () => props.appearance.position,
+  () => void nextTick(trackHit),
+);
+onMounted(() => {
+  resize();
+  stopViewport = window.island?.onViewport((v) => resizeCanvas(v.width, v.height));
+  observer = new ResizeObserver((entries) => {
+    if (entries.some((entry) => entry.target === document.documentElement)) resize();
+    else measure();
+  });
+  observer.observe(document.documentElement);
+  if (compact.value) observer.observe(compact.value);
+  if (details.value) observer.observe(details.value);
+  if (lessonSource.value) observer.observe(lessonSource.value);
+  clock = setInterval(() => (now.value = Date.now()), 1000);
+  window.addEventListener('resize', resize);
+  document.addEventListener('visibilitychange', visibility);
+  void document.fonts.ready.then(measure);
+});
+onUnmounted(() => {
+  stopViewport?.();
+  observer?.disconnect();
+  clearInterval(clock);
+  clearTimeout(hitTimer);
+  cancelAnimationFrame(hitFrame);
+  cancelAnimationFrame(morphFrame);
+  clearTimeout(morphFallback);
+  window.removeEventListener('resize', resize);
+  document.removeEventListener('visibilitychange', visibility);
+  window.island?.reportResidentControl(null);
+});
+</script>
+
+<template>
+  <div
+    class="resident-window"
+    :data-anchor="anchor"
+    :data-bottom="appearance.position.startsWith('bottom')"
+    @pointerdown.capture="pointer"
+  >
+    <section
+      ref="shell"
+      class="custom-card resident-card island-card"
+      :data-style="appearance.style"
+      :class="{
+        'resident-open': expanded,
+        expanded,
+        pill: !expanded,
+        urgent: state.active?.priority === 'URGENT',
+        call: state.active?.kind === 'call',
+        'resident-separated': scheme.separated && !expanded && !lesson,
+        'resident-lesson': !!lesson,
+        'message-surface': expanded && messages.length > 0 && !lesson,
+      }"
+      :style="style"
+      :role="expanded ? 'region' : 'button'"
+      tabindex="0"
+      :aria-label="
+        expanded
+          ? '自定义灵动岛内容'
+          : messages.length
+            ? `查看 ${messages.length} 条通知`
+            : '展开自定义灵动岛'
+      "
+      :aria-expanded="expanded"
+      @click="open"
+      @keydown="key"
+      @transitionend.self="reportHit"
+    >
+      <svg
+        class="shape"
+        :width="morph.width"
+        :height="morph.height"
+        :viewBox="`0 0 ${morph.width} ${morph.height}`"
+        preserveAspectRatio="none"
+        aria-hidden="true"
+      >
+        <path :d="path" />
+      </svg>
+      <span class="tint" aria-hidden="true" />
+      <div
+        class="resident-page resident-compact-page"
+        :style="{
+          '--resident-scale': compactFit.scale,
+          opacity: compactAlpha,
+          visibility: compactAlpha > 0 ? 'visible' : 'hidden',
+        }"
+        :class="{ 'page-active': !expanded }"
+        :inert="expanded"
+        :aria-hidden="expanded"
+      >
+        <div ref="compact" class="resident-source resident-compact">
+          <div class="layout-rows" :style="{ gap: `${scheme.spacing}px` }">
+            <section
+              v-for="row in scheme.rows"
+              :key="row.id"
+              class="layout-row"
+              :data-row="row.id"
+              :style="{ '--row-gap': `${row.gap}px` }"
+            >
+              <div class="row-components">
+                <ComponentNode
+                  v-for="node in row.nodes"
+                  :key="node.id"
+                  :node="node"
+                  :state="state"
+                  :now="now"
+                  :schedules="schedules"
+                  :time-points="timePoints"
+                  :editing="false"
+                  selected-id=""
+                  alert-node-id=""
+                />
+              </div>
+            </section>
+          </div>
+          <button
+            class="resident-bell"
+            :class="{ 'bell-empty': !messages.length }"
+            :aria-label="messages.length ? `查看 ${messages.length} 条通知` : '展开自定义灵动岛'"
+            @click.stop="action('expand')"
+          >
+            <ComponentIcon v-if="messages.length" kind="notification" />
+            <svg
+              v-else
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.6"
+              aria-hidden="true"
+            >
+              <path d="m8 10 4 4 4-4" />
+            </svg>
+            <span v-if="messages.length" :key="messages.length">
+              {{ messages.length > 99 ? '99+' : messages.length }}
+            </span>
+          </button>
+        </div>
+      </div>
+      <div
+        class="resident-page resident-detail-page"
+        :style="{
+          '--resident-scale': detailsFit.scale,
+          opacity: detailsAlpha,
+          visibility: detailsAlpha > 0 ? 'visible' : 'hidden',
+        }"
+        :class="{ 'page-active': expanded }"
+        :inert="!expanded"
+        :aria-hidden="!expanded"
+      >
+        <div
+          ref="details"
+          class="resident-source resident-details"
+          :class="{ 'with-messages': messages.length }"
+        >
+          <ClassicNotifications
+            v-if="messages.length"
+            id="custom-alert-host"
+            :state="state"
+            :appearance="appearance"
+            :max-height="available.height / scheme.scale"
+          />
+          <header v-else class="resident-panel-heading">
+            <span>自定义灵动岛</span>
+            <button class="icon-btn" aria-label="收起自定义灵动岛" @click.stop="action('collapse')">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6">
+                <path d="m8 14 4-4 4 4" />
+              </svg>
+            </button>
+          </header>
+          <div
+            v-if="!messages.length"
+            class="layout-rows resident-expanded-rows"
+            :style="{ gap: `${scheme.spacing}px` }"
+          >
+            <section
+              v-for="row in scheme.expandedRows"
+              :key="row.id"
+              class="layout-row"
+              :data-row="row.id"
+              :style="{ '--row-gap': `${row.gap}px` }"
+            >
+              <div class="row-components">
+                <ComponentNode
+                  v-for="node in row.nodes"
+                  :key="node.id"
+                  :node="node"
+                  :state="state"
+                  :now="now"
+                  :schedules="schedules"
+                  :time-points="timePoints"
+                  :editing="false"
+                  selected-id=""
+                  alert-node-id=""
+                />
+              </div>
+            </section>
+          </div>
+        </div>
+      </div>
+      <div
+        class="resident-page resident-lesson-page"
+        :style="{
+          '--resident-scale': lessonFit.scale,
+          opacity: lessonProgress,
+          visibility: lessonProgress > 0 ? 'visible' : 'hidden',
+        }"
+        :aria-hidden="!lesson"
+        :inert="!lesson"
+      >
+        <div ref="lessonSource" class="resident-source">
+          <LessonReminderContent
+            v-if="lastLesson"
+            :reminder="lastLesson"
+            :now="now"
+            :appearance="appearance"
+            :motion="motion"
+          />
+        </div>
+      </div>
+    </section>
+  </div>
+</template>
+<style src="./custom-runtime.css"></style>