Love_Chengke/ClassHelper
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(island,server): 连续圆角四角修正 + 叫人分紧急/普通两级

Browse Source 
灵动岛圆角（用户反馈"左上角和右下角缺一块 / 圆角边缘割裂"）：
- squircle.ts 改为"每个角独立圆心 + 角度参数"的超椭圆采样（原本四角共用同一个偏移向量，
  左上/右下被切掉一块）；四角几何与 WinIsland 的连续超椭圆一致，r 与 h/2、w/2 自动收敛。
- verify:desktop 新增像素级断言「连续圆角四角一致」：从四角沿对角线找岛体边界，
  四角步进必须两两一致（展开 15/15/15/15、紧急 14/14/14/14、胶囊 5/5/5/5），
  并保留路径绕行 |winding|≈2π 断言（抓"角上往回折"）。该断言即本次回归的守卫。
- 截图留档同时写入裁剪图与整窗图，便于人工复核角形。

叫人分紧急 / 普通两级（用户要求"叫人也分为紧急和普通"）：
- shared：CreateCallRequest 新增 urgent；紧急叫人 → URGENT（无视上课时段立即展开），
  普通叫人（默认）→ HIGH（按普通通知排队）。
- desktop：isImmediate 只认 priority=URGENT，不再把 kind=call 一律视为立即消息；
  普通叫人回到与普通通知相同的排队 / 隐藏 / 下课弹出路径。
- web：通知发布 → 叫人、学生管理 → 叫人 两个弹窗新增"级别"单选（默认普通）+ 联动提示文案。

