feat(courseware,docs): 完善课件传输与岛编辑并统一全仓文档

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

docs/dev/testing.md

@@ -1,131 +1,69 @@
 ---
 title: 验收与测试
-description: 验收验收脚本怎么跑、覆盖什么、哪些用例是脆弱的，以及怎么判断失败是不是真回归。
+description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
 ---
 
 # 验收与测试
 
-验收分为后台快速冒烟、隔离的接口与逻辑回归、显式视觉验收。日常默认不显示窗口、不占用前台；
-涉及动画、桌面像素和灵动岛几何时，再单独运行视觉验收。
+按改动范围选择验证；数量和结果读取本次输出，不沿用历史报告数字。
+默认客户端冒烟为后台快速模式；动画、透明度、桌面截图必须显式视觉模式。
 
-## 验收脚本
+## 命令与前置条件
 
-| 命令                   | 覆盖                                                                             | 需要什么                    |
-| ---------------------- | -------------------------------------------------------------------------------- | --------------------------- |
-| `pnpm verify:e2e`      | 后端 + 实时推送 + RBAC 越权 + 上课时段 + 导入 + 班级账号 + 数据库管理 + 更新检查 | **后端已启动**              |
-| `pnpm verify:web`      | Web 管理端真实点击回归（Electron 驱动）                                          | 后端已启动 + Web 产物已构建 |
-| `pnpm verify:desktop`  | 客户端冒烟（Electron，无人工点击）                                               | 已构建的客户端产物          |
-| `pnpm verify:packaged` | 对**打包后 / 已安装**的客户端 EXE 复跑同一套冒烟（`--exe` 指定路径）             | 打包产物                    |
+| 命令                                             | 覆盖/前置条件                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| pnpm lint / pnpm typecheck / pnpm check:icons    | 静态检查；typecheck 会先构建 shared                               |
+| pnpm docs:check                                  | docfx 严格构建，需 .NET SDK 与 docfx                              |
+| pnpm verify:e2e                                  | 自动临时 SQLite、种子和带前缀账号，启动随机端口服务；无需真实服务 |
+| pnpm verify:web:isolated                         | 同上隔离服务，隐藏 Electron UI 回归；先构建 Web 产物              |
+| pnpm verify:web                                  | 连接已准备测试服务，需 Web 产物和测试管理员；不应指向业务服务     |
+| pnpm verify:v14                                  | 临时库验证关系课表、周次、范围、隐私与升级等                      |
+| pnpm verify:courseware                           | 临时库和文件目录的课件专项，不向真实班级推送                      |
+| pnpm verify:client-agent                         | 假系统适配器验证命令、回执和更新策略                              |
+| pnpm verify:client-migrations                    | 临时旧库验证迁移、联动退役与默认组持久化                          |
+| pnpm verify:review-client                        | 无窗口逻辑回归                                                    |
+| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务，使用 VERIFY_BASE_URL 等脚本参数         |
+| pnpm verify:desktop                              | 先 pnpm build:desktop；隐藏快速检查，独立 userData                |
+| pnpm verify:desktop:online                       | 显式联网，需要测试管理员并创建临时教师/班级                       |
+| pnpm verify:desktop:visual                       | 显式使用桌面，完整岛几何/动画/透明度/截图检查                     |
+| pnpm verify:packaged --exe <客户端EXE>           | 默认快速离线，两次启动、packaged=true；--visual 才使用桌面        |
 
-条目数由脚本自行统计并打印（`=== 结果：N/N 项通过 ===`），**文档里不写死容易过期的总数** ——
-每次跑完看脚本输出。
+联网 packaged 使用 --online；调用方须预先准备隔离服务、临时教师和班级并显式注入凭据，该启动器不会自动创建它们。
+开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
+不得回退到真实班级、重置真实密码或向真实班级发测试通知；远控与安装器使用假执行器。
+桌面进程超时和失败日志先定位，不能因为一个历史脆弱用例名称就断言当前失败必然正常。
 
-客户端维护专项回归：
-
-- `pnpm verify:client-agent`：模拟操作系统验证远控、回执重试与安装策略，不执行真实关机或安装器。
-- `pnpm verify:client-migrations`：创建临时旧库验证升级、联动移除与默认组编辑持久化。
-- `pnpm verify:clients-api`：面向 `http://127.0.0.1:4199` 的演示测试库（可用 `VERIFY_BASE_URL` 指定），验证权限、远控与更新接口。会创建并清理测试记录，请使用隔离测试服务。
-- `pnpm verify:review-client`：无窗口验证缓存故障恢复、通知竞态、教学周同步、管理员界面权限与崩溃恢复。
-- `pnpm verify:review-api`：针对审查缺陷验证接口权限、导入边界和实时删除等，必须连接隔离测试服务。
-
-另外三套是"门禁"而不是验收：`pnpm typecheck`、`pnpm lint`、`pnpm check:icons`。
-
-### 一次完整的交付前检查
+## 常用检查顺序
 
 ```bash
-pnpm lint                # ESLint，0 error 是底线
-pnpm typecheck           # 全仓库类型检查（含 vue-tsc）
-
-pnpm verify:e2e          # 自建全新隔离库与临时账号，不依赖真实服务
-pnpm verify:v14          # 新课表/权限/年度升级专项隔离验收
-
-pnpm build:desktop && pnpm verify:desktop
-pnpm build && pnpm verify:web
+pnpm lint
+pnpm typecheck
+pnpm check:icons
+pnpm docs:check
+pnpm verify:e2e
+pnpm verify:v14
+pnpm verify:courseware
+pnpm build:desktop
+pnpm verify:desktop
+pnpm --filter @classhelper/web-admin build
+pnpm verify:web:isolated
 ```
 
