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

fix(island,homework,schedule,web): 16 项反馈修复（联合通知点不开 / 设置不生效 / 红点位置 / 看板当天且铺满 / 单双周与周数可调 / Web 手机端与批量通知等）

Browse Source 
一、灵动岛
- ①「紧急通知后来了新作业，收起再点开不了新作业」根因有二，都已修：
  (a) active 仍是紧急那条，点击只会反复打开它 —— 现在点击胶囊优先打开**最新**那条未处理消息（队列里更晚的）；
  (b) 上课时段 syncWindow 会把普通通知立刻隐藏（表现为点了没反应）—— 新增 explicitShowId，
      "用户主动点开"的那条守卫放行（岛完全隐藏时仍严格不打扰）。
  冒烟新增「紧急通知后来了新作业：收起再点击打开的是新作业（联合通知回归）」。
- ② 设置实时预览/保存：补「设置页真实链路」断言（window.desktop.islandSetAppearance → IPC → 主进程 →
  渲染进程 CSS 变量 + 窗口尺寸），并断言"岛显示中改尺寸立即生效"（实测均通过）。
- ③ 未读红点移到「通知」图标右上角（此前在文字后面），并加 DOM 几何断言（dx>0 且 dy<0，
  没有未读时自动造一条未读通知再断言、断言后删除）。
- 冒烟稳定性：新增 island.setBlurCollapseEnabled()（默认开），测试期间关掉"失焦收起"，
  避免系统抢焦点导致展开态被收回的随机失败；专门验证失焦的用例仍临时打开。

二、作业看板（学生端）
- ⑥ 只看当天：新增「只看今天」开关（默认开），按 createdAt 的本地日期过滤，昨天的过期作业不再混入。
- ⑧ 完整显示：卡片同时渲染标题 + 作业要求全文（列表模式也加「作业要求」列）。
- ⑨ 铺满不滚动：看板外层高度固定 + overflow hidden，按内容/可用高度算缩放系数用 transform: scale 适配
  （工具栏显示当前缩放比例），页面本身不出现滚动条。
- ⑦ 全屏看板标题栏用 #header 插槽：标题左对齐、当天日期时间绝对居中（受「显示时间」开关控制，每分钟刷新）。

三、课表与周数
- ⑤ 学期周数可调：新增 Class.termWeeks（默认 20，迁移 + 维护脚本），班主任在班级管理里改；
  GET /api/dashboard/term?classId= 返回该班 maxWeek，课表周次下拉与新建课表的默认 weekEnd 都按它来
  （不再固定 30 周）。
- ⑩ 课表管理只保留「导入 ClassIsland 课程表」入口（时间表由课程表 JSON 的 TimeLayouts 一并带入），
  「导入时间配置」按钮下线；ui-smoke 第 7.7 段改为断言新弹窗（解析 4 行 + 单双周标签 + 旧入口已下线）。

四、以班级为单位（⑬）与 Web 端
- 个人学生账号登录停用：POST /api/auth/login 对 role=STUDENT 返回 403（改用班级码 + 班级密码）；
  学生行仍作为个人数据记录键由班级会话代全班读写；e2e 全面切换到班级会话并新增该断言。
- ④ 作业科目过少：新增共享 SUBJECT_CATALOG（16 个常见科目）+ 种子课程扩到全科目；
  Web 作业发布弹窗可选「其他科目（新建）」，提交前自动建课（同名复用）。
- ⑪ 通知支持多班批量发布（多选 + 逐班发布 + 汇总结果 + 二次确认覆盖所有选中班）；
  ⑫ 单班只显示已读情况、跨班才显示已读率；⑭ 手机端课表可横向滚动看全 7 天；
  ⑮ 手机端已连接不再显示孤立绿点（仅未连接时显示文字标签）；⑯ 手机端「叫人/发布通知」按钮同宽左对齐；
  ⑬ Web 学生管理去掉「用户名」列（新建自动生成学号式用户名，导入仍支持显式指定）。