验证：verify:e2e 135/135（新增普通 / 紧急叫人级别断言）、verify:web 20/20（新增级别单选断言）、
verify:desktop 59/59 + 离线复跑 53/53、typecheck / lint / format 全绿。
This commit is contained in:
LoveChengke committed 2026-09-12 19:54:00 +08:00
1 parent 1b4dd14e4a
commit 0690546307
13 files changed
+553 -205
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+142 -128
View File
@@ -20,7 +20,7 @@
| 1 | pnpm monorepo 脚手架、TypeScript / ESLint / Prettier / 环境变量 | ✅ 已完成 |
| 2 | 后端：Prisma schema + 迁移 + 种子数据 + JWT 认证 + RBAC + 模块化 REST API + Socket.IO | ✅ 已完成 |
| 3 | Web 管理端：登录、主布局、仪表盘、班级/学生/课表/作业/通知/成绩页面、Axios 封装、实时提示 | ✅ 已完成 |
| 4 | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 54/54） |
| 4 | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 59/59） |
| 5 | 三端联调脚本、打包命令、完整 README | ✅ 已完成（三套安装包 + 两套 UI 回归测试） |
| 6 | 测试账号与种子数据说明 | ✅ 已完成（见下文） |
| 7 | 生产化：服务端安装程序（内置 Node）、Web 端 PWA 可安装、Docker + Nginx 部署、生产加固与运维文档 | ✅ 已完成（见 [`docs/production.md`](docs/production.md)） |
@@ -75,7 +75,7 @@ class-helper/
│ ├── prisma/migrations/ # 迁移历史（已生成并应用）
│ ├── prisma/seed.ts # 种子数据
│ ├── prisma.config.ts # Prisma 7 配置（迁移/种子/连接串）
│ ├── scripts/verify-e2e.mjs # 后端端到端验收脚本（133 项）
│ ├── scripts/verify-e2e.mjs # 后端端到端验收脚本（135 项）
│ └── src/
│ ├── app.ts # Express 装配（静态托管 + 探针 + 限流 + 模块挂载）
│ ├── index.ts # 启动入口（自检/初始化 + HTTP + Socket.IO + 优雅退出）
@@ -171,15 +171,15 @@ pnpm verify:desktop
```bash
# 另开一个终端先启动后端：pnpm dev:server
pnpm verify:e2e # 后端 + REST + Socket.IO + RBAC + 上课时段拦截 + 叫人 + 导入 + 班级账号：133 项
pnpm verify:web # Web 管理端真实点击（含权限入口隐藏、手机适配、叫人入口、紧急通知 + 成绩/时间配置导入弹窗）：19 项
pnpm verify:desktop # Electron 客户端（含灵动岛动画/收回/已读/作业/叫人、真实链路、课表时间轴、开合不震动、个性化 10 项参数与托盘/退出无残留）：49 项
pnpm verify:e2e # 后端 + REST + Socket.IO + RBAC + 上课时段拦截 + 紧急/普通叫人 + 导入 + 班级账号：135 项
pnpm verify:web # Web 管理端真实点击（含权限入口隐藏、手机适配、叫人入口 + 紧急/普通级别、紧急通知 + 成绩/时间配置导入弹窗）：20 项
pnpm verify:desktop # Electron 客户端（含灵动岛动画/收回/已读/作业/紧急与普通叫人、真实链路、课表时间轴、开合不震动、连续圆角四角一致、个性化 10 项参数与托盘/退出无残留）：59 项
```
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截、导入与失败回滚、班级账号代全班操作、老师端导入不越权**等 133 项，
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截、导入与失败回滚、班级账号代全班操作、老师端导入不越权**等 135 项，
实测通知 37ms、作业 26ms、成绩 25ms 到达（要求 < 5 秒），紧急通知 409 拦截与二次确认后发布均通过；
客户端脚本验证 preload 桥接、渲染进程、IndexedDB 读写、断网回退、**灵动岛四种状态切换**与联网集成
（**班级账号登录** + 四类数据 + Socket.IO），实测 54/54 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 48/48）。
（**班级账号登录** + 四类数据 + Socket.IO），实测 59/59 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 53/53）。
## 默认账号与种子数据
@@ -208,30 +208,30 @@ pnpm verify:desktop # Electron 客户端（含灵动岛动画/收回/已读
## 常用命令
| 命令 | 说明 |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `pnpm dev` | 并行启动 shared(tsc watch) + 后端 + Web 端 |
| `pnpm dev:server` / `pnpm dev:web` | 只启动后端 / 只启动 Web 端 |
| `pnpm dev:desktop` | 启动 EXE 客户端开发模式（Vite 5174 + Electron，热更新） |
| `pnpm build` | 构建 shared + 后端 + Web 端 + EXE 客户端 |
| `pnpm build:desktop` | 仅构建 EXE 客户端（esbuild 主进程/preload + Vite 渲染进程） |
| `pnpm icons` | 生成应用图标（PNG/ICO，用 Electron 渲染 SVG） |
| **`pnpm dist:server`** | **打包服务端 + Web 管理端**（免安装目录 + NSIS 安装程序，内置 Node） |
| `pnpm dist:dir` | 打包客户端免安装目录 `release/win-unpacked`（含可执行文件，最快） |
| `pnpm dist:win` | 打包客户端 nsis 安装包 + portable 单文件 EXE |
| `pnpm dist:all` | 服务端安装程序 + 客户端安装程序一起打 |
| `pnpm verify:e2e` | 后端端到端验收（133 项，含角色权限矩阵、导入与班级账号，需服务端已启动） |
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，19 项，含权限入口隐藏与导入弹窗） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（49 项，含灵动岛开合不震动/已读/作业/叫人、课表时间轴、个性化全参数） |
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
| `pnpm lint` / `pnpm lint:fix` | ESLint 检查 / 自动修复 |
| `pnpm format` / `pnpm format:check` | Prettier 格式化 / 检查 |
| `pnpm db:generate` | 生成 Prisma Client（输出到 `packages/server/src/generated/prisma`） |
| `pnpm db:migrate` | 创建并应用迁移 |
| `pnpm db:seed` | 写入种子数据 |
| `pnpm db:reset` | 重置数据库并重新执行 seed |
| `pnpm db:studio` | 打开 Prisma Studio |
| `pnpm db:switch:mysql` / `db:switch:sqlite` | 切换数据库 provider |
| 命令 | 说明 |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `pnpm dev` | 并行启动 shared(tsc watch) + 后端 + Web 端 |
| `pnpm dev:server` / `pnpm dev:web` | 只启动后端 / 只启动 Web 端 |
| `pnpm dev:desktop` | 启动 EXE 客户端开发模式（Vite 5174 + Electron，热更新） |
| `pnpm build` | 构建 shared + 后端 + Web 端 + EXE 客户端 |
| `pnpm build:desktop` | 仅构建 EXE 客户端（esbuild 主进程/preload + Vite 渲染进程） |
| `pnpm icons` | 生成应用图标（PNG/ICO，用 Electron 渲染 SVG） |
| **`pnpm dist:server`** | **打包服务端 + Web 管理端**（免安装目录 + NSIS 安装程序，内置 Node） |
| `pnpm dist:dir` | 打包客户端免安装目录 `release/win-unpacked`（含可执行文件，最快） |
| `pnpm dist:win` | 打包客户端 nsis 安装包 + portable 单文件 EXE |
| `pnpm dist:all` | 服务端安装程序 + 客户端安装程序一起打 |
| `pnpm verify:e2e` | 后端端到端验收（135 项，含角色权限矩阵、导入与班级账号，需服务端已启动） |
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，20 项，含权限入口隐藏、叫人紧急/普通与导入弹窗） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（59 项，含灵动岛圆角/开合不震动/已读/作业/紧急与普通叫人、课表时间轴、个性化全参数） |
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
| `pnpm lint` / `pnpm lint:fix` | ESLint 检查 / 自动修复 |
| `pnpm format` / `pnpm format:check` | Prettier 格式化 / 检查 |
| `pnpm db:generate` | 生成 Prisma Client（输出到 `packages/server/src/generated/prisma`） |
| `pnpm db:migrate` | 创建并应用迁移 |
| `pnpm db:seed` | 写入种子数据 |
| `pnpm db:reset` | 重置数据库并重新执行 seed |
| `pnpm db:studio` | 打开 Prisma Studio |
| `pnpm db:switch:mysql` / `db:switch:sqlite` | 切换数据库 provider |
## Web 管理端（含手机小屏适配）
@@ -267,7 +267,7 @@ pnpm verify:desktop # Electron 客户端（含灵动岛动画/收回/已读
实现位置：`src/composables/useResponsive.ts`（断点 + resize 监听）、`src/layouts/AdminLayout.vue`（抽屉/顶栏）、
`src/styles/index.css`（全局响应式规则）、各视图表格卡片加 `.table-card`。
`pnpm verify:web` 的 19 项里，最后 11 项专门验证权限入口隐藏、手机端、叫人入口、成绩导入入口与 ClassIsland 时间配置导入弹窗（Electron 真实点击）：
`pnpm verify:web` 的 20 项里，后半段专门验证权限入口隐藏、手机端、叫人入口（含紧急/普通两级）、成绩导入入口与 ClassIsland 时间配置导入弹窗（Electron 真实点击）：
| 校验项 | 实测结果 |
| -------------------------------------- | -------------------------------------------------------------------- |
@@ -332,22 +332,23 @@ pnpm verify:desktop # Electron 客户端（含灵动岛动画/收回/已读
> 渲染层做命中测试后只在指针进入岛体时打开命中——**大窗口不会吞掉桌面点击**（有专项断言）。
> 由于窗口固定，Windows 那条"透明窗口最小高度约 36px"的限制不再作用于岛：空闲细缝可以真正做到 6px 宽。
| 场景 | 灵动岛行为 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 收到通知（非上课时段） | **直接出现胶囊**（无"上岛"入场动画）：`新消息 · 共 N 条` + 发送人 + `点击查看`，15 秒后自动收起 |
| 点击胶囊 | 展开为**详情卡**（形变 + 淡入，无回弹）：标题、内容、时间、`打开应用 / 标为已读 / 知道了`，20 秒后收起 |
| 点击卡片空白处 | 回缩为**胶囊**（不直接消失，仍可再次点开） |
| **点击屏幕任意位置** | 同样回缩为胶囊：展开时窗口临时可聚焦，点到别处即失焦收起（WinUI 同款"点击外部关闭"） |
| **点"标为已读"** | 通知中心同步标记已读、未读红点立即减少（此前只从灵动岛队列移除、列表仍显示未读） |
| **新作业发布** | 也上岛：胶囊显示"新作业"（青蓝描边 + 书本图标），展开可见"截止时间：…" |
| **叫人（老师点名）** | **上课时段也立即展开**：琥珀金卡片、"叫人"徽标、"请 XXX 同学找 XXX 老师"、按钮为"收到" |
| 卡片形变 | 卡片是**固定尺寸、顶部居中锚定**的，窗口只负责露出/裁切透明区域 —— 收回时不会出现被拉伸的"方框"，图标也不会上下跳 |
| 点击右上角收起按钮 | 同上：回缩为胶囊 |
| 上课时间段收到普通通知 | **完全不显示**（窗口直接隐藏，不打扰课堂）并进入待发队列；下课后自动弹出详情（14 秒）→ 收起为胶囊（25 秒） |
| 上课时间段收到**紧急**通知 | **无论是否上课立刻展开**显示详情（带内部红色呼吸光晕与"紧急"角标，无需点击），45 秒后收起 |
| 上课时间段内的任何点击 | 一律不显示（不会展开、也不会回缩出胶囊），只有紧急通知能出现在屏幕上 |
| 多条约谈 | 队列按时间排序，紧急通知优先插播；卡片底部提示"还有 N 条通知" |
| 退出/断开 | 主窗口退出时灵动岛一并关闭；上课状态来自 `GET /api/schedules/current`（10 秒心跳 + 下课时长定时器） |
| 场景 | 灵动岛行为 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| 收到通知（非上课时段） | **直接出现胶囊**（无"上岛"入场动画）：`新消息 · 共 N 条` + 发送人 + `点击查看`，15 秒后自动收起 |
| 点击胶囊 | 展开为**详情卡**（形变 + 淡入，无回弹）：标题、内容、时间、`打开应用 / 标为已读 / 知道了`，20 秒后收起 |
| 点击卡片空白处 | 回缩为**胶囊**（不直接消失，仍可再次点开） |
| **点击屏幕任意位置** | 同样回缩为胶囊：展开时窗口临时可聚焦，点到别处即失焦收起（WinUI 同款"点击外部关闭"） |
| **点"标为已读"** | 通知中心同步标记已读、未读红点立即减少（此前只从灵动岛队列移除、列表仍显示未读） |
| **新作业发布** | 也上岛：胶囊显示"新作业"（青蓝描边 + 书本图标），展开可见"截止时间：…" |
| **紧急叫人**（老师点名·紧急） | **上课时段也立即展开**：琥珀金卡片、`叫人` 徽标、"请 XXX 同学找 XXX 老师"、按钮为"收到"（`priority=URGENT`） |
| **普通叫人**（默认级别） | 课间先显示 `叫人` 胶囊、点击展开；**上课时段只进队列**（不打断课堂），下课后自动弹出详情（`priority=HIGH`） |
| 卡片形变 | 卡片是**固定尺寸、顶部居中锚定**的，窗口只负责露出/裁切透明区域 —— 收回时不会出现被拉伸的"方框"，图标也不会上下跳 |
| 点击右上角收起按钮 | 同上：回缩为胶囊 |
| 上课时间段收到普通通知 | **完全不显示**（窗口直接隐藏，不打扰课堂）并进入待发队列；下课后自动弹出详情（14 秒）→ 收起为胶囊（25 秒） |
| 上课时间段收到**紧急**通知 | **无论是否上课立刻展开**显示详情（带内部红色呼吸光晕与"紧急"角标，无需点击），45 秒后收起 |
| 上课时间段内的任何点击 | 一律不显示（不会展开、也不会回缩出胶囊），只有紧急通知能出现在屏幕上 |
| 多条约谈 | 队列按时间排序，紧急通知优先插播；卡片底部提示"还有 N 条通知" |
| 退出/断开 | 主窗口退出时灵动岛一并关闭；上课状态来自 `GET /api/schedules/current`（10 秒心跳 + 下课时长定时器） |
- 动画：窗口尺寸用逐帧缓动实现"形变"，**单调不过冲**——展开 300ms、收回 220ms，统一 `easeOutCubic`
（早期版本用 `easeOutBack` 弹簧缓动 + 卡片 `cubic-bezier(0.34, 1.56, 0.64, 1)` 缩放入场，
@@ -498,66 +499,79 @@ pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS
`pnpm verify:desktop` 以 `ELECTRON_SMOKE_TEST=1` 启动应用（不弹窗），主进程依次校验后自动退出：
| 校验项 | 实测结果 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 渲染进程挂载 + 窗口标题 | ✅ `children=1` / `title=班级小助手` |
| 登录页渲染（三个输入框） | ✅ 服务器地址 / **班级码** / 班级密码 |
| preload contextBridge 注入 | ✅ 9 个方法（含灵动岛 3 个） |
| IPC 往返（getAppInfo/saveConfig） | ✅ Electron 44.3.0 |
| 配置文件写入用户目录 | ✅ `%APPDATA%\@classhelper\desktop-client\config.json` |
| IndexedDB 缓存读写 | ✅ 读写/统计/删除 + 6 个 store |
| 断网时回退本地缓存 | ✅ `fromCache=true`（请求不可达端口） |
| 灵动岛窗口创建（置顶/透明/不占任务栏） | ✅ `ready=true` |
| 上课期间普通通知自动隐藏 | ✅ `mode=hidden queued=1 visible=false`（窗口真的隐藏，不是只改状态） |
| 上课期间点击不展开（严格不显示） | ✅ `mode=hidden visible=false` |
| 下课后自动弹出暂存通知详情 | ✅ `mode=expanded reason=after-class` |
| 上课期间紧急通知立即展开（无需点击） | ✅ `mode=expanded reason=urgent` |
| **紧急通知带展开动画** | ✅ 16ms 采样 34 帧，出现 7 个中间尺寸，最终 `424x344`（窗口从胶囊尺寸单调展开，无过冲） |
| 上课期间收起不回缩成胶囊 | ✅ `mode=hidden visible=false` |
| **普通通知直接显示胶囊（无入场动画）** | ✅ 推送前已隐藏，60ms 内窗口即为 `268x44`、`mode=pill`（无"上岛"动画） |
| 胶囊 → 点击 → 展开详情 | ✅ `新消息 · 共 2 条` → `expanded`（含真实 DOM 断言与截图） |
| **点击卡片空白处回缩为胶囊** | ✅ 真实点击 `.body` 空白区域 → `mode=pill` |
| **点击右上角收起按钮回缩为胶囊** | ✅ 真实点击 `.icon-btn` → `mode=pill` |
| **灵动岛截图留档 + 像素级校验** | ✅ 4 张（808×632 / 848×688 / 536×88 / 808×632）；宽高比与状态机配置偏差 **0.000**；形态尺寸递增 pill < expanded < urgent；紧急态偏红 **20584 px**（卡片内部光晕） |
| **紧急红晕不外溢（窗口边缘无红光）** | ✅ 截图最外圈（2px）偏红像素 = **0**（守住"卡片周围不出现光晕硬边"） |
| 联网集成（`ELECTRON_SMOKE_ONLINE=1`） | ✅ `login=高一(1)班 classSession=true` / 1 班级 / 30 节课 / Socket.IO 已连接 |
| **个性化：尺寸联动不破坏布局** | ✅ 高 56 / 宽 300 / 圆角 26 / 字号 14 → 窗口 `300x56`，CSS 变量同步，展开态内容溢出 **0px** |
| **开合不震动：展开** | ✅ 逐帧采样 57 帧：岛中心波动 **0.00px**、上边缘 **0.00px**；**窗口冻结**（全程 `476x282@482,-2`）；岛最大 `440x246` = 目标无过冲 |
| **开合不震动：收回** | ✅ 逐帧采样 56 帧：岛中心/上边缘波动 **0.00px**；窗口全程冻结；岛 `386x230→…→268x44` 单调收缩无回跳 |
| **WinIsland 架构：窗口恒定 + 形状正确** | ✅ 逐帧窗口签名恒为 `476x282@482,-2`（只有 1 种）；SVG 形状 bbox 与卡片框一致（±2px，可抓出 viewBox 错位/残留角） |
| **岛外鼠标穿透** | ✅ 指针在岛内 `interactive=true`、在岛外 `interactive=false`（固定大包围盒窗口不吞桌面点击） |
| **WinIsland 排版：字号即时生效** | ✅ 13px → 19px：胶囊标题 `11.96→17.48`、胶囊副题 `9.62→14.06`、标题 `14.04→20.52`、正文 `12.35→18.05`、按钮 `9.88→14.44`，**倍率全部 1.462 = 19/13** |
| **WinIsland 风格：三种底即时切换** | ✅ 纯黑 `fill=rgb(0,0,0)`/材质 `none`；毛玻璃 `fill=rgba(10,10,14,.59)`/材质 **`acrylic`**；主题色 `fill=rgb(11,11,15)` |
| **WinIsland 空闲细缝** | ✅ 空闲时岛收成 `6x22`（窗口固定，不再受 Windows 36px 最小窗口高度限制）→ 来消息自动回到 `268x44`；关闭细缝后空闲 `isVisible=false` |
| **个性化：透明度 / 主题色** | ✅ `setOpacity` 实际 **0.62**（设置 0.62）；`--island-accent` = `#ff7043` |
| **个性化：停靠位置（6 个锚点）** | ✅ 左上 `8,8` / 右上 `1216,8` / 底部居中 `586,800` / 底部左 / 底部右 / 顶部居中 `586,8` |
| **个性化：置顶开关** | ✅ 关闭后 `isAlwaysOnTop=false`，开启后 `true` |
| **个性化：动画开关 / 速度** | ✅ 关闭动画后 60ms 内即到位（无过渡）；speed=2 收回明显快于 speed=0.5 |
| **个性化：持久化** | ✅ 写入客户端配置后重新读取完全一致（尺寸/圆角/透明度/主题色/字号/动画/速度/位置/置顶/风格/细缝） |
| **退出清理：托盘 / 灵动岛 / 窗口** | ✅ `isTrayReady()=false`、`island.isReady()=false`、窗口全部销毁 |
| **退出后无残留（文件锁 + 二次启动）** | ✅ 配置目录可删除（句柄已释放）→ 用同一配置目录二次启动成功并再次全绿 |
| 校验项 | 实测结果 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 渲染进程挂载 + 窗口标题 | ✅ `children=1` / `title=班级小助手` |
| 登录页渲染（三个输入框） | ✅ 服务器地址 / **班级码** / 班级密码 |
| preload contextBridge 注入 | ✅ 9 个方法（含灵动岛 3 个） |
| IPC 往返（getAppInfo/saveConfig） | ✅ Electron 44.3.0 |
| 配置文件写入用户目录 | ✅ `%APPDATA%\@classhelper\desktop-client\config.json` |
| IndexedDB 缓存读写 | ✅ 读写/统计/删除 + 6 个 store |
| 断网时回退本地缓存 | ✅ `fromCache=true`（请求不可达端口） |
| 灵动岛窗口创建（置顶/透明/不占任务栏） | ✅ `ready=true` |
| 上课期间普通通知自动隐藏 | ✅ `mode=hidden queued=1 visible=false`（窗口真的隐藏，不是只改状态） |
| 上课期间点击不展开（严格不显示） | ✅ `mode=hidden visible=false` |
| 下课后自动弹出暂存通知详情 | ✅ `mode=expanded reason=after-class` |
| 上课期间紧急通知立即展开（无需点击） | ✅ `mode=expanded reason=urgent` |
| **紧急通知带展开动画** | ✅ 16ms 采样 31 帧，出现 5 个中间尺寸，最终 `440x246`（岛在固定窗口内单调展开，无过冲） |
| 上课期间收起紧急通知 | ✅ 回缩为**胶囊且保持可见** `mode=pill visible=true 岛=268x44`（不再整块隐藏） |
| **上课期间紧急通知可再次展开（回归）** | ✅ 收起后点开 → `mode=expanded active=smoke-urgent-in-class 岛=440x246` |
| **普通通知直接显示胶囊（无入场动画）** | ✅ 推送前已隐藏，60ms 内窗口即为 `268x44`、`mode=pill`（无"上岛"动画） |
| 胶囊 → 点击 → 展开详情 | ✅ `新消息 · 共 2 条` → `expanded`（含真实 DOM 断言与截图） |
| **点击卡片空白处回缩为胶囊** | ✅ 真实点击 `.body` 空白区域 → `mode=pill` |
| **点击右上角收起按钮回缩为胶囊** | ✅ 真实点击 `.icon-btn` → `mode=pill` |
| **灵动岛截图留档 + 像素级校验** | ✅ 6 张（848×460 / 880×492 / 536×88 / 848×460 / 848×460 / 912×524）；宽高比与状态机配置偏差 **0.000**；形态尺寸递增 pill < expanded < urgent < call |
| **连续圆角四角一致（缺一块 / 角画反）** | ✅ 四角沿对角线边界步进两两一致：展开 `[15,15,15,15]`、紧急 `[14,14,14,14]`、胶囊 `[5,5,5,5]`、叫人 `[14,14,14,14]`，与超椭圆理论值（0.153r）吻合，离散 **0**（旧实现四角共用同一偏移向量 → 左上/右下被切掉一块，此断言即为该回归的守卫） |
| **紧急红晕不外溢（窗口边缘无红光）** | ✅ 截图最外圈（2px）偏红像素 = **0**（守住"卡片周围不出现光晕硬边"） |
| 联网集成（`ELECTRON_SMOKE_ONLINE=1`） | ✅ `login=高一(1)班 classSession=true` / 1 班级 / 30 节课 / Socket.IO 已连接 |
| **个性化：尺寸联动不破坏布局** | ✅ 高 56 / 宽 300 / 圆角 26 / 字号 14 → 窗口 `300x56`，CSS 变量同步，展开态内容溢出 **0px** |
| **开合不震动：展开** | ✅ 逐帧采样 57 帧：岛中心波动 **0.00px**、上边缘 **0.00px**；**窗口冻结**（全程 `476x282@482,-2`）；岛最大 `440x246` = 目标无过冲 |
| **开合不震动：收回** | ✅ 逐帧采样 56 帧：岛中心/上边缘波动 **0.00px**；窗口全程冻结；岛 `386x230→…→268x44` 单调收缩无回跳 |
| **WinIsland 架构：窗口恒定 + 形状正确** | ✅ 逐帧窗口签名恒为 `476x282@482,-2`（只有 1 种）；SVG 形状 bbox 与卡片框一致（±2px）；**路径绕行 \|winding\| ≈ 2π**（凸、不自交，可抓出"角上往回折"） |
| **岛外鼠标穿透** | ✅ 指针在岛内 `interactive=true`、在岛外 `interactive=false`（固定大包围盒窗口不吞桌面点击） |
| **紧急叫人（URGENT + 叫人）** | ✅ 上课中也立即展开：`mode=expanded kind=call reason=call 徽标=叫人 按钮=收到` |
| **普通叫人（HIGH + 叫人）** | ✅ 上课只进队列：`mode=hidden active≠smoke-call-normal queued=[…smoke-call-normal]`；下课后自动弹出 `active=smoke-call-normal kind=call` |
| **WinIsland 排版：字号即时生效** | ✅ 13px → 19px：胶囊标题 `11.96→17.48`、胶囊副题 `9.62→14.06`、标题 `14.04→20.52`、正文 `12.35→18.05`、按钮 `9.88→14.44`，**倍率全部 1.462 = 19/13** |
| **WinIsland 风格：三种底即时切换** | ✅ 纯黑 `fill=rgb(0,0,0)`/材质 `none`；毛玻璃 `fill=rgba(10,10,14,.59)`/材质 **`acrylic`**；主题色 `fill=rgb(11,11,15)` |
| **WinIsland 空闲细缝** | ✅ 空闲时岛收成 `6x22`（窗口固定，不再受 Windows 36px 最小窗口高度限制）→ 来消息自动回到 `268x44`；关闭细缝后空闲 `isVisible=false` |
| **个性化：透明度 / 主题色** | ✅ `setOpacity` 实际 **0.62**（设置 0.62）；`--island-accent` = `#ff7043` |
| **个性化：停靠位置（6 个锚点）** | ✅ 左上 `8,8` / 右上 `1216,8` / 底部居中 `586,800` / 底部左 / 底部右 / 顶部居中 `586,8` |
| **个性化：置顶开关** | ✅ 关闭后 `isAlwaysOnTop=false`，开启后 `true` |
| **个性化：动画开关 / 速度** | ✅ 关闭动画后 60ms 内即到位（无过渡）；speed=2 收回明显快于 speed=0.5 |
| **个性化：持久化** | ✅ 写入客户端配置后重新读取完全一致（尺寸/圆角/透明度/主题色/字号/动画/速度/位置/置顶/风格/细缝） |
| **退出清理：托盘 / 灵动岛 / 窗口** | ✅ `isTrayReady()=false`、`island.isReady()=false`、窗口全部销毁 |
| **退出后无残留（文件锁 + 二次启动）** | ✅ 配置目录可删除（句柄已释放）→ 用同一配置目录二次启动成功并再次全绿 |
该验证对**开发产物与打包后的 EXE 都适用**（打包后用 `ELECTRON_SMOKE_RESULT=<file>` 写出 JSON 结果，
已实测 `packaged: true`、54/54 通过、退出码 0）。灵动岛各状态的窗口截图会写到
已实测 `packaged: true`、59/59 通过、退出码 0）。灵动岛各状态的窗口截图会写到
`ISLAND_SHOTS_DIR`（默认 `.cache/island-shots/`，仓库内留档目录 `docs/screenshots/island/`），
并对尺寸、宽高比、绘制内容（不透明像素/颜色种类）、紧急态红色像素与外溢红光做断言。
冒烟进程使用独立 userData（`ELECTRON_SMOKE_PROFILE`），因此**用户开着客户端也能跑验证**。
## 叫人（老师点名让学生过来）
老师在 **Web 管理端 → 学生管理 → 叫人** 选中学生，配合**快捷短语**或**自定义消息**发送；
学生端桌面**立即浮出**灵动岛卡片，显示「请 XXX 同学找 XXX 老师」+ 具体事由，按钮为「收到」。
老师在 **Web 管理端 → 学生管理 → 叫人**（或 **通知发布 → 叫人**）选中学生，配合**快捷短语**或**自定义消息**发送。
叫人分**两档**，由弹窗里的「级别」单选决定（默认 **普通**）：
| 位置 | 行为 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 服务端 | `POST /api/calls`（教师/管理员）→ 落库一条 HIGH 级通知（进学生通知中心、可用已读状态） + 广播 `notification:new`（班级房间）与 `call:new`（定向到被叫学生 `user:{id}`） |
| 快捷短语 | `CALL_QUICK_PHRASES`（共享常量）：请到办公室/讲台/实验室/门卫处找我、请带上作业本/试卷找我、请到教室门口等我、请马上来一趟；点击选中，再点取消 |
| 自定义消息 | 输入框内容优先于快捷短语（最长 200 字），例如"带上昨天的数学作业到办公室" |
| 客户端 | `call:new` → 灵动岛 `kind=call`，**无视上课时段立即展开**（老师正在等这名学生），90 秒后自动收起 |
| 权限 | 学生调用被拒 403；教师只能叫自己班级的学生（跨班/不在本班返回 400/403） |
| 级别 | 落库级别 | 学生端行为 |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------- |
| **普通叫人** | `HIGH` | 课间：先显示"叫人"胶囊，点击展开；**上课时段：只进队列、不打断课堂**，下课后自动弹出详情（90 秒后收起） |
| **紧急叫人** | `URGENT` | **无视上课时段立即展开**（与紧急通知同待遇），上课时被收起后仍保留胶囊、可再次点开 |
`verify:e2e` 覆盖 6 项（201 + 标题模板、自定义消息优先、上课时段允许、学生 403、学生通知中心可见且未读、清理）；
`verify:web` 覆盖弹窗与短语可选中；`verify:desktop` 覆盖"上课中也立即展开 + 徽标/按钮文案"。
两档的学生端卡片都是「请 XXX 同学找 XXX 老师」+ 具体事由，徽标 `叫人`、按钮「收到」；点击「收到」复用通知已读机制。
| 位置 | 行为 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 服务端 | `POST /api/calls`（教师/管理员）→ `urgent: true` 落库 `URGENT`，否则 `HIGH`（进学生通知中心、可用已读状态） + 广播 `notification:new`（班级房间）与 `call:new`（定向到被叫学生 `user:{id}`） |
| 快捷短语 | `CALL_QUICK_PHRASES`（共享常量）：请到办公室/讲台/实验室/门卫处找我、请带上作业本/试卷找我、请到教室门口等我、请马上来一趟；点击选中，再点取消 |
| 自定义消息 | 输入框内容优先于快捷短语（最长 200 字），例如"带上昨天的数学作业到办公室" |
| 客户端 | `call:new` → 灵动岛 `kind=call`；**是否立即展开只由 `priority` 决定**（`isImmediate` 只认 `URGENT`），与"普通通知"共用同一条排队/隐藏/下课弹出路径 |
| 权限 | 学生调用被拒 403；教师只能叫自己班级的学生（跨班/不在本班返回 400/403） |
`verify:e2e` 覆盖 8 项（201 + 标题模板、**普通叫人 HIGH**、**紧急叫人 URGENT**、自定义消息优先、上课时段允许、
学生 403、学生通知中心可见且未读、清理）；
`verify:web` 覆盖弹窗、级别单选与短语可选中；`verify:desktop` 覆盖「紧急叫人上课中也立即展开 + 徽标/按钮文案」
与「普通叫人上课只进队列、下课自动弹出」。
## 上课时段策略（紧急通知二次确认）
@@ -859,28 +873,28 @@ pnpm db:migrate && pnpm db:seed
## 验收标准对照
| 验收项 | 结果 | 证据 |
| ------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------- |
| 教师 Web 端发布通知，学生端 5 秒内收到 | ✅ | `verify:e2e`：`notification:new` **37–44ms** |
| 教师发布作业，学生能查看并标记完成 | ✅ | `homework:new` **26–40ms**，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true` |
| 教师录入成绩，学生能查看个人成绩 | ✅ | `grade:updated` **21–25ms**，`/grades/my` 返回记录；批量录入与统计接口通过 |
| 学生能查看课表，支持按周切换 | ✅ | `/schedules/grid?week=1` 返回 30 节，`week` 过滤 `weekStart ≤ week ≤ weekEnd` |
| 断网后客户端可查看缓存数据 | ✅ | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true items=1`；离线横幅 + 缓存统计页可用 |
| 权限隔离：学生不能访问其他班级数据 | ✅ | 10 项越权断言全部 403/401（学生跨班/跨班作业/跨班课表、教师跨班发布、未登录访问…） |
| 上课时段发布紧急通知必须二次确认 | ✅ | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅ | `verify:desktop` 状态断言 + 像素级截图（`docs/screenshots/island/`） |
| 灵动岛：收回无"方框"闪烁 / 点击屏幕任意处收回 | ✅ | 采样卡片尺寸恒为固定值（396×308、260×38）+ 失焦自动收回 |
| 灵动岛"标为已读"同步通知中心 | ✅ | 真实链路：点击后 `read=false → true`、未读数 `1 → 0` |
| 作业发布也上岛（"新作业"胶囊 + 截止时间） | ✅ | `kind=homework` + 展开显示"截止时间：…" |
| 叫人（老师点名 → 学生灵动岛立即跳出） | ✅ | `verify:e2e` 6 项 + `verify:desktop` 上课中也立即展开（徽标"叫人"、按钮"收到"） |
| 成绩 / 名单表格导入（xlsx·xls·csv） | ✅ | 模板下载 + 预览映射 + 重复处理 + 行号级错误：`verify:e2e` 导入 22 项、`verify:web` 弹窗实测 |
| ClassIsland 时间配置导入（覆盖 / 合并 / 回滚） | ✅ | 合法 200、非法 400 `IMPORT_INVALID` 且原配置仍为 3 节、merge 覆盖 1 新增 1 共 4 节 |
| 安装版覆盖升级自动补迁移 | ✅ | 真实旧库升级日志：`升级安装：已应用 2 个迁移文件，跳过 34 个已存在对象`，`TimeLayout` 自动建表 |
| 学生端主体 = 班级（班级码 + 班级密码登录） | ✅ | `verify:e2e` 班级账号 19 项：登录 / 错误密码 401 / 跨班 403 / 发布 403 / 班级码重复 400 / 密码重置 / 班级码用后还原 | `n | 成绩与表格导入：老师端可用且不越权 | ✅ | 班主任预览/导入本班成绩 200、跨班 403、科任 403、名单导入与模板 403；Web 端班主任可见导入按钮并打开弹窗 |
| 班级设备代全班操作（已读 · 完成 · 成绩总览） | ✅ | 标记已读写入 6 条（全班 6 人）、教师端 `readCount=6`、`completedCount=6`、`/grades/my` 全班成绩 |
| 客户端只保留班级登录入口 | ✅ | `verify:desktop`：`login=高一(1)班 classSession=true`，导航「成绩」标题变为「本班成绩」 |
| 能成功打包 Windows EXE | ✅ | `班级小助手-0.1.0-x64-setup.exe` / `-portable.exe` / `win-unpacked/*.exe`（见下表） |
| 提供完整 README（启动、构建、打包、默认账号） | ✅ | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、MySQL 切换、打包与常见问题 |
| 验收项 | 结果 | 证据 |
| ------------------------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------------------- |
| 教师 Web 端发布通知，学生端 5 秒内收到 | ✅ | `verify:e2e`：`notification:new` **37–44ms** |
| 教师发布作业，学生能查看并标记完成 | ✅ | `homework:new` **26–40ms**，`PATCH /homeworks/:id/status` 200 且列表回显 `completed=true` |
| 教师录入成绩，学生能查看个人成绩 | ✅ | `grade:updated` **21–25ms**，`/grades/my` 返回记录；批量录入与统计接口通过 |
| 学生能查看课表，支持按周切换 | ✅ | `/schedules/grid?week=1` 返回 30 节，`week` 过滤 `weekStart ≤ week ≤ weekEnd` |
| 断网后客户端可查看缓存数据 | ✅ | 客户端冒烟：`断网时回退到本地缓存 → fromCache=true items=1`；离线横幅 + 缓存统计页可用 |
| 权限隔离：学生不能访问其他班级数据 | ✅ | 10 项越权断言全部 403/401（学生跨班/跨班作业/跨班课表、教师跨班发布、未登录访问…） |
| 上课时段发布紧急通知必须二次确认 | ✅ | 服务端 409 `URGENT_DURING_CLASS`（`confirmDuringClass` 后 201）；Web 端全屏警告 + 3 秒倒计时 |
| 客户端灵动岛：上课隐藏 / 下课弹出 / 紧急立即展开 | ✅ | `verify:desktop` 状态断言 + 像素级截图（`docs/screenshots/island/`） |
| 灵动岛：收回无"方框"闪烁 / 点击屏幕任意处收回 | ✅ | 采样卡片尺寸恒为固定值（396×308、260×38）+ 失焦自动收回 |
| 灵动岛"标为已读"同步通知中心 | ✅ | 真实链路：点击后 `read=false → true`、未读数 `1 → 0` |
| 作业发布也上岛（"新作业"胶囊 + 截止时间） | ✅ | `kind=homework` + 展开显示"截止时间：…" |
| 叫人（老师点名，分紧急/普通两级） | ✅ | `verify:e2e` 8 项（普通 HIGH / 紧急 URGENT）+ `verify:desktop`「紧急叫人上课也立即展开」「普通叫人上课只进队列、下课弹出」 |
| 成绩 / 名单表格导入（xlsx·xls·csv） | ✅ | 模板下载 + 预览映射 + 重复处理 + 行号级错误：`verify:e2e` 导入 22 项、`verify:web` 弹窗实测 |
| ClassIsland 时间配置导入（覆盖 / 合并 / 回滚） | ✅ | 合法 200、非法 400 `IMPORT_INVALID` 且原配置仍为 3 节、merge 覆盖 1 新增 1 共 4 节 |
| 安装版覆盖升级自动补迁移 | ✅ | 真实旧库升级日志：`升级安装：已应用 2 个迁移文件，跳过 34 个已存在对象`，`TimeLayout` 自动建表 |
| 学生端主体 = 班级（班级码 + 班级密码登录） | ✅ | `verify:e2e` 班级账号 19 项：登录 / 错误密码 401 / 跨班 403 / 发布 403 / 班级码重复 400 / 密码重置 / 班级码用后还原 | `n | 成绩与表格导入：老师端可用且不越权 | ✅ | 班主任预览/导入本班成绩 200、跨班 403、科任 403、名单导入与模板 403；Web 端班主任可见导入按钮并打开弹窗 |
| 班级设备代全班操作（已读 · 完成 · 成绩总览） | ✅ | 标记已读写入 6 条（全班 6 人）、教师端 `readCount=6`、`completedCount=6`、`/grades/my` 全班成绩 |
| 客户端只保留班级登录入口 | ✅ | `verify:desktop`：`login=高一(1)班 classSession=true`，导航「成绩」标题变为「本班成绩」 |
| 能成功打包 Windows EXE | ✅ | `班级小助手-0.1.0-x64-setup.exe` / `-portable.exe` / `win-unpacked/*.exe`（见下表） |
| 提供完整 README（启动、构建、打包、默认账号） | ✅ | 本文档含快速开始、命令表、API、WebSocket、RBAC、模块化、MySQL 切换、打包与常见问题 |
打包产物验证（对最终 EXE 实测，非仅开发产物）：
@@ -893,14 +907,14 @@ pnpm db:migrate && pnpm db:seed
当前实测：
| 验证 | 结果 |
| -------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **133/133** ✅ |
| `pnpm verify:web`（Web 管理端真实点击 + 权限入口隐藏 + 手机适配 + 叫人 + 成绩/时间配置导入 + PWA） | **19/19** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/开合不震动 + 个性化全参数 + 托盘与退出无残留） | **54/54** ✅ |
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |
| 验证 | 结果 |
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **133/133** ✅ |
| `pnpm verify:web`（Web 管理端真实点击 + 权限入口隐藏 + 手机适配 + 叫人 + 成绩/时间配置导入 + PWA） | **19/19** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/连续圆角/开合不震动 + 个性化全参数 + 托盘与退出无残留） | **59/59** ✅ |
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |
## 常见问题（本机环境已知坑）