-改动涉及打包/交付形态时，再加 `pnpm dist:all` 与
-`pnpm verify:packaged --exe "<客户端路径>"`（**开发产物通过不等于用户机器上的副本通过**）。
+仅文档修改只需格式、链接与 docs:check；不因此重打包或占用桌面。
+改打包/运行时裁剪还要构建实际副本并跑 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:visual`「真实通知链路」「灵动岛标为已读」等 3 项 | 要求**当前不在上课时段**。种子课表恰有课正在进行时，客户端会**正确地**把普通通知暂存到下课 —— 这三项就会红（日志里会写 `客户端判定上课中=true`） |
-| `verify:e2e`「上课状态接口（at=周一 08:10）」                    | 种子把周一第 1 节限制在第 1 周，且用例把 `2026-09-07` 当第 1 周。`.env` 的 `TERM_START_DATE` 对齐即可全绿                                        |
-| `verify:web`「课表科目为全校统一目录」                           | 种子给每个班建满了全部科目，下拉里就没有可自动建课的「统一科目」分组                                                                             |
-| `verify:desktop:visual`「课表今天时间轴」                        | 凌晨约 00:00–03:00 时「已结束」探针被夹紧成 0 长度而被过滤                                                                                       |
-| `verify:desktop:visual`「作业看板全屏自适应」                    | 演示数据某天有 6 条长作业、而冒烟窗口只有约 543px 高时，缩放被下限 0.45 钳住 → 必然溢出                                                          |
-| 岛交互 / 岛动画 / 岛截图留档                                     | 窗口被遮挡或跑在远程会话里时会间歇性失败：置顶透明小窗的 rAF 被限流、形变采样抓不到帧。**先原样重跑一次再动手改**                                |
+## 截图
 
-## 大面积报「登录失败 / 401」时
-
-先检查隔离服务是否启动，以及测试管理员的当前口令。不要修改真实班级密码来迁就测试。
-联网客户端和 Web 回归会自行创建临时教师与班级；下面的环境变量只配置测试管理员：
-
-| 脚本                | 管理员凭据                                               |
-| ------------------- | -------------------------------------------------------- |
-| 客户端联网/打包冒烟 | `ELECTRON_SMOKE_ADMIN` / `ELECTRON_SMOKE_ADMIN_PASSWORD` |
-| Web 回归            | `UI_SMOKE_ADMIN` / `UI_SMOKE_ADMIN_PASS`                 |
-| 后端端到端回归      | 使用隔离种子库，口令由种子脚本与验收脚本约定             |
-
-默认离线快速冒烟不需要服务端凭据。
-
-## 默认后台运行，视觉验收单独执行
-
-`pnpm verify:desktop` 默认运行隐藏、不可聚焦的离屏窗口，仅检查启动、桥接白名单、缓存读写、
-跨服务端/跨班级缓存隔离和关闭隐藏。二次启动也只跑快速检查，不再重复整套动画。
-
-需要联网时运行 `pnpm verify:desktop:online`，创建临时教师与临时班级，结束后删除。
-不再自动探测并复用真实班级，也不会重置真实班级密码。Web 回归同样使用隔离的验证教师与班级。
-
-`pnpm verify:desktop:visual`（或客户端启动器 `--visual`）才运行灵动岛动画、透明度、桌面截图等完整验收，
-这类用例确实需要使用桌面。`verify:packaged` 也默认快速模式，显式传 `--visual` 才跑视觉验收。
-视觉验收不适合在用户操作屏幕时自动运行。截图采集命令需要传入 `--visual`（或设置 `ELECTRON_SMOKE_MODE=visual`）。
-结果记录模式和耗时；启动器设置超时，避免验证进程无限等待。
-
-## 截图留档
-
-截图分两套，各管一件事：
-
-| 目录                | 谁在用                                                      | 谁产出                                                           |
-| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
-| `docs/images/`      | **文档站、README、官网用的是同一份图**，页面上展示的都是它  | `capture-shots.mjs`（Web / 手机）+ 客户端冒烟（客户端 / 灵动岛） |
-| `docs/screenshots/` | 回归留档，页面不展示；`verify:*` 的像素级断言比对的就是它们 | 各冒烟脚本自动写入（island / client / web-mobile 三组）          |
-
-**展示图重新采集**（保证文档站与 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 \
-  node packages/desktop-client/scripts/smoke.mjs --visual --online
-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 \
-  node packages/desktop-client/scripts/smoke.mjs --visual --online
-```
-
-> 展示图都是**逻辑像素 1×**（灵动岛的 268×44、424×230 就是这个数，不再乘 2），
-> 页面按原始尺寸显示即可 —— 换图时别顺手放大，否则整页的尺寸对不上。
-> 采集脚本会把窗口真的弹在屏幕上。客户端留档会**临时停掉 CSS 动画**再截图 ——
-> 窗口被遮挡时 Chromium 冻结动画，而页面入场动画的起始帧是 `opacity: 0`，
-> 不停掉的话截出来是**整片空白**（DOM 里文本齐全，只有图是空的）。
-
-## V1.4 专项验收
-
-`verify:e2e` 由根启动器创建独立数据库、带前缀的临时账号与服务；服务禁止外网，请勿改回真实班级。`verify:v14` 在专用临时库验证新模型与自动升级幂等。详细结果、迁移保留情况和十项自检见 [实施记录](20261017-implementation.md)。
+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 通过表述为动画/透明度已验证。