验证：verify:e2e 149/149、verify:web 20/20、verify:desktop 75/75（复跑 68/68，打包便携版 75/75 packaged=true）、
typecheck / lint / format 全绿；服务端与 Web 已重新打包并部署到本机安装目录。
This commit is contained in:
LoveChengke committed 2026-09-13 08:39:11 +08:00
1 parent b8ef5d8dbb
commit 11008928a1
34 files changed
+1421 -340
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+48 -18
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 离线缓存 | ✅ 已完成（冒烟验证 71/71） |
| 4 | EXE 客户端：Electron 主进程/preload/渲染进程、登录、课表/作业/通知/成绩/设置、实时推送、IndexedDB 离线缓存 | ✅ 已完成（冒烟验证 75/75） |
| 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 # 后端端到端验收脚本（148 项）
│ ├── scripts/verify-e2e.mjs # 后端端到端验收脚本（149 项）
│ └── 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 + 上课时段拦截 + 紧急/普通叫人 + 单双周课表/ClassIsland 课程表导入 + 导入 + 班级账号：148 项
pnpm verify:web # Web 管理端真实点击（含权限入口隐藏、手机适配、叫人入口 + 紧急/普通级别、紧急通知 + 成绩/时间配置导入弹窗）：20 项
pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中兜底/展开收起再展开/胶囊类型汇总、圆角四角一致、开合不震动、紧急与普通叫人、真实链路、课表时间轴、个性化 10 项参数与托盘/退出无残留）：71 项
pnpm verify:e2e # 后端 + REST + Socket.IO + RBAC + 上课时段拦截 + 紧急/普通叫人 + 单双周课表/ClassIsland 课程表导入 + 班级账号（个人学生登录停用）：149 项
pnpm verify:web # Web 管理端真实点击（含权限入口隐藏、手机适配、叫人入口 + 紧急/普通级别、多班批量发布、未交名单、课程表导入弹窗、手机端课表横向滚动）：20 项
pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中兜底/展开收起再展开/联合通知回归/胶囊类型汇总、未读红点位置、圆角四角一致、开合不震动、紧急与普通叫人、真实链路、课表时间轴、个性化与设置页链路、托盘/退出无残留）：75 项
```
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截、导入与失败回滚、班级账号代全班操作、老师端导入不越权、单双周课表与 ClassIsland 课程表导入**等 148 项，
后端脚本验证**实时推送时延、作业完成、成绩下发、权限隔离、上课时段紧急通知拦截、导入与失败回滚、班级账号代全班操作、老师端导入不越权、单双周课表与 ClassIsland 课程表导入、个人学生登录停用**等 149 项，
实测通知 37ms、作业 26ms、成绩 25ms 到达（要求 < 5 秒），紧急通知 409 拦截与二次确认后发布均通过；
客户端脚本验证 preload 桥接、渲染进程、IndexedDB 读写、断网回退、**灵动岛四种状态切换**与联网集成
（**班级账号登录** + 四类数据 + Socket.IO），实测 71/71 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 65/65）。
（**班级账号登录** + 四类数据 + Socket.IO），实测 75/75 通过；退出后再启动一次校验单实例锁与文件锁已释放（离线复跑 68/68）。
## 默认账号与种子数据
@@ -220,9 +220,9 @@ pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中
| `pnpm dist:dir` | 打包客户端免安装目录 `release/win-unpacked`（含可执行文件，最快） |
| `pnpm dist:win` | 打包客户端 nsis 安装包 + portable 单文件 EXE |
| `pnpm dist:all` | 服务端安装程序 + 客户端安装程序一起打 |
| `pnpm verify:e2e` | 后端端到端验收（148 项，含角色权限矩阵、单双周课表与 ClassIsland 课程表导入、导入与班级账号，需服务端已启动） |
| `pnpm verify:e2e` | 后端端到端验收（149 项，含角色权限矩阵、单双周课表与 ClassIsland 课程表导入、导入与班级账号，需服务端已启动） |
| `pnpm verify:web` | Web 管理端 UI 真实点击测试（Electron 驱动，20 项，含权限入口隐藏、叫人紧急/普通与导入弹窗） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（71 项，含灵动岛圆角/收起常驻/命中兜底/展开收起再展开/开合不震动/已读/作业/紧急与普通叫人、课表时间轴、个性化全参数） |
| `pnpm verify:desktop` | EXE 客户端冒烟验证（75 项，含灵动岛圆角/收起常驻/命中兜底/展开收起再展开/开合不震动/已读/作业/紧急与普通叫人、课表时间轴、个性化全参数） |
| `pnpm typecheck` | 全仓库类型检查（含 `vue-tsc`） |
| `pnpm lint` / `pnpm lint:fix` | ESLint 检查 / 自动修复 |
| `pnpm format` / `pnpm format:check` | Prettier 格式化 / 检查 |
@@ -332,10 +332,19 @@ pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中
工具栏可切「看板 / 列表」、开关「显示时间」、拖「字号」（11–28px 即时生效），
点卡片或「全屏看板」进入全屏放大视图；这些偏好写入客户端配置（`homeworkBoard`），重启后仍生效。
**未交名单（班级设备）**：作业列表/详情里点「未交名单」→ 勾选**没交作业**的同学 →
保存后其余同学自动标记为已完成（`PATCH /api/homeworks/:id/submissions`，
`GET .../submissions` 读名单）。教师端 Web 管理端的作业详情抽屉里也能看到未交名单并勾选保存，
普通学生调用该接口返回 403（只能标记自己）。
看板行为细节（按用户反馈逐条落地）：
| 需求 | 实现 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 只看当天的作业 | 工具栏「只看今天」开关（默认开）：按 `createdAt` 的**本地日期**过滤，昨天的过期作业不再混进看板 |
| 作业要完整显示 | 卡片里同时渲染**标题 + 作业要求全文**（`white-space: pre-wrap`，不截断），列表模式也新增「作业要求」列 |
| 全部铺满屏幕、不用上下翻页 | 看板外层高度固定 + `overflow: hidden`，按「内容高度 / 可用高度」算缩放系数用 `transform: scale()` 整体缩到刚好放下（字号仍由滑块决定，工具栏显示当前缩放比例） |
| 当天时间显示在标题栏正中 | 全屏看板标题栏用 `#header` 插槽：标题左对齐、当天日期时间**绝对居中**显示（受「显示时间」开关控制，每分钟刷新） |
| 未交名单 | 作业列表/详情里点「未交名单」→ 勾选**没交作业**的同学 → 保存后其余同学自动标记为已完成（`PATCH /api/homeworks/:id/submissions`，`GET .../submissions` 读名单）；Web 管理端作业详情抽屉里同样可看可改 |
**学生端主体 = 班级（个人学生账号不再允许登录）**：`POST /api/auth/login` 对 `role=STUDENT`
一律返回 **403**（提示改用「班级码 + 班级密码」）；学生用户行仍保留，作为作业完成 / 通知已读 / 成绩
等个人数据的记录键，由班级会话代全班读写。Web 端学生管理列表也不再展示「用户名」列。
> 通知到达时还会由**灵动岛**在桌面中上方浮出提醒（见上一节），上课时段自动隐藏、紧急通知立即展开。
@@ -343,6 +352,19 @@ pnpm verify:desktop # Electron 客户端（含灵动岛收起常驻/命中
客户端有一个独立于主窗口的**灵动岛**：一个无边框、透明、置顶、不占任务栏的窄条窗口。它是"消息到达"的第一现场。
> **联合通知（紧急 + 作业）为什么以前"点不开新作业"**：上课时段里紧急通知会自动展开，
> 学生收起后再来一条作业时 `active` 仍是紧急那条 —— 点击只会反复打开它；而且就算把 active
> 换成新作业，`syncWindow` 的上课时段守卫又会立刻把普通通知隐藏（表现为"点了没反应"）。
> 现在两处都修了：①点击胶囊优先打开**最新**那条未处理消息（队列里更晚的那条）；
> ②上课时段里"用户主动点开"的那条会记入 `explicitShowId`，守卫对它放行（岛完全隐藏时仍严格不打扰）。
> 冒烟里对应断言「紧急通知后来了新作业：收起再点击打开的是新作业（联合通知回归）」。
>
> **设置页实时生效链路有专项断言**：`window.desktop.islandSetAppearance` → IPC → 主进程 →
> 广播给灵动岛渲染进程（CSS 变量 + 窗口尺寸），岛显示中改尺寸同样立即生效。
>
> **未读红点位置**：客户端侧边栏的未读红点挂在「通知」图标的**右上方**（此前挂在文字后面，位置不对），
> 冒烟用 DOM 几何断言（`dx > 0 且 dy < 0`）守住。
> **视觉与排版参考 [WinIsland](https://github.com/WinIslandProject/WinIsland)（Rust/Direct2D 的 Windows 动态岛）重写**：
> 连续圆角（超椭圆 squircle）而不是 `border-radius`、纯黑／亚克力毛玻璃／主题色三种底、
> Apple 系统色强调色、白字 alpha 分级、**所有文本 = 基础字号 × 排版系数**、
@@ -593,7 +615,7 @@ pnpm dist:win # nsis 安装包 + portable 单文件（需联网下载 NSIS
| **退出后无残留（文件锁 + 二次启动）** | ✅ 配置目录可删除（句柄已释放）→ 用同一配置目录二次启动成功并再次全绿 |
该验证对**开发产物与打包后的 EXE 都适用**（打包后用 `ELECTRON_SMOKE_RESULT=<file>` 写出 JSON 结果，
已实测 `packaged: true`、71/71 通过、退出码 0）。灵动岛各状态的窗口截图会写到
已实测 `packaged: true`、75/75 通过、退出码 0）。灵动岛各状态的窗口截图会写到
`ISLAND_SHOTS_DIR`（默认 `.cache/island-shots/`，仓库内留档目录 `docs/screenshots/island/`），
并对尺寸、宽高比、绘制内容（不透明像素/颜色种类）、紧急态红色像素与外溢红光做断言。
冒烟进程使用独立 userData（`ELECTRON_SMOKE_PROFILE`），因此**用户开着客户端也能跑验证**。
@@ -771,9 +793,17 @@ POST /api/notifications { …, priority: "NORMAL" }（上课时段）
`第 1 周 = 单周` 的规则过滤（`weekParityOf(week)`，与 ClassIsland 默认相位一致），
历史数据默认 `ALL`，行为不变。手动添加课表时也能在弹窗里直接选「每周 / 单周 / 双周」。
> 手工覆盖 dist 部署（而非跑安装程序）时，已有数据库需要补一列：
> `node packages/server/scripts/apply-parity-column.cjs "<安装目录>/server/dist/lib/db.js"`
> （安装程序覆盖升级会自动补迁移；仅空库首次启动会执行随包迁移 SQL）。
> **学期周数（班主任可调）**：`Class.termWeeks`（默认 20）由班主任在「班级管理 → 编辑班级」里设置，
> `GET /api/dashboard/term?classId=` 返回该班的 `maxWeek`，课表周次下拉与新建课表的默认结束周都按它来
> （此前固定给到 30 周，与实际 20 周不符且无法调整）。
>
> **课表页入口只保留一个**：「导入 ClassIsland 课程表」——同一份档案 JSON 里的 `TimeLayouts`
> 已经把节次时间带进来了，因此「导入时间配置」按钮已下线（组件与接口仍保留，供旧脚本调用）。
> 手工覆盖 dist 部署（而非跑安装程序）时，已有数据库需要补列：
> `node packages/server/scripts/apply-column-migrations.cjs "<安装目录>/server/dist/lib/db.js"`
> （会幂等补齐 `Schedule.weekParity` 与 `Class.termWeeks`；安装程序覆盖升级会自动补迁移，
> 仅空库首次启动会执行随包迁移 SQL）。
## REST API 一览
@@ -994,7 +1024,7 @@ pnpm db:migrate && pnpm db:seed
| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `pnpm verify:e2e`（开发环境与**安装后的生产实例**各跑一次） | **133/133** ✅ |
| `pnpm verify:web`（Web 管理端真实点击 + 权限入口隐藏 + 手机适配 + 叫人 + 成绩/时间配置导入 + PWA） | **19/19** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/连续圆角/收起常驻 + 命中兜底与"展开收起再展开" + 个性化全参数 + 托盘与退出无残留） | **71/71** ✅ |
| `pnpm verify:desktop`（客户端冒烟 + WinIsland 架构/连续圆角/收起常驻 + 命中兜底与"展开收起再展开" + 个性化全参数 + 托盘与退出无残留） | **75/75** ✅ |
| `pnpm typecheck` / `pnpm lint` / `pnpm format:check` | 全部通过 ✅ |
| 安装程序完整生命周期（静默安装 → 启停脚本 → 卸载） | 通过 ✅ |
| Docker / Nginx 部署样例 | 文件已提供，本机无 Docker 未实测 ⚠️ |