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

fix(homework,island,verify): 全屏作业看板自适应 + 已安装副本覆盖升级 + 新增打包版冒烟

Browse Source 
① 全屏作业看板自适应（用户反馈：全屏模式没有自适应，卡片挤在左上角）
- 全屏看板按「可用宽 × 可用高」枚举 1..N 列，取**单卡面积最大且宽高比最接近 1.15** 的方案，
  注入 `--board-cols`（不再靠 CSS auto-fit 猜）；列数变了再量一次缩放系数，
  `transform-origin: top center` 保证整体居中、不溢出屏幕
- 两个全屏弹窗各自持有 ref（原来共用同名 ref，后挂载的会覆盖前一个，量到的是另一个弹窗）；
  列表型「单个科目全屏」补上 `transform: scale()`（该规则原先只作用于 `.board`，列表全屏从未缩放）
- 弹窗 `@opened` 后轮询等待布局就绪（最多 20×60ms）再计算；窗口 resize 时自动重算；
  另加一条全局 `.board-fullscreen .el-dialog__body` 兜底，保证内容区铺满整屏
- 实测：6 个科目 → 3 列、排版宽 1155px（视口 1187px）、可视底 678px（视口高 765px）

② 「灵动岛设置没办法生效」的真正原因：用户机器上的副本一直没被更新
- 学生端实际运行的是安装目录 `D:\class\@classhelperdesktop-client` 里的 `resources/app.asar`，
  而 `pnpm dist:win` 只更新 `release/`；只发新版 release 不动安装目录，用户看到的还是旧界面
- 已就地覆盖升级该目录，并用同一套冒烟实测**那个副本**：`packaged: true`、76/76 全绿
- README 补充「把修复交付到已安装的客户端」步骤（robocopy 覆盖 + verify:packaged 实测）

③ 新增/加固自动化验证
- `verify:desktop` 新增「作业看板全屏自适应（铺满屏幕、内容不溢出）」：进作业页 → 切看板 →
  打开全屏 → 断言排版宽铺满视口、可视底不超出屏幕；再把卡片补到 6 张触发 resize，
  要求列数自动变多（1 → 3）且仍不溢出
- 点击/命中这类异步链路由"固定 sleep 后读一次"改为**轮询等待**（曾偶发误判为"点不开"），
  失败时把渲染进程当前类名、窗口可见性、岛体矩形写进结论，便于区分真 bug 与竞态
- 新增 `pnpm verify:packaged`：对**打包后/已安装**的 EXE 跑同一套冒烟（含二次启动校验文件锁），
  避免"开发产物全绿但交付给学生的 EXE 是旧的"这类问题
- 实测：`verify:desktop` 76/76（离线复跑 68/68）；`verify:packaged` 对
  `release/win-unpacked` 与 `D:\class\@classhelperdesktop-client` 均 76/76、`packaged: true`；
  `verify:e2e` 149/149（安装实例）；`typecheck` / `lint` / `format:check` 全绿
This commit is contained in:
LoveChengke committed 2026-09-13 09:26:52 +08:00
1 parent 11008928a1
commit 0ff2dc228b
7 files changed
+466 -67
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+68 -49
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 离线缓存 | ✅ 已完成（冒烟验证 75/75） |
| 4 | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 76/76） |
| 5 | 三端联调脚本、打包命令、完整 README | ✅ 已完成（三套安装包 + 两套 UI 回归测试） |
| 6 | 测试账号与种子数据说明 | ✅ 已完成（见下文） |
| 7 | 生产化：服务端安装程序（内置 Node）、Web 端 PWA 可安装、Docker + Nginx 部署、生产加固与运维文档 | ✅ 已完成（见 [`docs/production.md`](docs/production.md)） |
@@ -173,13 +173,16 @@ pnpm verify:desktop
# 另开一个终端先启动后端：pnpm dev:server
pnpm verify:e2e # 后端 + REST + Socket.IO + RBAC + 上课时段拦截 + 紧急/普通叫人 + 单双周课表/ClassIsland 课程表导入 + 班级账号（个人学生登录停用）：149 项
pnpm verify:web # Web 管理端真实点击（含权限入口隐藏、手机适配、叫人入口 + 紧急/普通级别、多班批量发布、未交名单、课程表导入弹窗、手机端课表横向滚动）：20 项
pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中兜底/展开收起再展开/联合通知回归/胶囊类型汇总、未读红点位置、圆角四角一致、开合不震动、紧急与普通叫人、真实链路、课表时间轴、个性化与设置页链路、托盘/退出无残留）：75 项
pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中兜底/展开收起再展开/联合通知回归/胶囊类型汇总、未读红点位置、圆角四角一致、开合不震动、紧急与普通叫人、真实链路、课表时间轴、作业看板全屏自适应、个性化与设置页链路、托盘/退出无残留）：76 项
pnpm verify:packaged # 对**打包后/已安装**的客户端 EXE 跑同一套冒烟（证明 packaged=true，默认 release/win-unpacked）
```
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截、导入与失败回滚、班级账号代全班操作、老师端导入不越权、单双周课表与 ClassIsland 课程表导入、个人学生登录停用**等 149 项，
实测通知 37ms、作业 26ms、成绩 25ms 到达（要求 < 5 秒），紧急通知 409 拦截与二次确认后发布均通过；
客户端脚本验证 preload 桥接、渲染进程、IndexedDB 读写、断网回退、**灵动岛四种状态切换**与联网集成
（**班级账号登录** + 四类数据 + Socket.IO），实测 75/75 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 68/68）。
（**班级账号登录** + 四类数据 + Socket.IO），实测 76/76 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 68/68）。
`pnpm verify:packaged --exe "<客户端路径>"` 对**打包后/已安装**的 EXE 跑同一套用例（`packaged: true`），
用于确认交付给学生的那个副本真的带上了本次修复 —— 开发产物通过**不等于**用户机器上的副本通过。
## 默认账号与种子数据
@@ -208,30 +211,31 @@ 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` | 后端端到端验收（149 项，含角色权限矩阵、单双周课表与 ClassIsland 课程表导入、导入与班级账号，需服务端已启动） |
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，20 项，含权限入口隐藏、叫人紧急/普通与导入弹窗） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（75 项，含灵动岛圆角/收起常驻/命中兜底/展开收起再展开/开合不震动/已读/作业/紧急与普通叫人、课表时间轴、个性化全参数） |
| `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` | 后端端到端验收（149 项，含角色权限矩阵、单双周课表与 ClassIsland 课程表导入、导入与班级账号，需服务端已启动） |
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，20 项，含权限入口隐藏、叫人紧急/普通与导入弹窗） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（76 项，含灵动岛圆角/收起常驻/命中兜底/展开收起再展开/开合不震动/已读/作业/紧急与普通叫人、课表时间轴、作业看板全屏自适应、个性化全参数） |
| `pnpm verify:packaged` | 对打包后/已安装的客户端 EXE 跑同一套冒烟（`--exe` 指定路径，实测 `packaged: true`） |
| `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 管理端（含手机小屏适配）
@@ -334,13 +338,14 @@ pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中
看板行为细节（按用户反馈逐条落地）：
| 需求 | 实现 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 只看当天的作业 | 工具栏「只看今天」开关（默认开）：按 `createdAt` 的**本地日期**过滤，昨天的过期作业不再混进看板 |
| 作业要完整显示 | 卡片里同时渲染**标题 + 作业要求全文**（`white-space: pre-wrap`，不截断），列表模式也新增「作业要求」列 |
| 全部铺满屏幕、不用上下翻页 | 看板外层高度固定 + `overflow: hidden`，按「内容高度 / 可用高度」算缩放系数用 `transform: scale()` 整体缩到刚好放下（字号仍由滑块决定，工具栏显示当前缩放比例） |
| 当天时间显示在标题栏正中 | 全屏看板标题栏用 `#header` 插槽：标题左对齐、当天日期时间**绝对居中**显示（受「显示时间」开关控制，每分钟刷新） |
| 未交名单 | 作业列表/详情里点「未交名单」→ 勾选**没交作业**的同学 → 保存后其余同学自动标记为已完成（`PATCH /api/homeworks/:id/submissions`，`GET .../submissions` 读名单）；Web 管理端作业详情抽屉里同样可看可改 |
| 需求 | 实现 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 只看当天的作业 | 工具栏「只看今天」开关（默认开）：按 `createdAt` 的**本地日期**过滤，昨天的过期作业不再混进看板 |
| 作业要完整显示 | 卡片里同时渲染**标题 + 作业要求全文**（`white-space: pre-wrap`，不截断），列表模式也新增「作业要求」列 |
| 全部铺满屏幕、不用上下翻页 | 看板外层高度固定 + `overflow: hidden`，按「内容高度 / 可用高度」算缩放系数用 `transform: scale()` 整体缩到刚好放下（字号仍由滑块决定，工具栏显示当前缩放比例） |
| 全屏看板要自适应 | 全屏弹窗打开后按「可用宽 × 可用高」枚举 1..N 列，取**单卡面积最大且宽高比最接近 1.15** 的方案注入 `--board-cols`（`fitFullscreen()` 轮询等待弹窗挂载后再算，最多 20×60ms）；列数变了再量一次缩放系数，`transform-origin: top center` 保证整体居中不溢出；窗口 resize 时自动重算。实测 6 个科目 → 3 列、排版宽 1155px（视口 1187px）、可视底 677px（视口高 765px） |
| 当天时间显示在标题栏正中 | 全屏看板标题栏用 `#header` 插槽：标题左对齐、当天日期时间**绝对居中**显示（受「显示时间」开关控制，每分钟刷新） |
| 未交名单 | 作业列表/详情里点「未交名单」→ 勾选**没交作业**的同学 → 保存后其余同学自动标记为已完成（`PATCH /api/homeworks/:id/submissions`，`GET .../submissions` 读名单）；Web 管理端作业详情抽屉里同样可看可改 |
**学生端主体 = 班级（个人学生账号不再允许登录）**：`POST /api/auth/login` 对 `role=STUDENT`
一律返回 **403**（提示改用「班级码 + 班级密码」）；学生用户行仍保留，作为作业完成 / 通知已读 / 成绩
@@ -615,7 +620,7 @@ pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS
| **退出后无残留（文件锁 + 二次启动）** | ✅ 配置目录可删除（句柄已释放）→ 用同一配置目录二次启动成功并再次全绿 |
该验证对**开发产物与打包后的 EXE 都适用**（打包后用 `ELECTRON_SMOKE_RESULT=<file>` 写出 JSON 结果，
已实测 `packaged: true`、75/75 通过、退出码 0）。灵动岛各状态的窗口截图会写到
已实测 `packaged: true`、76/76 通过、退出码 0）。灵动岛各状态的窗口截图会写到
`ISLAND_SHOTS_DIR`（默认 `.cache/island-shots/`，仓库内留档目录 `docs/screenshots/island/`），
并对尺寸、宽高比、绘制内容（不透明像素/颜色种类）、紧急态红色像素与外溢红光做断言。
冒烟进程使用独立 userData（`ELECTRON_SMOKE_PROFILE`），因此**用户开着客户端也能跑验证**。
@@ -1011,23 +1016,37 @@ pnpm db:migrate && pnpm db:seed
打包产物验证（对最终 EXE 实测，非仅开发产物）：
| 产物 | 大小 | 冒烟结果 |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| 服务端安装程序（内置 Node + Web 端） | 34MB | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 → **对安装实例跑 62/62 e2e + 15/15 UI** |
| `release/win-unpacked/班级小助手.exe` | 234.7MB | ✅ **28/28**，`packaged: true`，退出码 0（含灵动岛动画/作业/叫人/时间轴） |
| `release/…-x64-portable.exe`（单文件） | 106.9MB | ✅ 打包后冒烟 **28/28**，`packaged: true`，退出码 0（自解压单文件同样通过） |
| `release/…-x64-setup.exe`（客户端） | 107.2MB | ✅ 构建成功，已嵌入自定义图标；含灵动岛与本次行为修正 |
| 产物 | 大小 | 冒烟结果 |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| 服务端安装程序（内置 Node + Web 端） | 34MB | ✅ 静默安装（升级保留 `.env` 与数据库）→ 自动建库建号 → 服务就绪 → **对安装实例跑 149/149 e2e + 20/20 UI** |
| `release/win-unpacked/班级小助手.exe` | 234.7MB | ✅ 打包版冒烟 **76/76**（离线复跑 68/68），`packaged: true`，退出码 0（含灵动岛动画/作业看板全屏自适应/叫人/时间轴） |
| `release/…-x64-portable.exe`（单文件） | 107.1MB | ✅ 打包后冒烟 **76/76**，`packaged: true`，退出码 0（自解压单文件同样通过） |
| `release/…-x64-setup.exe`（客户端） | 107.4MB | ✅ 构建成功，已嵌入自定义图标；含灵动岛与本次行为修正 |
> **把修复交付到"已安装的客户端"**：给学生的 EXE 安装在 `D:\class\@classhelperdesktop-client`（桌面/开始菜单快捷方式指向它），
> 而 `pnpm dist:win` 只产出 `packages/desktop-client/release/`。只更新 release 而不同步安装目录，
> 用户打开的还是旧 `resources/app.asar`，就会出现"改了但设置/界面还是不生效"。
> 覆盖升级（用户配置在 `%APPDATA%`，不受影响）：
>
> ```powershell
> # 1) 先退出客户端（如有进程在跑，用任务管理器/PID 精确结束）
> # 2) 用新产物覆盖安装目录（不删 Uninstall 等安装器文件，所以不加 /MIR）
> robocopy "packages\desktop-client\release\win-unpacked" "D:\class\@classhelperdesktop-client" /E /NFL /NDL /NJH /NJS /R:2 /W:1
> # 3) 实测**那个副本**真的带上了修复（packaged=true）
> pnpm verify:packaged --exe "D:\class\@classhelperdesktop-client\班级小助手.exe"
> ```
当前实测：
| 验证 | 结果 |
| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **133/133** ✅ |
| `pnpm verify:web`（Web 管理端真实点击 + 权限入口隐藏 + 手机适配 + 叫人 + 成绩/时间配置导入 + PWA） | **19/19** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/连续圆角/收起常驻 + 命中兜底与"展开收起再展开" + 个性化全参数 + 托盘与退出无残留） | **75/75** ✅ |
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |
| 验证 | 结果 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **149/149** ✅ |
| `pnpm verify:web`（Web 管理端真实点击 + 权限入口隐藏 + 手机适配 + 叫人 + 成绩/时间配置导入 + PWA） | **20/20** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/连续圆角/收起常驻 + 命中兜底与"展开收起再展开" + 作业看板全屏自适应 + 个性化全参数 + 托盘与退出无残留） | **76/76** ✅（离线复跑 68/68） |
| `pnpm verify:packaged`（对 `release/win-unpacked` 与 `D:\class\@classhelperdesktop-client` 实测） | **76/76**，`packaged: true` ✅ |
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |
## 常见问题（本机环境已知坑）