19 Commits
Author SHA1 Message Date
LoveChengke 0b35a58f07 feat: 统一两端界面并扩展受权限约束的AI助手 2026-11-07 16:27:38 +08:00
LoveChengke 79a31ebe9d chore(release): 升级至1.4.3并记录本地验收结果 2026-11-07 02:02:26 +08:00
LoveChengke 8bd5bcb9ff docs(audit): 同步安全边界并整理全仓审计入口 2026-11-07 02:02:22 +08:00
LoveChengke 3a7aed0800 chore(test): 完善审计门禁和后台验收诊断 2026-11-07 02:02:18 +08:00
LoveChengke 3d7e551838 fix(pwa): 保护离线外壳并限制缓存清理范围 2026-11-07 02:02:15 +08:00
LoveChengke ff55c95ea0 perf(web): 按实际使用注册界面组件以缩小入口包 2026-11-07 02:02:13 +08:00
LoveChengke 81c96eebaf perf(server): 复用默认组初始化与批量关系查询 2026-11-07 02:02:11 +08:00
LoveChengke a0a6b50485 fix(notifications): 并发已读冲突后重读补齐记录 2026-11-07 02:02:08 +08:00
LoveChengke f60114af85 fix(database): 快照恢复失败时回滚并保留原库 2026-11-07 02:02:06 +08:00
LoveChengke ff33d163e3 fix(grades): 批量成绩校验与写入使用同一事务 2026-11-07 02:02:03 +08:00
LoveChengke e49dd0bc39 fix(authz): 禁止教师通过新建课程自授任课关系 2026-11-07 02:02:01 +08:00
LoveChengke 71cc8eb605 fix(update): 修复云端安装交接并完善发布验收
修复隐藏缓存目录下载和响应收尾,使用原生助手校验安装包并确认交接。
补齐真实静默升级、便携版及中文路径验收,并按现行设备和科目授权契约更新回归。
服务端安装时生成独立密钥,覆盖升级保留既有配置;补齐安装包副本验证说明。
2026-10-31 17:07:17 +08:00
LoveChengke 66be3a63b1 feat(authz): 重写权限模板分配与班级授权边界
拆分能力、分配范围和业务关系,固定管理员能力并收紧组织级写入口。
补齐内容、课表、设备会话和实时通道授权,兼容旧库分配及历史快照。
重写权限分配预览,按实际可操作范围展示维护入口,合并学生入口并独立学年升级页。
增加授权攻击矩阵及静态门禁,更新隔离回归与开发契约。

验证:授权矩阵 23 段通过,Node 24 下 Web 63/63,类型检查、lint 与文档严格构建通过。
2026-10-31 09:40:23 +08:00
LoveChengke 682818dd4a feat: 重做灵动岛编辑器与课表档案时间表编辑
灵动岛
- 重构自定义方案编辑器:组件库常驻、拖拽添加与排序、方案切换/新建/复制/删除、编辑模式预览与缩放,容器在编辑时展开全部子组件。
- 新增天气简报组件:主进程固定请求 Open-Meteo,只接受数值经纬度,失败退避并保留本次运行缓存;冒烟模式不访问外网。
- 倒计时支持目标名称与日期;课程表组件新增「今日时间点」,按时间点类型折叠/展开,课中不再常驻倒计时。
- preload 暴露 getIslandWeather 与时间点订阅,契约同步 desktop.d.ts。

课表档案
- 时间点默认课程:布局返回 defaultCourse,日课表没有条目时回退;新增 apply-default 覆盖所有引用课表;全校时间表不携带默认课程。
- 新增 ClassIsland 式时间表编辑器(列表/时间轴视图、拖动把柄、按类型添加、默认时长与缩放)与「课表信息」表单。
- 课表页默认进入单表编辑,底部保留列表/周/月视图;时间表支持新路由删除。
- 「课间」统一改称「课间休息」。

验证
- pnpm typecheck、pnpm lint 通过。
- verify:e2e 隔离验收 248/248 项通过(含默认课程回退、覆盖写入与时间表删除)。
- ui-smoke 覆盖单表编辑、课表信息与时间轴视图,并更新回归截图。
2026-10-25 16:41:29 +08:00
Love_Chengke 938285bb9c fix: 修复课表回归截图文件 2026-10-25 08:59:59 +08:00
Love_Chengke d63100e0e1 fix: 修正 UI 回归脚本文件编码 2026-10-25 08:57:59 +08:00
Love_Chengke e43c3a93d8 feat(web-admin): 整合课表档案页面 2026-10-24 15:43:32 +08:00
LoveChengke 24e8dd902b feat: 完善学生生命周期管理与权限范围并发布 1.4.2 2026-10-23 22:55:21 +08:00
LoveChengke 6347d1e5aa feat: 完善课表档案、课件归档、提醒与客户端更新并发布 1.4.1
- 重写课表档案工作区并合并时间表、课表与完整档案导入导出
- 修复课前/上下课提醒遮罩与通知收回冲突
- 增加课件文件夹分类、教师归档路径和客户端本机归档
- 打通客户端下载/安装/完成状态上报并在管理端展示更新过程
- 修复侧栏折叠裁切、课时多选与上传控件样式
- 统一版本到 1.4.1
2026-10-18 17:39:54 +08:00
312 changed files with 25950 additions and 6977 deletions

No files matched your search

+19 -10
View File
@@ -11,10 +11,13 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
| 目录 | 用途 | | 目录 | 用途 |
| -------------------------- | --------------------------------------------------------- | | -------------------------- | --------------------------------------------------------- |
| `packages/ui/src/` | Web 与桌面端共享 Vue 控件、主题、日期选择器与全屏引导 |
| `packages/shared/src/` | 三端共享类型、权限、常量、动效、岛方案与课件契约 | | `packages/shared/src/` | 三端共享类型、权限、常量、动效、岛方案与课件契约 |
| `packages/server/` | Express、Prisma、Socket.IO;API 前缀 `/api` | | `packages/server/` | Express、Prisma、Socket.IO;API 前缀 `/api` |
| `packages/web-admin/` | Vue Web 管理端,PWA | | `packages/web-admin/` | Vue Web 管理端,PWA |
| `packages/desktop-client/` | Electron 主进程、preload、主窗口与独立灵动岛渲染进程 | | `packages/desktop-client/` | Electron 主进程、preload、主窗口与独立灵动岛渲染进程 |
| `packages/data/` | 运行期课件、安装包等数据;不是 workspace 包,不作源码清理 |
| `prompts/` | 可执行任务提示词;历史 `*.result.md` 仅为当时交付记录 |
| `scripts/` | 版本、构建、验证、打包、图标与 Pages 脚本 | | `scripts/` | 版本、构建、验证、打包、图标与 Pages 脚本 |
| `deploy/` | Windows/Linux/Docker 部署与运维模板 | | `deploy/` | Windows/Linux/Docker 部署与运维模板 |
| `docs/` | docfx 文档;`images/` 为展示图,`screenshots/` 为回归截图 | | `docs/` | docfx 文档;`images/` 为展示图,`screenshots/` 为回归截图 |
@@ -28,15 +31,17 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
- 模块由 `packages/server/src/modules/registry.ts` 注册;新增或下线功能改注册表,不另改 `app.ts` 挂载。 - 模块由 `packages/server/src/modules/registry.ts` 注册;新增或下线功能改注册表,不另改 `app.ts` 挂载。
- 路由用 `middleware/validate.ts` 与 zod;响应复用 `lib/http.ts`,错误交给统一中间件。 - 路由用 `middleware/validate.ts` 与 zod;响应复用 `lib/http.ts`,错误交给统一中间件。
- 学生是 `Student` 名单记录,没有账号、角色或密码。教师/管理员存 `User`;班级登录读取 `Class.code/passwordHash`,会话角色 `CLASS_DEVICE`,主体 id 为班级 id。 - 学生是 `Student` 名单记录,没有账号、角色或密码。教师/管理员存 `User`;班级登录读取 `Class.code/passwordHash`,会话角色 `CLASS_DEVICE`,主体 id 为班级 id。
- 任课关系只在 `Course(classId, name, teacherId)`。班主任不自动获得别的科目的作业、成绩写权限,统一走 `assertCanManageSubjectContent`。班级端可录作业,不可写成绩;员工还须对应功能权限。 - 任课关系只在 `Course(classId, name, teacherId)`。班主任不自动获得别的科目的作业、成绩写权限,统一走 `lib/authz/assert.ts` 的 `assertContentWrite`。班级端可录作业,不可写成绩;员工还须对应功能权限。
- 功能权限取 `lib/permissions.ts` 的 `loadEffectivePermissions()`:已分组取并集;未分组使用数据库对应角色的可编辑默认组;管理员永远保留 `permission:manage/system:manage`;班级端为空集。 - 新建课程会建立任课关系,仅管理员可执行;课表维护范围不能用来给自己任课。现有课程的排课与外观维护仍按 `schedule:write` 和班级管理关系校验。
- 岗位组不新增 `User.role`。班主任/教师/级长/部长仍为 TEACHER;范围在 `PermissionGroup.scope/scopeValue`,由 `lib/permission-scope.ts` 收口,空年级/部范围拒绝。设备写权限只合并含对应键的分组范围,范围不替代科目授权。 - 功能、范围、关系统一由 `lib/authz/` 判定,所有服务显式传权限键。ADMIN 固定全部能力;TEACHER 永久忽略管理员专用键;CLASS_DEVICE 为空集,接口明确允许并校验本班。权限管理仅 ADMIN。
- 岗位模板只管能力与建议范围,生效范围存 `UserPermissionGroup.scope/scopeValue`,使用 TEACHING/HEAD/GRADE/DIVISION/ALL。无显式分配的教师使用默认模板与固定 TEACHING;空或未知年级拒绝。按键独立合并范围,无键查询为空集;班级账号/学期设置永远要求本班班主任,科目写检查原/目标科目。具体断言和迁移见 `docs/dev/permissions.md`。
- 只有一份 `prisma/schema.prisma`,切库改 provider;保持 SQLite/MySQL 通用,不加 Prisma enum 或 `@db.*`。模型变动同步迁移、`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 与旧库兼容逻辑。 - 只有一份 `prisma/schema.prisma`,切库改 provider;保持 SQLite/MySQL 通用,不加 Prisma enum 或 `@db.*`。模型变动同步迁移、`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 与旧库兼容逻辑。
- `deleteTeacher` 必须保护班主任、课程任课、发布的作业/通知和所属课件,避免级联删除业务内容。 - `deleteTeacher` 必须保护班主任、课程任课、发布的作业/通知和所属课件,避免级联删除业务内容。
- 作业和通知按本地 `assignDate` 归类,使用 `dayKeyLocal/isDayKey/shiftDayKey`,不用 UTC 日期切片。 - 作业和通知按本地 `assignDate` 归类,使用 `dayKeyLocal/isDayKey/shiftDayKey`,不用 UTC 日期切片。
- 批量通知/作业逐班返回结果;跨班作业按科目名匹配既有课程,找不到则该班失败,不自动把发布者设为任课老师。 - 批量通知/作业逐班返回结果;跨班作业按科目名匹配既有课程,找不到则该班失败,不自动把发布者设为任课老师。
- 两个登录接口共用登录限流。附件链接校验 scheme;表格文件上限 8 MB、JSON 请求体 12 MB,超限映射 413。 - 两个登录接口共用登录限流。附件链接校验 scheme;表格文件上限 8 MB、JSON 请求体 12 MB,超限映射 413。
- AI 助手只解析待确认动作,前端确认后调既有发布接口;参数重新校验,Key 加密存储且不回传。自动化用 mock,不访问外网。 - AI 查询和模型上下文按原业务权限读取;写操作由动作目录生成计划,用户确认后调用既有业务接口,入口绑定操作者、参数和步骤并持久去重。数据库维护、服务器运维与密钥操作不注册为 AI 动作。密码经专用表单提交,计划参数加密保存;自动化用 mock,不访问外网。
- AI 可管理客户端安装包缓存:写入仅 ADMIN + `client:update`,要求专门确认,固定复用 `/update/client/fetch` 和 `/update/client/releases`。预览和执行核对版本、文件及已有登记;不开放服务器更新或任意下载地址,不自动推送或运行安装器。
## 3. 课表、周次、成绩与学年 ## 3. 课表、周次、成绩与学年
@@ -44,7 +49,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
- `/api/schedules/*` 是新模型兼容门面。启用解析统一走 `lib/class-plan.ts`,在线客户端不得另写启用优先级。 - `/api/schedules/*` 是新模型兼容门面。启用解析统一走 `lib/class-plan.ts`,在线客户端不得另写启用优先级。
- 时间点有上课、课间、分割线、行动四种;课程显式引用时间点外键。排序不能靠数组下标代替关联。 - 时间点有上课、课间、分割线、行动四种;课程显式引用时间点外键。排序不能靠数组下标代替关联。
- 支持 1–9 周轮换、群组、预定及临时层;完整档案导入走 `profile-import.service.ts`,不经过单双周有损格式。 - 支持 1–9 周轮换、群组、预定及临时层;完整档案导入走 `profile-import.service.ts`,不经过单双周有损格式。
- 全校时间表写入用 `timetable:manage`;班级日课表写入还须班主任/管理员断言。离线整套课表导入可建立班级自有作息,不把 JSON 的 TeacherName 当授权。 - 全校时间表写入仅管理员;班级时间表按存储 classId 校验 `schedule:write` 与班主任关系,引用班级也校验。日课表/名单在 TEACHING/HEAD 范围要求班主任,显式年级/部/全校分配可在范围内维护。离线整套课表导入可建立班级自有作息,不把 JSON 的 TeacherName 当授权。
- 周次统一 `loadTermContext/resolveCurrentWeek`:班级逐周区间优先于全校区间,缺省再线性推算。开学日会参考班级设置、第 1 周区间、全校设置与环境兜底,详见 `lib/term.ts`。 - 周次统一 `loadTermContext/resolveCurrentWeek`:班级逐周区间优先于全校区间,缺省再线性推算。开学日会参考班级设置、第 1 周区间、全校设置与环境兜底,详见 `lib/term.ts`。
- 全校周数上限存 `term.maxWeeks`,默认 30、范围 1–60;服务端 `getMaxTermWeeks()`,shared 做归一化与离线兜底。班级周数不超全校上限。 - 全校周数上限存 `term.maxWeeks`,默认 30、范围 1–60;服务端 `getMaxTermWeeks()`,shared 做归一化与离线兜底。班级周数不超全校上限。
- 关闭个人成绩查询后,班级端仍可看服务端集体聚合;个人明细、原始全班成绩和排名拒绝读取。稀疏样本及补集抑制,不下发原始成绩后在客户端聚合。 - 关闭个人成绩查询后,班级端仍可看服务端集体聚合;个人明细、原始全班成绩和排名拒绝读取。稀疏样本及补集抑制,不下发原始成绩后在客户端聚合。
@@ -57,9 +62,9 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
- preload 仅暴露 contextBridge 白名单,不暴露 ipcRenderer;跨桥接传纯数据,不传 Vue Proxy。契约写在 `src/types/desktop.d.ts`。 - preload 仅暴露 contextBridge 白名单,不暴露 ipcRenderer;跨桥接传纯数据,不传 Vue Proxy。契约写在 `src/types/desktop.d.ts`。
- 保留 CSP、导航同源校验与弹窗限制。安装包不能含凭据,保留 `check-bundle-secrets` 构建门禁。 - 保留 CSP、导航同源校验与弹窗限制。安装包不能含凭据,保留 `check-bundle-secrets` 构建门禁。
- 离线缓存按服务端与班级隔离,缓存故障不应阻断在线读取。退出、切服务器时清理会话状态,设备 `deviceKey` 保持不变,渲染层不能改写它。 - 离线缓存按服务端与班级隔离,缓存故障不应阻断在线读取。退出、切服务器时清理会话状态,设备 `deviceKey` 保持不变,渲染层不能改写它。
- 设备维护只走 `/api/clients/*`,管理页 `ClientsView.vue`。心跳约 30 秒,90 秒窗口判在线;未登录不报,401/403 退避,切配置重置计时并隔离迟到响应。 - 设备维护只走 `/api/clients/*`,管理页 `ClientsView.vue`;心跳、进度、回执仅接受本班 CLASS_DEVICE,deviceKey 不可跨班迁移。心跳约 30 秒,90 秒窗口判在线;未登录不报,401/403 退避,切配置重置计时并隔离迟到响应。
- 远控须 `remote:control`,只允许 shutdown/restart/logoff/lock,客户端立即执行、持久去重并回执。冒烟始终假执行,不得真关机/重启/注销/锁屏。 - 远控须 `remote:control`,只允许 shutdown/restart/logoff/lock,客户端立即执行、持久去重并回执。冒烟始终假执行,不得真关机/重启/注销/锁屏。
- 更新写入口用 `client:update`;服务端缓存包并登记 SHA256,教室机从本服务下载;无哈希拒收,按立即/放学后/空闲策略执行,关闭自动更新不得强装。冒烟不运行安装器。 - 安装包登记/删除为管理员 `client:update`;班级推送用 `client:update-push`;服务端缓存包并登记 SHA256,教室机从本服务下载;无哈希拒收,按立即/放学后/空闲策略执行,关闭自动更新不得强装。冒烟不运行安装器。
- 灵动岛方案保存在本机 `config.json.islandLayout`,默认 `layout=fixed`;`custom` 当前即常驻模式,旧 `residentEnabled` 是兼容字段。新尺寸上报仅在 custom 模式执行。 - 灵动岛方案保存在本机 `config.json.islandLayout`,默认 `layout=fixed`;`custom` 当前即常驻模式,旧 `residentEnabled` 是兼容字段。新尺寸上报仅在 custom 模式执行。
- `LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`,共用一个原生岛窗口;课件传输状态优先显示 `CoursewareTransfer.vue`。 - `LayoutIslandApp.vue` 选择经典 `IslandApp.vue` 或 `CustomIslandRuntime.vue`,共用一个原生岛窗口;课件传输状态优先显示 `CoursewareTransfer.vue`。
- 经典模式:普通通知/作业上课暂存;普通叫人保留可点击胶囊;紧急消息立即展开。自定义常驻模式:消息先提示铃铛数量,用户主动展开;上课也可主动查看。不要把两个模式规则混写。 - 经典模式:普通通知/作业上课暂存;普通叫人保留可点击胶囊;紧急消息立即展开。自定义常驻模式:消息先提示铃铛数量,用户主动展开;上课也可主动查看。不要把两个模式规则混写。
@@ -71,9 +76,10 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
## 5. 实时、界面与资源 ## 5. 实时、界面与资源
- 事件名与房间名取 shared 常量。业务用 `emitToClass/emitToSession`,不直接依赖 Socket.IO 实例。 - 事件名与房间名取 shared 常量。班级房间为 `class:{id}:{channel}`,教师按每域读键及范围订阅,班级端仅本班全部通道;握手回查数据库身份。业务用 `emitToClass/emitToSession`,由总线选择事件域。
- 会话房间为 `session:{id}`;教师/管理员 id 为账号 id,班级端为班级 id。`students` 是班级端广播房间,不是个人学生账号房间。 - 会话房间为 `session:{id}`;教师/管理员 id 为账号 id,班级端为班级 id。`students` 是班级端广播房间,不是个人学生账号房间。
- 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。 - 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。
- 两端基础控件、主题、日期圆点与全屏引导维护在 `packages/ui`。日期统计跟随当前筛选和日历可见范围,缓存按服务器与班级隔离;业务日期使用本地日期工具。
- Web 菜单分组在 `config/navigation.ts`,标题/图标/权限取路由;守卫与服务端都检查权限,前端隐藏不能代替鉴权。 - Web 菜单分组在 `config/navigation.ts`,标题/图标/权限取路由;守卫与服务端都检查权限,前端隐藏不能代替鉴权。
- 侧栏折叠用 CSS 保持 DOM,关怀模式放大字号/控件,不改变几何令牌。使用语义色,动效统一 shared 令牌;图标新增后检查注册表。 - 侧栏折叠用 CSS 保持 DOM,关怀模式放大字号/控件,不改变几何令牌。使用语义色,动效统一 shared 令牌;图标新增后检查注册表。
- 图标源是 `build/classhelper.png` 与设计导出的 `.ico`,`pnpm icons` 派生其余资源。ICO 原样透传,客户端兜底 `build/icon.*` 同步保留。 - 图标源是 `build/classhelper.png` 与设计导出的 `.ico`,`pnpm icons` 派生其余资源。ICO 原样透传,客户端兜底 `build/icon.*` 同步保留。
@@ -95,6 +101,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
$env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH $env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH
$env:DSH_NODE = 'D:\Node.js\node.exe' $env:DSH_NODE = 'D:\Node.js\node.exe'
$env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs' $env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs'
$env:DSH_PREFER_BUNDLED_PNPM = '1'
Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue
pnpm --version pnpm --version
``` ```
@@ -108,6 +115,8 @@ Prisma 使用 driver adapter;本机优先应用已有迁移,不用 `migrate
| `pnpm lint` / `pnpm typecheck` / `pnpm check:icons` | 代码静态门禁;按改动范围执行 | | `pnpm lint` / `pnpm typecheck` / `pnpm check:icons` | 代码静态门禁;按改动范围执行 |
| `pnpm docs:check` | 文档严格构建,警告即失败 | | `pnpm docs:check` | 文档严格构建,警告即失败 |
| `pnpm verify:e2e` | 自动创建临时 SQLite 和账号,无需先开开发服务,禁止外网 | | `pnpm verify:e2e` | 自动创建临时 SQLite 和账号,无需先开开发服务,禁止外网 |
| `pnpm verify:ai` | AI 白名单、计划确认、权限与附件隔离验收 |
| `pnpm verify:authz` / `pnpm verify:audit` | 隔离授权攻击矩阵;审计事务、竞态、模型操作计数和 PWA |
| `pnpm verify:web:isolated` | 构建 Web 后运行隔离服务和隐藏 UI 回归 | | `pnpm verify:web:isolated` | 构建 Web 后运行隔离服务和隐藏 UI 回归 |
| `pnpm verify:courseware` / `pnpm verify:v14` | 课件/课表等隔离专项 | | `pnpm verify:courseware` / `pnpm verify:v14` | 课件/课表等隔离专项 |
| `pnpm verify:desktop` / `pnpm verify:packaged --exe <路径>` | 默认后台快速检查,不创建可见岛或托盘 | | `pnpm verify:desktop` / `pnpm verify:packaged --exe <路径>` | 默认后台快速检查,不创建可见岛或托盘 |
@@ -116,7 +125,7 @@ Prisma 使用 driver adapter;本机优先应用已有迁移,不用 `migrate
禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。 禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。
仅文档修改做格式、链接、构建检查,不为此反复占用桌面或重打安装包。 仅文档修改做格式、链接、构建检查,不为此反复占用桌面或重打安装包。
Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化源码。 Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化源码。根 `typecheck` 按包串行以限制峰值内存;若 Node 22 出现 V8 原生内存错误,记录失败并使用符合 engines 的已安装 Node LTS 复验,不删断言或依赖。
改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证;改打包逻辑需打包后副本复验。 改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证;改打包逻辑需打包后副本复验。
## 7. 发布与工作区清理 ## 7. 发布与工作区清理
@@ -125,7 +134,7 @@ Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化
- 本地 `pnpm dist:all` 产出 Windows 服务端和客户端;Linux 正式包由 `release-linux-server.yml` 在 Linux runner 构建,非 Linux 交叉构建仅供验证。 - 本地 `pnpm dist:all` 产出 Windows 服务端和客户端;Linux 正式包由 `release-linux-server.yml` 在 Linux runner 构建,非 Linux 交叉构建仅供验证。
- 本地文件名与 Release 的 ASCII 上传名不同,校验清单应明确映射;保留当前版本清单、更新日志及最新包。 - 本地文件名与 Release 的 ASCII 上传名不同,校验清单应明确映射;保留当前版本清单、更新日志及最新包。
- `releases/` 只放交付物及少量构建信息,不留 win-unpacked、服务端 staging、解包副本;staging 在 `.cache/server-staging/`,成功后脚本删除。 - `releases/` 只放交付物及少量构建信息,不留 win-unpacked、服务端 staging、解包副本;staging 在 `.cache/server-staging/`,成功后脚本删除。
- 2026-10-18 按用户要求清除 1.4.0 旧重构建归档,只保留 `client/1.4.0`、`server/1.4.0` 与当前清单/说明。以后同号重构建可临时留回滚副本,最新包验证完成且用户要求清理时再删除。 - 各版本交付物以 `releases/` 现场目录为准,不沿用历史清理记录推断当前版本。同号重构建可临时留回滚副本,最新包验证完成且用户要求清理时再删除。
- 递归删除/移动前核实绝对路径在指定工作区,禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。 - 递归删除/移动前核实绝对路径在指定工作区,禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。
- 不清理 `node_modules`、`.pnpm-store`、`.cache/{nuget,npm-cache,dotnet-home,mingit}`、`packages/*/dist`、生成的 Prisma Client,除非任务明确要求。 - 不清理 `node_modules`、`.pnpm-store`、`.cache/{nuget,npm-cache,dotnet-home,mingit}`、`packages/*/dist`、生成的 Prisma Client,除非任务明确要求。
- 保留已有未提交工作;提交前查看 diff,中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。 - 保留已有未提交工作;提交前查看 diff,中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。
+4 -4
View File
@@ -161,7 +161,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
| 教室机器 / 学生电脑 | **学生客户端** | `ClassHelper-<版本>-x64-client-setup.exe`,或 `-client-portable.exe` 免安装 | | 教室机器 / 学生电脑 | **学生客户端** | `ClassHelper-<版本>-x64-client-setup.exe`,或 `-client-portable.exe` 免安装 |
也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑: 也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑:
选一个版本,四个包排成四张卡,文件名、体积与 SHA256 清单都在那儿 —— 选一个版本,按客户端、Windows 服务端和 Linux 服务端展示下载卡片,文件名、体积与 SHA256 清单都在那儿 ——
那一页的清单是**当场**读 GitHub Releases 的,显示什么就能下什么。 那一页的清单是**当场**读 GitHub Releases 的,显示什么就能下什么。
服务端**装上就算跑起来了**:双击安装程序,建库、建号、开机自启都由它自己办, 服务端**装上就算跑起来了**:双击安装程序,建库、建号、开机自启都由它自己办,
@@ -180,7 +180,7 @@ curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/Love
## 获取帮助 ## 获取帮助
- **使用文档**:[docs/](docs/index.md) —— 分四块:第一次装、已经在用了、负责运维、要改代码 - **使用文档**:[docs/](docs/index.md) —— 分四块:第一次装、已经在用了、负责运维、要改代码
- **完整参考**:[docs/reference.md](docs/reference.md) —— 功能口径、REST API、权限矩阵、验收证据 - **功能与源码索引**:[docs/reference.md](docs/reference.md) —— 各帮助章节、开发契约与源码入口
- **遇到问题 / 想提需求**:[提交 Issue](https://github.com/LoveChengke/ClassHelper/issues/new/choose) - **遇到问题 / 想提需求**:[提交 Issue](https://github.com/LoveChengke/ClassHelper/issues/new/choose)
## 开发 ## 开发
@@ -198,11 +198,11 @@ cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
pnpm db:generate pnpm db:generate
pnpm --filter @classhelper/server db:deploy # 根 scripts 里没有 db:deploy pnpm --filter @classhelper/server db:deploy # 根 scripts 里没有 db:deploy
pnpm build:shared # 三端与 seed 的前置产物 pnpm build:shared # 三端与 seed 的前置产物
pnpm db:seed # 仅新建演示库时按需执行 pnpm db:seed(会清空业务表)
pnpm dev # 后端 4000 + Web 端 5173 pnpm dev # 后端 4000 + Web 端 5173
``` ```
`pnpm db:seed` 会写一套演示数据(1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩): `pnpm db:seed` 会清空并写入演示账号、班级、学生、课表与教学内容,仅用于独立演示库:
| 角色 | 账号 | 密码 | | 角色 | 账号 | 密码 |
| -------------------------- | ------------- | ------------ | | -------------------------- | ------------- | ------------ |
+32
View File
@@ -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;
}
}
+1 -1
View File
@@ -23,7 +23,7 @@ services:
context: .. context: ..
dockerfile: deploy/Dockerfile dockerfile: deploy/Dockerfile
target: runtime target: runtime
image: classhelper-server:${APP_VERSION:-1.4.0} image: classhelper-server:${APP_VERSION:-1.4.4}
restart: unless-stopped restart: unless-stopped
environment: environment:
NODE_ENV: production NODE_ENV: production
+1 -1
View File
@@ -60,7 +60,7 @@ services:
context: .. context: ..
dockerfile: deploy/Dockerfile dockerfile: deploy/Dockerfile
target: runtime target: runtime
image: classhelper-server:${APP_VERSION:-1.4.0} image: classhelper-server:${APP_VERSION:-1.4.4}
restart: unless-stopped restart: unless-stopped
environment: environment:
NODE_ENV: production NODE_ENV: production
+2 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "classhelper-server-runtime", "name": "classhelper-server-runtime",
"version": "1.4.0", "version": "1.4.4",
"private": true, "private": true,
"type": "module", "type": "module",
"description": "ClassHelper 服务端运行时(安装包 / 容器内置)", "description": "ClassHelper 服务端运行时(安装包 / 容器内置)",
@@ -21,6 +21,7 @@
"socket.io": "^4.8.3", "socket.io": "^4.8.3",
"typescript": "~5.9.3", "typescript": "~5.9.3",
"xlsx": "0.18.5", "xlsx": "0.18.5",
"yaml": "^2.9.1",
"zod": "^4.6.2" "zod": "^4.6.2"
} }
} }
+10 -8
View File
@@ -7,7 +7,7 @@ description: 深浅色主题、界面风格、设计令牌与动效语言,以
## 深浅色主题 ## 深浅色主题
**两端都有深色主题,机制完全一致**:在 `<html>` 上挂 `.dark` 类,由各自的样式表覆盖**语义色令牌**, **两端都有深色主题,机制完全一致**:在 `<html>` 上挂 `.dark` 类,由共享 UI 主题覆盖**语义色令牌**,
Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts` 都在挂载之前就把主题落好, Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts` 都在挂载之前就把主题落好,
所以深色用户打开时不会"先白后黑"闪一下。 所以深色用户打开时不会"先白后黑"闪一下。
@@ -19,7 +19,7 @@ Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts`
| 切换效果 | 从点击位置**扩散的圆**铺满整页换肤 | | 切换效果 | 从点击位置**扩散的圆**铺满整页换肤 |
**刻意不随主题的区域**:登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、 **刻意不随主题的区域**:登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、
Web 管理端的侧边栏(本来就是深色),以及深色底上的白色文字。 以及深色底上的白色文字。
Web 端还会同步 `<meta name="theme-color">`,并设 `color-scheme` 让**原生控件** Web 端还会同步 `<meta name="theme-color">`,并设 `color-scheme` 让**原生控件**
(滚动条、日期选择器弹层、自动填充底色)也跟着走 —— 只改 CSS 变量的话它们会仍是浅色。 (滚动条、日期选择器弹层、自动填充底色)也跟着走 —— 只改 CSS 变量的话它们会仍是浅色。
@@ -44,13 +44,15 @@ Web 端还会同步 `<meta name="theme-color">`,并设 `color-scheme` 让**原
## 界面风格 ## 界面风格
- 浅色底 `#f3f3f3` + 半透明卡片(`rgba(255,255,255,.7)` + `backdrop-filter: blur(20px)`); Web 和桌面主窗口共用简洁的管理界面:浅灰底、实色卡片、统一描边与紫蓝强调色。标题、筛选、操作栏和表单按同一套控件与间距规范呈现;深浅色切换保持相同几何。
- 强调色 `#0F6CBD`(悬停 `#115EA3`);选中的导航项 = 强调色淡底 + 左侧 3px 强调条;
- 圆角统一:卡片 8px / 控件 4px;描边用半透明黑代替灰线;阴影极轻;
- 字体 `Segoe UI Variable / 微软雅黑 UI`;Element Plus 的变量整体对齐这套规范。
Web 管理端走的是另一套(1Panel 风格:深色侧边栏 + 白色圆角卡片), 共享主题和控件由 UI 包维护,灵动岛只引入共用语义令牌,保留透明窗口和各模式的布局规则。
圆角与投影集中定义在它的 `:root` 令牌里。
日期统一通过日历选择。有记录的日期下方显示圆点,统计随当前筛选和可见月份更新。日期目录与日期下拉列表已改为日历,教师和文件夹仍可独立筛选。
Web 的作业、通知日期统计保留在当前会话缓存中,按服务器、操作者、权限范围和筛选条件隔离;退出或收到授权失败时清理。桌面端复用按服务器和班级隔离的离线缓存。只有网络不可达时才回退缓存,缓存故障不阻断在线读取。
首次进入新版会显示全屏分步引导,可以返回、跳过或完成;账号菜单、客户端登录页和通用设置保留重看入口。引导中的内容为示意,不创建业务数据。
## 动效语言 ## 动效语言
+34
View File
@@ -0,0 +1,34 @@
---
title: AI 助手
description: 多轮对话、文件处理与操作计划,核对后通过现有业务接口执行。
---
# AI 助手
在 Web 管理端描述任务、补充条件或添加文件,助手会查询所需信息并生成操作计划。查询直接显示结果;任何发布、修改、导入和设备操作,都要核对计划并确认后执行。
## 使用
1. 可先选择目标班级,再输入任务;文件也可以直接拖入对话区。
2. 信息不足时补充说明。核对目标、文件、修改前内容和本次变更;表格导入可调整字段对应。
3. 确认执行后逐步显示结果。跨班发布按班显示进度,成功班级不会重复执行。失败时只重试尚未成功的步骤;结果不明时先在对应业务页面核对。
文件推送复用课件上传、哈希校验和设备回执,普通课件上限 512 MB。结构化导入支持现有 CSV、Excel、JSON、YAML 格式,上限 8 MB,先解析预览,确认后才写入业务数据。
## 权限
助手权限跟随操作者。教学业务、课表时间表、名单成绩、账号岗位和设备操作均使用原业务接口的授权规则;管理员专用功能仍限管理员。确认期间撤权、调班或任课关系变化后会重新校验。
数据库备份、恢复、清空、切换、SQL,以及服务器配置、启停、升级和密钥维护不向助手开放。删除、权限调整、升学和远控保留专门确认;上课时的紧急通知仍需二次确认。
管理员可让助手抓取、登记或删除客户端安装包缓存,核对版本、文件与替换信息并专门确认后执行。缓存管理不会自动推送、运行安装器或升级服务器。助手也可按设备权限处理远控、更新推送和移除设备登记。
密码通过操作卡片中的专用表单输入,不提供给模型。用户指令与任务所需的已授权业务信息由学校配置的模型服务解析;普通课件只提供文件元数据。对话历史保留在当前页面会话,计划与执行结果记入服务端审计。
## 模型配置与验收
管理员在大模型设置中配置服务地址、模型和 API Key。Key 加密保存且不回传;改变服务器 JWT 密钥后需重新配置 Key。
`mock` 用于离线示例和自动化验收,真实服务失败不会自动切换为 mock 或发布内容。`pnpm verify:ai` 使用临时数据库和模型 stub 验证权限、计划、附件和重复提交,不访问外网。
相关功能:[课件](courseware.md)、[课表](schedules.md)、[作业](homeworks.md)、[通知](notifications.md)、[角色与权限](../dev/permissions.md)。
+31 -5
View File
@@ -17,10 +17,12 @@ description: 名单、班级会话、任课关系与年度升级。
## 学生名单 ## 学生名单
Web 统一从“学生管理”查看和维护名单;旧 `/roster` 地址转到同一页面,不再提供重复菜单。班级详情中的名单与课程按当前班级的生效范围展示维护入口,任课关系本身不授予跨班名单、课程或班级设置管理权。
Student 存学号、姓名、班级、性别、家长电话和状态,没有密码或角色字段。 Student 存学号、姓名、班级、性别、家长电话和状态,没有密码或角色字段。
学号为必填唯一标识,格式为 1–32 位字母、数字或 . _ -;不会自动生成登录名。 学号为必填唯一标识,格式为 1–32 位字母、数字或 . _ -;不会自动生成登录名。
管理员或本班班主任在具备名单管理权限后管理学生,教师也可按授权范围只读名单。 具有名单管理键的管理员、本班班主任或全校名单范围的授权员工管理学生;只读账号按名单读取键和范围查看历史。
名单表格导入仍要求管理员及相应导入权限;学号查重在 Student 表完成,不当成 User 用户名。 名单表格导入要求 import:students、roster:manage 和对应班级范围;学号查重在 Student 表完成,不当成 User 用户名。
调班保留历史内容原归属;转出独立记账并从现行业务名单过滤,学号不可复用。 调班保留历史内容原归属;转出独立记账并从现行业务名单过滤,学号不可复用。
## 教师与科目 ## 教师与科目
@@ -30,14 +32,38 @@ Student 存学号、姓名、班级、性别、家长电话和状态,没有密
科任关系唯一存于 Course(classId, name, teacherId),分配任课关系由班级管理权限及服务端断言限制。 科任关系唯一存于 Course(classId, name, teacherId),分配任课关系由班级管理权限及服务端断言限制。
班主任不任教某科就不能修改该科作业/成绩;科任老师有相应权限时可以管理自己任教科目。 班主任不任教某科就不能修改该科作业/成绩;科任老师有相应权限时可以管理自己任教科目。
新建科目同时建立任课关系,只对管理员开放。教师需要增加科目或改变任课老师时,请联系管理员;年级、部或全校课表维护范围不能用来给自己任课。
删除教师前,服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件;仍有业务内容则返回冲突,避免级联丢失。 删除教师前,服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件;仍有业务内容则返回冲突,避免级联丢失。
教师本人改密码、管理员修改教师密码、班级账号密码是不同入口;学生没有密码接口。 教师本人改密码、管理员修改教师密码、班级账号密码是不同入口;学生没有密码接口。
## 权限、学年与归档 ## 权限、学年与归档
角色给默认权限模板,实际入口由可编辑权限组决定;岗位组还能配置年级或部范围。 管理员固定拥有全部能力;教师按岗位模板及每项分配的范围获得能力,未显式分配时使用教师默认模板与固定任教范围。
范围不代替科目写权限,详见[角色与权限](../dev/permissions.md)。 范围不代替科目写权限,详见[角色与权限](../dev/permissions.md)。
“学期周次”只维护教学周与日期区间;年度轨道、执行计划与补跑统一在管理员专用的“学年升级”页维护。
学期周数受全校可配置上限约束,默认上限 30、允许 1–60,见[课表](schedules.md)。 学期周数受全校可配置上限约束,默认上限 30、允许 1–60,见[课表](schedules.md)。
学年升级按计划时间运行,执行前保存快照,以年份幂等;启动发现漏跑需管理员预览补跑。 学年升级按计划时间运行,执行前保存快照,以年份幂等;启动发现漏跑需管理员预览补跑。
高三归档、高一/高二升一级,新高一不复制任课关系。归档页查看届别历史与转出记录, 默认高中轨道按高一、高二、高三排列,毕业学段归档,其余升一级;也可配置其他轨道。新班不复制任课关系。归档页查看届别历史与转出记录,
不再通过手动创建归档来代替年度升级。撤回转出等操作仍受归档与管理员业务检查约束。 不再通过手动创建归档来代替年度升级。撤回转出由 roster:manage 控制,原班归档后可指定其他在读班。
## 学生生命周期
资料编辑仅修改学号、姓名、性别与家长电话,不接受状态或班级字段;旧客户端发送这两项会收到 400 和专用接口提示。
默认名单只显示未归档的 active;状态筛选可查看 inactive、transferred、graduated,“包含归档”另行控制归档标记。
调班、转出、转入、复学、撤回与移出班级均在一个事务内修改学生并写历史,包含批次、学年、原新班级与年级、来源去向学校、操作人和备注。
调班需同时覆盖源班与目标班;跨年级须管理员勾选允许跨年级并填写备注。目标班必须在读。
转出保留原班及业务历史,只接受在读或停用学生。转入支持新建学号或选择转出/停用学生,毕业或归档学生不能通过名单入口复活。
撤回转出可选择另一个在读班,原历史保留。默认删除动作改为停用;硬删除另须管理员确认且无成绩、作业、已读或历史。
## 升级预览与执行
“学年升级”页面独立要求 promotion:manage,全校范围。先保存轨道、有序年级、起始班数、执行时间、开学日和周次重置策略,再预览逐班影响。
预览包含在读/停用/转出人数、新班码、周次删除行数、阻断和警告、计划哈希。未知年级、缺失届别、重复班号、已有届别档案或新班码冲突会阻断执行。
执行需确认学年和预览哈希;业务或配置变化后必须重新预览。未来学年禁止执行,过去学年仅 ADMIN 明确补跑。
毕业班所有学生挂届别:在读转毕业,转出和停用保留状态;非毕业班只升到下一学段并清本班开学日覆盖。
新班只有骨架,开学日取计划值(未配置时为执行学年 9 月 1 日)。保留周次时,旧逐周区间会继续覆盖新学年,页面会警告。
同年执行幂等,执行记录显示操作人、快照路径、SHA256、明细与错误。快照失败不升级,失败事务回滚后可修正重试。
撤销归档只清标记并将毕业生恢复在读,转出/停用不变;不回滚年级、不删除新班、不恢复已清空周次,整学年恢复需管理员手工使用快照。
+9 -4
View File
@@ -6,7 +6,8 @@
1. 选择本地文件。 1. 选择本地文件。
2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级;仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。 2. 选择可以查看课件的班级。候选项只包含本人担任任课教师的在读班级;仅担任班主任、级长或部长不会额外获得上传到这些班级的权限。
3. 选择「仅保存云端」或「保存后推送所选班级」,点击上传。 3. 可新建分类文件夹,使用 `/` 分隔多层目录,例如 `地理/必修一`;不选文件夹时直接按日期归档。
4. 选择「仅保存云端」或「保存后推送所选班级」,点击上传。
不选择班级时,课件仅自己可见。仅保存云端并指定可见班级后,这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端,再给所选班级创建下载任务;不会从教师电脑直接传到教室电脑。 不选择班级时,课件仅自己可见。仅保存云端并指定可见班级后,这些班级可在客户端自主下载。推送模式会先把文件完整保存到服务端,再给所选班级创建下载任务;不会从教师电脑直接传到教室电脑。
@@ -14,10 +15,14 @@
「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限,可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限;升级时自定义权限组需管理员按需授权。 「查看与下载课件」和「上传、设置可见范围与推送自己的课件」为独立权限,可在权限组中分配。默认教师与管理员、内置教师与班主任岗位包含这两项权限;升级时自定义权限组需管理员按需授权。
「日期归档」按教师、年、月、日和上传时间选择目录;「文件夹分类」按自建目录筛选,已有文件可随时调整分类。文件夹按教师隔离,分类本身不授予班级下载权限。
## 班级客户端 ## 班级客户端
客户端侧栏新增「课件」,仅列出本班可见的文件,显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机,点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。 客户端侧栏新增「课件」,仅列出本班可见的文件,显示文件名、类型、上传教师、日期与大小。点击「下载」将课件保存到本机,点击「打开文件夹」定位已下载文件。客户端不会自动运行文件。
「本机归档」独立列出已经接收的课件,离线时也可按教师和日期目录查找。每个服务端与班级会话有独立归档根目录,文件路径采用 `Teachers\老师名字\上传年份\上传月\上传日\上传时间\文件名`,例如 `Teachers\Wanghong\2026\10\18\15-30-42\大气环流.pptx`。目录时间取上传时间,重复推送会复用已校验的文件;同秒同名的不同课件会添加编号,避免覆盖。
收到教师推送后,客户端自动下载;离线时任务保留在服务端,上线后的心跳会补拉,每台设备独立回执。实时通道正常时会立即触发检查;断线时通过心跳继续补收。传输失败会显示原因,推送任务在后续心跳中重试,不会影响远控和在线状态上报。 收到教师推送后,客户端自动下载;离线时任务保留在服务端,上线后的心跳会补拉,每台设备独立回执。实时通道正常时会立即触发检查;断线时通过心跳继续补收。传输失败会显示原因,推送任务在后续心跳中重试,不会影响远控和在线状态上报。
下载期间,固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256,再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件;重新联网后同步当前可见范围。 下载期间,固定岛和自定义常驻岛都会显示文件名、文件类型、传输教师、接收字节数和进度条。下载完成后校验 SHA256,再保存正式文件并回执。断网时可以查看已缓存的课件目录与已经下载的本地文件;重新联网后同步当前可见范围。
@@ -26,11 +31,11 @@
## 服务端归档与备份 ## 服务端归档与备份
默认文件实体目录为 `<服务端根目录的上一级>/data/courseware/YYYY-MM-DD/<类型>/<随机编号>`,展示名称与扩展名单独保存在数据库中。可通过环境变量 `COURSEWARE_DIR` 指定文件目录。上传使用流式写入,未完成文件使用 `.part` 临时文件;失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。 默认文件实体目录为 `<服务端根目录的上一级>/data/courseware/<随机编号>/Teachers/<教师>/<年>/<月>/<日>/<时间>/<文件名>`,随机编号隔离同名教师和同秒上传,旧课件保留原存储位置。可通过环境变量 `COURSEWARE_DIR` 指定文件目录。上传使用流式写入,未完成文件使用 `.part` 临时文件;失败或上传中断时清理。只有完整收到文件并完成摘要计算后才记录元数据和创建推送任务。
数据库迁移 `20261018000000_add_courseware` 新增课件、可见班级、推送和设备回执四张表。SQLite 安装部署按现有自动迁移流程更新;源码开发部署执行 `pnpm --filter @classhelper/server db:deploy`。MySQL 按现有换库流程基于更新后的 schema 建模。 数据库迁移新增课件、可见班级、推送、设备回执和分类目录,并记录上传归档路径。SQLite 安装部署按现有自动迁移流程更新;源码开发部署执行 `pnpm --filter @classhelper/server db:deploy`。MySQL 按现有换库流程基于更新后的 schema 建模。
数据库 JSON 备份包含这四张表,但**不包含二进制文件本身**。完整备份必须同时备份 `data/courseware`(自定义目录时备份对应目录)。SQLite Docker 的现有数据卷覆盖此目录;MySQL Docker 配置增加 `server-data:/app/data` 数据卷。复制到新机器时需同时恢复数据库和文件目录。 数据库 JSON 备份包含课件元数据和分类目录,但**不包含二进制文件本身**。完整备份必须同时备份 `data/courseware`(自定义目录时备份对应目录)。SQLite Docker 的现有数据卷覆盖此目录;MySQL Docker 配置增加 `server-data:/app/data` 数据卷。复制到新机器时需同时恢复数据库和文件目录。
使用反向代理时,需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时,其他接口维持原有大小限制。 使用反向代理时,需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时,其他接口维持原有大小限制。
+3 -1
View File
@@ -6,11 +6,13 @@ description: 录入、按学号查询、排名与关闭个人查询后的集体
# 成绩 # 成绩
Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。 Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。 科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。新增科目及任课关系由管理员配置。
成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查: 成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查:
管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。 管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。
表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。 表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。
整班批量录入在同一事务中校验学生、授权并写入成绩;任意一行无效或写入失败时整批回滚,不留下部分成绩。等级批量修改按每个班级与科目组合独立检查授权。
## 查看、排名与隐私 ## 查看、排名与隐私
班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。 班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。
+32 -1
View File
@@ -22,7 +22,7 @@ description: 表格预览、名单与成绩校验,以及完整离线档案导
## 完整 ClassIsland 档案 ## 完整 ClassIsland 档案
在“课表管理 → 导入 ClassIsland 课程表”选择或粘贴 JSON,先预览再导入。 在“课表档案 → 导入/导出 → 导入课表(JSON / YAML)”选择或粘贴 JSON,先预览再导入。
完整输入包含 TimeLayouts、ClassPlans、Subjects 字典,可包含 ClassPlanGroups 和 OrderedSchedules 等配置。 完整输入包含 TimeLayouts、ClassPlans、Subjects 字典,可包含 ClassPlanGroups 和 OrderedSchedules 等配置。
JSON 只作为离线文件导入,不依赖在线联动插件。 JSON 只作为离线文件导入,不依赖在线联动插件。
@@ -44,6 +44,37 @@ JSON 只作为离线文件导入,不依赖在线联动插件。
不完整展示群组/空课/停用等结构;提交直接调用完整导入,不能把预览的单双周列当作实际数据模型。 不完整展示群组/空课/停用等结构;提交直接调用完整导入,不能把预览的单双周列当作实际数据模型。
完整导入失败时事务回滚;部分缺失引用可能返回 warnings,须检查导入结果和日课表编辑器。 完整导入失败时事务回滚;部分缺失引用可能返回 warnings,须检查导入结果和日课表编辑器。
## YAML 课表
同一导入窗口支持 `.yaml` / `.yml` 文件和粘贴内容,提供示例下载。先解析预览,再选择合并或覆盖。
文件上限 8 MB。格式如下:
```yaml
version: 1
subjects:
- name: 数学
simplified_name: 数
teacher: 李梅
room: '101'
schedules:
- name: 星期一
enable_day: 1
weeks: all
classes:
- subject: 数学
start_time: '080000'
end_time: '090000'
```
`enable_day` 为 1–7(周一至周日);`weeks` 支持 `all`(每周)、`odd`(单周)、`even`(双周)。
同一天的单周与双周分开填写,同一天同一相位不可重复,也不能混用每周与单双周课表。
时间支持 `HHMMSS`、`HH:mm`、`HH:mm:ss`,秒必须为 `00`;未加引号的六位数字也可识别。
兼容以 `version 1` 开头、字段省略冒号的示例写法,并在预览中提示;新文件建议采用上述标准 YAML。
`simplified_name` 保存为科目简称,`room` 保存为课次地点;`teacher` 只在预览中展示,不创建教师账号或改变任课关系。
缺失科目按完整档案规则补建。YAML 归一化为关系化时间点和日课表后复用完整导入的权限、事务和实时更新。
合并按星期与单双周更新同一套 YAML 对象;覆盖会替换该班已有日课表。语法或字段校验失败时不会写库。
## 时间配置兼容入口 ## 时间配置兼容入口
旧 /imports/time-layout 接口保留,写入和删除需 timetable:manage,现行写入同步关系化时间点。 旧 /imports/time-layout 接口保留,写入和删除需 timetable:manage,现行写入同步关系化时间点。
+1
View File
@@ -10,6 +10,7 @@ description: ClassHelper每一项功能怎么用:课表、作业、通知、
| 页面 | 讲什么 | | 页面 | 讲什么 |
| --------------------------------- | ---------------------------------------------------------- | | --------------------------------- | ---------------------------------------------------------- |
| [AI 助手](assistant.md) | 自然语言解析、核对确认、业务权限与离线示例 |
| [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 | | [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 |
| [课件](courseware.md) | 上传、班级可见范围、推送与逐设备接收 | | [课件](courseware.md) | 上传、班级可见范围、推送与逐设备接收 |
| [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 | | [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
+15 -2
View File
@@ -36,8 +36,13 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
## 编辑自定义方案 ## 编辑自定义方案
“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。 “设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
方案支持复制、删除、JSON 导入导出;组件支持日期、时钟、倒计时、课程、文本、分隔符、通知/作业/叫人及组合容器。 页面上方排列当前组件,右上角选择配置方案;刷新图标重置当前方案,加号新建方案,文件夹菜单提供方案设置、复制、删除及 JSON 导入导出。
分别编辑常态 rows 与无消息展开 expandedRows,拖动调整结构,设置内容、外观、尺寸与隐藏条件。 下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器,并保留班级通知、作业和叫人组件。
从组件库拖入上方的行或容器以添加,拖动已有组件调整顺序或跨行移动;也可点击组件库添加到选中的容器或当前行。
分别编辑常态 rows 与无消息展开 expandedRows,点选组件打开内容、外观、尺寸与隐藏条件设置;行可以新增、排序、设为主要行或删除。
“进入编辑模式”切换为实际内容预览,支持预览缩放;退出后回到组件标签排列。轮播和滚动容器在编辑时展示全部子组件,便于选择和排列。
倒计时可指定目标名称与日期,也可按课表倒数至上课、下课或放学。
天气简报需填写地点名称及经纬度,使用 [Open-Meteo](https://open-meteo.com/en/docs) 的天气数据,每 15 分钟更新;断网时保留本次客户端运行中的缓存并标明“缓存”。天气提示根据天气概况生成,不提供官方气象预警。
方案保存到本机 config.json.islandLayout,不增加服务端同步。 方案保存到本机 config.json.islandLayout,不增加服务端同步。
编辑预览不创建额外桌面窗口;打开编辑页不自动切布局,应用后启用自定义方案。 编辑预览不创建额外桌面窗口;打开编辑页不自动切布局,应用后启用自定义方案。
保存按序进行,失败可重试,主题与关怀模式沿用客户端设置。 保存按序进行,失败可重试,主题与关怀模式沿用客户端设置。
@@ -56,6 +61,14 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
## 课程与课件 ## 课程与课件
准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关,课程依据服务端解析后的课表。 准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关,课程依据服务端解析后的课表。
自定义常驻岛的「课程表」组件可选「当前时间点 / 下一节课 / 今日时间点」:
「今日时间点」显示当天全部时间点,只有当前项展开显示起止时间,其余折叠只显示课程名;
课间休息与「默认隐藏」的上课时间点折叠时完全隐藏,轮到它们时才展开;分割线显示一条竖线,行动不显示。
课中课程表不再常驻显示倒计时,只在最后一分钟由既有的「下课提醒」页显示「距下课还剩」;
倒计时阈值沿用本机提醒设置(默认 60 秒)。没有时间点数据时退回按课表条目显示课程。
经典 fixed 岛的课中提醒条保持原有倒计时行为。
课件接收时显示文件名、类型、教师、字节和进度,覆盖当前固定/自定义内容;完成后校验 SHA256 并回执。 课件接收时显示文件名、类型、教师、字节和进度,覆盖当前固定/自定义内容;完成后校验 SHA256 并回执。
客户端不会自动执行收到的文件,见[课件](courseware.md)。 客户端不会自动执行收到的文件,见[课件](courseware.md)。
+15 -1
View File
@@ -5,13 +5,27 @@ description: 日课表、共享作息、轮换、临时换课和教学周。
# 课表 # 课表
Web 管理端可查看周课表并编辑时间表与日课表,客户端提供“今天”时间轴和“本周”视图。 Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表,客户端提供“今天”时间轴和“本周”视图。
上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。 上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
编辑工作区参照 [ClassIsland 档案编辑器](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/ProfileSettingsWindow.axaml) 的课表交互实现,作为管理端内的普通页面展示,沿用全站的导航、间距、控件及浅色/深色主题。顶部切换课表、时间表、科目和调课;课表页默认进入单表编辑:左侧按课表群分组的课表列表,中间逐节选择科目,右侧切换「科目 / 课表信息」。底部仍可切换列表、周和月视图。旧管理页地址 `/schedules` 自动进入同一页面,侧栏和顶部导航始终可用。
点击每天列头的「新课表」选择时间表并创建日课表。周视图点击网格中的课时后可用右侧科目按钮快速填充,支持选择是否自动移动到下一节;方向键可移动焦点,Delete 可清空选中课程。课表名称、时间表、启用星期、轮换规则、生效周次与群组在右侧「课表信息」中维护。列表视图提供批量排课、复制粘贴、拖动交换课程等操作。
时间表页采用 ClassIsland 式编辑器:左侧时间表列表(新建、复制、搜索),顶部按类型添加上课、课间休息、分割线、行动,中间可在列表视图与时间轴视图之间切换,右侧编辑选中时间点,左下设置默认上课/课间时长,右下缩放。时间轴视图可按分钟拖动时间点的开始/结束把柄,并按 1 分钟取整;列表视图可拖动排序。保存仍走页面顶部「保存」或 Ctrl+S;切周与实时刷新保留草稿,切换班级和离开页面时提醒未保存的修改。
上课时间点可以设置一个默认课程。日课表里**没有单独条目**的课时会回退到该默认课程;已有条目(包括显式空课)不会被覆盖。「覆盖现有课程」会把这门课写入所有引用该时间表的日课表。默认隐藏的上课时间点只在轮到时才在主界面显示;课间休息类型代表下课时间,折叠时完全隐藏,轮到它时才展开。
完整档案可在页头「导入/导出」中导入或导出 JSON,保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航,点击日期后由服务端解析教学周并进入周视图。
「导入课表(JSON / YAML)」还支持简化的 YAML 课表,包含星期、单双周、科目和起止时间;字段与示例见[表格与课表导入](imports.md)。
## 日课表与时间表 ## 日课表与时间表
时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。 时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。
可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。 可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
新增科目会建立任课关系,仅管理员可执行;课表维护者可以使用已配置的科目排课,需要新增或更换任课老师时联系管理员。
时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。 时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。
日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。 日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。
+2
View File
@@ -1,5 +1,7 @@
- name: 应用帮助 - name: 应用帮助
href: index.md href: index.md
- name: AI 助手
href: assistant.md
- name: 课表 - name: 课表
href: schedules.md href: schedules.md
- name: 作业 - name: 作业
+2 -2
View File
@@ -34,7 +34,7 @@ function readVersion() {
/** 找不到 docfx 时给出可照抄的安装命令,而不是一句 spawn ENOENT */ /** 找不到 docfx 时给出可照抄的安装命令,而不是一句 spawn ENOENT */
function ensureDocfx() { function ensureDocfx() {
const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' }); const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8' });
if (probe.status === 0) return probe.stdout.trim(); if (probe.status === 0) return probe.stdout.trim();
console.error('[docs] 找不到 docfx。docfx 是 .NET 工具,安装方式:'); console.error('[docs] 找不到 docfx。docfx 是 .NET 工具,安装方式:');
@@ -50,7 +50,7 @@ function ensureDocfx() {
function run(command, args, options = {}) { function run(command, args, options = {}) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
const child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32', ...options }); const child = spawn(command, args, { stdio: 'inherit', ...options });
child.on('error', reject); child.on('error', reject);
child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`)))); child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`))));
}); });
+101 -39
View File
@@ -16,8 +16,8 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
| ----------------------------------------------------------------------- | -------------------------------------------------------------- | | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| POST /auth/login、/auth/class-login | 员工/班级登录,共享登录限流;学生无账号 | | POST /auth/login、/auth/class-login | 员工/班级登录,共享登录限流;学生无账号 |
| GET /auth/me;POST /auth/logout;PATCH /auth/password | 当前身份、退出、员工本人改密码 | | GET /auth/me;POST /auth/logout;PATCH /auth/password | 当前身份、退出、员工本人改密码 |
| GET/POST /classes;GET/PATCH/DELETE /classes/:id | 班级查询/管理,写入需 class:manage 与管理员业务断言 | | GET/POST /classes;GET/PATCH/DELETE /classes/:id | 班级查询/管理,读取 class:read;写入 class:manage 且仅管理员 |
| PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据/班主任维护 | | PATCH /classes/:id/class-account、/classes/:id/head-teacher | 班级凭据 class:account + 班主任;班主任分配仅管理员 |
| PUT /classes/:id/subject-teachers | 任课关系设置,Course 为唯一来源 | | PUT /classes/:id/subject-teachers | 任课关系设置,Course 为唯一来源 |
| GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关,班级端不能修改 | | GET/PATCH /classes/:id/student-grade-query | 查看/修改班级个人成绩查询开关,班级端不能修改 |
| GET/POST /classes/:id/students;DELETE /classes/:id/students/:studentId | 本班名单及维护,受名单功能权限和班级关系约束 | | GET/POST /classes/:id/students;DELETE /classes/:id/students/:studentId | 本班名单及维护,受名单功能权限和班级关系约束 |
@@ -27,48 +27,110 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
## 教学与文件 ## 教学与文件
| 路径/动作 | 行为及边界 | | 路径/动作 | 行为及边界 |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| /courses | 班级科目与任课关系 | | /courses | 班级科目与任课关系 |
| GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影,按班级范围读取 | | GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影,按班级范围读取 |
| POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD,写新模型,不双写旧 Schedule | | POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD,写新模型,不双写旧 Schedule |
| POST /schedules/swap、/overlay、/scheduled;GET /schedules/scheduled;DELETE /schedules/scheduled/:id | 换课、临时层、预定 | | POST /schedules/swap、/overlay、/scheduled;GET /schedules/scheduled;DELETE /schedules/scheduled/:id | 换课、临时层、预定 |
| /time-layouts;POST /time-layouts/:id/clone、/:id/import | 时间表 CRUD/克隆/导入,写入 timetable:manage | | /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 + 班主任/管理员 | | /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 | 复制、导入导出及完整档案导入 | | 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 | 群组及当前/临时选择 | | /class-plan-groups;GET /class-plan-groups/selection;POST /class-plan-groups/select | 群组及当前/临时选择 |
| /homeworks、/homeworks/bulk、/:id/status、/:id/submissions | 作业、批量、完成与未交;员工功能键+科目检查,班级端可录作业 | | /homeworks、/homeworks/bulk、/:id/status、/:id/submissions | 作业、批量、完成与未交;员工功能键+科目检查,班级端可录作业 |
| /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all | 通知、归档和已读;发布需 notification:publish,课堂紧急须确认 | | /notifications、/notifications/bulk、/days、/creators、/unread-count、/:id/read、/read-all | 通知、归档和已读;发布需 notification:publish,课堂紧急须确认 |
| POST /calls | 叫人,call:create + 范围检查 | | POST /calls | 叫人,call:create + 范围检查 |
| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md),查询列表参数用 studentId,写入仍按科目 | | /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md),查询列表参数用 studentId,写入仍按科目 |
| /imports/template、/table/preview、/table/commit | 表格导入,按 kind 再检查角色、导入权限、班级和科目 | | /imports/template、/table/preview、/table/commit | 表格导入,按 kind 再检查对应导入键、管理键、班级和科目 |
| /imports/class-plan/preview、/imports/class-plan | 旧预览与完整档案提交;提交走关系化导入 | | /imports/class-plan/preview、/imports/class-plan | 预览与提交均需 import:schedule + schedule:write;提交走关系化导入 |
| /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口,写入/删除需 timetable:manage | | POST /imports/class-plan/yaml/preview、/imports/class-plan/yaml | YAML 预览/导入;同课表导入权限与班级范围,支持 all/odd/even 与 HHMMSS,提交复用完整档案事务 |
| GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载;员工需 courseware:read,班级端按可见范围 | | /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口,导入需 import:schedule + timetable:manage,删除需 timetable:manage |
| POST /courseware/upload、/:id/push;PATCH /courseware/:id/visibility;DELETE /courseware/:id | 写入 courseware:write + 员工身份;本人文件、任课班级与可见范围限制 | | GET /class-plans/profile?classId= | 完整档案导出,按班级范围读取,保留时间点与课表关联 |
| GET /courseware/transfers;POST /courseware/transfers/:id/ack | 班级端补领、逐设备回执 | | 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 /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执,校验 deviceKey 和归属 | | POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执,校验 deviceKey 和归属 |
| GET /clients/devices;DELETE /clients/devices/:id | 设备读取/维护,分别检查功能键和范围 | | POST /clients/update-progress | 设备上传下载、校验、等待、安装和失败状态,校验设备班级归属 |
| POST /clients/commands | remote:control + 对应范围,白名单动作 | | GET /clients/devices;DELETE /clients/devices/:id | 设备读取/维护,分别检查功能键和范围 |
| POST /clients/updates | client:update,安装策略 immediate/after-school/idle | | POST /clients/commands | remote:control + 对应范围,白名单动作 |
| GET /update/check | 员工需 update:check;强制刷新另检查 update:force | | POST /clients/updates | client:update-push,安装策略 immediate/after-school/idle |
| GET /update/client/releases | 缓存版本读取,按路由允许的读取权限 | | GET /update/check | 员工需 update:check;强制刷新另检查 update:force |
| POST /update/client/fetch、/update/client/releases;DELETE /update/client/releases/:version | 安装包写入口统一 client:update | | GET /update/client/releases | 缓存版本读取,按路由允许的读取权限 |
| GET /update/client/download/:version | 已登录下载,不挂员工权限键,供班级端更新 | | POST /update/client/fetch、/update/client/releases;DELETE /update/client/releases/:version | 安装包写入口仅管理员 client:update |
| /term;POST /term/auto;GET /term/holidays | 学期读取/编辑/假日建议,term:read/term:write | | GET /update/client/download/:version | 本班 CLASS_DEVICE 或 client:read + 有效班级范围 |
| GET/PUT /term/promotion;POST /term/promotion/run | 升级计划、预览和执行,system:manage,执行还做业务校验 | | /term;POST /term/auto;GET /term/holidays | 学期读取/编辑/假日建议,term:read/term:write |
| /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档与撤回转出,archive:manage;不提供创建归档代替年度升级的入口 | | GET/PUT /term/promotion;POST /term/promotion/run | 升级计划与执行,promotion:manage + 全校范围,执行要求确认与计划哈希 |
| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage;目标空库、快照及换库子进程保护 | | /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档需 archive:manage 全校范围;撤回转出需 roster:manage;不提供手动创建归档 |
| /system/settings、/autostart、/diagnostics | system:manage,非安装形态自启动返回不可用原因 | | /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage;目标空库、快照及换库子进程保护 |
| /ai/settings、/interpret、/audit | ai:manage/ai:use;只解析待确认动作,密钥只进不出 | | /system/settings、/autostart、/diagnostics | system:manage,非安装形态自启动返回不可用原因 |
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 | | /ai/settings、/interpret、/audit、/capabilities、/plans/:id | ai:manage/ai:use;查询遵循业务权限,写入计划确认后调用原接口,密钥只进不出 |
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 |
探针 /healthz 和 /readyz 不带 API 前缀;/api/health 提供版本与模块详情。 探针 /healthz 和 /readyz 不带 API 前缀;/api/health 提供版本与模块详情。
课件上传是原始文件流,512 MB 限制独立于表格 JSON 的 12 MB 限制;metadata 走上传查询 schema。 课件上传是原始文件流,512 MB 限制独立于表格 JSON 的 12 MB 限制;metadata 走上传查询 schema。
心跳 agentProtocol:2 使用统一响应 data,旧协议兼容字段只用于升级过渡。 心跳 agentProtocol:2 使用统一响应 data,旧协议兼容字段只用于升级过渡。
更多说明见[权限](permissions.md)、[实时事件](realtime.md)、[数据模型](data-model.md)。 更多说明见[权限](permissions.md)、[实时事件](realtime.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 对名单、日课表、导入和考试配置叠加班主任或显式组织范围规则。界面范围提示不替代服务端断言。
## AI 操作计划
跨班作业与通知会归一为逐班步骤,分别调用单班业务接口。成功班级保持成功状态,后续重试跳过这些步骤。
客户端安装包缓存允许 `clients.releases` 查询,以及仅限 ADMIN + `client:update` 的 `clients.release-fetch/register/delete`。写入均要求专门确认,并核对版本、已有登记及缓存文件状态。更新模块只开放固定的 `/update/client/releases` 查询、`/update/client/fetch` 抓取、`/update/client/releases` 登记及按版本删除;没有服务器更新、配置或任意下载地址入口。抓取复用现有官方项目下载地址与流式校验,不推送或安装。
`POST /ai/interpret` 接收 `text`、可选班级、当前会话的 `messages` 和附件元数据 `attachments`,返回 `planId/message/steps/results`,并保留旧响应字段的兼容形状。附件包含 id、文件名、大小与 SHA256;普通课件内容不发送给模型。
- `GET /ai/capabilities`:当前操作者可用的动作及参数契约,目录不包含数据库维护、服务器运维和密钥操作。
- `GET /ai/plans/:id`:本人计划和分步状态;业务权限及范围重新校验。
- `POST /ai/plans/:id/prepare`:结构化附件经哈希核对后复用原导入解析器生成预览,不发布业务数据。
- `POST /ai/plans/:id/confirm`:提交明确确认、必要的高影响操作确认和专用敏感字段;返回绑定后的业务请求。
- `DELETE /ai/plans/:id`:取消尚未执行的步骤。
前端以 `x-classhelper-ai-step` 关联既有业务接口。服务端核对操作者、方法、路径、查询和正文后原子领取步骤,再由原接口执行完整鉴权。上传另核对文件哈希;已成功步骤返回保存的结果,不重复操作。连接中断或结果不明的步骤需先核对业务状态。自动化入口为 `pnpm verify:ai`,仅使用隔离库和模型 stub。
+15
View File
@@ -25,6 +25,8 @@ ClassHelper 是 pnpm workspace:Express/Prisma/Socket.IO 服务端、Vue Web
| `packages/desktop-client/src/island/` | 经典岛、自定义运行时、课程与课件提醒 | | `packages/desktop-client/src/island/` | 经典岛、自定义运行时、课程与课件提醒 |
| `packages/desktop-client/src/renderer/` | 主窗口页面、状态、IndexedDB 与岛桥接 | | `packages/desktop-client/src/renderer/` | 主窗口页面、状态、IndexedDB 与岛桥接 |
| `scripts/` / `deploy/` | 验证、版本、打包、部署与运维 | | `scripts/` / `deploy/` | 验证、版本、打包、部署与运维 |
| `packages/data/` | 运行期数据,非 workspace 包 |
| `prompts/` | 任务提示词与历史交付记录 |
| `docs/` / `website/` | 文档站与官网,Pages 构建时拼接 | | `docs/` / `website/` | 文档站与官网,Pages 构建时拼接 |
## 模块与数据流 ## 模块与数据流
@@ -37,6 +39,19 @@ ClassHelper 是 pnpm workspace:Express/Prisma/Socket.IO 服务端、Vue Web
客户端先维护 IndexedDB 缓存,断网读取缓存;主窗口通过 preload 与主进程通信,主进程管理唯一原生岛窗口。 客户端先维护 IndexedDB 缓存,断网读取缓存;主窗口通过 preload 与主进程通信,主进程管理唯一原生岛窗口。
课件先流式上传到服务端文件目录,再由客户端下载、验摘要并独立回执。 课件先流式上传到服务端文件目录,再由客户端下载、验摘要并独立回执。
客户端统一更新由服务端缓存安装包、校验设备权限并通过心跳下发。客户端下载并校验 SHA256 后,
把安装交给独立的 Windows 原生助手;助手从本机 `updates` 目录运行,再次验包并确认就绪,
主进程复核更新策略后才退出。助手等待旧进程结束、执行安装并检查安装版的新版本及启动状态,
失败写入 `install-result.json` 并尝试恢复客户端;成功仍以新版心跳为最终回执。
排障日志为同目录下的 `install-helper.log`。Windows 构建使用系统 .NET Framework 编译器生成助手,
教室机运行时不需要安装开发工具;助手与安装包均随客户端构建,不能只替换主进程 JS。
更新专项验证使用 `pnpm verify:update-download`、Windows 下的 `pnpm verify:update-installer`。
显式执行 `pnpm verify:client-update:real` 会创建临时数据库、班级和独立应用标识,真实安装并升级
测试副本,再卸载测试安装,报告保存在 `.cache/client-update-real/`;它不属于普通冒烟,
不会使用真实班级或桌面自动化,也不修改根版本号。
传入 `--portable --unicode-paths --prefix-version` 可覆盖便携运行转安装版、中文空格路径和带 `v` 的目标版本号。
## 工程边界 ## 工程边界
- 三端契约只放 shared,改后先 `pnpm build:shared`。 - 三端契约只放 shared,改后先 `pnpm build:shared`。
+56 -35
View File
@@ -10,41 +10,43 @@ description: 现行模型职责、迁移与快照边界。
## 模型职责 ## 模型职责
| 模型 | 职责 | | 模型 | 职责 |
| ---------------------- | -------------------------------------------------- | | ---------------------- | --------------------------------------------------- |
| `User` | 教师与管理员账号;学生不在此表,班级凭据在 Class | | `User` | 教师与管理员账号;学生不在此表,班级凭据在 Class |
| `Student` | 学生名单、学号、在读/转出/毕业状态,无密码和角色 | | `Student` | 学生名单、学号、在读/转出/毕业状态,无密码和角色 |
| `StudentClassTransfer` | 调班与转出历史,保留班级/姓名快照 | | `StudentClassTransfer` | 生命周期历史,kind/batchId/学年/班级年级及学校快照 |
| `ArchivedYear` | 毕业届别与统计快照 | | `ArchivedYear` | 毕业届别与统计快照 |
| `TermWeek` | 逐周日期区间,classId 空串为全校默认 | | `TermWeek` | 逐周日期区间,classId 空串为全校默认 |
| `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 | | `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 |
| `Course` | 班级+科目+教师任课关系,含简称和室外标记 | | `Course` | 班级+科目+教师任课关系,含简称和室外标记 |
| `Schedule` | 旧课表迁移审计来源,现行接口不再以它为业务真值 | | `Schedule` | 旧课表迁移审计来源,现行接口不再以它为业务真值 |
| `Homework` | 作业与本地 assignDate;dueAt 为遗留列 | | `Homework` | 作业与本地 assignDate;dueAt 为遗留列 |
| `HomeworkStatus` | 按 studentId 记录作业完成状态 | | `HomeworkStatus` | 按 studentId 记录作业完成状态 |
| `Notification` | 通知/叫人记录、优先级与本地 assignDate | | `Notification` | 通知/叫人记录、优先级与本地 assignDate |
| `NotificationRead` | 按 studentId 记录已读 | | `NotificationRead` | 按 studentId 记录已读 |
| `TimeLayout` | 共享或班级自有时间表;旧 items JSON 保留迁移审计 | | `TimeLayout` | 共享或班级自有时间表;旧 items JSON 保留迁移审计 |
| `Grade` | studentId、课程、考试、分数和等级 | | `Grade` | studentId、课程、考试、分数和等级 |
| `PermissionGroup` | 默认/自定义/岗位组及 scope/scopeValue | | `PermissionAudit` | 权限与人工升级审计,操作人和前后 JSON,不建账号外键 |
| `PermissionGroupItem` | 组内权限键 | | `PermissionGroup` | 岗位模板与建议 scope/scopeValue |
| `UserPermissionGroup` | 账号与组的多对多分配 | | `PermissionGroupItem` | 组内权限键 |
| `AppSetting` | 周次、升级、AI 和系统设置 | | `UserPermissionGroup` | 账号与模板的分配及实际 scope/scopeValue |
| `ClientDevice` | deviceKey、心跳、更新目标与状态 | | `AppSetting` | 周次、升级、AI 和系统设置 |
| `ClientCommand` | 白名单远控、有效期与执行回执 | | `ClientDevice` | deviceKey、心跳、更新目标与状态 |
| `ClientRelease` | 服务端缓存安装包、SHA256 与大小 | | `ClientCommand` | 白名单远控、有效期与执行回执 |
| `AiAudit` | 助手解析审计,不保存 API Key | | `ClientRelease` | 服务端缓存安装包、SHA256 与大小 |
| `Exam` | 考试名称与是否计入总分 | | `AiAudit` | 助手解析审计,不保存 API Key |
| `TimeLayoutItem` | 有序时间点及类型,被课程显式引用 | | `Exam` | 考试名称与是否计入总分 |
| `ClassPlanGroup` | 班级课表群组、全局/默认标记 | | `TimeLayoutItem` | 有序时间点及类型,被课程显式引用 |
| `ClassPlan` | 日课表、时间表、轮换、启用与临时层规则 | | `ClassPlanGroup` | 班级课表群组、全局/默认标记 |
| `ClassPlanEntry` | 日课表与时间点、课程的外键关联、空课/停用/换课标记 | | `ClassPlan` | 日课表、时间表、轮换、启用与临时层规则 |
| `ScheduledClassPlan` | 按本地日期预定日课表 | | `ClassPlanEntry` | 日课表与时间点、课程的外键关联、空课/停用/换课标记 |
| `PromotionRun` | 年度升级幂等与审计 | | `ScheduledClassPlan` | 按本地日期预定日课表 |
| `Courseware` | 文件元数据、上传教师、存储路径与 SHA256 | | `PromotionRun` | 年度升级幂等与审计 |
| `CoursewareVisibility` | 课件可见班级 | | `Courseware` | 文件元数据、上传教师、存储路径与 SHA256 |
| `CoursewarePush` | 按班级的推送任务 | | `CoursewareFolder` | 教师自建分类目录,按上传者隔离 |
| `CoursewareReceipt` | 按设备的课件接收回执 | | `CoursewareVisibility` | 课件可见班级 |
| `CoursewarePush` | 按班级的推送任务 |
| `CoursewareReceipt` | 按设备的课件接收回执 |
学生和账号分离:Student 没有密码/角色;教师/管理员存 User,CLASS_DEVICE 只是 Class 登录形成的会话。 学生和账号分离:Student 没有密码/角色;教师/管理员存 User,CLASS_DEVICE 只是 Class 登录形成的会话。
任课关系只在 Course;班主任关系在 Class.teacherId,可以与任课关系指向同一账号。 任课关系只在 Course;班主任关系在 Class.teacherId,可以与任课关系指向同一账号。
@@ -72,3 +74,22 @@ User.careMode 是预留列;当前 Web 偏好在 localStorage,客户端偏好
2. 核对外键级联与删除护栏,特别是教师的班级、课程、作业、通知和课件。 2. 核对外键级联与删除护栏,特别是教师的班级、课程、作业、通知和课件。
3. 在临时库验证新建和旧库升级;不对真实业务库运行 seed/reset。 3. 在临时库验证新建和旧库升级;不对真实业务库运行 seed/reset。
4. 重新生成 Prisma Client,并按修改范围执行[验收](testing.md)。 4. 重新生成 Prisma Client,并按修改范围执行[验收](testing.md)。
## 权限与生命周期迁移
`20261023000000_promotion_permission` 为已初始化的 ADMIN 默认组补 promotion:manage;默认组尚未创建时允许不插入,由运行时模板创建。
`20261023010000_student_lifecycle_audit` 增加 PermissionAudit、StudentClassTransfer 的批次/学年/班级年级/学校快照、ArchivedYear.inactiveCount、PromotionRun 的操作人/明细/摘要/错误。
旧 mode 按 single/batch → class-change、transfer-out → transfer-out、restore-transfer → restore 迁移后删除该列,避免双事实源。
旧行的新字符串为空,学年为空,统计默认零;不臆造无法恢复的历史年级或批次。
SNAPSHOT_TABLES 已加入 PermissionAudit,新增字段随模型导出。旧快照没有审计表可恢复为空,旧历史 mode 在恢复时转为 kind;
没有新增列的旧行使用 schema 默认值。执行记录与升级快照不自动清理。
升级计划存 AppSetting.term.promotionPlan,时间存 term.promotionAt,无需新增学校或学生账号模型。
## 授权分配迁移
`20261031000000_authz_assignments` 为 UserPermissionGroup 增加 scope(默认 TEACHING)与 scopeValue。先按旧模板范围回填分配,再将模板 SELF_CLASS/空值和 SELF_CLASS/HEAD 规范为 TEACHING/HEAD。教师默认模板建议范围固定 TEACHING;旧 ADMIN 默认模板与旧管理员专用键保留在库中,由运行时忽略。
同一成员可将同一模板分配到多个范围,唯一约束为 userId/groupId/scope/scopeValue。PermissionGroup 的范围列仅作建议,不参与已有分配求值。
快照表集合和版本 1 保持兼容。恢复旧模板时映射 SELF_CLASS;旧 UserPermissionGroup 没有范围列时按快照内对应模板推导,缺组回落 TEACHING。新快照按实际分配列恢复。真实库升级前先备份快照,隔离回归不替代真实库升级演练。
+16 -2
View File
@@ -18,10 +18,10 @@ description: 课表、周次、学年、岛、设备与课件的现行实现入
## 权限、成绩与年度升级 ## 权限、成绩与年度升级
默认权限组、岗位范围、科目写权限分别由 permissions/permission-scope/access 维护,范围并集不授予任课权。 能力、分配范围、业务关系统一由 lib/authz 的 principal/scope/relations/assert 维护;access 只提供带显式键的窄封装。ADMIN 固定全集,TEACHER 过滤管理员专用键。
全校周数上限在 `term.maxWeeks`,默认 30、允许 1–60;开学日和逐周区间支持全校与班级设置。 全校周数上限在 `term.maxWeeks`,默认 30、允许 1–60;开学日和逐周区间支持全校与班级设置。
个人成绩查询关闭后只返回服务端集体聚合,个人明细、原始全班成绩与排名拒绝读取;样本不足或稀疏分段抑制。 个人成绩查询关闭后只返回服务端集体聚合,个人明细、原始全班成绩与排名拒绝读取;样本不足或稀疏分段抑制。
年度升级由 `term.promotionAt` 和 `PromotionRun.year` 管理,先存快照;运行期到点执行,启动漏跑需管理员预览补跑。 年度升级由 `term.promotionPlan`、`term.promotionAt` 和 `PromotionRun.year` 管理,先存快照;运行期到点执行,启动漏跑需管理员预览补跑。
毕业班归档,其余升一级,新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。 毕业班归档,其余升一级,新班不复制任课关系。转出学生由 `lib/students.ts` 统一过滤。
## 岛与本机配置 ## 岛与本机配置
@@ -38,3 +38,17 @@ description: 课表、周次、学年、岛、设备与课件的现行实现入
更新从服务端缓存下载,客户端验 SHA256,按下发策略安装;远控白名单动作执行后回执,测试只用假执行器。 更新从服务端缓存下载,客户端验 SHA256,按下发策略安装;远控白名单动作执行后回执,测试只用假执行器。
课件上限 512 MB,服务端流式落盘后创建元数据和推送,客户端逐设备验摘要并回执,不自动运行文件。 课件上限 512 MB,服务端流式落盘后创建元数据和推送,客户端逐设备验摘要并回执,不自动运行文件。
JSON 快照含课件表,完整恢复还必须带文件实体目录。细节见[课件](../app/courseware.md)。 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 握手共用数据库身份加载;敏感权限与账号变更使旧订阅失效。事务路径传递同一数据库连接给授权断言,保留原/目标资源的校验。
+3 -3
View File
@@ -5,9 +5,9 @@ description: ClassHelper的架构、接口、数据模型、权限、动效层
# 开发文档 # 开发文档
ClassHelper是一个 **pnpm monorepo**,一份代码产出四个交付物: ClassHelper 是一个 **pnpm monorepo**,应用包含后端服务、Web 管理端与桌面客户端;共享契约是内部依赖包:
| 交付物 | 位置 | 形态 | | 组成 | 位置 | 形态 |
| ---------- | ------------------------- | --------------------------------------------------------------- | | ---------- | ------------------------- | --------------------------------------------------------------- |
| 后端服务 | `packages/server` | Express 5 + Prisma 7 + Socket.IO,接口前缀 `/api` | | 后端服务 | `packages/server` | Express 5 + Prisma 7 + Socket.IO,接口前缀 `/api` |
| Web 管理端 | `packages/web-admin` | Vue 3 + Vite + Element Plus(教师 / 管理员用,PWA 可安装) | | Web 管理端 | `packages/web-admin` | Vue 3 + Vite + Element Plus(教师 / 管理员用,PWA 可安装) |
@@ -23,7 +23,7 @@ ClassHelper是一个 **pnpm monorepo**,一份代码产出四个交付物:
后端服务(Express + Prisma) 后端服务(Express + Prisma)
│ 写库 + 按班级房间广播 │ 写库 + 按班级房间广播
▼ ▼
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI(含灵动岛) Socket.IO ──► class:{classId}:{channel} 房间 ──► 班级桌面客户端实时更新 UI(含灵动岛)
▲ │ ▲ │
└──── 老师下发的提醒 ◄──────┘ └──── 老师下发的提醒 ◄──────┘
+59 -50
View File
@@ -1,69 +1,78 @@
--- ---
title: 角色与权限 title: 角色与权限
description: 功能权限、岗位范围与班级科目边界。 description: 能力目录、岗位模板、分配范围与业务关系的授权契约。
--- ---
# 角色与权限 # 角色与权限
授权分为功能权限、数据范围和业务关系三层,任何一层拒绝都不能操作。 授权依次检查能力、该能力的数据范围、数据行上的业务关系。服务端统一入口为 `lib/authz/`,路由预检不能替代服务断言。共享目录 `PERMISSION_META` 提供分类、风险、关系提示、合法范围、标签和默认角色;完整键目录读取源码,不在文档维护固定数量。
shared 的 `permissions.ts` 定义键、标签、默认模板与班级关系规则;服务端 `lib/permissions.ts`、
`lib/permission-scope.ts`、`lib/access.ts` 分别计算生效键、查询范围和具体业务断言。
## 身份与权限组 ## 身份与模板
账号角色为 ADMIN、TEACHER;班级登录形成 CLASS_DEVICE 会话。学生是 Student 名单,不是账号。 | 主体 | 生效能力 |
HEAD/SUBJECT 是班级关系,级长/部长是岗位组,均不新增 User.role。 | -------------------- | -------------------------------------------------- |
| ADMIN | 固定拥有全部目录键及全校范围,忽略权限组 |
| TEACHER | 显式分配模板的可分配能力并集;管理员专用键永久无效 |
| 未显式分配的 TEACHER | 数据库教师默认模板与固定 TEACHING 范围 |
| CLASS_DEVICE | 空集;接口明确允许班级端并校验本班关系 |
| 情况 | 有效功能权限 | 学生是 Student 名单记录,没有账号。HEAD/SUBJECT 是班主任和科任关系,级长/部长是岗位模板,不增加 User.role。权限管理只允许 ADMIN;旧 ADMIN 默认模板保留存储但隐藏、忽略。
| ------------ | ----------------------------------------------------- |
| 已分配权限组 | 所有分组键的并集,可以比角色默认更少 |
| 没有分组 | 数据库对应角色的可编辑默认组 |
| ADMIN | 同上,始终额外保留 permission:manage 与 system:manage |
| CLASS_DEVICE | 空集;通过明确允许班级会话的接口与业务断言操作 |
每请求读取生效权限,编辑后无需等待令牌过期。内置组可改不可删,默认组不是写死的全权限快捷方式。 `PermissionGroup` 保存能力和新分配的建议范围,`UserPermissionGroup` 保存实际 `scope/scopeValue`。模板改建议范围不会改变已有分配;模板改能力会影响其成员。同一模板可分配不同范围,多条分配按键取并集。空分配恢复默认模板,界面不会将未分组成员自动转换成显式默认组。
路由使用 requirePermission(AND)、requireAnyPermission(OR),员工与班级端共享读取入口按 requireStaffPermission 等规则检查。
具体 API 的额外角色限制以模块路由和服务断言为准,不能把“默认只分配给管理员”写成所有接口硬编码 ADMIN。
## 数据范围与科目 ## 能力目录与范围
| 岗位/身份 | 范围 | 能力分为管理员专用、班级级、组织只读。管理员专用能力包括组织与账号维护、权限/系统/数据库、全局周次、全校时间表、升级归档、安装包管理等;具体清单以 `PERMISSION_META.kind` 为准。`teacher:read` 和 `update:check` 为组织只读,忽略班级范围。其余班级级能力按分配范围求值。
| ----------- | --------------------------------------------- |
| 管理员 | 全部班级;仍须功能键 |
| 班主任/教师 | 自己担任班主任或任课的班级,按分组 scope 收敛 |
| 级长 | 配置年级 |
| 部长 | 配置的一组年级,scopeValue 用逗号分隔 |
| 班级端 | 登录绑定班级 |
空年级/部配置不放行。设备写操作只合并含对应功能键的分组范围,不能借只读组扩权。 | 范围 | 语义 |
科目编辑再由 `assertCanManageSubjectContent` 检查:管理员可管理,教师仅自己任课科目,无科目内容归班主任。 | -------- | -------------------------- |
班主任不任教某科就不能改该科的作业或成绩;班级端只允许作业写入,不能写成绩。 | TEACHING | 本人担任班主任或任课的班级 |
| HEAD | 仅本人担任班主任的班级 |
| GRADE | 指定一个年级 |
| DIVISION | 指定多个年级 |
| ALL | 全校 |
| 业务 | 主要功能键与额外边界 | `parsePermissionScope` 统一校验范围。GRADE/DIVISION 必须选择已有年级或升级计划中的年级,范围值按逗号分隔、去重排序;其余范围值必须为空串。旧 SELF_CLASS 仅在迁移和旧快照恢复中映射为 TEACHING/HEAD,不是运行时枚举。
| ---------------- | ---------------------------------------------------------------------------- |
| 名单读取/管理 | roster:read / roster:manage;管理仍须管理员或本班班主任断言 |
| 教师列表/维护 | teacher:read / teacher:manage;导入名单另检查导入权限和角色 |
| 日课表写入 | schedule:write + 管理员/本班班主任 |
| 全校时间表写入 | timetable:manage;默认给 ADMIN |
| 作业/成绩 | homework:write / grade:write 或 grade:import,再按班级科目收口 |
| 通知/叫人 | notification:publish / call:create,再检查班级范围 |
| 课件 | courseware:read / courseware:write,上传和推送自己的文件还受本人授课班级约束 |
| 客户端维护/远控 | client:read、client:manage、remote:control,写操作按对应键范围 |
| 版本与安装包写入 | client:update;旧 client:update-push 不再作为写入口要求 |
| 数据库/系统/权限 | database:manage / system:manage / permission:manage |
完整键目录读取 `PERMISSION_KEYS`,不在文档维护固定键数。 `loadAuthPrincipal` 在请求主体上缓存只读能力和分配快照,没有可变的“当前权限键”。`classIdsFor(user, key)` 和 `classWhere(user, key)` 强制传键,无键或无授权返回空集合;不会合并其他能力的范围。`classWhere` 过滤 Class 表主键,下游子表使用明确的 classId 条件。
## 前端门控与成绩隐私 ## 关系与写入
Web 菜单属性来自路由,`meta.roles` 粗筛、`meta.permission` 细筛;先 ensurePermissions 再按生效集合判断。 | 操作 | 功能与关系 |
服务端仍检查功能、范围与业务关系,直接构造请求不能绕过。 | --------------------------------------------- | -------------------------------------------------------------------------------- |
岗位范围可以扩大读范围,不能自动扩大科目写权限,也不能替代课件的本人任课关系。 | 建班/删班/届别班号、班主任/任课分配、教师账号 | 管理员专用,记录审计;最后一个管理员不可降级或删除 |
班级成绩查询开关仅员工按业务权限修改;关闭后班级端仍看集体聚合,个人明细、原始全班成绩和排名返回拒绝。 | 班级账号 | class:account + 本班班主任,管理员例外;班级码只给班主任或管理员 |
稀疏分段与补集抑制,服务端不向客户端下发个人原始成绩再聚合。 | 班级学期设置/班级周次 | class:settings + 本班班主任,管理员例外 |
| 名单、日课表与课程写入 | 对应写键;TEACHING/HEAD 要求班主任,显式年级/部/全校范围允许范围内维护 |
| 学生/课表导入 | 导入键与相应写键同时满足;先校验全部班级再写,学生及任课导入使用事务 |
| 班级时间表写入 | schedule:write + 本班班主任;按存储 classId 校验,所有引用班级也要校验 |
| 全校时间表、全局周次 | 管理员;班级设置使用独立接口 |
| 作业/成绩写入 | assertContentWrite;有科目要求该科任教,无科目要求班主任;原科目与目标科目都检查 |
| 作业提交/未交名单 | homework:write + 同样的科目关系;班级端明确允许本班作业 |
| 通知/叫人 | 发布能力和范围,再检查班主任/任课关系;班级端限本班 |
| 通知删除 | notification:delete + 发布者/班主任/管理员 |
| 课件 | 本人文件、对应功能范围与本人授课班级共同约束,不赋予班主任同事文件访问权 |
## 设备维护 ALL 也不能替代班主任、任课、发布者关系,只有 ADMIN 无条件绕过关系。班级端可代录作业,不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接,不能因事务路径省略授权。
`/api/clients/heartbeat` 和命令回执供已登录设备使用,不依赖班级端的空权限集合;服务端校验 deviceKey 与班级归属。 `POST /courses` 会建立任课关系,仅管理员可新建。教师的日课表维护范围不授予建课或自分配任课资格;已有课程仍可按课表权限排课及维护外观。离线档案导入复用既有科目,新增占位科目按班主任归属,不采信导入文件中的教师姓名作为授权。
远控从管理端确认下发,客户端执行后回传真实结果。更新文件由服务端缓存,教室机验 SHA256,
按立即、放学后、空闲策略安装;关闭自动更新不会强制安装。详见[更新与升级](../management/upgrade.md)。 成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后,本班设备仍可获得集体聚合,个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护,服务端执行稀疏样本和补集抑制。
## 实时与设备
班级房间为 `class:{id}:{channel}`,事件映射见 `SOCKET_EVENT_CHANNELS`。班级端加入本班全部通道;教师按各域读键及范围加入,core 由 class:read/schedule:read 决定。显式订阅再次校验通道,握手与 HTTP 共用数据库身份加载;权限/账号变更断开旧订阅。
心跳、进度和命令回执只接受 CLASS_DEVICE,deviceKey 必须属于会话班级。远控只排队允许的系统指令,自动化始终假执行。安装包登记/删除使用管理员 client:update;班级推送使用 client:update-push。下载要求本班班级端或有范围的 client:read。版本与文件名在请求校验和路径构造两处拒绝不安全路径段。
## 权限页与审计
权限页默认展示成员与范围,每条分配独立选择范围,保存前预览新增/移除能力、每键合并范围、班级列表、混合范围提示、班主任专属提示和风险标记。模板页仅提供可分配能力,旧管理员键显示为停用。组织只读能力标注“不限班级”。路由用 `meta.permission` 检查读取能力;维护页面额外用 `meta.menuActions` 声明可执行动作,动作须在至少一个可读班级生效才显示侧栏、搜索及页签,有部分功能可操作就保留入口。`permissions/me.actionScopes` 结合范围和班主任、任课、发布者关系提供动作班级;班级管理动作另用 `manageScopes`。纯查看页面按读取能力展示,服务端始终做最终判定。
学期周次维护入口要求全校周次写能力或至少一个可维护的本班设置范围。非全校维护者进入后默认选择可编辑班级,仍可切换查看授权范围内的其他班级。
目录、模板、成员、分配预览和审计的公开契约见[API](api.md)。模板/分配和账号敏感操作写入 PermissionAudit;审计不保存密码明文或哈希。迁移与快照兼容见[数据模型](data-model.md)。
## 验证
`pnpm check:authz` 扫描旧授权符号和缺少显式键的查询,并接入 lint。`pnpm verify:authz` 使用临时 SQLite 验证接管班级、管理员提权、跨键借范围、科目改挂、跨班时间表/周次/导入、成绩隐私、通道订阅、设备冒用和旧快照等攻击场景。其他专项回归保留生命周期、课表、课件、设备与升级覆盖。验证不触及真实班级、不访问外网、不执行系统指令。
+14 -11
View File
@@ -5,22 +5,21 @@ description: 实际事件与房间、断线恢复和客户端提醒分工。
# 实时事件(Socket.IO) # 实时事件(Socket.IO)
连接使用 `io(url, { auth: { token } })`,服务端在握手校验 JWT。 连接使用 `io(url, { auth: { token } })`,服务端握手校验 JWT 并与 HTTP 共用数据库身份加载。
事件与房间定义在 shared 的 `constants.ts`,载荷类型在 shared 的 `types.ts`,以这些契约和发送点为准。 事件与房间定义在 shared 的 `constants.ts`,载荷类型在 shared 的 `types.ts`,以这些契约和发送点为准。
## 房间与定向推送 ## 房间与定向推送
| 房间 | 作用 | | 房间 | 作用 |
| --------------- | -------------------------------------------------- | | ------------------------- | -------------------------------------------------- |
| class:{classId} | 某班级的业务广播 | | class:{classId}:{channel} | 某班级对应读域的业务广播 |
| session:{id} | 会话定向名;员工 id 为账号 id,班级端 id 为班级 id | | session:{id} | 会话定向名;员工 id 为账号 id,班级端 id 为班级 id |
| role:{role} | 角色房间名,定义在共享常量 | | role:{role} | 角色房间名,定义在共享常量 |
| teacher:{id} | 教师房间名,定义在共享常量 | | teacher:{id} | 教师房间名,定义在共享常量 |
| students | 班级端连接的广播房间,代表全班,不是个人学生账号 | | students | 班级端连接的广播房间,代表全班,不是个人学生账号 |
| teachers | 教师和管理员连接的广播房间 | | teachers | 教师和管理员连接的广播房间 |
`realtime/socket.ts` 当前显式 join 可访问的 class 房间与 students/teachers 广播房间; `realtime/socket.ts` 按域加入授权班级房间,并加入 session/role 与 students/teachers 房间;connected 载荷列出实际已加入房间。
同时在 connected 载荷列出 session/role 名。不能把共享常量或该列表当成所有房间均已成功 join 的证明,实际订阅以 join 调用为准。
业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。 业务经 `realtime/bus.ts` 的 emitToClass/emitToSession/emitToRooms 推送。
叫人记录属于班级通知,并发送班级广播与班级会话定向事件;学生本身没有连接和个人房间。 叫人记录属于班级通知,并发送班级广播与班级会话定向事件;学生本身没有连接和个人房间。
@@ -47,3 +46,7 @@ description: 实际事件与房间、断线恢复和客户端提醒分工。
同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。 同步修改共享事件名与载荷、服务端发送点、Web `stores/realtime.ts`、客户端 `stores/realtime.ts` 及相关缓存/岛逻辑。
不要手写事件名;只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。 不要手写事件名;只改服务端会导致前端静默不刷新。涉及成绩时另检查隐私载荷和班级范围。
## 读域订阅
现行班级房间为 `class:{id}:{channel}`。channel 为 core/homework/notification/grade/courseware,事件映射来自 shared 的 SOCKET_EVENT_CHANNELS。旧 `class:{id}` 仅保留兼容名称,生产不订阅。班级端加入本班全部域;教师按对应读键和分配范围加入。`class:join` 接受旧 classId 字符串或 `{classId, channels}`,后者逐通道校验,有任一无权则拒绝整次请求。握手回查账号与角色,权限变更断开旧订阅。
+3 -1
View File
@@ -30,7 +30,7 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版
以上按发布改动范围执行;显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。 以上按发布改动范围执行;显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本,最新包核验完成后按用户要求清理旧归档。 完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本,最新包核验完成后按用户要求清理旧归档。
2026-10-18 工作区清理后,1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。 版本目录与清单以本次实际构建结果为准;历史清理记录不代表当前保留的版本。
## 产物与文件名 ## 产物与文件名
@@ -41,6 +41,8 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版
| releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-server-setup.exe | | releases/server/<版本>/安装包/ClassHelper 服务端-<版本>-x64-setup.exe | ClassHelper-<版本>-x64-server-setup.exe |
| releases/server/<版本>/linux-x64/classhelper-server-linux-x64-<版本>.tar.gz | 同名 | | 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; Linux 还需同名 .tar.gz.sha256。正式 Linux 包在 Linux runner 运行 pnpm dist:server:linux;
Windows 上的交叉构建仅作验证,可能缺目标平台的 Prisma engine。 Windows 上的交叉构建仅作验证,可能缺目标平台的 Prisma engine。
构建中间物可再生成,不将 win-unpacked、server staging 或解包副本当交付物保留。 构建中间物可再生成,不将 win-unpacked、server staging 或解包副本当交付物保留。
+27 -17
View File
@@ -10,23 +10,26 @@ description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
## 命令与前置条件 ## 命令与前置条件
| 命令 | 覆盖/前置条件 | | 命令 | 覆盖/前置条件 |
| ------------------------------------------------ | ----------------------------------------------------------------- | | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| pnpm lint / pnpm typecheck / pnpm check:icons | 静态检查;typecheck 会先构建 shared | | pnpm lint / pnpm typecheck / pnpm check:icons | 静态检查;typecheck 会先构建 shared |
| pnpm docs:check | docfx 严格构建,需 .NET SDK 与 docfx | | pnpm docs:check | docfx 严格构建,需 .NET SDK 与 docfx |
| pnpm verify:e2e | 自动临时 SQLite、种子和带前缀账号,启动随机端口服务;无需真实服务 | | pnpm verify:e2e | 自动临时 SQLite、种子和带前缀账号,启动随机端口服务;无需真实服务 |
| pnpm verify:web:isolated | 同上隔离服务,隐藏 Electron UI 回归;先构建 Web 产物 | | pnpm verify:web:isolated | 同上隔离服务,隐藏 Electron UI 回归;先构建 Web 产物 |
| pnpm verify:web | 连接已准备测试服务,需 Web 产物和测试管理员;不应指向业务服务 | | pnpm verify:web | 连接已准备测试服务,需 Web 产物和测试管理员;不应指向业务服务 |
| pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 | | pnpm verify:lifecycle | 临时 SQLite 验证权限治理、事务故障回滚、状态机、历史、多轨道、计划哈希和快照 |
| pnpm verify:courseware | 临时库和文件目录的课件专项,不向真实班级推送 | | pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 |
| pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 | | pnpm verify:courseware | 临时库和文件目录的课件专项,不向真实班级推送 |
| pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 | | pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 |
| pnpm verify:review-client | 无窗口逻辑回归 | | pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 |
| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务,使用 VERIFY_BASE_URL 等脚本参数 | | pnpm verify:review-client | 无窗口逻辑回归 |
| pnpm verify:desktop | 先 pnpm build:desktop;隐藏快速检查,独立 userData | | pnpm verify:review-api / pnpm verify:clients-api | 包装器自动创建临时 SQLite、账号和随机端口服务,无需手动准备服务 |
| pnpm verify:desktop:online | 显式联网,需要测试管理员并创建临时教师/班级 | | pnpm verify:authz | 隔离授权攻击矩阵,覆盖按键范围、身份、任课与实时订阅 |
| pnpm verify:desktop:visual | 显式使用桌面,完整岛几何/动画/透明度/截图检查 | | pnpm verify:audit | 隔离事务故障、任课自授权、并发已读、模型操作计数和 Service Worker 回归 |
| pnpm verify:packaged --exe <客户端EXE> | 默认快速离线,两次启动、packaged=true;--visual 才使用桌面 | | pnpm verify:desktop | 先 pnpm build:desktop;隐藏快速检查,独立 userData |
| pnpm verify:desktop:online | 显式联网,需要测试管理员并创建临时教师/班级 |
| pnpm verify:desktop:visual | 显式使用桌面,完整岛几何/动画/透明度/截图检查 |
| pnpm verify:packaged --exe <客户端EXE> | 默认快速离线,两次启动、packaged=true;--visual 才使用桌面 |
联网 packaged 使用 --online;调用方须预先准备隔离服务、临时教师和班级并显式注入凭据,该启动器不会自动创建它们。 联网 packaged 使用 --online;调用方须预先准备隔离服务、临时教师和班级并显式注入凭据,该启动器不会自动创建它们。
开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。 开发版 verify:desktop:online 则通过 provisionSmokeClass 创建和清理临时身份。--offline 保持离线。
@@ -42,6 +45,8 @@ pnpm check:icons
pnpm docs:check pnpm docs:check
pnpm verify:e2e pnpm verify:e2e
pnpm verify:v14 pnpm verify:v14
pnpm verify:lifecycle
pnpm verify:client-migrations
pnpm verify:courseware pnpm verify:courseware
pnpm build:desktop pnpm build:desktop
pnpm verify:desktop pnpm verify:desktop
@@ -59,6 +64,7 @@ pnpm verify:web:isolated
- 视觉用例需要真实桌面与稳定帧,先区分状态未稳定、窗口遮挡和实际回归,再针对原因重跑。 - 视觉用例需要真实桌面与稳定帧,先区分状态未稳定、窗口遮挡和实际回归,再针对原因重跑。
- Element Plus dialog 关闭后 DOM 仍保留,应检查 overlay 的可见状态。 - Element Plus dialog 关闭后 DOM 仍保留,应检查 overlay 的可见状态。
- 本地 HTTP 探测绕过代理;Prisma 生成物和 shared/dist 缺失时先补前置构建。 - 本地 HTTP 探测绕过代理;Prisma 生成物和 shared/dist 缺失时先补前置构建。
- 根类型检查按包串行控制峰值内存;Node 22 若出现 V8 原生内存错误,保留失败日志,使用满足 engines 的已安装 Node LTS 复验,记录实际版本。
## 截图 ## 截图
@@ -67,3 +73,7 @@ docs/images 为 README/文档展示图;docs/screenshots 为回归留档;webs
Web 采集入口 `website/tools/capture-shots.mjs`,先准备隔离测试服务和数据。 Web 采集入口 `website/tools/capture-shots.mjs`,先准备隔离测试服务和数据。
岛/客户端采集使用 smoke.mjs --visual,并按需 --online;ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。 岛/客户端采集使用 smoke.mjs --visual,并按需 --online;ISLAND_SHOTS_DIR 与 ELECTRON_CLIENT_SHOTS_DIR 指向临时目录。
日常 quick 模式不会生成完整视觉截图,不能把 quick 通过表述为动画/透明度已验证。 日常 quick 模式不会生成完整视觉截图,不能把 quick 通过表述为动画/透明度已验证。
权限与年度流程回归入口为 `scripts/verify-lifecycle.mjs`,为子进程指定临时库与测试密钥,不使用业务 .env 的登录凭据。
旧库升级脚本动态读取最新迁移,另建重构前夹具校验 ADMIN 默认组补键、历史 kind 映射、空组保留及重复启动。
事务回滚用 SQLite 触发器模拟历史写入失败,不能通过删除断言或放宽状态规则通过测试。
+10
View File
@@ -84,3 +84,13 @@ pnpm dist:win # 安装包 + 便携版(两个都是成品,没有中间的
- 服务器与教室机器之间能互相 ping 通吗?防火墙放行 4000 了吗? - 服务器与教室机器之间能互相 ping 通吗?防火墙放行 4000 了吗?
排查清单见[常见问题](../faq.md)。 排查清单见[常见问题](../faq.md)。
## 7. 接收统一更新
管理员在设备管理中缓存并推送客户端安装包,客户端会后台下载、校验文件,再按立即、放学后或空闲策略安装。
关闭本机自动更新后,不会执行服务端下发的安装。安装助手未能就绪时,旧客户端会继续运行并显示失败原因。
服务端下发的是安装版:便携运行的客户端接收更新后转为安装版,原便携文件不会原地替换,后续请使用安装版入口。
新版重新连接服务端后,设备管理中的更新状态才会变为完成。
已发布旧版若在拉起安装器时失败,需要先手动安装 1.4.2 以获得新的安装助手;服务端推送安装包不能替换旧客户端中已经损坏的交接逻辑。
+13 -9
View File
@@ -12,16 +12,16 @@ description: 登录、菜单分组、权限与移动布局。
侧栏按以下分组组织,具体页面由路由权限筛选,并支持浅色/深色和关怀模式。 侧栏按以下分组组织,具体页面由路由权限筛选,并支持浅色/深色和关怀模式。
| 分组 | 主要页面 | | 分组 | 主要页面 |
| ---------- | -------------------------------------------------- | | ---------- | ------------------------------------------------------------ |
| 工作台 | 仪表盘、AI 助手 | | 工作台 | 仪表盘、AI 助手 |
| 教学事务 | 课表、时间表与日课表编辑、作业、通知、课件、成绩 | | 教学事务 | 课表、时间表与日课表编辑、作业、通知、课件、成绩 |
| 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、毕业归档 | | 班级与人员 | 班级、学生、教师、只读学生名单、学期周次、学年升级、毕业归档 |
| 设备运维 | 客户端在线状态、命令、更新与安装策略 | | 设备运维 | 客户端在线状态、命令、更新与安装策略 |
| 系统管理 | 权限组、系统设置、大模型设置、数据库管理 | | 系统管理 | 权限组、系统设置、大模型设置、数据库管理 |
班级/学生/教师管理、学期周次、归档和数据库页面还有管理员角色门槛; 班级、学生、学期周次、学年升级和归档页面按各自生效权限开放;教师管理和数据库页面仍保留角色门槛。
教师只读名单、教学页与设备页按权限键和数据范围开放。 名单、教学页与设备页还按对应数据范围开放,写按钮需额外管理键。
每次操作服务端继续校验,不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。 每次操作服务端继续校验,不是显示菜单就能改所有班和科目。详见[角色与权限](../dev/permissions.md)。
顶栏提供本人密码、使用引导、检查更新与退出等入口。 顶栏提供本人密码、使用引导、检查更新与退出等入口。
@@ -32,3 +32,7 @@ description: 登录、菜单分组、权限与移动布局。
同局域网手机填写服务器局域网地址,不用 localhost;公网反代见[生产部署](../management/production.md)。 同局域网手机填写服务器局域网地址,不用 localhost;公网反代见[生产部署](../management/production.md)。
下一步:[建班级、排课表](setup-class.md)。 下一步:[建班级、排课表](setup-class.md)。
权限页选组会替代角色默认模板,保存前可查看新增/移除权限与影响成员;保留默认能力时同时选择同角色默认组。
名单页默认在读,历史状态与包含归档分开筛选;资料编辑、调班、转出、转入/复学各有专用入口。
学年升级先保存计划、预览阻断项和周次影响,再输入学年确认执行;执行记录保留快照与 SHA256。
+1
View File
@@ -25,6 +25,7 @@ Web 管理端有一个「数据库管理」页(`/database`,**仅管理员可
- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出; - 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出;
- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联,表清单与恢复顺序由 `lib/snapshot.ts` 统一维护; - 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联,表清单与恢复顺序由 `lib/snapshot.ts` 统一维护;
- 清空与重新写入属于同一事务;中途写入失败时回滚并保留原库。MySQL 的外键开关在该事务的同一连接上恢复,SQLite 在事务前后切换;
- 分批 `createMany` 写入。 - 分批 `createMany` 写入。
相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复;格式与缺失表由快照校验器检查。 相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复;格式与缺失表由快照校验器检查。
+2
View File
@@ -109,6 +109,8 @@ docker compose up -d
### 客户端(ClassHelper 班级端) ### 客户端(ClassHelper 班级端)
Web「客户端」可缓存安装包并推送目标版本,客户端从本服务下载并校验 SHA256,按立即、放学后或空闲策略安装。管理页显示下载字节与百分比、校验中、等待安装、安装中和失败原因。安装前先上报「正在更新,将会短暂离线」,新版上线后的心跳确认「已完成更新,版本 xxxx」;仅离线不会被判为更新成功。关闭自动更新的客户端会显示原因。
从 Releases 取新的 `setup.exe` 覆盖安装即可,配置在 `%APPDATA%`,不受影响。 从 Releases 取新的 `setup.exe` 覆盖安装即可,配置在 `%APPDATA%`,不受影响。
> 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录, > 如果你是在**自己维护的机器**上只替换了 `releases/` 里的产物、而没有同步到安装目录,
+19 -18
View File
@@ -8,24 +8,25 @@ description: 当前功能说明、开发契约与实现入口,避免重复维
本文为现行文档入口。功能规则在对应章节维护;源码行为发生变化时,同步修改对应章节。 本文为现行文档入口。功能规则在对应章节维护;源码行为发生变化时,同步修改对应章节。
旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。 旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。
| 主题 | 文档 | 工作区源码入口 | | 主题 | 文档 | 工作区源码入口 |
| ------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` | | 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` |
| 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` | | 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` |
| 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` | | 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` |
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/permission-scope.ts` | | 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/authz/`、`server/src/lib/permissions.ts` |
| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` | | 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` |
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` | | AI 助手 | [解析与确认发布](app/assistant.md) | `server/src/modules/ai/`、`web-admin/src/views/AssistantView.vue` |
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` | | 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` | | 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` | | 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` | | 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` |
| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` | | 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` |
| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` | | API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` |
| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` | | 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` |
| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` | | 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` |
| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` | | 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` |
| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 | | 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` |
| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 |
表中的包路径均相对仓库 `packages/`;脚本和部署目录相对仓库根。 表中的包路径均相对仓库 `packages/`;脚本和部署目录相对仓库根。
源码总入口:[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。 源码总入口:[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。
Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 35 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 94 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 131 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 139 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 93 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

+15 -6
View File
@@ -1,6 +1,6 @@
{ {
"name": "class-helper", "name": "class-helper",
"version": "1.4.0", "version": "1.4.4",
"private": true, "private": true,
"description": "ClassHelper - 班级信息管理系统(Web 管理端 + 后端服务 + 桌面客户端)", "description": "ClassHelper - 班级信息管理系统(Web 管理端 + 后端服务 + 桌面客户端)",
"packageManager": "pnpm@11.8.0", "packageManager": "pnpm@11.8.0",
@@ -16,8 +16,8 @@
"build": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && pnpm --filter @classhelper/desktop-client build", "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:desktop": "pnpm build:shared && pnpm --filter @classhelper/desktop-client build",
"check:icons": "node scripts/check-icons.mjs", "check:icons": "node scripts/check-icons.mjs",
"typecheck": "pnpm build:shared && pnpm -r --no-bail typecheck", "typecheck": "pnpm build:shared && pnpm -r --workspace-concurrency=1 --no-bail typecheck",
"lint": "eslint .", "lint": "node scripts/check-authz.mjs && eslint .",
"lint:fix": "eslint . --fix", "lint:fix": "eslint . --fix",
"format": "prettier --write \"**/*.{ts,js,mjs,cjs,vue,json,md,yaml,yml,css,scss,html}\"", "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}\"", "format:check": "prettier --check \"**/*.{ts,js,mjs,cjs,vue,json,md,yaml,yml,css,scss,html}\"",
@@ -29,12 +29,17 @@
"db:switch:mysql": "node scripts/use-database.mjs mysql", "db:switch:mysql": "node scripts/use-database.mjs mysql",
"db:switch:sqlite": "node scripts/use-database.mjs sqlite", "db:switch:sqlite": "node scripts/use-database.mjs sqlite",
"verify:e2e": "node scripts/verify-e2e-isolated.mjs", "verify:e2e": "node scripts/verify-e2e-isolated.mjs",
"verify:ai": "node scripts/verify-ai.mjs",
"verify:courseware": "node scripts/verify-courseware.mjs", "verify:courseware": "node scripts/verify-courseware.mjs",
"verify:v14": "node scripts/verify-v14.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: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-client": "node scripts/verify-review-client.mjs",
"verify:review-api": "node scripts/verify-review-api.mjs", "verify:review-api": "node scripts/verify-e2e-isolated.mjs --review-api",
"verify:clients-api": "node scripts/verify-clients-api.mjs", "verify:clients-api": "node scripts/verify-e2e-isolated.mjs --clients-api",
"verify:client-migrations": "node scripts/verify-client-migrations.mjs", "verify:client-migrations": "node scripts/verify-client-migrations.mjs",
"verify:desktop": "pnpm --filter @classhelper/desktop-client smoke", "verify:desktop": "pnpm --filter @classhelper/desktop-client smoke",
"verify:web": "node scripts/ui-smoke/run.mjs", "verify:web": "node scripts/ui-smoke/run.mjs",
@@ -53,7 +58,11 @@
"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:server:linux": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && node scripts/dist-server.mjs --platform linux",
"dist:all": "pnpm dist:server && pnpm dist:win", "dist:all": "pnpm dist:server && pnpm dist:win",
"verify:desktop:visual": "node packages/desktop-client/scripts/smoke.mjs --visual", "verify:desktop:visual": "node packages/desktop-client/scripts/smoke.mjs --visual",
"verify:desktop:online": "node packages/desktop-client/scripts/smoke.mjs --online" "verify:desktop:online": "node packages/desktop-client/scripts/smoke.mjs --online",
"verify:authz": "node scripts/verify-authz.mjs",
"verify:audit": "node scripts/verify-authz.mjs --audit && node scripts/verify-web-worker.mjs",
"check:authz": "node scripts/check-authz.mjs",
"verify:server-bootstrap": "node scripts/verify-server-bootstrap.mjs"
}, },
"devDependencies": { "devDependencies": {
"concurrently": "^10.0.5", "concurrently": "^10.0.5",
@@ -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);
}
}
+3 -2
View File
@@ -1,6 +1,6 @@
{ {
"name": "@classhelper/desktop-client", "name": "@classhelper/desktop-client",
"version": "1.4.0", "version": "1.4.4",
"private": true, "private": true,
"description": "ClassHelper EXE 客户端(Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存)", "description": "ClassHelper EXE 客户端(Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存)",
"author": "Class Helper", "author": "Class Helper",
@@ -24,7 +24,8 @@
"pinia": "^4.0.3", "pinia": "^4.0.3",
"socket.io-client": "^4.8.3", "socket.io-client": "^4.8.3",
"vue": "^3.5.42", "vue": "^3.5.42",
"vue-router": "^5.3.1" "vue-router": "^5.3.1",
"@classhelper/ui": "workspace:*"
}, },
"devDependencies": { "devDependencies": {
"@types/node": "^22.20.2", "@types/node": "^22.20.2",
@@ -6,8 +6,10 @@
import path from 'node:path'; import path from 'node:path';
import { fileURLToPath } from 'node:url'; import { fileURLToPath } from 'node:url';
import { build } from 'esbuild'; import { build } from 'esbuild';
import { buildUpdateHelper } from './build-update-helper.mjs';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
buildUpdateHelper(path.join(root, 'dist/main/update-helper.exe'));
const shared = { const shared = {
bundle: true, bundle: true,
@@ -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 },
);
}
@@ -3,10 +3,12 @@ import type { IslandComponentKind } from '@classhelper/shared';
defineProps<{ kind: IslandComponentKind }>(); defineProps<{ kind: IslandComponentKind }>();
const paths: Record<IslandComponentKind, string> = { const paths: Record<IslandComponentKind, string> = {
clock: 'M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0ZM12 7v5l3 2', 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', 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', schedule: 'M9 5h11M9 12h11M9 19h11M4 5h1m-1 7h1m-1 7h1',
countdown: 'M6 3h12M6 21h12M8 3v4l4 5-4 5v4m8-18v4l-4 5 4 5v4', countdown: 'M6 3h12M6 21h12M8 3v4l4 5-4 5v4m8-18v4l-4 5 4 5v4',
text: 'M5 6V4h14v2M12 4v16m-4 0h8', 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', separator: 'M12 4v16M5 8v8m14-8v8',
notification: 'M9 19a3 3 0 0 0 6 0M6 10a6 6 0 0 1 12 0v4l2 3H4l2-3v-4Z', 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', homework: 'M9 4H6a2 2 0 0 0-2 2v14h16V6a2 2 0 0 0-2-2h-3M9 3h6v4H9V3Zm-1 9h8m-8 4h5',
@@ -5,13 +5,16 @@ import {
resolveClassStatus, resolveClassStatus,
type IslandComponentNode, type IslandComponentNode,
type IslandState, type IslandState,
type IslandTimePointDto,
type ScheduleDto, type ScheduleDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
import WeatherBrief from './WeatherBrief.vue';
const props = defineProps<{ const props = defineProps<{
node: IslandComponentNode; node: IslandComponentNode;
state: IslandState; state: IslandState;
now: number; now: number;
schedules: ScheduleDto[]; schedules: ScheduleDto[];
timePoints: IslandTimePointDto[];
editing: boolean; editing: boolean;
selectedId: string; selectedId: string;
alertNodeId: string; alertNodeId: string;
@@ -38,20 +41,69 @@ function timeAt(time: string) {
d.setHours(h!, m!, 0, 0); d.setHours(h!, m!, 0, 0);
return d.getTime(); return d.getTime();
} }
const elapsed = computed(() => /**
current.value * 今天的时间点:优先用服务端下发的完整时间表(含课间/分割线/默认隐藏),
? Math.max( * 没有时回退到课表条目,保证旧服务端与离线缓存仍能显示课程。
0, */
Math.min( const dayPoints = computed<IslandTimePointDto[]>(() => {
1, const source = props.timePoints.length
(props.now - timeAt(current.value.startTime)) / ? props.timePoints
Math.max(1, timeAt(current.value.endTime) - timeAt(current.value.startTime)), : today.value.map<IslandTimePointDto>((s) => ({
), id: s.id,
) timeType: 'LESSON',
: 0, 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(() => const remaining = computed(() =>
current.value ? Math.max(0, Math.ceil((timeAt(current.value.endTime) - props.now) / 1000)) : 0, currentLesson.value ? Math.max(0, Math.ceil((timeAt(currentLesson.value.endTime) - props.now) / 1000)) : 0,
); );
const hidden = computed( const hidden = computed(
() => () =>
@@ -62,11 +114,11 @@ const hidden = computed(
(r) => (r) =>
(r === 'in-class' && props.state.inClass) || (r === 'in-class' && props.state.inClass) ||
(r === 'no-message' && !props.state.active) || (r === 'no-message' && !props.state.active) ||
(r === 'no-class' && !current.value), (r === 'no-class' && !currentLesson.value),
)), )),
); );
const visibleChildren = computed(() => const visibleChildren = computed(() =>
props.node.kind === 'slide' props.node.kind === 'slide' && !props.editing
? props.node.children.filter( ? props.node.children.filter(
(_, i) => (_, i) =>
i === i ===
@@ -95,6 +147,18 @@ const content = computed(() => {
.replaceAll('{course}', current.value?.course?.name || '暂无课程') .replaceAll('{course}', current.value?.course?.name || '暂无课程')
: n.settings.text; : n.settings.text;
if (n.kind === 'countdown') { 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 ending = n.settings.target === 'end' || (n.settings.target === 'auto' && !!current.value);
const time = const time =
n.settings.target === 'school' n.settings.target === 'school'
@@ -111,13 +175,6 @@ const content = computed(() => {
} }
return ''; return '';
}); });
const lessons = computed(() =>
props.node.settings.display === 'today'
? today.value.slice(0, props.node.settings.count)
: [props.node.settings.display === 'next' ? next.value : current.value || next.value].filter(
(s): s is ScheduleDto => Boolean(s),
),
);
const style = computed<CSSProperties>(() => { const style = computed<CSSProperties>(() => {
const n = props.node, const n = props.node,
a = n.appearance, a = n.appearance,
@@ -177,6 +234,7 @@ const style = computed<CSSProperties>(() => {
:state="state" :state="state"
:now="now" :now="now"
:schedules="schedules" :schedules="schedules"
:time-points="timePoints"
:editing="editing" :editing="editing"
:selected-id="selectedId" :selected-id="selectedId"
:alert-node-id="alertNodeId" :alert-node-id="alertNodeId"
@@ -188,26 +246,33 @@ const style = computed<CSSProperties>(() => {
</ComponentNode> </ComponentNode>
</template> </template>
<template v-else-if="node.kind === 'separator'"><span aria-hidden="true">│</span></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-else-if="node.kind === 'schedule'">
<div v-for="s in lessons" :key="s.id" class="lesson-line"> <template v-for="p in schedulePoints" :key="p.id">
<strong>{{ s.course?.name }}</strong> <span v-if="p.timeType === 'DIVIDER'" class="time-divider" aria-hidden="true">│</span>
<small v-if="node.settings.showPeriod" class="lesson-time">{{ s.startTime }}–{{ s.endTime }}</small> <div
<small v-if="node.settings.showProgress && current?.id === s.id" class="lesson-remaining"> v-else
距下课 {{ Math.floor(remaining / 60) }}:{{ String(remaining % 60).padStart(2, '0') }} class="lesson-line"
</small> :class="{ current: p.id === currentPoint?.id, break: p.timeType === 'BREAK' }"
</div> >
<span v-if="!lessons.length">暂无课程</span> <strong>{{ p.courseName || p.name || '—' }}</strong>
<div <small v-if="p.id === currentPoint?.id && node.settings.showPeriod" class="lesson-time">
v-if="current && node.settings.showProgress && node.settings.display !== 'next'" {{ p.startTime }}–{{ p.endTime }}
class="lesson-progress" </small>
role="progressbar" <span
:aria-valuenow="Math.round(elapsed * 100)" v-if="p.id === currentPoint?.id && p.timeType === 'LESSON' && node.settings.showProgress"
:aria-valuemin="0" class="lesson-progress"
:aria-valuemax="100" role="progressbar"
:aria-label="`${current.course?.name}课程进度,距下课${remaining}秒`" :aria-valuenow="Math.round(elapsed * 100)"
> aria-valuemin="0"
<i :style="{ transform: `scaleX(${elapsed})` }" /> aria-valuemax="100"
</div> :aria-label="`${p.courseName || '课程'}课程进度,距下课${remaining}秒`"
>
<i :style="{ transform: `scaleX(${elapsed})` }" />
</span>
</div>
</template>
<span v-if="!schedulePoints.length">暂无课程</span>
</template> </template>
<template v-else-if="['notification', 'homework', 'call'].includes(node.kind)"> <template v-else-if="['notification', 'homework', 'call'].includes(node.kind)">
<slot v-if="node.id === alertNodeId" name="alerts" /> <slot v-if="node.id === alertNodeId" name="alerts" />
@@ -238,11 +303,13 @@ const style = computed<CSSProperties>(() => {
white-space: nowrap; white-space: nowrap;
} }
.schedule > .lesson-line { .schedule > .lesson-line {
position: relative;
display: flex; display: flex;
flex-direction: row; flex-direction: row;
align-items: center; align-items: center;
justify-content: center; justify-content: center;
gap: 6px; gap: 6px;
padding-bottom: 3px;
} }
.lesson-line strong { .lesson-line strong {
min-width: 0; min-width: 0;
@@ -250,6 +317,21 @@ const style = computed<CSSProperties>(() => {
text-overflow: ellipsis; text-overflow: ellipsis;
white-space: nowrap; 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 { .lesson-time {
flex-shrink: 0; flex-shrink: 0;
font-variant-numeric: tabular-nums; font-variant-numeric: tabular-nums;
@@ -257,10 +339,11 @@ const style = computed<CSSProperties>(() => {
} }
.lesson-progress { .lesson-progress {
position: absolute; position: absolute;
inset: auto 4px 0; inset: auto 0 0;
height: 2px; height: 2px;
background: #ffffff24; background: #ffffff24;
overflow: hidden; overflow: hidden;
border-radius: 1px;
} }
.lesson-progress i { .lesson-progress i {
display: block; display: block;
@@ -272,12 +355,6 @@ const style = computed<CSSProperties>(() => {
.schedule > .lesson-line + .lesson-line { .schedule > .lesson-line + .lesson-line {
margin-top: 8px; margin-top: 8px;
} }
.lesson-remaining {
font-size: var(--secondary, 14px);
font-variant-numeric: tabular-nums;
opacity: 0.8;
white-space: nowrap;
}
.separator > span { .separator > span {
display: block; display: block;
width: 1px; width: 1px;
@@ -299,6 +376,9 @@ const style = computed<CSSProperties>(() => {
.rolling > :deep(.component-node) { .rolling > :deep(.component-node) {
animation: rolling var(--rolling-duration) linear infinite; animation: rolling var(--rolling-duration) linear infinite;
} }
.rolling.node-editing > :deep(.component-node) {
animation: none;
}
.selected { .selected {
outline: 2px solid #85aaff; outline: 2px solid #85aaff;
border-radius: 8px; border-radius: 8px;
@@ -6,6 +6,7 @@ import {
type IslandAppearance, type IslandAppearance,
type IslandLayoutSettings, type IslandLayoutSettings,
type IslandState, type IslandState,
type IslandTimePointDto,
type ScheduleDto, type ScheduleDto,
type IslandLessonReminder, type IslandLessonReminder,
} from '@classhelper/shared'; } from '@classhelper/shared';
@@ -20,6 +21,7 @@ const props = defineProps<{
settings: IslandLayoutSettings; settings: IslandLayoutSettings;
state: IslandState; state: IslandState;
schedules: ScheduleDto[]; schedules: ScheduleDto[];
timePoints: IslandTimePointDto[];
appearance: IslandAppearance; appearance: IslandAppearance;
nativeVisible: boolean; nativeVisible: boolean;
}>(); }>();
@@ -267,10 +269,19 @@ function visibility() {
void nextTick(reportHit); void nextTick(reportHit);
} }
// 不深度监听整份状态;只在目标内容/几何变化时测量,时钟每秒只改文本。 // 不深度监听整份状态;只在目标内容/几何变化时测量,时钟每秒只改文本。
watch([expanded, scheme, lesson, () => props.state.listExpanded, messages], measure, { watch(
deep: true, [
flush: 'post', expanded,
}); scheme,
lesson,
() => props.state.listExpanded,
messages,
() => props.timePoints,
() => Math.floor(now.value / 60_000),
],
measure,
{ deep: true, flush: 'post' },
);
watch( watch(
[fit, motion, expanded, lesson, () => props.appearance.radius, () => props.appearance.speed], [fit, motion, expanded, lesson, () => props.appearance.radius, () => props.appearance.speed],
() => { () => {
@@ -388,6 +399,7 @@ onUnmounted(() => {
:state="state" :state="state"
:now="now" :now="now"
:schedules="schedules" :schedules="schedules"
:time-points="timePoints"
:editing="false" :editing="false"
selected-id="" selected-id=""
alert-node-id="" alert-node-id=""
@@ -469,6 +481,7 @@ onUnmounted(() => {
:state="state" :state="state"
:now="now" :now="now"
:schedules="schedules" :schedules="schedules"
:time-points="timePoints"
:editing="false" :editing="false"
selected-id="" selected-id=""
alert-node-id="" alert-node-id=""
@@ -390,7 +390,7 @@ const islandClass = computed(() => ({
mode.value === 'hidden' && !appearance.value.idleSliver && !state.value.lessonReminder, mode.value === 'hidden' && !appearance.value.idleSliver && !state.value.lessonReminder,
'ci-lesson-card': !!state.value.lessonReminder, 'ci-lesson-card': !!state.value.lessonReminder,
'message-surface': !!state.value.active && mode.value !== 'hidden' && !state.value.lessonReminder, 'message-surface': !!state.value.active && mode.value !== 'hidden' && !state.value.lessonReminder,
sliver: mode.value === 'hidden' && appearance.value.idleSliver, sliver: mode.value === 'hidden' && appearance.value.idleSliver && !state.value.lessonReminder,
urgent: isUrgent.value, urgent: isUrgent.value,
call: isCall.value, call: isCall.value,
homework: isHomework.value, homework: isHomework.value,
@@ -5,6 +5,7 @@ import {
DEFAULT_ISLAND_APPEARANCE, DEFAULT_ISLAND_APPEARANCE,
type IslandAppearance, type IslandAppearance,
type IslandState, type IslandState,
type IslandTimePointDto,
type ScheduleDto, type ScheduleDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
import FixedIsland from './IslandApp.vue'; import FixedIsland from './IslandApp.vue';
@@ -14,6 +15,7 @@ import CustomIslandRuntime from './CustomIslandRuntime.vue';
const settings = ref(defaultIslandLayouts()), const settings = ref(defaultIslandLayouts()),
ready = ref(false); ready = ref(false);
const schedules = ref<ScheduleDto[]>([]); const schedules = ref<ScheduleDto[]>([]);
const timePoints = ref<IslandTimePointDto[]>([]);
const appearance = ref<IslandAppearance>({ ...DEFAULT_ISLAND_APPEARANCE }); const appearance = ref<IslandAppearance>({ ...DEFAULT_ISLAND_APPEARANCE });
const nativeVisible = ref(false); const nativeVisible = ref(false);
const resident = () => settings.value.layout === 'custom'; const resident = () => settings.value.layout === 'custom';
@@ -36,6 +38,7 @@ onMounted(async () => {
if (bridge) { if (bridge) {
bridge.onLayout((value) => (settings.value = value)); bridge.onLayout((value) => (settings.value = value));
bridge.onSchedules((value) => (schedules.value = value)); bridge.onSchedules((value) => (schedules.value = value));
bridge.onTimePoints((value) => (timePoints.value = value));
bridge.onState((value) => (state.value = value)); bridge.onState((value) => (state.value = value));
bridge.onAppearance((value) => (appearance.value = value)); bridge.onAppearance((value) => (appearance.value = value));
bridge.onVisibility((value) => (nativeVisible.value = value)); bridge.onVisibility((value) => (nativeVisible.value = value));
@@ -43,6 +46,7 @@ onMounted(async () => {
appearance.value = await bridge.getAppearance(); appearance.value = await bridge.getAppearance();
settings.value = await bridge.getLayout(); settings.value = await bridge.getLayout();
schedules.value = await bridge.getSchedules(); schedules.value = await bridge.getSchedules();
timePoints.value = await bridge.getTimePoints();
state.value = await bridge.getState(); state.value = await bridge.getState();
} }
await nextTick(); await nextTick();
@@ -55,9 +59,18 @@ onMounted(async () => {
:settings="settings" :settings="settings"
:state="state" :state="state"
:schedules="schedules" :schedules="schedules"
:time-points="timePoints"
:appearance="appearance" :appearance="appearance"
:native-visible="nativeVisible" :native-visible="nativeVisible"
/> />
<FixedIsland v-if="ready" v-show="!resident() && !state.coursewareTransfer" :suspended="resident() || !!state.coursewareTransfer" /> <FixedIsland
<CoursewareTransfer v-if="state.coursewareTransfer" :transfer="state.coursewareTransfer" :appearance="appearance" /> v-if="ready"
v-show="!resident() && !state.coursewareTransfer"
:suspended="resident() || !!state.coursewareTransfer"
/>
<CoursewareTransfer
v-if="state.coursewareTransfer"
:transfer="state.coursewareTransfer"
:appearance="appearance"
/>
</template> </template>
@@ -58,6 +58,7 @@ const time = computed(() =>
); );
const regions = ref([0, 0, 0, 0, 0]); const regions = ref([0, 0, 0, 0, 0]);
let frame = 0; let frame = 0;
let fallback: ReturnType<typeof setTimeout> | undefined;
// ClassIsland SlantedMaskControl:5 个斜切区域、30°偏移、两侧向中央打开,中央向两侧关闭。 // ClassIsland SlantedMaskControl:5 个斜切区域、30°偏移、两侧向中央打开,中央向两侧关闭。
const polygons = computed(() => { const polygons = computed(() => {
const offset = Math.tan(Math.PI / 6) * 40; const offset = Math.tan(Math.PI / 6) * 40;
@@ -71,12 +72,21 @@ const polygons = computed(() => {
}); });
function animateMask() { function animateMask() {
cancelAnimationFrame(frame); cancelAnimationFrame(frame);
clearTimeout(fallback);
const target = mask.value ? 1 : 0; const target = mask.value ? 1 : 0;
if (!props.motion) { if (!props.motion) {
regions.value = [target, target, target, target, target]; regions.value = [target, target, target, target, target];
return; return;
} }
const from = [...regions.value]; const from = [...regions.value];
// 隐藏窗口恢复或系统合成暂停时 rAF 可能停住,遮罩仍须在有限时间内成为可见实体。
fallback = setTimeout(
() => {
cancelAnimationFrame(frame);
regions.value = [target, target, target, target, target];
},
600 / Math.max(0.25, props.appearance.speed),
);
const started = performance.now(); const started = performance.now();
const delays = mask.value ? [0, 90, 120, 90, 0] : [120, 90, 0, 90, 120]; const delays = mask.value ? [0, 90, 120, 90, 0] : [120, 90, 0, 90, 120];
const update = (at: number) => { const update = (at: number) => {
@@ -109,6 +119,7 @@ onMounted(() => {
onUnmounted(() => { onUnmounted(() => {
observer?.disconnect(); observer?.disconnect();
cancelAnimationFrame(frame); cancelAnimationFrame(frame);
clearTimeout(fallback);
}); });
</script> </script>
@@ -137,7 +148,7 @@ onUnmounted(() => {
<strong>{{ leftSeconds }}</strong> <strong>{{ leftSeconds }}</strong>
秒 秒
</span> </span>
<span v-else class="ci-countdown">课间休息</span> <span v-else class="ci-countdown">{{ reminder.kind === 'on-class' ? '开始上课' : '课间休息' }}</span>
<span class="ci-lesson-course"> <span class="ci-lesson-course">
<span> <span>
{{ {{
@@ -146,8 +157,8 @@ onUnmounted(() => {
: '下节课是:' : '下节课是:'
}} }}
</span> </span>
<strong>{{ course }}</strong> <strong>{{ course || '今日课程已结束' }}</strong>
<small>{{ time }}</small> <small v-if="course">{{ time }}</small>
</span> </span>
</div> </div>
<div <div
@@ -194,8 +205,8 @@ onUnmounted(() => {
display: flex; display: flex;
align-items: center; align-items: center;
justify-content: center; justify-content: center;
gap: 24px; gap: 12px;
padding: 0 28px; padding: 0 14px;
white-space: nowrap; white-space: nowrap;
transition: opacity var(--ci-duration) ease-in; transition: opacity var(--ci-duration) ease-in;
} }
@@ -222,6 +233,7 @@ onUnmounted(() => {
text-overflow: ellipsis; text-overflow: ellipsis;
} }
.ci-lesson-course small { .ci-lesson-course small {
flex-shrink: 0;
font-size: 14px; font-size: 14px;
font-variant-numeric: tabular-nums; font-variant-numeric: tabular-nums;
} }
@@ -0,0 +1,91 @@
<script setup lang="ts">
import { computed, onUnmounted, ref, watch } from 'vue';
import type { IslandComponentNode, IslandWeather } from '@classhelper/shared';
const props = defineProps<{ settings: IslandComponentNode['settings'] }>();
const weather = ref<IslandWeather | null>(null),
loading = ref(false),
unavailable = ref(false);
const configured = computed(
() => typeof props.settings.latitude === 'number' && typeof props.settings.longitude === 'number',
);
let revision = 0;
async function refresh() {
const current = ++revision;
if (!configured.value) {
loading.value = false;
return;
}
loading.value = true;
try {
const bridge = window.island ?? window.desktop;
if (!bridge) throw new Error('仅桌面客户端可读取天气');
const result = await bridge.getIslandWeather({
latitude: props.settings.latitude!,
longitude: props.settings.longitude!,
});
if (current === revision) {
weather.value = result;
unavailable.value = false;
}
} catch {
if (current === revision) unavailable.value = true;
} finally {
if (current === revision) loading.value = false;
}
}
watch(
() => [props.settings.latitude, props.settings.longitude],
() => {
weather.value = null;
unavailable.value = false;
void refresh();
},
{ immediate: true },
);
const timer = setInterval(() => void refresh(), 60_000);
onUnmounted(() => {
clearInterval(timer);
revision++;
});
const description = computed(() => {
const code = weather.value?.code ?? -1;
if (code === 0) return '晴';
if (code <= 3 && code > 0) return ['少云', '多云', '阴'][code - 1];
if ([45, 48].includes(code)) return '雾';
if ([51, 53, 55, 56, 57].includes(code)) return '毛毛雨';
if ([61, 63, 65, 66, 67, 80, 81, 82].includes(code)) return '雨';
if ([71, 73, 75, 77, 85, 86].includes(code)) return '雪';
if ([95, 96, 99].includes(code)) return '雷雨';
return '天气';
});
const advice = computed(() => {
if (!weather.value) return '';
if (weather.value.code >= 95) return '雷雨天气,注意避雷';
if (weather.value.windSpeed >= 40) return '风力较大,注意出行';
return '';
});
</script>
<template>
<span
class="weather-brief"
:title="weather ? `Open-Meteo · ${new Date(weather.fetchedAt).toLocaleString('zh-CN')}\n${advice}` : ''"
>
<template v-if="weather">
{{ settings.locationName }} {{ description }} {{ Math.round(weather.temperature) }}°C
<span v-if="weather.stale || unavailable">· 缓存</span>
<small v-if="advice">{{ advice }}</small>
</template>
<template v-else>
{{ !configured ? '请设置天气地点' : loading ? '天气加载中…' : '天气暂不可用' }}
</template>
</span>
</template>
<style scoped>
.weather-brief {
white-space: nowrap;
}
small {
display: block;
font-size: var(--secondary, 12px);
}
</style>
@@ -1,3 +1,4 @@
import '@classhelper/ui/tokens.css';
import { createApp } from 'vue'; import { createApp } from 'vue';
import IslandApp from './LayoutIslandApp.vue'; import IslandApp from './LayoutIslandApp.vue';
import { applyMotionTokens } from '../renderer/composables/motion.js'; import { applyMotionTokens } from '../renderer/composables/motion.js';
+191 -32
View File
@@ -3,7 +3,6 @@ import crypto from 'node:crypto';
import fs from 'node:fs'; import fs from 'node:fs';
import fsp from 'node:fs/promises'; import fsp from 'node:fs/promises';
import path from 'node:path'; import path from 'node:path';
import { spawn } from 'node:child_process';
import { BrowserWindow, app } from 'electron'; import { BrowserWindow, app } from 'electron';
import { import {
isNewerVersion, isNewerVersion,
@@ -14,6 +13,27 @@ import {
import { getConfig, saveConfig } from './config.js'; import { getConfig, saveConfig } from './config.js';
import { island } from './island.js'; import { island } from './island.js';
import { logger } from './logger.js'; import { logger } from './logger.js';
import { connectionEvents } from './config-events.js';
import { prepareUpdateInstaller } from './update-installer.js';
let updateEpoch = 0;
let downloadAbort = new AbortController();
connectionEvents.on('changed', () => {
updateEpoch++;
downloadAbort.abort();
downloadAbort = new AbortController();
policy = null;
installationRetryAt = 0;
installResultChecked = false;
updateProgress = {
version: '',
stage: 'idle',
downloadedBytes: 0,
totalBytes: 0,
percent: null,
error: '',
};
});
/** /**
* 服务端统一下发的自动更新(下载 + 空闲时静默安装)。 * 服务端统一下发的自动更新(下载 + 空闲时静默安装)。
@@ -23,20 +43,31 @@ import { logger } from './logger.js';
* 空闲安装要求不在上课且主窗口隐藏满五分钟; * 空闲安装要求不在上课且主窗口隐藏满五分钟;
* 2. **下完先校验 sha256**:服务端给的哈希对不上就删掉文件、记 error,**不做任何信任放行** * 2. **下完先校验 sha256**:服务端给的哈希对不上就删掉文件、记 error,**不做任何信任放行**
* (宁可这次更新失败,也不能把一个来源不明的 exe 装到教室里); * (宁可这次更新失败,也不能把一个来源不明的 exe 装到教室里);
* 3. **安装脚本脱离本进程**:PowerShell 等旧进程退出、安装器完成后重新拉起应用, * 3. **独立安装助手**:助手就绪后才退出旧进程,由助手执行安装并确认新版启动;
* 本进程随即走既有退出路径退出(重启应用这件事交给安装脚本,而不是自己 `relaunch`, * 助手从更新目录运行,不锁住正在被安装器替换的应用文件。
* 否则会与"安装器正在覆盖自己"撞车 —— Windows 上正在运行的程序文件是删不掉的)。
*/ */
let policy: Pick<ClientHeartbeatResponse, 'updateTargetVersion' | 'updateMode' | 'updateNotBefore'> | null = let policy:
null; | (Pick<ClientHeartbeatResponse, 'updateTargetVersion' | 'updateMode' | 'updateNotBefore'> & {
serverUrl: string;
username: string;
updateSha256: string;
updateSize: number;
updateFileName: string;
})
| null = null;
function policyPath(): string { function policyPath(): string {
return path.join(pendingUpdateDir(), 'policy.json'); return path.join(pendingUpdateDir(), 'policy.json');
} }
function loadPolicy(): typeof policy { function loadPolicy(): typeof policy {
if (policy) return policy; if (policy)
return policy.serverUrl === getConfig().serverUrl && policy.username === getConfig().username
? policy
: null;
try { try {
policy = JSON.parse(fs.readFileSync(policyPath(), 'utf8')); policy = JSON.parse(fs.readFileSync(policyPath(), 'utf8'));
if (policy?.serverUrl !== getConfig().serverUrl || policy?.username !== getConfig().username)
policy = null;
} catch { } catch {
/* 尚无下发策略 */ /* 尚无下发策略 */
} }
@@ -58,10 +89,29 @@ function removeManagedInstaller(file: string): void {
/** 每次成功心跳先同步策略;取消或更换目标后旧包不得自行安装。 */ /** 每次成功心跳先同步策略;取消或更换目标后旧包不得自行安装。 */
export function syncUpdatePolicy(next: ClientHeartbeatResponse): void { export function syncUpdatePolicy(next: ClientHeartbeatResponse): void {
if (policy && policy.updateTargetVersion !== next.updateTargetVersion) {
installationRetryAt = 0;
updateEpoch++;
downloadAbort.abort();
downloadAbort = new AbortController();
updateProgress = {
version: next.updateTargetVersion || '',
stage: 'idle',
downloadedBytes: 0,
totalBytes: 0,
percent: null,
error: '',
};
}
policy = { policy = {
serverUrl: getConfig().serverUrl,
username: getConfig().username,
updateTargetVersion: next.updateTargetVersion, updateTargetVersion: next.updateTargetVersion,
updateMode: next.updateMode ?? 'idle', updateMode: next.updateMode ?? 'idle',
updateNotBefore: next.updateNotBefore ?? null, updateNotBefore: next.updateNotBefore ?? null,
updateSha256: next.update?.version === next.updateTargetVersion ? next.update.sha256 : '',
updateSize: next.update?.version === next.updateTargetVersion ? next.update.size : 0,
updateFileName: next.update?.version === next.updateTargetVersion ? next.update.fileName : '',
}; };
fs.mkdirSync(pendingUpdateDir(), { recursive: true }); fs.mkdirSync(pendingUpdateDir(), { recursive: true });
fs.writeFileSync(policyPath(), JSON.stringify(policy), 'utf8'); fs.writeFileSync(policyPath(), JSON.stringify(policy), 'utf8');
@@ -86,6 +136,8 @@ export function pendingUpdateDir(): string {
let mainWindowHiddenAt: number | null = null; let mainWindowHiddenAt: number | null = null;
/** 本进程是否已经发起过安装(防止心跳与 hide 事件重复触发) */ /** 本进程是否已经发起过安装(防止心跳与 hide 事件重复触发) */
let installing = false; let installing = false;
let installationRetryAt = 0;
let installResultChecked = false;
let updateProgress: ContractReleaseProgressDto = { let updateProgress: ContractReleaseProgressDto = {
version: '', version: '',
stage: 'idle', stage: 'idle',
@@ -95,12 +147,69 @@ let updateProgress: ContractReleaseProgressDto = {
error: '', error: '',
}; };
export function getUpdateProgress() { export function getUpdateProgress() {
if (!installResultChecked) {
installResultChecked = true;
const resultFile = path.join(pendingUpdateDir(), 'install-result.json');
try {
const result = JSON.parse(fs.readFileSync(resultFile, 'utf8').replace(/^\uFEFF/, ''));
if (
result.serverUrl === getConfig().serverUrl &&
result.username === getConfig().username &&
typeof result.version === 'string' &&
result.version === getConfig().pendingUpdateVersion &&
isNewerVersion(app.getVersion(), result.version) &&
typeof result.error === 'string' &&
result.error
) {
updateProgress = {
...updateProgress,
version: result.version,
stage: 'failed',
error: result.error.slice(0, 1000),
};
installationRetryAt = Date.now() + 5 * 60_000;
fs.rmSync(resultFile, { force: true });
}
} catch {
/* 尚未执行安装助手,或上一次已成功。 */
}
}
return { ...updateProgress }; return { ...updateProgress };
} }
let progressPublishedAt = 0; let progressPublishedAt = 0;
let reportAt = 0;
let reporting: Promise<boolean> = Promise.resolve(true);
/** 与心跳分离,按顺序上报;安装前等待该队列完成再退出。 */
function reportProgress(): Promise<boolean> {
const config = getConfig(),
snapshot = getUpdateProgress(),
epoch = updateEpoch;
if (!config.token || process.env.ELECTRON_SMOKE_TEST === '1') return Promise.resolve(true);
reporting = reporting
.catch(() => false)
.then(async () => {
if (epoch !== updateEpoch) return false;
try {
const response = await fetch(`${config.serverUrl}/api/clients/update-progress`, {
method: 'POST',
headers: { authorization: `Bearer ${config.token}`, 'content-type': 'application/json' },
body: JSON.stringify({ deviceKey: config.deviceKey, progress: snapshot }),
signal: AbortSignal.timeout(5000),
redirect: 'error',
});
if (!response.ok) logger.warn(`更新进度上报失败:HTTP ${response.status}`);
return response.ok;
} catch (error) {
logger.warn(`更新进度上报失败:${String(error)}`);
return false;
}
});
return reporting;
}
function publishProgress(patch: Partial<typeof updateProgress>) { function publishProgress(patch: Partial<typeof updateProgress>) {
const previousStage = updateProgress.stage; const previousStage = updateProgress.stage;
updateProgress = { ...updateProgress, ...patch }; updateProgress = { ...updateProgress, ...patch };
updateProgress.error = updateProgress.error.slice(0, 1000);
updateProgress.percent = updateProgress.totalBytes updateProgress.percent = updateProgress.totalBytes
? Math.min(100, Math.round((updateProgress.downloadedBytes / updateProgress.totalBytes) * 100)) ? Math.min(100, Math.round((updateProgress.downloadedBytes / updateProgress.totalBytes) * 100))
: null; : null;
@@ -108,6 +217,10 @@ function publishProgress(patch: Partial<typeof updateProgress>) {
progressPublishedAt = Date.now(); progressPublishedAt = Date.now();
for (const win of BrowserWindow.getAllWindows()) for (const win of BrowserWindow.getAllWindows())
if (!win.isDestroyed()) win.webContents.send('client:update-progress', getUpdateProgress()); if (!win.isDestroyed()) win.webContents.send('client:update-progress', getUpdateProgress());
if (previousStage !== updateProgress.stage || Date.now() - reportAt >= 2000) {
reportAt = Date.now();
void reportProgress();
}
} }
/** /**
* 退出本进程的回调(由 index.ts 注册成既有的 `quitApp()`)。 * 退出本进程的回调(由 index.ts 注册成既有的 `quitApp()`)。
@@ -175,6 +288,7 @@ export function shouldConsider(version: string): boolean {
* - 同一版本已经下载过(`pendingUpdateVersion` 命中且文件还在):跳过下载,直接尝试安装。 * - 同一版本已经下载过(`pendingUpdateVersion` 命中且文件还在):跳过下载,直接尝试安装。
*/ */
export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: string): Promise<void> { export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: string): Promise<void> {
const epoch = updateEpoch;
const version = targetVersion.trim() || info.version.trim(); const version = targetVersion.trim() || info.version.trim();
if (!shouldConsider(version)) { if (!shouldConsider(version)) {
logger.info(`忽略服务端下发的更新 ${version || '(未指定版本)'}:自动更新已在设置中关闭`); logger.info(`忽略服务端下发的更新 ${version || '(未指定版本)'}:自动更新已在设置中关闭`);
@@ -189,6 +303,13 @@ export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: s
if (config.pendingUpdateVersion === version) { if (config.pendingUpdateVersion === version) {
const existing = config.pendingUpdateFile; const existing = config.pendingUpdateFile;
if (existing && fs.existsSync(existing)) { if (existing && fs.existsSync(existing)) {
publishProgress({
version,
stage: 'waiting',
downloadedBytes: info.size,
totalBytes: info.size,
error: '',
});
logger.info(`更新 ${version} 早已下载完成,直接尝试安装`); logger.info(`更新 ${version} 早已下载完成,直接尝试安装`);
await maybeInstallPendingUpdate(); await maybeInstallPendingUpdate();
return; return;
@@ -222,7 +343,8 @@ export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: s
logger.info(`开始下载更新 ${version}(${info.fileName},${formatSize(info.size)})`); logger.info(`开始下载更新 ${version}(${info.fileName},${formatSize(info.size)})`);
const response = await fetch(url, { const response = await fetch(url, {
headers: { authorization: `Bearer ${token}` }, headers: { authorization: `Bearer ${token}` },
signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS), signal: AbortSignal.any([AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS), downloadAbort.signal]),
redirect: 'error',
}); });
if (!response.ok) { if (!response.ok) {
throw new Error(`下载失败:HTTP ${response.status}`); throw new Error(`下载失败:HTTP ${response.status}`);
@@ -235,13 +357,20 @@ export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: s
const handle = await fsp.open(temp, 'w'); const handle = await fsp.open(temp, 'w');
try { try {
for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) { for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) {
await handle.write(chunk); let offset = 0;
while (offset < chunk.byteLength) {
const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset);
if (!bytesWritten) throw new Error('更新包写入失败');
offset += bytesWritten;
}
publishProgress({ downloadedBytes: updateProgress.downloadedBytes + chunk.byteLength }); publishProgress({ downloadedBytes: updateProgress.downloadedBytes + chunk.byteLength });
} }
} finally { } finally {
await handle.close(); await handle.close();
} }
if (epoch !== updateEpoch) return;
if (info.size > 0 && updateProgress.downloadedBytes !== info.size) throw new Error('更新包长度不匹配');
publishProgress({ stage: 'verifying' }); publishProgress({ stage: 'verifying' });
const digest = await sha256File(temp); const digest = await sha256File(temp);
const expected = info.sha256.trim().toLowerCase(); const expected = info.sha256.trim().toLowerCase();
@@ -264,7 +393,7 @@ export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: s
await fsp.rm(target, { force: true }); await fsp.rm(target, { force: true });
await fsp.rename(temp, target); await fsp.rename(temp, target);
publishProgress({ stage: 'waiting' }); publishProgress({ stage: 'waiting' });
if (loadPolicy()?.updateTargetVersion !== version) { if (epoch !== updateEpoch || loadPolicy()?.updateTargetVersion !== version) {
removeManagedInstaller(target); removeManagedInstaller(target);
return; return;
} }
@@ -277,6 +406,7 @@ export async function considerUpdate(info: ClientUpdateInfoDto, targetVersion: s
await maybeInstallPendingUpdate(); await maybeInstallPendingUpdate();
} catch (error) { } catch (error) {
await fsp.rm(temp, { force: true }).catch(() => undefined); await fsp.rm(temp, { force: true }).catch(() => undefined);
if (epoch !== updateEpoch) return;
publishProgress({ stage: 'failed', error: String(error) }); publishProgress({ stage: 'failed', error: String(error) });
logger.error(`下载更新 ${version} 失败:${error instanceof Error ? error.message : String(error)}`); logger.error(`下载更新 ${version} 失败:${error instanceof Error ? error.message : String(error)}`);
} finally { } finally {
@@ -319,6 +449,7 @@ export async function maybeInstallPendingUpdate(): Promise<void> {
const courseware = island.getCoursewareTransfer(); const courseware = island.getCoursewareTransfer();
if (courseware && ['downloading', 'verifying'].includes(courseware.stage)) return; if (courseware && ['downloading', 'verifying'].includes(courseware.stage)) return;
if (installing) return; if (installing) return;
if (Date.now() < installationRetryAt) return;
if (process.env.ELECTRON_SMOKE_TEST === '1') return; if (process.env.ELECTRON_SMOKE_TEST === '1') return;
const config = getConfig(); const config = getConfig();
@@ -332,6 +463,14 @@ export async function maybeInstallPendingUpdate(): Promise<void> {
} }
const active = loadPolicy(); const active = loadPolicy();
if (!active || active.updateTargetVersion !== version) return; if (!active || active.updateTargetVersion !== version) return;
if (
!/^[0-9a-f]{64}$/i.test(active.updateSha256 ?? '') ||
active.updateSize <= 0 ||
active.updateFileName !== path.basename(installer)
) {
logger.warn(`更新 ${version} 尚无有效的服务端摘要,等待心跳重新确认安装包`);
return;
}
if (active.updateMode === 'after-school') { if (active.updateMode === 'after-school') {
const at = Date.parse(active.updateNotBefore ?? ''); const at = Date.parse(active.updateNotBefore ?? '');
if (!Number.isFinite(at) || Date.now() < at) return; if (!Number.isFinite(at) || Date.now() < at) return;
@@ -375,31 +514,48 @@ export async function maybeInstallPendingUpdate(): Promise<void> {
} }
installing = true; installing = true;
publishProgress({ stage: 'installing' }); const installEpoch = updateEpoch;
publishProgress({ version, stage: 'installing', error: '' });
const reported = await reporting;
if (!reported) {
installing = false;
publishProgress({ stage: 'waiting', error: '安装前状态尚未送达服务端,等待网络恢复后重试' });
return;
}
if (
installEpoch !== updateEpoch ||
loadPolicy()?.updateTargetVersion !== version ||
getConfig().autoUpdate === false
) {
installing = false;
return;
}
logger.info(`开始静默安装更新 ${version}:${installer}`); logger.info(`开始静默安装更新 ${version}:${installer}`);
try { try {
const exe = app.getPath('exe'); const exe = process.env.PORTABLE_EXECUTABLE_FILE || app.getPath('exe');
const quote = (value: string): string => "'" + value.replaceAll("'", "''") + "'"; const config = getConfig();
const script = const helper = await prepareUpdateInstaller({
`$ErrorActionPreference = 'Stop'; Wait-Process -Id ${process.pid} -ErrorAction SilentlyContinue; ` + directory: pendingUpdateDir(),
`$installer = Start-Process -FilePath ${quote(installer)} -ArgumentList '/S','--updated','--force-run' -Wait -PassThru; ` + installer,
`if ($installer.ExitCode -ne 0 -and (Test-Path -LiteralPath ${quote(exe)})) { Start-Process -FilePath ${quote(exe)} }`; version,
const encoded = Buffer.from(script, 'utf16le').toString('base64'); sha256: active.updateSha256,
const child = spawn( size: active.updateSize,
'powershell.exe', serverUrl: config.serverUrl,
['-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-EncodedCommand', encoded], username: config.username,
{ restartExe: exe,
detached: true, portable: Boolean(process.env.PORTABLE_EXECUTABLE_FILE),
stdio: 'ignore',
windowsHide: true,
},
);
await new Promise<void>((resolve, reject) => {
child.once('spawn', resolve);
child.once('error', reject);
}); });
child.unref(); if (
// 安装器从实际安装目录启动新版;免安装版的旧 exe 可能随退出消失,只在安装失败时尝试恢复它。 installEpoch !== updateEpoch ||
loadPolicy()?.updateTargetVersion !== version ||
getConfig().autoUpdate === false
) {
helper.cancel();
installing = false;
return;
}
helper.commit();
logger.info(`更新 ${version} 的独立安装助手已就绪,确认退出旧客户端`);
if (quitHandler) { if (quitHandler) {
quitHandler(); quitHandler();
} else { } else {
@@ -408,6 +564,9 @@ export async function maybeInstallPendingUpdate(): Promise<void> {
} }
} catch (error) { } catch (error) {
installing = false; installing = false;
if (installEpoch !== updateEpoch) return;
installationRetryAt = Date.now() + 5 * 60_000;
publishProgress({ stage: 'failed', error: String(error).slice(0, 1000) });
logger.error( logger.error(
`启动更新安装失败(将在下次满足安装条件时重试):${error instanceof Error ? error.message : String(error)}`, `启动更新安装失败(将在下次满足安装条件时重试):${error instanceof Error ? error.message : String(error)}`,
); );
@@ -15,7 +15,12 @@ import {
type ClientHeartbeatResponse, type ClientHeartbeatResponse,
type ClientUpdateInfoDto, type ClientUpdateInfoDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
import { maybeInstallPendingUpdate, considerUpdate, syncUpdatePolicy } from './auto-update.js'; import {
maybeInstallPendingUpdate,
considerUpdate,
syncUpdatePolicy,
getUpdateProgress,
} from './auto-update.js';
import { connectionEvents, type ConnectionEvent } from './config-events.js'; import { connectionEvents, type ConnectionEvent } from './config-events.js';
import { getConfig } from './config.js'; import { getConfig } from './config.js';
import { island } from './island.js'; import { island } from './island.js';
@@ -178,6 +183,7 @@ async function beat(): Promise<void> {
autoUpdate: config.autoUpdate !== false, autoUpdate: config.autoUpdate !== false,
pendingVersion: pendingVersionOrNull(), pendingVersion: pendingVersionOrNull(),
stateNote: currentStateNote(), stateNote: currentStateNote(),
updateProgress: getUpdateProgress(),
}; };
const response = await fetch(`${config.serverUrl}/api/clients/heartbeat`, { const response = await fetch(`${config.serverUrl}/api/clients/heartbeat`, {
method: 'POST', method: 'POST',
@@ -38,6 +38,7 @@ interface PersistedConfig {
homeworkPhrases?: string[]; homeworkPhrases?: string[];
/** 是否已看过初次启动引导(向后兼容:旧配置没有该字段视为没看过,首启弹一次) */ /** 是否已看过初次启动引导(向后兼容:旧配置没有该字段视为没看过,首启弹一次) */
onboardingDone?: boolean; onboardingDone?: boolean;
onboardingVersion?: number;
/** 界面主题(向后兼容:旧配置没有该字段用浅色) */ /** 界面主题(向后兼容:旧配置没有该字段用浅色) */
theme?: 'light' | 'dark'; theme?: 'light' | 'dark';
/** 主侧边栏是否折叠(向后兼容:旧配置没有该字段视为展开) */ /** 主侧边栏是否折叠(向后兼容:旧配置没有该字段视为展开) */
@@ -69,6 +70,7 @@ const DEFAULT_CONFIG: PersistedConfig = {
homeworkBoard: { ...DEFAULT_HOMEWORK_BOARD }, homeworkBoard: { ...DEFAULT_HOMEWORK_BOARD },
homeworkPhrases: [...HOMEWORK_PHRASE_DEFAULTS], homeworkPhrases: [...HOMEWORK_PHRASE_DEFAULTS],
onboardingDone: false, onboardingDone: false,
onboardingVersion: 0,
theme: 'light', theme: 'light',
sidebarCollapsed: false, sidebarCollapsed: false,
ignoredUpdateVersion: '', ignoredUpdateVersion: '',
@@ -210,6 +212,7 @@ function readPersistedFromDisk(): PersistedConfig {
homeworkBoard: normalizeHomeworkBoard(parsed.homeworkBoard), homeworkBoard: normalizeHomeworkBoard(parsed.homeworkBoard),
homeworkPhrases: normalizeHomeworkPhrases(parsed.homeworkPhrases), homeworkPhrases: normalizeHomeworkPhrases(parsed.homeworkPhrases),
onboardingDone: parsed.onboardingDone === true, onboardingDone: parsed.onboardingDone === true,
onboardingVersion: Number.isInteger(parsed.onboardingVersion) ? Number(parsed.onboardingVersion) : 0,
theme: normalizeTheme(parsed.theme), theme: normalizeTheme(parsed.theme),
sidebarCollapsed: parsed.sidebarCollapsed === true, sidebarCollapsed: parsed.sidebarCollapsed === true,
ignoredUpdateVersion: ignoredUpdateVersion:
@@ -373,6 +376,7 @@ function toDesktopConfig(state: ConfigCache): DesktopStoredConfig {
homeworkBoard: normalizeHomeworkBoard(persisted.homeworkBoard), homeworkBoard: normalizeHomeworkBoard(persisted.homeworkBoard),
homeworkPhrases: normalizeHomeworkPhrases(persisted.homeworkPhrases), homeworkPhrases: normalizeHomeworkPhrases(persisted.homeworkPhrases),
onboardingDone: persisted.onboardingDone === true, onboardingDone: persisted.onboardingDone === true,
onboardingVersion: persisted.onboardingVersion ?? 0,
theme: normalizeTheme(persisted.theme), theme: normalizeTheme(persisted.theme),
sidebarCollapsed: persisted.sidebarCollapsed === true, sidebarCollapsed: persisted.sidebarCollapsed === true,
ignoredUpdateVersion: persisted.ignoredUpdateVersion ?? '', ignoredUpdateVersion: persisted.ignoredUpdateVersion ?? '',
@@ -460,6 +464,11 @@ export function saveConfig(patch: Partial<DesktopStoredConfig>): DesktopStoredCo
if (patch.onboardingDone === true) { if (patch.onboardingDone === true) {
persisted.onboardingDone = true; persisted.onboardingDone = true;
} }
if (
Number.isInteger(patch.onboardingVersion) &&
Number(patch.onboardingVersion) > (persisted.onboardingVersion ?? 0)
)
persisted.onboardingVersion = Number(patch.onboardingVersion);
if (patch.theme !== undefined) { if (patch.theme !== undefined) {
persisted.theme = normalizeTheme(patch.theme); persisted.theme = normalizeTheme(patch.theme);
} }
+66 -4
View File
@@ -9,6 +9,8 @@ import { app, BrowserWindow, shell } from 'electron';
import { import {
COURSEWARE_MAX_BYTES, COURSEWARE_MAX_BYTES,
COURSEWARE_TRANSFER_TIMEOUT_MS, COURSEWARE_TRANSFER_TIMEOUT_MS,
coursewareArchivePath,
coursewarePathSegment,
type ApiResponse, type ApiResponse,
type CoursewareDto, type CoursewareDto,
type CoursewarePushDto, type CoursewarePushDto,
@@ -74,6 +76,34 @@ async function digest(file: string) {
for await (const chunk of fs.createReadStream(file)) hash.update(chunk); for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
return hash.digest('hex'); return hash.digest('hex');
} }
interface LocalCourseware {
item: CoursewareDto;
relativePath: string;
}
function localFile(root: string, relative: string) {
const file = path.resolve(root, relative);
if (!file.startsWith(path.resolve(root) + path.sep)) throw new Error('课件路径无效');
return file;
}
async function localRecord(id: string, root = scopeDirectory()): Promise<LocalCourseware | null> {
try {
return JSON.parse(await fsp.readFile(path.join(root, '.index', `${id}.json`), 'utf8'));
} catch {
return null;
}
}
export async function listLocalCourseware(): Promise<CoursewareDto[]> {
if (!getConfig().token) return [];
const root = scopeDirectory();
const startedEpoch = epoch;
const names = await fsp.readdir(path.join(root, '.index')).catch(() => []);
const result: CoursewareDto[] = [];
for (const name of names.filter((name) => /^[a-z0-9-]+\.json$/i.test(name))) {
const record = await localRecord(name.slice(0, -5), root);
if (record && fs.existsSync(localFile(root, record.relativePath))) result.push(record.item);
}
return startedEpoch === epoch ? result.sort((a, b) => b.createdAt.localeCompare(a.createdAt)) : [];
}
export function downloadCourseware(id: string): Promise<void> { export function downloadCourseware(id: string): Promise<void> {
checkId(id); checkId(id);
const startedEpoch = epoch, const startedEpoch = epoch,
@@ -99,10 +129,22 @@ export function downloadCourseware(id: string): Promise<void> {
!/^[a-f0-9]{64}$/.test(item.sha256) !/^[a-f0-9]{64}$/.test(item.sha256)
) )
throw new Error('课件文件信息无效'); throw new Error('课件文件信息无效');
const safeName = const root = scopeDirectory();
`_${item.name.replace(/[<>:"/\\|?*\u0000-\u001f]/g, '_').replace(/[. ]+$/, '')}`.slice(0, 182); const stored = await localRecord(id, root);
const dir = path.join(scopeDirectory(), id), let relativePath =
file = path.join(dir, safeName); stored?.relativePath ||
(item.archivePath || coursewareArchivePath(item.teacher.name, new Date(item.createdAt), item.name))
.split('/')
.map(coursewarePathSegment)
.join(path.sep);
let file = localFile(root, relativePath);
// 同秒、同名文件不得覆盖先前课件;重试通过本地索引始终定位同一文件。
if (!stored && fs.existsSync(file)) {
const ext = path.extname(file);
relativePath = relativePath.slice(0, relativePath.length - ext.length) + ` (${id})` + ext;
file = localFile(root, relativePath);
}
const dir = path.dirname(file);
partial = `${file}.part`; partial = `${file}.part`;
const base: CoursewareTransfer = { const base: CoursewareTransfer = {
id, id,
@@ -164,6 +206,17 @@ export function downloadCourseware(id: string): Promise<void> {
await fsp.rename(partial, file); await fsp.rename(partial, file);
} }
if (startedEpoch !== epoch) throw new Error('登录会话已切换'); if (startedEpoch !== epoch) throw new Error('登录会话已切换');
await fsp.mkdir(path.join(root, '.index'), { recursive: true });
const indexFile = path.join(root, '.index', `${id}.json`);
await fsp.writeFile(
`${indexFile}.part`,
JSON.stringify({
item: { ...item, archivePath: relativePath.split(path.sep).join('/') },
relativePath,
}),
'utf8',
);
await fsp.rename(`${indexFile}.part`, indexFile);
publish({ ...base, receivedBytes: item.size, progress: 100, stage: 'completed' }); publish({ ...base, receivedBytes: item.size, progress: 100, stage: 'completed' });
} catch (error) { } catch (error) {
if (partial) await fsp.rm(partial, { force: true }).catch(() => undefined); if (partial) await fsp.rm(partial, { force: true }).catch(() => undefined);
@@ -232,6 +285,15 @@ export async function pollCourseware() {
} }
export async function revealCourseware(id: string) { export async function revealCourseware(id: string) {
checkId(id); checkId(id);
if (!getConfig().token) throw new Error('请先登录班级账号');
const stored = await localRecord(id);
if (stored) {
const file = localFile(scopeDirectory(), stored.relativePath);
if (fs.existsSync(file)) {
shell.showItemInFolder(file);
return;
}
}
const dir = path.join(scopeDirectory(), id); const dir = path.join(scopeDirectory(), id);
const names = await fsp.readdir(dir).catch(() => []); const names = await fsp.readdir(dir).catch(() => []);
const file = names.find((name) => !name.endsWith('.part')); const file = names.find((name) => !name.endsWith('.part'));
+13 -2
View File
@@ -1,5 +1,12 @@
import { downloadCourseware, getCoursewareTransfer, pollCourseware, revealCourseware } from './courseware.js'; import {
downloadCourseware,
getCoursewareTransfer,
pollCourseware,
revealCourseware,
listLocalCourseware,
} from './courseware.js';
import { island } from './island.js'; import { island } from './island.js';
import { getIslandWeather } from './island-weather.js';
import { getUpdateProgress } from './auto-update.js'; import { getUpdateProgress } from './auto-update.js';
import { app, BrowserWindow, ipcMain, shell } from 'electron'; import { app, BrowserWindow, ipcMain, shell } from 'electron';
import type { UpdateInfo } from '@classhelper/shared'; import type { UpdateInfo } from '@classhelper/shared';
@@ -15,9 +22,13 @@ import type { DesktopAppInfo, DesktopStoredConfig } from '../types/desktop.js';
export { IPC_CHANNELS }; export { IPC_CHANNELS };
export function registerIpcHandlers(): void { export function registerIpcHandlers(): void {
ipcMain.handle('island:weather', (_event, coordinates: unknown) => getIslandWeather(coordinates));
ipcMain.handle('courseware:download', (_event, id: string) => downloadCourseware(id)); ipcMain.handle('courseware:download', (_event, id: string) => downloadCourseware(id));
ipcMain.handle('courseware:reveal', (_event, id: string) => revealCourseware(id)); ipcMain.handle('courseware:reveal', (_event, id: string) => revealCourseware(id));
ipcMain.handle('courseware:sync', () => { void pollCourseware(); }); ipcMain.handle('courseware:local-list', () => listLocalCourseware());
ipcMain.handle('courseware:sync', () => {
void pollCourseware();
});
ipcMain.handle('courseware:get-progress', () => getCoursewareTransfer()); ipcMain.handle('courseware:get-progress', () => getCoursewareTransfer());
ipcMain.handle('client:get-update-progress', () => getUpdateProgress()); ipcMain.handle('client:get-update-progress', () => getUpdateProgress());
ipcMain.handle(IPC_CHANNELS.getConfig, (): DesktopStoredConfig => getConfig()); ipcMain.handle(IPC_CHANNELS.getConfig, (): DesktopStoredConfig => getConfig());
@@ -0,0 +1,73 @@
import type { IslandWeather } from '@classhelper/shared';
const cache = new Map<string, { data: IslandWeather | null; retryAt: number }>();
const pending = new Map<string, Promise<IslandWeather>>();
/** 固定天气服务与数值坐标,不接受渲染层传入 URL。失败退避并保留本次运行的缓存。 */
export async function getIslandWeather(
input: unknown,
request: typeof fetch = fetch,
): Promise<IslandWeather> {
const coordinates = input as { latitude?: unknown; longitude?: unknown } | null;
const latitude = coordinates?.latitude,
longitude = coordinates?.longitude;
if (
typeof latitude !== 'number' ||
!Number.isFinite(latitude) ||
Math.abs(latitude) > 90 ||
typeof longitude !== 'number' ||
!Number.isFinite(longitude) ||
Math.abs(longitude) > 180
)
throw new Error('请设置有效的经纬度');
const key = `${latitude.toFixed(4)},${longitude.toFixed(4)}`;
const stored = cache.get(key);
if (stored && stored.retryAt > Date.now()) {
if (stored.data) return { ...stored.data, stale: Date.now() - stored.data.fetchedAt >= 15 * 60_000 };
throw new Error('天气暂不可用,稍后自动重试');
}
const running = pending.get(key);
if (running) return running;
const job = Promise.resolve().then(async () => {
try {
if (process.env.ELECTRON_SMOKE_TEST === '1' && request === fetch)
throw new Error('自动验收不访问外部天气服务');
const url = new URL('https://api.open-meteo.com/v1/forecast');
url.search = new URLSearchParams({
latitude: String(latitude),
longitude: String(longitude),
current: 'temperature_2m,weather_code,wind_speed_10m',
forecast_days: '1',
}).toString();
const response = await request(url, { signal: AbortSignal.timeout(8000), redirect: 'error' });
if (!response.ok) throw new Error('天气服务暂不可用');
const body = await response.text();
if (body.length > 64_000) throw new Error('天气响应过大');
const current = JSON.parse(body).current;
if (
![current?.temperature_2m, current?.weather_code, current?.wind_speed_10m].every(
(value) => typeof value === 'number' && Number.isFinite(value),
)
)
throw new Error('天气数据格式不正确');
const data: IslandWeather = {
temperature: current.temperature_2m,
code: current.weather_code,
windSpeed: current.wind_speed_10m,
fetchedAt: Date.now(),
stale: false,
};
cache.set(key, { data, retryAt: Date.now() + 15 * 60_000 });
return data;
} catch {
cache.set(key, { data: stored?.data ?? null, retryAt: Date.now() + 60_000 });
if (stored?.data) return { ...stored.data, stale: true };
throw new Error('天气暂不可用,请检查网络或坐标');
} finally {
pending.delete(key);
while (cache.size > 32) cache.delete(cache.keys().next().value!);
}
});
pending.set(key, job);
return job;
}
+37 -8
View File
@@ -1,4 +1,7 @@
import type { ScheduleDto as ContractScheduleDto } from '@classhelper/shared'; import type {
IslandTimePointDto as ContractIslandTimePointDto,
ScheduleDto as ContractScheduleDto,
} from '@classhelper/shared';
import path from 'node:path'; import path from 'node:path';
import { pathToFileURL } from 'node:url'; import { pathToFileURL } from 'node:url';
import { BrowserWindow, ipcMain, screen } from 'electron'; import { BrowserWindow, ipcMain, screen } from 'electron';
@@ -138,6 +141,7 @@ export interface IslandPushContext {
export interface IslandClassStatePayload { export interface IslandClassStatePayload {
schedules?: ContractScheduleDto[]; schedules?: ContractScheduleDto[];
timePoints?: ContractIslandTimePointDto[];
inClass: boolean; inClass: boolean;
currentPeriodEnd?: string | null; currentPeriodEnd?: string | null;
week?: number; week?: number;
@@ -195,7 +199,14 @@ class IslandController {
if (JSON.stringify(next) === JSON.stringify(this.lessonCue)) return; if (JSON.stringify(next) === JSON.stringify(this.lessonCue)) return;
this.lessonCue = next; this.lessonCue = next;
// 触摸窗口先放得下新横条,再下发内容;混合宽高变化也只能增大画布。 // 触摸窗口先放得下新横条,再下发内容;混合宽高变化也只能增大画布。
if (this.lessonShowing) this.syncTouchLayout(); if (this.lessonShowing) {
// 通知收回的延迟回调不能在课表提醒出现后再隐藏同一扇原生窗口。
if (this.closeTimer) clearTimeout(this.closeTimer);
this.closeTimer = null;
this.cancelFade();
this.syncResidentShape(true);
this.syncTouchLayout();
}
this.emit(); this.emit();
this.syncWindow(); this.syncWindow();
} }
@@ -357,14 +368,15 @@ class IslandController {
if (this.customTimer) clearTimeout(this.customTimer); if (this.customTimer) clearTimeout(this.customTimer);
this.customTimer = null; this.customTimer = null;
// 常驻岛只报告目标几何;窗口画布固定,禁止逐帧 setBounds 和两端尺寸防抖互相追赶。 // 常驻岛只报告目标几何;窗口画布固定,禁止逐帧 setBounds 和两端尺寸防抖互相追赶。
if ( const width = Math.ceil(value.width);
this.customSize.width !== Math.ceil(value.width) || const height = Math.ceil(value.height);
this.customSize.height !== Math.ceil(value.height) const changed = this.customSize.width !== width || this.customSize.height !== height;
) if (changed)
this.residentMotionUntil = this.residentMotionUntil =
Date.now() + (this.appearance.animations ? 600 / this.appearance.speed : 0); Date.now() + (this.appearance.animations ? 600 / this.appearance.speed : 0);
this.customSize = { width: Math.ceil(value.width), height: Math.ceil(value.height) }; this.customSize = { width, height };
this.syncResidentShape(true); // 时钟每分钟触发的重复测量尺寸没变,不要清空触摸形状(那 750ms 会漏掉点击)。
if (changed || !this.residentShaped) this.syncResidentShape(true);
return; return;
} }
if (this.customTimer) clearTimeout(this.customTimer); if (this.customTimer) clearTimeout(this.customTimer);
@@ -611,6 +623,7 @@ class IslandController {
// 首次进入时同步一次外观与状态,保证渲染进程不会停在初始默认值 // 首次进入时同步一次外观与状态,保证渲染进程不会停在初始默认值
this.emitAppearance(); this.emitAppearance();
this.win?.webContents.send('island:schedules', this.schedules); this.win?.webContents.send('island:schedules', this.schedules);
this.win?.webContents.send('island:time-points', this.timePoints);
this.emit(); this.emit();
if (this.residentEnabled) { if (this.residentEnabled) {
this.residentWasEnabled = true; this.residentWasEnabled = true;
@@ -627,6 +640,10 @@ class IslandController {
getSchedules(): ContractScheduleDto[] { getSchedules(): ContractScheduleDto[] {
return [...this.schedules]; return [...this.schedules];
} }
private timePoints: ContractIslandTimePointDto[] = [];
getTimePoints(): ContractIslandTimePointDto[] {
return [...this.timePoints];
}
getState(): IslandState { getState(): IslandState {
return { return {
@@ -853,6 +870,11 @@ class IslandController {
if (this.ready && this.win && !this.win.isDestroyed()) if (this.ready && this.win && !this.win.isDestroyed())
this.win.webContents.send('island:schedules', this.schedules); this.win.webContents.send('island:schedules', this.schedules);
} }
if (Array.isArray(payload.timePoints)) {
this.timePoints = payload.timePoints.slice(0, 100);
if (this.ready && this.win && !this.win.isDestroyed())
this.win.webContents.send('island:time-points', this.timePoints);
}
const wasInClass = this.state.inClass; const wasInClass = this.state.inClass;
this.state.inClass = payload.inClass; this.state.inClass = payload.inClass;
this.state.currentPeriodEnd = payload.currentPeriodEnd ?? null; this.state.currentPeriodEnd = payload.currentPeriodEnd ?? null;
@@ -1106,6 +1128,10 @@ class IslandController {
* 所以"窗口最终会隐藏"的既有断言(含轮询写法)不受影响。 * 所以"窗口最终会隐藏"的既有断言(含轮询写法)不受影响。
*/ */
private finishClose(): void { private finishClose(): void {
if (this.lessonShowing || this.coursewareShowing) {
this.setState({ mode: 'hidden', reason: null });
return;
}
// 动画期间又来了新消息 / 被显式唤起:这次收回归属于旧的一批,放弃收尾 // 动画期间又来了新消息 / 被显式唤起:这次收回归属于旧的一批,放弃收尾
if (this.state.mode !== 'pill' || this.state.reason !== 'closing') return; if (this.state.mode !== 'pill' || this.state.reason !== 'closing') return;
if (this.state.active || this.state.queued.length > 0) return; if (this.state.active || this.state.queued.length > 0) return;
@@ -2309,6 +2335,9 @@ export function registerIslandIpc(): void {
ipcMain.handle('island:get-schedules', (event) => ipcMain.handle('island:get-schedules', (event) =>
event.sender === island.getWindow()?.webContents ? island.getSchedules() : [], event.sender === island.getWindow()?.webContents ? island.getSchedules() : [],
); );
ipcMain.handle('island:get-time-points', (event) =>
event.sender === island.getWindow()?.webContents ? island.getTimePoints() : [],
);
ipcMain.handle('island:get-layout', () => getConfig().islandLayout); ipcMain.handle('island:get-layout', () => getConfig().islandLayout);
ipcMain.handle('island:save-layout', (_event, value: unknown) => { ipcMain.handle('island:save-layout', (_event, value: unknown) => {
const result = saveConfig({ islandLayout: normalizeIslandLayouts(value) }).islandLayout; const result = saveConfig({ islandLayout: normalizeIslandLayouts(value) }).islandLayout;
@@ -1,6 +1,5 @@
import { import {
dayKeyLocal, dayKeyLocal,
resolveClassStatus,
DEFAULT_LESSON_REMINDERS, DEFAULT_LESSON_REMINDERS,
type LessonReminderSettings, type LessonReminderSettings,
type IslandLessonReminder, type IslandLessonReminder,
@@ -23,16 +22,18 @@ export class LessonReminderTracker {
const at = now.getTime(); const at = now.getTime();
const keyOf = (s: ScheduleDto, kind: IslandLessonReminder['kind']) => const keyOf = (s: ScheduleDto, kind: IslandLessonReminder['kind']) =>
`${dayKeyLocal(now)}:${s.id}:${s.startTime}:${s.endTime}:${kind}`; `${dayKeyLocal(now)}:${s.id}:${s.startTime}:${s.endTime}:${kind}`;
const status = resolveClassStatus(schedules, now);
const timeAt = (time: string) => { const timeAt = (time: string) => {
const d = new Date(now); const d = new Date(now);
const [h, m] = time.split(':').map(Number); const [h, m, s = 0] = time.split(':').map(Number);
d.setHours(h!, m!, 0, 0); d.setHours(h!, m!, s, 0);
return d.getTime(); return d.getTime();
}; };
const today = schedules.filter((s) => s.dayOfWeek === (now.getDay() || 7)); const today = schedules
const current = today.find((s) => s.id === status.current?.scheduleId); .filter((s) => s.dayOfWeek === (now.getDay() || 7))
const next = today.find((s) => s.id === status.next?.scheduleId); .sort((a, b) => timeAt(a.startTime) - timeAt(b.startTime));
// 已解析日课表只按准确时间比较,避免带秒的课时提前触发或错过上课遮罩。
const current = today.find((s) => at >= timeAt(s.startTime) && at < timeAt(s.endTime));
const next = today.find((s) => timeAt(s.startTime) > at);
const ended = today const ended = today
.filter((s) => at >= timeAt(s.endTime) && at - timeAt(s.endTime) < 12_000) .filter((s) => at >= timeAt(s.endTime) && at - timeAt(s.endTime) < 12_000)
.sort((a, b) => b.endTime.localeCompare(a.endTime))[0]; .sort((a, b) => b.endTime.localeCompare(a.endTime))[0];
@@ -74,12 +75,14 @@ export class LessonReminderTracker {
const entered = this.current?.id === id && at >= this.current.startedAt ? this.current.startedAt : at; const entered = this.current?.id === id && at >= this.current.startedAt ? this.current.startedAt : at;
const start = timeAt(lesson.startTime); const start = timeAt(lesson.startTime);
const end = timeAt(lesson.endTime); const end = timeAt(lesson.endTime);
// 导入的 ClassIsland 时间点可能带秒;提醒条只显示到分钟,宽度保持稳定。
const clock = (value: string) => value.slice(0, 5);
return (this.current = { return (this.current = {
id, id,
kind, kind,
courseName: lesson.course?.name || '课程', courseName: lesson.course?.name || '课程',
startTime: lesson.startTime, startTime: clock(lesson.startTime),
endTime: lesson.endTime, endTime: clock(lesson.endTime),
startedAt: entered, startedAt: entered,
maskUntil: maskUntil:
kind === 'ending' || kind === 'in-class' kind === 'ending' || kind === 'in-class'
@@ -100,8 +103,8 @@ export class LessonReminderTracker {
lessonStartsAt: start, lessonStartsAt: start,
lessonEndsAt: end, lessonEndsAt: end,
nextCourseName: kind === 'break' ? next?.course?.name : undefined, nextCourseName: kind === 'break' ? next?.course?.name : undefined,
nextStartTime: kind === 'break' ? next?.startTime : undefined, nextStartTime: kind === 'break' && next ? clock(next.startTime) : undefined,
nextEndTime: kind === 'break' ? next?.endTime : undefined, nextEndTime: kind === 'break' && next ? clock(next.endTime) : undefined,
}); });
} }
} }
@@ -8,7 +8,7 @@ import { app } from 'electron';
import type { CoursewareDto } from '@classhelper/shared'; import type { CoursewareDto } from '@classhelper/shared';
import { defaultIslandLayouts } from '@classhelper/shared'; import { defaultIslandLayouts } from '@classhelper/shared';
import { getConfig, saveConfig } from './config.js'; import { getConfig, saveConfig } from './config.js';
import { downloadCourseware, getCoursewareTransfer } from './courseware.js'; import { downloadCourseware, getCoursewareTransfer, listLocalCourseware } from './courseware.js';
import { island } from './island.js'; import { island } from './island.js';
export async function verifyCoursewareSmoke( export async function verifyCoursewareSmoke(
check: (name: string, action: () => Promise<boolean | string> | boolean) => Promise<void>, check: (name: string, action: () => Promise<boolean | string> | boolean) => Promise<void>,
@@ -93,7 +93,7 @@ export async function verifyCoursewareSmoke(
}); });
await job; await job;
await check('课件校验完成后保存正式文件并显示完成', async () => { await check('课件校验完成后保存正式文件并显示完成', async () => {
const files = await localFiles(); const files = (await localFiles()).filter((file) => file.endsWith('.pptx'));
return ( return (
getCoursewareTransfer()?.stage === 'completed' && getCoursewareTransfer()?.stage === 'completed' &&
getCoursewareTransfer()?.progress === 100 && getCoursewareTransfer()?.progress === 100 &&
@@ -101,6 +101,18 @@ export async function verifyCoursewareSmoke(
(await fs.readFile(files[0]!)).equals(bytes) (await fs.readFile(files[0]!)).equals(bytes)
); );
}); });
await check('本机归档索引支持离线浏览且路径按教师年月日时间分类', async () => {
const saved = await listLocalCourseware();
const files = (await localFiles()).filter((file) => file.endsWith('.pptx'));
return (
saved.some((local) => local.id === item.id) &&
files.some((file) =>
/Teachers[\\/]临时课件教师[\\/]\d{4}[\\/]\d{2}[\\/]\d{2}[\\/]\d{2}-\d{2}-\d{2}[\\/]课件接收验证\.pptx$/.test(
file,
),
)
);
});
await check('已完整接收的相同课件不重复传输', async () => { await check('已完整接收的相同课件不重复传输', async () => {
await downloadCourseware(item.id); await downloadCourseware(item.id);
return downloads === 1; return downloads === 1;
@@ -3,7 +3,13 @@ import { BrowserWindow } from 'electron';
import path from 'node:path'; import path from 'node:path';
import { island } from './island.js'; import { island } from './island.js';
import { getConfig, saveConfig } from './config.js'; import { getConfig, saveConfig } from './config.js';
import { defaultIslandLayouts, ISLAND_SHADOW_PAD } from '@classhelper/shared'; import {
defaultIslandLayouts,
islandNode,
normalizeIslandLayouts,
ISLAND_SHADOW_PAD,
} from '@classhelper/shared';
import { getIslandWeather } from './island-weather.js';
import { verifyResidentSmoke } from './smoke-resident.js'; import { verifyResidentSmoke } from './smoke-resident.js';
export async function verifyLayoutSmoke( export async function verifyLayoutSmoke(
check: (name: string, action: () => Promise<boolean | string> | boolean) => Promise<void>, check: (name: string, action: () => Promise<boolean | string> | boolean) => Promise<void>,
@@ -38,12 +44,30 @@ export async function verifyLayoutSmoke(
editingBounds = win.getBounds(); editingBounds = win.getBounds();
await editor.webContents.executeJavaScript('window.__classhelperSmoke__.islandEditorSmoke(true)'); await editor.webContents.executeJavaScript('window.__classhelperSmoke__.islandEditorSmoke(true)');
await pause(); await pause();
if (process.env.ISLAND_SHOTS_DIR) {
fs.mkdirSync(process.env.ISLAND_SHOTS_DIR, { recursive: true });
const bounds = editor.getContentBounds();
editor.setContentSize(1600, 1000);
for (const theme of ['light', 'dark']) {
await editor.webContents.executeJavaScript(
`document.documentElement.classList.toggle('dark', ${theme === 'dark'})`,
);
await pause();
fs.writeFileSync(
path.join(process.env.ISLAND_SHOTS_DIR, `component-editor-${theme}.png`),
(await editor.webContents.capturePage()).toPNG(),
);
}
await editor.webContents.executeJavaScript(`document.documentElement.classList.remove('dark')`);
editor.setContentSize(bounds.width, bounds.height);
await pause();
}
return ( return (
(await editor.webContents.executeJavaScript( (await editor.webContents.executeJavaScript(
'location.hash.includes("/settings/island/editor") && Boolean(document.querySelector(".aside"))', 'location.hash.includes("/settings/island/editor") && Boolean(document.querySelector(".aside"))',
)) && )) &&
editor.webContents.executeJavaScript( editor.webContents.executeJavaScript(
`(() => { const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()==='新增行');b?.click();return Boolean(document.querySelector('.island-editor-page .el-card')) && !document.querySelector('.layout-editor, iframe'); })()`, `(() => { const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()==='新增行');b?.click();return document.querySelectorAll('.component-library > .component-options:first-of-type .library-item').length===11 && !document.querySelector('.layout-editor, iframe'); })()`,
) )
); );
}); });
@@ -66,12 +90,16 @@ export async function verifyLayoutSmoke(
return true; return true;
}); });
await check('组件可以包裹进容器且设置独立保存', async () => { await check('组件可以包裹进容器且设置独立保存', async () => {
await editor.webContents.executeJavaScript(
`document.querySelector('.node-handle[data-kind=clock]')?.click()`,
);
await pause();
await editor.webContents.executeJavaScript( await editor.webContents.executeJavaScript(
`document.querySelector('[data-action=wrap] .el-select__wrapper')?.click()`, `document.querySelector('[data-action=wrap] .el-select__wrapper')?.click()`,
); );
await pause(); await pause();
await editor.webContents.executeJavaScript( await editor.webContents.executeJavaScript(
`(() => { const option=[...document.querySelectorAll('.el-select-dropdown__item')].find(e=>e.textContent.trim()==='分组'); if(!option)throw Error('容器菜单未出现');option.click(); })()`, `(() => { const option=[...document.querySelectorAll('.el-select-dropdown__item')].find(e=>e.textContent.trim()==='分组容器'); if(!option)throw Error('容器菜单未出现');option.click(); })()`,
); );
await pause(); await pause();
return ( return (
@@ -108,6 +136,10 @@ export async function verifyLayoutSmoke(
return initial && appearance && advanced; return initial && appearance && advanced;
}); });
await check('主窗口编辑器的预览完整适配画布且不遮挡缩放控件', async () => { await check('主窗口编辑器的预览完整适配画布且不遮挡缩放控件', async () => {
await editor.webContents.executeJavaScript(
`document.querySelector('.el-drawer__close-btn')?.click();document.querySelector('.surface-actions button:last-child')?.click()`,
);
await pause();
return editor.webContents.executeJavaScript(`(() => { return editor.webContents.executeJavaScript(`(() => {
const canvas=document.querySelector('.preview-canvas')?.getBoundingClientRect(); const canvas=document.querySelector('.preview-canvas')?.getBoundingClientRect();
const footer=document.querySelector('.preview-toolbar')?.getBoundingClientRect(); const footer=document.querySelector('.preview-toolbar')?.getBoundingClientRect();
@@ -118,11 +150,214 @@ export async function verifyLayoutSmoke(
return editor.webContents.executeJavaScript(`(() => { return editor.webContents.executeJavaScript(`(() => {
const root=document.documentElement, wasDark=root.classList.contains('dark'); const root=document.documentElement, wasDark=root.classList.contains('dark');
root.classList.add('dark'); root.classList.add('dark');
const card=document.querySelector('.scheme-card'), style=getComputedStyle(card); const page=document.querySelector('.island-editor-page'), style=getComputedStyle(page);
const ok=style.getPropertyValue('--ch-text').trim() && !document.querySelector('.layout-editor, iframe') && document.querySelectorAll('.island-editor-page .el-card').length>=4; const ok=style.getPropertyValue('--ch-text').trim() && !document.querySelector('.layout-editor, iframe') && document.querySelector('.component-library .library-title') && document.querySelector('.scheme-controls');
root.classList.toggle('dark',wasDark);return Boolean(ok); root.classList.toggle('dark',wasDark);return Boolean(ok);
})()`); })()`);
}); });
await check('从常驻组件库拖入容器,阻止将父组件放进自己的后代', async () => {
await editor.webContents.executeJavaScript(
`document.querySelector('.surface-actions button:last-child')?.click()`,
);
await pause();
await editor.webContents.executeJavaScript(`(() => {
const source=document.querySelector('[data-library-kind=text]'), target=document.querySelector('.editor-component.container');
if(!source||!target)throw Error('缺少组件库或容器');
const r=target.getBoundingClientRect(), x=r.left+r.width/2, y=r.top+r.height/2;
source.dispatchEvent(new PointerEvent('pointerdown',{bubbles:true,pointerId:21,clientX:10,clientY:10}));
source.dispatchEvent(new PointerEvent('pointermove',{bubbles:true,pointerId:21,clientX:x,clientY:y}));
source.dispatchEvent(new PointerEvent('pointerup',{bubbles:true,pointerId:21,clientX:x,clientY:y}));
})()`);
await pause();
const group = getConfig()
.islandLayout.schemes[0]!.rows.flatMap((r) => r.nodes)
.find((n) => n.kind === 'group');
if (!group?.children.some((n) => n.kind === 'text')) throw Error('组件库内容没有进入容器');
const before = JSON.stringify(getConfig().islandLayout);
await editor.webContents.executeJavaScript(`(() => {
const source=document.querySelector('.editor-component.container > .node-handle'), target=document.querySelector('.editor-component.container .container-children .node-handle');
const r=target.getBoundingClientRect(), x=r.left+r.width/2, y=r.top+r.height/2;
source.dispatchEvent(new PointerEvent('pointerdown',{bubbles:true,pointerId:22,clientX:10,clientY:10}));
source.dispatchEvent(new PointerEvent('pointerup',{bubbles:true,pointerId:22,clientX:x,clientY:y}));
})()`);
await pause();
return before === JSON.stringify(getConfig().islandLayout);
});
await check('常态与无通知展开内容分别保存,日期倒计时可配置并预览', async () => {
const before = JSON.stringify(getConfig().islandLayout.schemes[0]!.rows);
await editor.webContents.executeJavaScript(
`document.querySelectorAll('.surface-tabs button')[1].click();document.querySelector('[data-library-kind=countdown]').click()`,
);
await pause();
await editor.webContents.executeJavaScript(`(() => {
const set=(input,value)=>{input.value=value;input.dispatchEvent(new Event('input',{bubbles:true}));input.dispatchEvent(new Event('change',{bubbles:true}));};
const field=[...document.querySelectorAll('.component-settings .el-form-item')].find(e=>e.textContent.includes('目标名称'));
set(field.querySelector('input'),'运动会');
document.querySelector('.component-settings .el-date-editor input').focus();
})()`);
await pause();
await editor.webContents.executeJavaScript(`(() => {
const picker=document.querySelector('.component-settings .el-date-editor input');
picker.value='2099-10-25';picker.dispatchEvent(new Event('input',{bubbles:true}));
})()`);
await pause();
await editor.webContents.executeJavaScript(`(() => {
const picker=document.querySelector('.component-settings .el-date-editor input');
picker.dispatchEvent(new Event('change',{bubbles:true}));picker.dispatchEvent(new KeyboardEvent('keydown',{key:'Enter',code:'Enter',bubbles:true}));picker.blur();
})()`);
await pause();
const added = getConfig()
.islandLayout.schemes[0]!.expandedRows.flatMap((r) => r.nodes)
.find((n) => n.kind === 'countdown');
if (added?.settings.targetDate !== '2099-10-25' || added.settings.countdownTitle !== '运动会')
throw Error(JSON.stringify(added?.settings));
await editor.webContents.executeJavaScript(
`document.querySelector('.el-drawer__close-btn')?.click();document.querySelector('.surface-actions button:last-child')?.click()`,
);
await pause();
const preview = await editor.webContents.executeJavaScript(
`document.querySelector('.island-preview .countdown')?.textContent.includes('距运动会')`,
);
await editor.webContents.executeJavaScript(
`document.querySelectorAll('.surface-tabs button')[0].click()`,
);
await pause();
return preview && JSON.stringify(getConfig().islandLayout.schemes[0]!.rows) === before;
});
await check('天气坐标校验、并发合并与缓存使用 mock,不访问外网', async () => {
let calls = 0;
const request: typeof fetch = async (input) => {
calls++;
const url = new URL(String(input));
if (url.origin !== 'https://api.open-meteo.com' || url.searchParams.get('latitude') !== '12.34')
throw Error('请求边界错误');
return new Response(
JSON.stringify({ current: { temperature_2m: 23.4, weather_code: 2, wind_speed_10m: 8 } }),
);
};
const results = await Promise.all([
getIslandWeather({ latitude: 12.34, longitude: 56.78 }, request),
getIslandWeather({ latitude: 12.34, longitude: 56.78 }, request),
]);
await getIslandWeather({ latitude: 12.34, longitude: 56.78 }, request);
let invalid = false;
try {
await getIslandWeather({ latitude: 100, longitude: 0 }, request);
} catch {
invalid = true;
}
const weather = islandNode('weather', 'weather-test'),
countdown = islandNode('countdown', 'countdown-test');
weather.settings.latitude = NaN;
countdown.settings.targetDate = '2026-02-31';
const config = defaultIslandLayouts();
config.schemes[0]!.rows[0]!.nodes = [weather, countdown];
const normalized = normalizeIslandLayouts(config).schemes[0]!.rows[0]!.nodes;
return (
calls === 1 &&
results.every((r) => r.temperature === 23.4 && !r.stale) &&
invalid &&
normalized[0]!.settings.latitude === null &&
normalized[1]!.settings.targetDate === ''
);
});
await check('右上角新建、重置和删除方案均可保存并恢复原方案', async () => {
await editor.webContents.executeJavaScript(`document.querySelector('[aria-label="新建方案"]').click()`);
await pause();
await editor.webContents.executeJavaScript(
`(() => { const input=[...document.querySelectorAll('.el-message-box__input input')].filter(e=>e.getBoundingClientRect().width>0).at(-1); input.value='组件方案验收';input.dispatchEvent(new Event('input',{bubbles:true}));[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click(); })()`,
);
await pause();
if (getConfig().islandLayout.schemes.length !== 2) throw Error('新建方案没有保存');
await editor.webContents.executeJavaScript(
`document.querySelector('[aria-label="重置当前方案"]').click()`,
);
await pause();
await editor.webContents.executeJavaScript(
`[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click()`,
);
await pause();
await editor.webContents.executeJavaScript(`document.querySelector('[aria-label="管理方案"]').click()`);
await pause();
await editor.webContents.executeJavaScript(
`[...document.querySelectorAll('.el-dropdown-menu__item')].find(e=>e.textContent.trim()==='删除方案').click()`,
);
await pause();
await editor.webContents.executeJavaScript(
`[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click()`,
);
await pause();
const restored =
getConfig().islandLayout.schemes.length === 1 &&
getConfig().islandLayout.activeSchemeId === 'default' &&
getConfig().islandLayout.schemes[0]!.rows.length === 2;
if (!restored)
throw Error(
'方案未恢复:' +
JSON.stringify({
active: getConfig().islandLayout.activeSchemeId,
schemes: getConfig().islandLayout.schemes.map((s) => ({
id: s.id,
name: s.name,
rows: s.rows.length,
})),
}),
);
return restored;
});
await check('方案 JSON 导入导出保留容器结构并重新生成标识', async () => {
await editor.webContents.executeJavaScript(`document.querySelector('[aria-label="管理方案"]').click()`);
await pause();
const exported = await editor.webContents.executeJavaScript(`(async () => {
let blob; const originalURL=URL.createObjectURL, originalClick=HTMLAnchorElement.prototype.click;
try {
URL.createObjectURL=value=>{blob=value;return 'blob:editor-smoke';};HTMLAnchorElement.prototype.click=()=>{};
[...document.querySelectorAll('.el-dropdown-menu__item')].find(e=>e.textContent.trim()==='导出方案').click();
} finally { URL.createObjectURL=originalURL;HTMLAnchorElement.prototype.click=originalClick; }
const text=await blob.text(), parsed=JSON.parse(text);
const input=document.querySelector('.island-editor-page input[type=file]'), transfer=new DataTransfer();
transfer.items.add(new File([text],'组件方案.json',{type:'application/json'}));input.files=transfer.files;
input.dispatchEvent(new Event('change',{bubbles:true}));return parsed;
})()`);
await pause();
const layouts = getConfig().islandLayout;
const imported = layouts.schemes.find((s) => s.id === layouts.activeSchemeId)!;
const shape = (nodes: ReturnType<typeof islandNode>[]): string =>
JSON.stringify(
nodes.map((n) => ({ kind: n.kind, children: shape(n.children), settings: n.settings })),
);
const preserved =
exported.format === 'classhelper-island-layout' &&
imported.id !== exported.scheme.id &&
imported.rows.every(
(row, index) =>
row.id !== exported.scheme.rows[index].id &&
shape(row.nodes) === shape(exported.scheme.rows[index].nodes),
);
await editor.webContents.executeJavaScript(`document.querySelector('[aria-label="管理方案"]').click()`);
await pause();
await editor.webContents.executeJavaScript(
`[...document.querySelectorAll('.el-dropdown-menu__item')].find(e=>e.textContent.trim()==='删除方案').click()`,
);
await pause();
await editor.webContents.executeJavaScript(
`[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click()`,
);
await pause();
if (!preserved || getConfig().islandLayout.schemes.length !== 1)
throw Error(
'方案导入或收尾不一致:' +
JSON.stringify({
preserved,
schemes: getConfig().islandLayout.schemes.map((s) => ({
id: s.id,
name: s.name,
rows: s.rows.length,
})),
}),
);
return true;
});
if (process.env.ISLAND_SHOTS_DIR) { if (process.env.ISLAND_SHOTS_DIR) {
await editor.webContents.executeJavaScript(`document.querySelector('.main').scrollTop=0`); await editor.webContents.executeJavaScript(`document.querySelector('.main').scrollTop=0`);
fs.mkdirSync(process.env.ISLAND_SHOTS_DIR, { recursive: true }); fs.mkdirSync(process.env.ISLAND_SHOTS_DIR, { recursive: true });
@@ -5,6 +5,7 @@ import {
islandNode, islandNode,
normalizeIslandLayouts, normalizeIslandLayouts,
ISLAND_SHADOW_PAD, ISLAND_SHADOW_PAD,
type IslandTimePointDto,
type ScheduleDto, type ScheduleDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
import { getConfig, saveConfig } from './config.js'; import { getConfig, saveConfig } from './config.js';
@@ -391,7 +392,9 @@ export async function verifyResidentSmoke(
} }
return false; return false;
}; };
const immediate = (await waitForCourse()) && Date.now() - started < 600; const ready = await waitForCourse();
const latencyMs = Date.now() - started;
const immediate = ready && latencyMs < 600;
const aligned = await win.webContents.executeJavaScript(`(() => { const aligned = await win.webContents.executeJavaScript(`(() => {
const name=document.querySelector('.resident-compact .schedule strong')?.getBoundingClientRect(), time=document.querySelector('.resident-compact .lesson-time')?.getBoundingClientRect(); const name=document.querySelector('.resident-compact .schedule strong')?.getBoundingClientRect(), time=document.querySelector('.resident-compact .lesson-time')?.getBoundingClientRect();
return Boolean(name&&time&&time.left>=name.right&&Math.abs(time.top+time.height/2-name.top-name.height/2)<=2); return Boolean(name&&time&&time.left>=name.right&&Math.abs(time.top+time.height/2-name.top-name.height/2)<=2);
@@ -404,7 +407,12 @@ export async function verifyResidentSmoke(
island.syncCustomLayout(); island.syncCustomLayout();
await pause(800); await pause(800);
island.setClassState({ inClass: true, currentPeriodEnd: null, week: 1, schedules: [] }); island.setClassState({ inClass: true, currentPeriodEnd: null, week: 1, schedules: [] });
return immediate && aligned && restored && snapshot[0]?.course?.name === '实时课程'; const snapshotMatches = snapshot[0]?.course?.name === '实时课程';
if (!immediate || !aligned || !restored || !snapshotMatches)
throw new Error(
`课表同步检查:${JSON.stringify({ ready, latencyMs, aligned, restored, snapshotMatches })}`,
);
return true;
}); });
await check('常驻岛开合复用固定画布,动画中没有滚动容器或旧胶囊形变', async () => { await check('常驻岛开合复用固定画布,动画中没有滚动容器或旧胶囊形变', async () => {
const bounds = new Set<string>(); const bounds = new Set<string>();
@@ -558,7 +566,15 @@ export async function verifyResidentSmoke(
await pause(800); await pause(800);
if (island.getState().lessonReminder?.kind !== 'prepare') return false; if (island.getState().lessonReminder?.kind !== 'prepare') return false;
const mask = await win.webContents.executeJavaScript( const mask = await win.webContents.executeJavaScript(
`(() => {const cue=document.querySelector('${layout === 'custom' ? '.resident-lesson-page' : '.ci-fixed-lesson'} .ci-mask')||document.querySelector('.ci-fixed-lesson .ci-mask');return Boolean(cue&&cue.querySelectorAll('polygon').length===5);})()`, `(() => {
const cue=document.querySelector('${layout === 'custom' ? '.resident-lesson-page' : '.ci-fixed-lesson'} .ci-mask')||document.querySelector('.ci-fixed-lesson .ci-mask');
if (!cue || cue.querySelectorAll('polygon').length !== 5) return false;
const card=cue.closest('.ci-lesson'), title=card?.querySelector('.ci-mask-title');
const bounds=card?.getBoundingClientRect(), painted=cue.getBBox();
let opacity=1, node=card;
while(node&&node!==document.body){const style=getComputedStyle(node);if(style.visibility==='hidden'||style.display==='none')return false;opacity*=Number(style.opacity);node=node.parentElement;}
return Boolean(bounds&&bounds.width>=290&&bounds.height>=39&&painted.width>=bounds.width*.9&&title&&Number(getComputedStyle(title).opacity)>.8&&opacity>.8);
})()`,
); );
if (!mask) return false; if (!mask) return false;
await shot('lesson-prepare-mask-' + layout); await shot('lesson-prepare-mask-' + layout);
@@ -599,7 +615,9 @@ export async function verifyResidentSmoke(
await pause(1100); await pause(1100);
const half = await win.webContents.executeJavaScript(`(() => { const half = await win.webContents.executeJavaScript(`(() => {
const root=document.querySelector('${layout === 'custom' ? '.resident-compact' : '.ci-fixed-lesson'}'); const root=document.querySelector('${layout === 'custom' ? '.resident-compact' : '.ci-fixed-lesson'}');
return Boolean(root&&root.textContent.includes('数学')&&root.textContent.includes('距下课')&&Number(root.querySelector('[role=progressbar]')?.getAttribute('aria-valuenow'))===50); const text=root?.textContent??'';
const progress=Number(root?.querySelector('[role=progressbar]')?.getAttribute('aria-valuenow'));
return Boolean(root&&text.includes('数学')&&progress===50&&(${layout === 'custom' ? "text.includes('09:00–09:45')&&!text.includes('距下课')" : "text.includes('距下课')"}));
})()`); })()`);
if (!half) if (!half)
throw new Error( throw new Error(
@@ -671,6 +689,87 @@ export async function verifyResidentSmoke(
await pause(800); await pause(800);
} }
}); });
await check('自定义岛课程表按时间点折叠:课间折叠隐藏、当前项展开显示时间段', async () => {
const scheduleLayout = JSON.parse(JSON.stringify(fixture));
const node = islandNode('schedule', 'time-point-schedule');
node.settings.display = 'today';
node.settings.count = 10;
scheduleLayout.schemes[0].rows[0].nodes = [node];
saveConfig({ islandLayout: { ...scheduleLayout, layout: 'custom' } });
island.syncCustomLayout();
const timePoints: IslandTimePointDto[] = [
{
id: 'p-math',
timeType: 'LESSON',
name: '第 1 节',
courseName: '数学',
startTime: '09:00',
endTime: '09:45',
isHideDefault: false,
},
{
id: 'p-break',
timeType: 'BREAK',
name: '课间休息',
courseName: null,
startTime: '09:45',
endTime: '09:55',
isHideDefault: false,
},
{
id: 'p-chinese',
timeType: 'LESSON',
name: '第 2 节',
courseName: '语文',
startTime: '09:55',
endTime: '10:40',
isHideDefault: false,
},
];
const setTime = async (hour: number, minute: number) => {
const at = dateAt(hour, minute).getTime();
await win.webContents.executeJavaScript(`window.__lessonSmokeTime=${at}`);
island.setLessonReminderTestTime(at);
};
try {
await win.webContents.executeJavaScript(
`window.__lessonRealNow=Date.now;Date.now=()=>window.__lessonSmokeTime??window.__lessonRealNow();true`,
);
island.setClassState({ inClass: false, schedules: lessonFixtures, timePoints });
await setTime(9, 20);
await pause(900);
const duringClass = await win.webContents.executeJavaScript(`(() => {
const text=document.querySelector('.resident-compact')?.textContent??'';
return { math: text.includes('数学'), chinese: text.includes('语文'), rest: text.includes('课间休息'), period: text.includes('09:00–09:45'), otherPeriod: text.includes('09:55–10:40') };
})()`);
await setTime(9, 50);
await pause(900);
const duringBreak = await win.webContents.executeJavaScript(`(() => {
const text=document.querySelector('.resident-compact')?.textContent??'';
return { math: text.includes('数学'), chinese: text.includes('语文'), rest: text.includes('课间休息'), period: text.includes('09:45–09:55') };
})()`);
if (!(
duringClass.math &&
duringClass.chinese &&
!duringClass.rest &&
duringClass.period &&
!duringClass.otherPeriod
))
throw new Error('课中时间点折叠错误:' + JSON.stringify(duringClass));
if (!(duringBreak.math && duringBreak.chinese && duringBreak.rest && duringBreak.period))
throw new Error('课间展开错误:' + JSON.stringify(duringBreak));
return true;
} finally {
await win.webContents.executeJavaScript(
`Date.now=window.__lessonRealNow;delete window.__lessonRealNow;delete window.__lessonSmokeTime`,
);
island.setLessonReminderTestTime(null);
island.setClassState({ inClass: false, schedules: [], timePoints: [] });
saveConfig({ islandLayout: fixture });
island.syncCustomLayout();
await pause(800);
}
});
await check('长文本多行与2.5倍字号自动适配,变窄窗口和底部右侧停靠均不溢出', async () => { await check('长文本多行与2.5倍字号自动适配,变窄窗口和底部右侧停靠均不溢出', async () => {
const appearance = island.getAppearance(); const appearance = island.getAppearance();
const dense = JSON.parse(JSON.stringify(fixture)); const dense = JSON.parse(JSON.stringify(fixture));
@@ -735,15 +834,26 @@ export async function verifyResidentSmoke(
island.handleAction({ action: 'expand' }); island.handleAction({ action: 'expand' });
await pause(1000); await pause(1000);
island.handleAction({ action: 'collapse' }); island.handleAction({ action: 'collapse' });
await pause(1000); // 收起后渲染进程要重新量宽并走 750ms 的触摸形状延时;尺寸稳定前不要断言。
let settled = false;
const deadline = Date.now() + 3500;
while (Date.now() < deadline) {
await pause(100);
const current = island.getHitRect();
if (
current &&
shape.length === 1 &&
shape[0]!.width <= current.width + 18 &&
shape[0]!.height <= current.height + 18
) {
settled = true;
break;
}
}
const hit = island.getHitRect(); const hit = island.getHitRect();
return Boolean( const ok = Boolean(settled && hit && JSON.stringify(box) === JSON.stringify(win.getBounds()));
hit && if (!ok) throw new Error(JSON.stringify({ hit, shape, bounds: win.getBounds(), box, settled }));
shape.length === 1 && return true;
shape[0]!.width <= hit.width + 18 &&
shape[0]!.height <= hit.height + 18 &&
JSON.stringify(box) === JSON.stringify(win.getBounds()),
);
} finally { } finally {
win.setShape = original; win.setShape = original;
island.setTouchMode(false); island.setTouchMode(false);
+4 -2
View File
@@ -3078,7 +3078,9 @@ async function runIslandChecks(
`${islandStateSummary()}`, `${islandStateSummary()}`,
); );
// 10.7) 视觉风格:纯黑 / 毛玻璃(亚克力)/ 主题色渐变,切换立即生效 // 消息使用实色底;先清空消息,单独验证用户设置的三种基础风格。
await drainIsland();
await sleep(260);
const probeStyle = async (style: IslandAppearance['style']): Promise<{ fill: string; stroke: string }> => { const probeStyle = async (style: IslandAppearance['style']): Promise<{ fill: string; stroke: string }> => {
island.setAppearance({ ...appearanceBefore, style }); island.setAppearance({ ...appearanceBefore, style });
await sleep(260); await sleep(260);
@@ -3102,7 +3104,7 @@ async function runIslandChecks(
const glassStyle = await probeStyle('glass'); const glassStyle = await probeStyle('glass');
const tintedStyle = await probeStyle('tinted'); const tintedStyle = await probeStyle('tinted');
record( record(
'视觉风格切换立刻生效(纯黑 / 毛玻璃半透明 / 主题色)', '无消息时视觉风格切换立刻生效(纯黑 / 毛玻璃半透明 / 主题色)',
blackStyle.fill === 'rgb(0, 0, 0)' && blackStyle.fill === 'rgb(0, 0, 0)' &&
glassStyle.fill.startsWith('rgba(32, 32, 36') && glassStyle.fill.startsWith('rgba(32, 32, 36') &&
tintedStyle.fill === 'rgb(11, 11, 15)', tintedStyle.fill === 'rgb(11, 11, 15)',
@@ -0,0 +1,105 @@
import crypto from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
import { spawn } from 'node:child_process';
interface InstallerOptions {
directory: string;
installer: string;
version: string;
sha256: string;
size: number;
serverUrl: string;
username: string;
restartExe: string;
portable: boolean;
}
/** 先确认独立助手就绪;调用方复核策略后 commit,再退出应用。 */
export async function prepareUpdateInstaller(options: InstallerOptions) {
const attempt = crypto.randomUUID();
const prefix = path.join(options.directory, `install-${attempt}`);
const helper = path.join(options.directory, `updater-${attempt}.exe`);
const resultFile = path.join(options.directory, 'install-result.json');
const logFile = path.join(options.directory, 'install-helper.log');
fs.mkdirSync(options.directory, { recursive: true });
for (const name of fs.readdirSync(options.directory)) {
if (/^updater-[0-9a-f-]{36}\.exe$/i.test(name)) {
try {
fs.rmSync(path.join(options.directory, name));
} catch {
/* 仍在运行的助手留待下次清理 */
}
}
}
fs.copyFileSync(path.join(__dirname, 'update-helper.exe'), helper);
fs.writeFileSync(
`${prefix}.json`,
JSON.stringify({
Attempt: attempt,
ParentId: process.pid,
ParentExe: process.execPath,
Installer: options.installer,
RestartExe: options.restartExe,
Version: options.version,
ServerUrl: options.serverUrl,
Username: options.username,
Sha256: options.sha256,
Size: options.size,
Portable: options.portable,
}),
'utf8',
);
fs.rmSync(resultFile, { force: true });
fs.writeFileSync(logFile, `${new Date().toISOString()} 准备安装 ${options.version}\n`, 'utf8');
let child: ReturnType<typeof spawn>;
try {
child = spawn(helper, [`${prefix}.json`], {
detached: true,
stdio: 'ignore',
windowsHide: true,
cwd: options.directory,
});
await new Promise<void>((resolve, reject) => {
const timeout = setTimeout(
() => finish(new Error('更新助手就绪超时,请查看 install-helper.log')),
15_000,
);
const poll = setInterval(() => {
try {
if (fs.readFileSync(`${prefix}.ready`, 'utf8').trim() === attempt) finish();
} catch {
/* 尚未就绪 */
}
}, 50);
const onError = (error: Error) => finish(error);
const onExit = (code: number | null) => {
let detail = '';
try {
detail = JSON.parse(fs.readFileSync(resultFile, 'utf8')).error ?? '';
} catch {
/* 原生进程未能启动 */
}
finish(new Error(detail || `更新助手提前退出(${code ?? '未知退出码'}),请查看 install-helper.log`));
};
function finish(error?: Error) {
clearTimeout(timeout);
clearInterval(poll);
child.removeListener('error', onError);
child.removeListener('exit', onExit);
if (error) reject(error);
else resolve();
}
child.once('error', onError);
child.once('exit', onExit);
});
child.unref();
} catch (error) {
fs.writeFileSync(`${prefix}.cancel`, attempt, 'utf8');
throw error;
}
return {
commit: () => fs.writeFileSync(`${prefix}.start`, attempt, 'utf8'),
cancel: () => fs.writeFileSync(`${prefix}.cancel`, attempt, 'utf8'),
};
}
+6 -1
View File
@@ -1,4 +1,7 @@
import type { ReleaseProgressDto as ContractReleaseProgressDto, CoursewareTransfer } from '@classhelper/shared'; import type {
ReleaseProgressDto as ContractReleaseProgressDto,
CoursewareTransfer,
} from '@classhelper/shared';
import { contextBridge, ipcRenderer } from 'electron'; import { contextBridge, ipcRenderer } from 'electron';
import { IPC_CHANNELS, UPDATE_AVAILABLE_CHANNEL } from '../main/channels.js'; import { IPC_CHANNELS, UPDATE_AVAILABLE_CHANNEL } from '../main/channels.js';
import type { ClientAgentStatus } from '../main/client-agent.js'; import type { ClientAgentStatus } from '../main/client-agent.js';
@@ -20,8 +23,10 @@ import type { IslandNotification, UpdateInfo } from '@classhelper/shared';
* 之前就抛 `An object could not be cloned.`。调用方必须传纯数据,见 desktop.d.ts。 * 之前就抛 `An object could not be cloned.`。调用方必须传纯数据,见 desktop.d.ts。
*/ */
const bridge: DesktopBridge = { const bridge: DesktopBridge = {
getIslandWeather: (coordinates) => ipcRenderer.invoke('island:weather', coordinates),
downloadCourseware: (id) => ipcRenderer.invoke('courseware:download', id), downloadCourseware: (id) => ipcRenderer.invoke('courseware:download', id),
revealCourseware: (id) => ipcRenderer.invoke('courseware:reveal', id), revealCourseware: (id) => ipcRenderer.invoke('courseware:reveal', id),
listLocalCourseware: () => ipcRenderer.invoke('courseware:local-list'),
syncCourseware: () => ipcRenderer.invoke('courseware:sync'), syncCourseware: () => ipcRenderer.invoke('courseware:sync'),
getCoursewareTransfer: () => ipcRenderer.invoke('courseware:get-progress'), getCoursewareTransfer: () => ipcRenderer.invoke('courseware:get-progress'),
onCoursewareTransfer: (handler) => { onCoursewareTransfer: (handler) => {
@@ -1,5 +1,7 @@
import type { import type {
IslandLayoutSettings as ContractIslandLayoutSettings, IslandLayoutSettings as ContractIslandLayoutSettings,
IslandTimePointDto as ContractIslandTimePointDto,
IslandWeather,
ScheduleDto as ContractScheduleDto, ScheduleDto as ContractScheduleDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
import { contextBridge, ipcRenderer } from 'electron'; import { contextBridge, ipcRenderer } from 'electron';
@@ -10,6 +12,7 @@ import type { IslandAppearance, IslandState } from '@classhelper/shared';
* 只暴露「订阅状态/外观」与「发送用户操作」两件事,渲染进程不接触任何 Node 能力。 * 只暴露「订阅状态/外观」与「发送用户操作」两件事,渲染进程不接触任何 Node 能力。
*/ */
export interface IslandBridge { export interface IslandBridge {
getIslandWeather(coordinates: { latitude: number; longitude: number }): Promise<IslandWeather>;
getLayout(): Promise<ContractIslandLayoutSettings>; getLayout(): Promise<ContractIslandLayoutSettings>;
saveLayout(value: ContractIslandLayoutSettings): Promise<ContractIslandLayoutSettings>; saveLayout(value: ContractIslandLayoutSettings): Promise<ContractIslandLayoutSettings>;
onLayout(handler: (value: ContractIslandLayoutSettings) => void): void; onLayout(handler: (value: ContractIslandLayoutSettings) => void): void;
@@ -24,6 +27,8 @@ export interface IslandBridge {
onViewport(handler: (value: { width: number; height: number }) => void): () => void; onViewport(handler: (value: { width: number; height: number }) => void): () => void;
getSchedules(): Promise<ContractScheduleDto[]>; getSchedules(): Promise<ContractScheduleDto[]>;
onSchedules(handler: (value: ContractScheduleDto[]) => void): void; onSchedules(handler: (value: ContractScheduleDto[]) => void): void;
getTimePoints(): Promise<ContractIslandTimePointDto[]>;
onTimePoints(handler: (value: ContractIslandTimePointDto[]) => void): void;
onState(handler: (state: IslandState) => void): void; onState(handler: (state: IslandState) => void): void;
sendAction( sendAction(
@@ -57,6 +62,7 @@ export interface IslandBridge {
} }
const bridge: IslandBridge = { const bridge: IslandBridge = {
getIslandWeather: (coordinates) => ipcRenderer.invoke('island:weather', coordinates),
getLayout: () => ipcRenderer.invoke('island:get-layout'), getLayout: () => ipcRenderer.invoke('island:get-layout'),
saveLayout: (value) => ipcRenderer.invoke('island:save-layout', value), saveLayout: (value) => ipcRenderer.invoke('island:save-layout', value),
onLayout: (handler) => { onLayout: (handler) => {
@@ -84,6 +90,10 @@ const bridge: IslandBridge = {
onSchedules: (handler) => { onSchedules: (handler) => {
ipcRenderer.on('island:schedules', (_event, value) => handler(value)); ipcRenderer.on('island:schedules', (_event, value) => handler(value));
}, },
getTimePoints: () => ipcRenderer.invoke('island:get-time-points'),
onTimePoints: (handler) => {
ipcRenderer.on('island:time-points', (_event, value) => handler(value));
},
onState: (handler) => { onState: (handler) => {
ipcRenderer.on('island:state', (_event, state: IslandState) => handler(state)); ipcRenderer.on('island:state', (_event, state: IslandState) => handler(state));
+3 -2
View File
@@ -13,6 +13,7 @@ import {
import OnboardingWelcome from './components/OnboardingWelcome.vue'; import OnboardingWelcome from './components/OnboardingWelcome.vue';
import { useAppStore } from './stores/app.js'; import { useAppStore } from './stores/app.js';
import { useAuthStore } from './stores/auth.js'; import { useAuthStore } from './stores/auth.js';
import { ONBOARDING_VERSION } from '@classhelper/ui';
import { useOnboardingStore } from './stores/onboarding.js'; import { useOnboardingStore } from './stores/onboarding.js';
import { useRealtimeStore } from './stores/realtime.js'; import { useRealtimeStore } from './stores/realtime.js';
import { useUiStore } from './stores/ui.js'; import { useUiStore } from './stores/ui.js';
@@ -123,13 +124,13 @@ onMounted(async () => {
if (auth.isAuthenticated) await router.replace('/schedule'); if (auth.isAuthenticated) await router.replace('/schedule');
else await router.replace('/login'); else await router.replace('/login');
// 初次启动引导:配置里没记「已看过」就自动弹一次(完成/跳过后由引导组件写入配置)。 // 引导按版本展示,完成或跳过后记住当前版本。
// 稍等一拍再弹:让登录页/主界面先渲染完,避免和启动过渡的收尾抢帧。 // 稍等一拍再弹:让登录页/主界面先渲染完,避免和启动过渡的收尾抢帧。
window.setTimeout(() => { window.setTimeout(() => {
void window.desktop void window.desktop
?.getConfig() ?.getConfig()
.then((config) => { .then((config) => {
if (config.onboardingDone !== true) onboarding.open(); if ((config.onboardingVersion ?? 0) < ONBOARDING_VERSION) onboarding.open();
}) })
.catch(() => undefined); .catch(() => undefined);
}, 400); }, 400);
@@ -67,8 +67,15 @@ export const homeworkApi = {
date?: string; date?: string;
}): Promise<HomeworkDto[]> => api.get(API_PATHS.homeworks, params), }): Promise<HomeworkDto[]> => api.get(API_PATHS.homeworks, params),
/** 哪些天有作业(日期选择器高亮) */ /** 哪些天有作业(日期选择器高亮) */
days: (params: { classId?: string; from?: string; to?: string; days?: number }): Promise<HomeworkDaysDto> => days: (params: {
api.get(`${API_PATHS.homeworks}/days`, params), classId?: string;
courseId?: string;
keyword?: string;
pendingOnly?: boolean;
from?: string;
to?: string;
days?: number;
}): Promise<HomeworkDaysDto> => api.get(`${API_PATHS.homeworks}/days`, params),
/** 在教室机器上直接录入作业(班级账号可调用;也可选所属日期) */ /** 在教室机器上直接录入作业(班级账号可调用;也可选所属日期) */
create: (payload: { create: (payload: {
classId: string; classId: string;
@@ -88,8 +95,21 @@ export const homeworkApi = {
}; };
export const notificationApi = { export const notificationApi = {
list: (params?: { classId?: string; unreadOnly?: boolean }): Promise<NotificationDto[]> => days: (params: {
api.get(API_PATHS.notifications, params), classId?: string;
from?: string;
to?: string;
createdBy?: string;
priority?: string;
unreadOnly?: boolean;
}): Promise<{ days: { date: string; count: number }[] }> => api.get('/notifications/days', params),
list: (params?: {
classId?: string;
unreadOnly?: boolean;
date?: string;
createdBy?: string;
priority?: string;
}): Promise<NotificationDto[]> => api.get(API_PATHS.notifications, params),
unreadCount: (): Promise<{ count: number }> => api.get(`${API_PATHS.notifications}/unread-count`), unreadCount: (): Promise<{ count: number }> => api.get(`${API_PATHS.notifications}/unread-count`),
// id 来自服务端或灵动岛(作业卡是本地合成的 `homework-…`),一律 encodeURIComponent: // id 来自服务端或灵动岛(作业卡是本地合成的 `homework-…`),一律 encodeURIComponent:
// 否则含 `/` 或 `..` 的 id 会改变实际请求的路径 // 否则含 `/` 或 `..` 的 id 会改变实际请求的路径
+9 -12
View File
@@ -885,14 +885,7 @@ export async function islandHomeworkSuppressionCheck(): Promise<SmokeCheckResult
} }
} }
/** /** 全新配置首次展示全屏引导,完成后保存版本标记。 */
* 冒烟自检(不需要后端):**初次启动引导**。
*
* 冒烟每次都用全新配置目录(等于"首次启动"),因此引导必须自动弹出;
* 这里真实点击把它一步步走完,断言:遮罩关闭 + `onboardingDone` 已写入配置。
* 关闭判据用「元素从 DOM 消失」——引导是 v-if 自绘遮罩(特意不用 el-dialog,
* 避免"关闭后 DOM 残留在文档里"的误报,见 AGENTS §7 第 22 条)。
*/
export async function onboardingSelfTest(): Promise<SmokeCheckResult> { export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
try { try {
// 引导在启动后延迟 ~400ms 弹出,这里轮询等它出现 // 引导在启动后延迟 ~400ms 弹出,这里轮询等它出现
@@ -908,7 +901,10 @@ export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
}; };
} }
// 逐页「下一步」到最后一页再点「开始使用」(按钮由 data-action 标识,不依赖文案) const guide = document.querySelector<HTMLElement>('.ch-guide')!;
const bounds = guide.getBoundingClientRect();
const fullscreen = Math.abs(bounds.width - innerWidth) < 2 && Math.abs(bounds.height - innerHeight) < 2;
const focused = guide.contains(document.activeElement);
const clicks: string[] = []; const clicks: string[] = [];
for (let attempt = 0; attempt < 12; attempt += 1) { for (let attempt = 0; attempt < 12; attempt += 1) {
const action = document.querySelector('.onboarding-welcome [data-action="finish"]') ? 'finish' : 'next'; const action = document.querySelector('.onboarding-welcome [data-action="finish"]') ? 'finish' : 'next';
@@ -928,10 +924,11 @@ export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
} }
const config = await window.desktop?.getConfig?.(); const config = await window.desktop?.getConfig?.();
const done = config?.onboardingDone === true; const { ONBOARDING_VERSION } = await import('@classhelper/ui');
const done = config?.onboardingDone === true && config.onboardingVersion === ONBOARDING_VERSION;
return { return {
ok: closed && done, ok: closed && done && fullscreen && focused,
detail: `步骤点击=[${clicks.join(',')}] 已关闭=${closed} onboardingDone=${config?.onboardingDone ?? '-'}`, detail: `步骤点击=[${clicks.join(',')}] 全屏=${fullscreen} 焦点=${focused} 已关闭=${closed} 引导版本=${config?.onboardingVersion ?? '-'}`,
}; };
} catch (error) { } catch (error) {
return { return {
@@ -37,14 +37,63 @@ const containers = ['group', 'stack', 'slide', 'rolling'] as const;
<el-switch v-model="node.settings.seconds" @change="emit('change')" /> <el-switch v-model="node.settings.seconds" @change="emit('change')" />
</el-form-item> </el-form-item>
</template> </template>
<el-form-item v-else-if="node.kind === 'countdown'" label="倒计时目标"> <template v-else-if="node.kind === 'countdown'">
<el-select v-model="node.settings.target" @change="emit('change')"> <el-form-item label="倒计时目标">
<el-option label="自动:距上课 / 下课" value="auto" /> <el-select v-model="node.settings.target" @change="emit('change')">
<el-option label="下一节课" value="next" /> <el-option label="自动:距上课 / 下课" value="auto" />
<el-option label="本节下课" value="end" /> <el-option label="下一节课" value="next" />
<el-option label="放学" value="school" /> <el-option label="本节下课" value="end" />
</el-select> <el-option label="放学" value="school" />
</el-form-item> <el-option label="指定日期" value="date" />
</el-select>
</el-form-item>
<template v-if="node.settings.target === 'date'">
<el-form-item label="目标名称">
<el-input v-model="node.settings.countdownTitle" :maxlength="64" @change="emit('change')" />
</el-form-item>
<el-form-item label="目标日期">
<ch-date-picker
v-model="node.settings.targetDate"
type="date"
value-format="YYYY-MM-DD"
placeholder="选择日期"
@change="emit('change')"
/>
</el-form-item>
</template>
</template>
<template v-else-if="node.kind === 'weather'">
<el-form-item label="地点名称">
<el-input
v-model="node.settings.locationName"
placeholder="例如:学校"
:maxlength="64"
@change="emit('change')"
/>
</el-form-item>
<el-form-item label="纬度">
<el-input-number
v-model="node.settings.latitude"
:min="-90"
:max="90"
:precision="4"
@change="emit('change')"
/>
</el-form-item>
<el-form-item label="经度">
<el-input-number
v-model="node.settings.longitude"
:min="-180"
:max="180"
:precision="4"
@change="emit('change')"
/>
</el-form-item>
<p class="hint">
填写地点坐标后每 15 分钟更新天气。数据来自
Open-Meteo,断网时显示本次运行的缓存;天气提示不作为官方预警。
</p>
</template>
<template v-else-if="node.kind === 'text'"> <template v-else-if="node.kind === 'text'">
<el-form-item label="文字内容"> <el-form-item label="文字内容">
<el-input v-model="node.settings.text" type="textarea" :rows="3" @change="emit('change')" /> <el-input v-model="node.settings.text" type="textarea" :rows="3" @change="emit('change')" />
@@ -57,20 +106,24 @@ const containers = ['group', 'stack', 'slide', 'rolling'] as const;
<template v-else-if="node.kind === 'schedule'"> <template v-else-if="node.kind === 'schedule'">
<el-form-item label="显示课程"> <el-form-item label="显示课程">
<el-select v-model="node.settings.display" @change="emit('change')"> <el-select v-model="node.settings.display" @change="emit('change')">
<el-option label="当前课程" value="current" /> <el-option label="当前时间点" value="current" />
<el-option label="下一节课" value="next" /> <el-option label="下一节课" value="next" />
<el-option label="今日课表" value="today" /> <el-option label="今日时间点" value="today" />
</el-select> </el-select>
</el-form-item> </el-form-item>
<el-form-item v-if="node.settings.display === 'today'" label="显示节数"> <el-form-item v-if="node.settings.display === 'today'" label="显示时间点数">
<el-input-number v-model="node.settings.count" :min="1" :max="30" @change="emit('change')" /> <el-input-number v-model="node.settings.count" :min="1" :max="30" @change="emit('change')" />
</el-form-item> </el-form-item>
<el-form-item label="显示课程时间"> <el-form-item label="当前时间点显示起止时间">
<el-switch v-model="node.settings.showPeriod" @change="emit('change')" /> <el-switch v-model="node.settings.showPeriod" @change="emit('change')" />
</el-form-item> </el-form-item>
<el-form-item label="显示上课进度"> <el-form-item label="当前课程显示进度">
<el-switch v-model="node.settings.showProgress" @change="emit('change')" /> <el-switch v-model="node.settings.showProgress" @change="emit('change')" />
</el-form-item> </el-form-item>
<p class="hint">
今日时间点只展开当前项并显示时间段;课间休息与默认隐藏的时间点折叠时完全隐藏,轮到时才展开。
下课前一分钟的倒计时由「提醒」设置里的下课提醒负责。
</p>
</template> </template>
<template v-else-if="containers.includes(node.kind as (typeof containers)[number])"> <template v-else-if="containers.includes(node.kind as (typeof containers)[number])">
<el-form-item label="排列方向"> <el-form-item label="排列方向">
@@ -80,7 +133,7 @@ const containers = ['group', 'stack', 'slide', 'rolling'] as const;
</el-select> </el-select>
</el-form-item> </el-form-item>
<el-form-item label="组件间距"> <el-form-item label="组件间距">
<el-input-number v-model="node.settings.gap" :min="0" :max="80" @change="emit('change')" /> <el-input-number v-model="node.settings.gap" :min="0" :max="64" @change="emit('change')" />
</el-form-item> </el-form-item>
<el-form-item v-if="node.kind === 'slide'" label="切换间隔(秒)"> <el-form-item v-if="node.kind === 'slide'" label="切换间隔(秒)">
<el-input-number <el-input-number
@@ -0,0 +1,124 @@
<script setup lang="ts">
import { computed } from 'vue';
import { ISLAND_COMPONENT_LABELS, type IslandComponentNode } from '@classhelper/shared';
import ComponentIcon from '../../island/ComponentIcon.vue';
const props = defineProps<{
node: IslandComponentNode;
selectedId: string;
dropId?: string;
dropPosition?: string;
}>();
const emit = defineEmits<{ select: [id: string]; drag: [event: PointerEvent, id: string] }>();
const container = computed(() => ['group', 'stack', 'slide', 'rolling'].includes(props.node.kind));
</script>
<template>
<div
class="editor-component"
:class="{
container,
selected: selectedId === node.id,
'drop-before': dropId === node.id && dropPosition === 'before',
'drop-after': dropId === node.id && dropPosition === 'after',
'drop-inside': dropId === node.id && dropPosition === 'inside',
}"
:data-node="node.id"
>
<button
class="component-chip node-handle"
:data-kind="node.kind"
:aria-label="`编辑${ISLAND_COMPONENT_LABELS[node.kind]}`"
@pointerdown="emit('drag', $event, node.id)"
@click.stop="emit('select', node.id)"
>
<ComponentIcon :kind="node.kind" />
<span>{{ ISLAND_COMPONENT_LABELS[node.kind] }}</span>
</button>
<div v-if="container" class="container-children">
<IslandEditorNode
v-for="child in node.children"
:key="child.id"
:node="child"
:selected-id="selectedId"
:drop-id="dropId"
:drop-position="dropPosition"
@select="emit('select', $event)"
@drag="(event, id) => emit('drag', event, id)"
/>
<span v-if="!node.children.length" class="container-empty">拖入组件</span>
</div>
</div>
</template>
<style scoped>
.editor-component {
position: relative;
display: flex;
align-items: center;
flex-shrink: 0;
border-radius: 5px;
}
.component-chip {
display: flex;
align-items: center;
gap: 5px;
min-height: 36px;
padding: 5px 9px;
border: 1px solid transparent;
border-radius: 5px;
background: transparent;
color: inherit;
font: inherit;
white-space: nowrap;
cursor: grab;
touch-action: none;
}
.component-chip svg {
width: 18px;
height: 18px;
flex-shrink: 0;
}
.component-chip:hover {
background: var(--ch-hover-soft);
}
.component-chip:focus-visible {
outline: 2px solid var(--ch-accent);
outline-offset: 2px;
}
.selected > .component-chip {
background: var(--ch-accent-soft);
border-color: var(--ch-accent);
}
.container {
border: 1px dashed var(--ch-border-strong);
padding: 3px;
gap: 3px;
}
.container-children {
display: flex;
align-items: center;
gap: 3px;
min-width: 60px;
min-height: 34px;
}
.container-empty {
color: var(--ch-text-tertiary);
font-size: 12px;
padding: 0 10px;
}
.drop-inside {
background: var(--ch-accent-soft);
outline: 2px solid var(--ch-accent);
}
.drop-before::before,
.drop-after::after {
content: '';
position: absolute;
inset: 3px auto 3px -4px;
width: 3px;
border-radius: 3px;
background: var(--ch-accent);
}
.drop-after::after {
left: auto;
right: -4px;
}
</style>
@@ -1,309 +1,59 @@
<script setup lang="ts"> <script setup lang="ts">
import { computed, onUnmounted, ref, watch } from 'vue'; import { FullScreenGuide, ONBOARDING_VERSION } from '@classhelper/ui';
import { useOnboardingStore } from '../stores/onboarding.js'; import { useOnboardingStore } from '../stores/onboarding.js';
import { BRAND_LOGO_URL } from '../config.js';
/**
* 初次启动引导(六步向导)。
*
* - 首次启动自动弹出(App.vue 按 `onboardingDone` 判定);完成 / 跳过(右上角按钮 / Esc)
* 都算看过,由这里写入主进程配置,之后不再自动弹出。
* - 登录页与设置页的「使用引导」入口可随时重看(重看关闭时再写一次也无副作用)。
* - **用 v-if 自绘遮罩而不是 el-dialog**:关闭即从 DOM 卸载。冒烟断言"引导已关闭"时
* 不会踩 el-dialog「DOM 残留在文档里」的坑(AGENTS §7 第 22 条)。
* - 操作按钮用 `data-action` 标识(prev/next/finish/skip),冒烟点击不依赖按钮文案。
*/
const onboarding = useOnboardingStore(); const onboarding = useOnboardingStore();
const steps = [ const steps = [
{ {
icon: 'School', id: 'server',
title: '欢迎使用 ClassHelper', title: '连接学校服务器',
lines: [ text: '填写管理员提供的服务器地址,测试连接后继续。',
'这台电脑将以「班级」的身份使用 ClassHelper:实时接收课表、作业、通知与成绩。', example: ['服务器地址', '测试连接', '连接成功'],
'第一次使用,先花半分钟看看怎么开始。',
],
}, },
{ {
icon: 'Link', id: 'login',
title: '第一步 · 连接服务器', title: '登录班级',
lines: [ text: '使用班级码和班级密码登录,这台设备将代表本班。',
'在登录页填写老师或管理员提供的服务器地址(通常形如 http://192.168.x.x:4000)。', example: ['班级码', '班级密码', '登录'],
'点「测试连接」确认可达;以后也能在「设置」里随时修改。',
],
}, },
{ {
icon: 'Key', id: 'teaching',
title: '第二步 · 登录班级', title: '查看课表与作业',
lines: [ text: '从菜单切换页面,用日历查找记录;断网时可查看已缓存的内容。',
'使用班级码 + 班级密码登录(向老师或管理员索取)。', example: ['今日课表', '作业看板', '日期下方的圆点 ·'],
'登录后这台设备就代表全班:作业完成、通知已读都会按全班记录,不需要每个学生单独登录。',
],
}, },
{ {
icon: 'Calendar', id: 'files',
title: '登录之后', title: '接收通知与课件',
lines: [ text: '新内容自动同步,课件下载后由你选择如何打开。',
'左侧菜单切换「课表 / 作业 / 通知 / 成绩」四个页面,作业支持看板全屏展示。', example: ['班级通知', '课件传输进度', '打开所在文件夹'],
'断网时自动显示最近同步的缓存数据,联网后自动更新。',
],
}, },
{ {
icon: 'Bell', id: 'island',
title: '灵动岛提醒', title: '选择灵动岛模式',
lines: [ text: '经典模式自动呈现提醒;常驻模式先显示消息数量,由你展开查看。',
'屏幕上方会有一条「灵动岛」浮窗:新通知、叫人、作业都会在那里弹出。', example: ['经典模式', '自定义常驻模式', '设置 → 灵动岛'],
'上课时段自动隐藏、下课自动弹出;外观与位置可在「设置 → 灵动岛」调整。',
],
}, },
{ {
icon: 'CircleCheckFilled', id: 'settings',
title: '准备好了', title: '准备好了',
lines: [ text: '在设置中调整外观和关怀模式,也可以随时重看引导。',
'按上面的步骤登录就可以开始使用了。', example: ['通用设置', '外观', '使用引导'],
'侧边栏「设置」分组里有通用、外观(深色模式)、灵动岛等页面;这份引导可以在登录页或「设置 → 通用 → 使用引导」随时重看。',
],
}, },
]; ];
async function finish(): Promise<void> {
const index = ref(0); try {
const current = computed(() => steps[index.value] ?? steps[0]); await window.desktop?.saveConfig({ onboardingDone: true, onboardingVersion: ONBOARDING_VERSION });
const isFirst = computed(() => index.value === 0); } finally {
const isLast = computed(() => index.value === steps.length - 1);
/** 每次打开都从第一步开始(重看入口也走完整流程) */
watch(
() => onboarding.visible,
(visible) => {
if (visible) index.value = 0;
},
);
function goNext(): void {
if (isLast.value) finish();
else index.value += 1;
}
function goPrev(): void {
if (!isFirst.value) index.value -= 1;
}
/** 完成 / 跳过统一走这里:记「已看过」并关闭(重看时重复写一次无副作用) */
function finish(): void {
const bridge = window.desktop;
// 桥接不可用(浏览器调试)也要能正常关掉引导
if (!bridge) {
onboarding.close(); onboarding.close();
return;
} }
void bridge
.saveConfig({ onboardingDone: true })
.then(() => onboarding.close())
.catch(() => onboarding.close());
} }
function onKeydown(event: KeyboardEvent): void {
if (onboarding.visible && event.key === 'Escape') finish();
}
if (typeof window !== 'undefined') {
window.addEventListener('keydown', onKeydown);
}
onUnmounted(() => {
window.removeEventListener('keydown', onKeydown);
});
</script> </script>
<template> <template>
<Transition name="onboarding-fade"> <FullScreenGuide
<div :model-value="onboarding.visible"
v-if="onboarding.visible" :steps="steps"
class="onboarding-mask" :brand-logo="BRAND_LOGO_URL"
role="dialog" @finish="finish"
aria-modal="true" />
aria-label="初次启动引导"
>
<div class="onboarding-card onboarding-welcome">
<div class="onboarding-head">
<span class="onboarding-logo">
<el-icon :size="18"><School /></el-icon>
</span>
<div class="onboarding-heading">
<h2 class="onboarding-title">ClassHelper</h2>
<p class="onboarding-sub">初次启动引导 · 第 {{ index + 1 }} / {{ steps.length }} 步</p>
</div>
<el-button link class="onboarding-skip" data-action="skip" @click="finish">跳过引导</el-button>
</div>
<div class="onboarding-body">
<span class="onboarding-icon">
<el-icon :size="30"><component :is="current.icon" /></el-icon>
</span>
<h3 class="onboarding-step-title">{{ current.title }}</h3>
<p v-for="(line, lineIndex) in current.lines" :key="lineIndex" class="onboarding-line">
{{ line }}
</p>
</div>
<div class="onboarding-foot">
<div class="onboarding-dots">
<span
v-for="(step, dotIndex) in steps"
:key="dotIndex"
class="dot"
:class="{ active: dotIndex === index }"
/>
</div>
<div class="onboarding-actions">
<el-button v-if="!isFirst" data-action="prev" @click="goPrev">上一步</el-button>
<el-button v-if="!isLast" type="primary" data-action="next" @click="goNext">下一步</el-button>
<el-button v-else type="primary" data-action="finish" @click="finish">开始使用</el-button>
</div>
</div>
</div>
</div>
</Transition>
</template> </template>
<style scoped>
.onboarding-mask {
position: fixed;
inset: 0;
z-index: 3000;
display: flex;
align-items: center;
justify-content: center;
padding: 24px;
background: rgba(15, 30, 50, 0.55);
}
.onboarding-card {
width: 520px;
max-width: 92vw;
max-height: 86vh;
overflow-y: auto;
background: var(--ch-layer-solid);
border-radius: 16px;
padding: 22px 24px 18px;
box-shadow: 0 24px 64px rgba(15, 30, 50, 0.35);
}
.onboarding-head {
display: flex;
align-items: center;
gap: 10px;
}
.onboarding-logo {
display: inline-flex;
align-items: center;
justify-content: center;
width: 34px;
height: 34px;
border-radius: 9px;
color: #fff;
background: linear-gradient(135deg, var(--ch-accent) 0%, #4d94d1 100%);
}
.onboarding-heading {
flex: 1;
min-width: 0;
}
.onboarding-title {
margin: 0;
font-size: 15px;
line-height: 1.3;
}
.onboarding-sub {
margin: 2px 0 0;
font-size: 12px;
color: var(--ch-text-tertiary);
}
.onboarding-body {
display: flex;
flex-direction: column;
align-items: flex-start;
padding: 18px 4px 6px;
}
.onboarding-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 58px;
height: 58px;
border-radius: 16px;
margin-bottom: 14px;
color: var(--ch-accent);
background: var(--ch-accent-soft);
}
.onboarding-step-title {
margin: 0 0 10px;
font-size: 18px;
}
.onboarding-line {
margin: 0 0 8px;
font-size: 13px;
line-height: 1.8;
color: var(--ch-text-secondary);
}
.onboarding-foot {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-top: 14px;
padding-top: 14px;
border-top: 1px solid var(--ch-divider);
}
.onboarding-dots {
display: flex;
align-items: center;
gap: 6px;
}
.dot {
width: 7px;
height: 7px;
border-radius: 999px;
background: var(--ch-border-strong);
transition: all 0.2s ease;
}
.dot.active {
width: 20px;
background: var(--ch-accent);
}
.onboarding-actions {
display: flex;
align-items: center;
gap: 8px;
}
/* 进出场:淡入 + 轻微上浮,跟随系统"动画"开关无强依赖 */
.onboarding-fade-enter-active,
.onboarding-fade-leave-active {
transition: opacity 0.22s ease;
}
.onboarding-fade-enter-active .onboarding-card,
.onboarding-fade-leave-active .onboarding-card {
transition: transform 0.22s ease;
}
.onboarding-fade-enter-from,
.onboarding-fade-leave-to {
opacity: 0;
}
.onboarding-fade-enter-from .onboarding-card,
.onboarding-fade-leave-to .onboarding-card {
transform: translateY(10px) scale(0.98);
}
</style>
@@ -5,6 +5,7 @@ import {
resolveClassStatus, resolveClassStatus,
type ClassPeriod, type ClassPeriod,
type HomeworkDto, type HomeworkDto,
type IslandTimePointDto,
type NotificationDto, type NotificationDto,
type ScheduleDto, type ScheduleDto,
} from '@classhelper/shared'; } from '@classhelper/shared';
@@ -30,6 +31,8 @@ const TICK_INTERVAL_MS = 1_000;
const REFRESH_INTERVAL_MS = 30_000; const REFRESH_INTERVAL_MS = 30_000;
let schedules: ScheduleDto[] = []; let schedules: ScheduleDto[] = [];
/** 今天的完整时间点(含课间/分割线/默认隐藏),自定义岛的课程表组件使用。 */
let dayTimePoints: IslandTimePointDto[] = [];
let currentPeriod: ClassPeriod | null = null; let currentPeriod: ClassPeriod | null = null;
let inClass = false; let inClass = false;
let tickTimer: ReturnType<typeof setInterval> | null = null; let tickTimer: ReturnType<typeof setInterval> | null = null;
@@ -47,6 +50,51 @@ export function getIslandSchedules(): ScheduleDto[] {
return schedules; return schedules;
} }
export function getIslandTimePoints(): IslandTimePointDto[] {
return dayTimePoints;
}
/** 从 active-week 的今天取完整时间点;课程名优先条目、没有条目才回退默认课程。 */
function buildDayTimePoints(days: ContractActiveClassPlanWeekDto['days']): IslandTimePointDto[] {
const weekday = new Date().getDay() || 7;
const day = days.find((item) => item.weekday === weekday);
const points = day?.timeLayout?.points ?? [];
if (!points.length) return [];
const entries = day?.classPlan?.entries ?? [];
return points.map((point) => {
const entry = entries.find((item) => item.timeLayoutItemId === point.id);
return {
id: point.id,
timeType: point.timeType,
name: point.breakName || point.name || '',
courseName: entry
? entry.isEnabled
? (entry.course?.name ?? null)
: null
: (point.defaultCourse?.name ?? null),
startTime: point.startTime,
endTime: point.endTime,
isHideDefault: point.isHideDefault,
};
});
}
/** 离线/旧服务端只有课表条目时退化成只有上课时间点。 */
function timePointsFromSchedules(list: ScheduleDto[]): IslandTimePointDto[] {
const weekday = new Date().getDay() || 7;
return list
.filter((item) => item.dayOfWeek === weekday)
.map((item) => ({
id: item.id,
timeType: 'LESSON' as const,
name: '',
courseName: item.course?.name ?? null,
startTime: item.startTime,
endTime: item.endTime,
isHideDefault: false,
}));
}
/** 主动刷新课表(课表变更事件触发) */ /** 主动刷新课表(课表变更事件触发) */
export async function refreshIslandSchedules(): Promise<void> { export async function refreshIslandSchedules(): Promise<void> {
const appStore = useAppStore(); const appStore = useAppStore();
@@ -61,13 +109,16 @@ export async function refreshIslandSchedules(): Promise<void> {
'schedules', 'schedules',
`week:${week}`, `week:${week}`,
async () => { async () => {
const data = ( const payload = await api.get<ContractActiveClassPlanWeekDto>('/schedules/active-week', {
await api.get<ContractActiveClassPlanWeekDto>('/schedules/active-week', { classId, week }) classId,
).days.flatMap((day) => day.schedules); week,
});
const data = payload.days.flatMap((day) => day.schedules);
// 网络结果先上岛,IndexedDB 写入不再挡住可见内容;旧请求与切换账号的结果不得回写。 // 网络结果先上岛,IndexedDB 写入不再挡住可见内容;旧请求与切换账号的结果不得回写。
if (scope !== getCacheScope() || request !== scheduleRequest || !auth.token) if (scope !== getCacheScope() || request !== scheduleRequest || !auth.token)
throw new Error('课表刷新已被新请求替代'); throw new Error('课表刷新已被新请求替代');
schedules = data; schedules = data;
dayTimePoints = buildDayTimePoints(payload.days);
scheduleWeek = week; scheduleWeek = week;
recomputeClassState(true); recomputeClassState(true);
return data; return data;
@@ -78,12 +129,22 @@ export async function refreshIslandSchedules(): Promise<void> {
if (result.error && !result.updatedAt) return; if (result.error && !result.updatedAt) return;
if (result.fromCache) { if (result.fromCache) {
schedules = result.data; schedules = result.data;
dayTimePoints = timePointsFromSchedules(result.data);
scheduleWeek = week; scheduleWeek = week;
recomputeClassState(true); recomputeClassState(true);
} }
} }
let sentDay = ''; let sentDay = '';
let sentTimePoints = '';
function timePointsKey(): string {
return dayTimePoints
.map(
(point) =>
`${point.id}|${point.timeType}|${point.startTime}|${point.endTime}|${point.name}|${point.courseName ?? ''}|${point.isHideDefault ? 1 : 0}`,
)
.join(',');
}
function recomputeClassState(force = false): void { function recomputeClassState(force = false): void {
const day = new Date().toDateString(); const day = new Date().toDateString();
const appStore = useAppStore(); const appStore = useAppStore();
@@ -94,15 +155,19 @@ function recomputeClassState(force = false): void {
currentPeriod?.endTime === status.current?.endTime; currentPeriod?.endTime === status.current?.endTime;
currentPeriod = status.current; currentPeriod = status.current;
if (!force && day === sentDay && nextInClass === inClass && samePeriod) return; const pointsKey = timePointsKey();
if (!force && day === sentDay && nextInClass === inClass && samePeriod && pointsKey === sentTimePoints)
return;
sentDay = day; sentDay = day;
inClass = nextInClass; inClass = nextInClass;
sentTimePoints = pointsKey;
window.desktop?.islandSetClassState({ window.desktop?.islandSetClassState({
inClass, inClass,
currentPeriodEnd: currentPeriod?.endTime ?? null, currentPeriodEnd: currentPeriod?.endTime ?? null,
week: appStore.currentWeek, week: appStore.currentWeek,
schedules: schedules.filter((s) => s.dayOfWeek === (new Date().getDay() || 7)), schedules: schedules.filter((s) => s.dayOfWeek === (new Date().getDay() || 7)),
timePoints: dayTimePoints,
}); });
} }
@@ -389,7 +454,9 @@ export function stopIslandBridge(): void {
useRealtimeStore().off(SOCKET_EVENTS.scheduleUpdated, onScheduleUpdated); useRealtimeStore().off(SOCKET_EVENTS.scheduleUpdated, onScheduleUpdated);
useRealtimeStore().off('__connected__', onScheduleUpdated); useRealtimeStore().off('__connected__', onScheduleUpdated);
sentDay = ''; sentDay = '';
sentTimePoints = '';
schedules = []; schedules = [];
dayTimePoints = [];
currentPeriod = null; currentPeriod = null;
inClass = false; inClass = false;
@@ -401,5 +468,6 @@ export function stopIslandBridge(): void {
currentPeriodEnd: null, currentPeriodEnd: null,
week: useAppStore().currentWeek, week: useAppStore().currentWeek,
schedules: [], schedules: [],
timePoints: [],
}); });
} }
@@ -11,6 +11,8 @@ import router from './router/index.js';
import { registerAppIcons } from './icons.js'; import { registerAppIcons } from './icons.js';
import { applyMotionTokens } from './composables/motion.js'; import { applyMotionTokens } from './composables/motion.js';
import './styles/index.css'; import './styles/index.css';
import { registerSharedUi } from '@classhelper/ui';
import '@classhelper/ui/theme.css';
const app = createApp(App); const app = createApp(App);
@@ -20,6 +22,7 @@ registerAppIcons(app);
app.use(createPinia()); app.use(createPinia());
app.use(router); app.use(router);
app.use(ElementPlus, { locale: zhCn }); app.use(ElementPlus, { locale: zhCn });
registerSharedUi(app);
// 冒烟验证模式:把缓存自检钩子暴露给主进程调用(正常运行时不存在)。 // 冒烟验证模式:把缓存自检钩子暴露给主进程调用(正常运行时不存在)。
// //
@@ -1,14 +1,7 @@
import { ref } from 'vue'; import { ref } from 'vue';
import { defineStore } from 'pinia'; import { defineStore } from 'pinia';
/** /** App.vue 按引导版本自动展示;登录页和设置页可随时重看。 */
* 初次启动引导的显示状态。
*
* 首次启动由 App.vue 按「配置里是否记过 onboardingDone」自动弹出;
* 登录页与设置页的「使用引导」入口调用 open() 随时重看。
* 单独一个 store 而不是组件内部 ref:触发入口(登录页 / 设置页)与
* 渲染点(App.vue 顶层)分处两棵互不相干的子树。
*/
export const useOnboardingStore = defineStore('onboarding', () => { export const useOnboardingStore = defineStore('onboarding', () => {
const visible = ref(false); const visible = ref(false);
@@ -60,9 +60,10 @@ export const useRealtimeStore = defineStore('realtime', () => {
connecting.value = false; connecting.value = false;
dispatch('__connected__', null); dispatch('__connected__', null);
}); });
instance.on('disconnect', () => { instance.on('disconnect', (reason: string) => {
connected.value = false; connected.value = false;
dispatch('__disconnected__', null); dispatch('__disconnected__', null);
if (reason === 'io server disconnect' && socket === instance) instance.connect();
}); });
instance.on('connect_error', (error: Error) => { instance.on('connect_error', (error: Error) => {
connected.value = false; connected.value = false;
@@ -0,0 +1,453 @@
.island-editor-page {
display: flex;
flex-direction: column;
flex: 1 0 auto;
min-height: 0;
min-width: 0;
color: var(--ch-text);
padding: 12px 24px 16px;
background: var(--editor-background, var(--ch-bg));
}
:global(.main:has(> .island-editor-page)) {
display: flex;
flex-direction: column;
}
:global(.main:has(> .island-editor-page) > .offline-banner),
.island-editor-page > * {
flex-shrink: 0;
}
:global(html.dark) .island-editor-page {
--editor-background: #262626;
--editor-divider: #3a3a3a;
--editor-card: #2c2c2c;
}
.editor-actions {
display: flex;
align-items: center;
justify-content: flex-end;
gap: 8px;
min-height: 30px;
margin-bottom: 4px;
}
.save-status {
color: var(--ch-text-tertiary);
font-size: 12px;
margin-right: 8px;
}
.save-status.failed {
color: var(--el-color-danger);
}
.component-heading {
align-items: flex-end;
gap: 24px;
margin-bottom: 20px;
}
.heading-copy {
flex: 1 1 380px;
}
.component-heading .page-title {
font-size: calc(34px * var(--ch-font-scale));
font-weight: 600;
line-height: 1.4;
margin-bottom: 20px;
}
.heading-copy p {
font-size: calc(16px * var(--ch-font-scale));
margin: 0;
line-height: 1.6;
}
.scheme-tools {
flex: 0 1 348px;
min-width: 300px;
}
.scheme-tools label {
display: block;
margin-bottom: 6px;
font-size: 14px;
font-weight: 600;
}
.scheme-controls {
display: flex;
gap: 6px;
align-items: center;
}
.scheme-controls .el-select {
min-width: 140px;
flex: 1;
}
.scheme-controls :deep(.el-select__wrapper) {
min-height: 38px;
background: var(--ch-card-subtle);
}
.icon-button {
width: 34px;
height: 36px;
padding: 8px;
margin: 0;
flex-shrink: 0;
font-size: 19px;
}
.surface-toolbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
flex-wrap: wrap;
}
.surface-tabs,
.surface-actions {
display: flex;
gap: 12px;
align-items: center;
}
.surface-actions {
gap: 0;
}
.surface-tabs button {
position: relative;
border: 0;
background: transparent;
color: var(--ch-text-secondary);
font: inherit;
font-size: 12px;
padding: 6px 0 9px;
cursor: pointer;
}
.surface-tabs button.active {
color: var(--ch-text);
}
.surface-tabs button.active::after {
content: '';
position: absolute;
bottom: 0;
left: 10%;
right: 10%;
height: 2px;
background: var(--ch-accent);
border-radius: 2px;
}
.preview-canvas {
min-height: 80px;
overflow: auto;
padding: 10px 0 20px;
}
.component-lines {
min-width: 100%;
width: max-content;
}
.component-line {
display: flex;
align-items: center;
min-height: 54px;
border-radius: 6px;
gap: 12px;
padding: 4px;
border: 1px solid transparent;
}
.component-line + .component-line {
margin-top: 6px;
}
.component-line.active-row {
border-color: var(--ch-border-strong);
}
.row-handle {
align-self: stretch;
width: 24px;
flex-shrink: 0;
padding: 0;
border: 0;
background: transparent;
color: var(--ch-text-secondary);
font: inherit;
font-size: 20px;
cursor: grab;
touch-action: none;
}
.row-handle:hover {
color: var(--ch-accent);
background: var(--ch-hover-soft);
}
.line-components {
display: flex;
justify-content: center;
align-items: center;
flex: 1;
padding: 0 28px 0 0;
min-height: 38px;
}
.empty-line {
border: 1px dashed var(--ch-border-strong);
background: transparent;
color: var(--ch-text-tertiary);
padding: 10px 24px;
border-radius: 5px;
font: inherit;
font-size: 12px;
cursor: pointer;
}
.preview-canvas.live-preview {
display: grid;
place-items: center;
min-height: 160px;
padding: 24px;
background: var(--ch-layer-alt);
border-radius: 6px;
margin-top: 8px;
}
.island-preview {
display: flex;
flex-direction: column;
gap: var(--preview-gap);
width: max-content;
color: #ffffffeb;
padding: 12px;
border-radius: var(--preview-radius);
background: #202024;
}
.preview-row {
display: flex;
align-items: center;
min-width: 120px;
min-height: 44px;
border-radius: var(--preview-radius);
}
.island-preview.separated {
background: transparent;
padding: 0;
}
.separated .preview-row {
padding: 12px;
background: #202024;
}
.empty-preview {
color: #ffffffb8;
background: transparent;
border: 1px dashed #ffffff60;
border-radius: 5px;
padding: 10px 20px;
cursor: pointer;
font: inherit;
font-size: 13px;
}
.drop-row {
outline: 2px dashed var(--ch-accent);
outline-offset: -2px;
background: var(--ch-accent-soft);
}
.preview-toolbar {
display: flex;
align-items: center;
gap: 14px;
padding: 6px 0 12px;
color: var(--ch-text-secondary);
font-size: 12px;
}
.preview-toolbar .el-slider {
width: 130px;
}
.hint {
color: var(--ch-text-secondary);
line-height: 1.6;
font-size: 12px;
}
.component-library {
border-top: 6px solid var(--editor-divider, var(--ch-divider));
margin: 0 -24px;
padding: 14px 24px 24px;
flex: 1 0 auto;
}
.library-title {
position: relative;
width: max-content;
font-size: 17px;
font-weight: 600;
margin: 0 0 12px;
padding: 0 0 7px;
}
.library-title::after {
content: '';
position: absolute;
bottom: 0;
left: 0;
right: 0;
height: 3px;
border-radius: 3px;
background: var(--ch-accent);
}
.component-options {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
gap: 12px 20px;
}
.library-item {
min-width: 0;
width: 100%;
display: flex;
gap: 12px;
align-items: center;
text-align: left;
min-height: 76px;
padding: 10px 8px;
border: 1px solid transparent;
border-radius: 6px;
background: transparent;
color: inherit;
font: inherit;
cursor: grab;
touch-action: none;
transition:
background var(--ch-dur-fast) var(--ch-ease-out),
border-color var(--ch-dur-fast) var(--ch-ease-out);
}
.library-item:hover {
background: var(--ch-hover-soft);
border-color: var(--ch-border);
}
.library-item:active {
background: var(--ch-accent-soft);
}
.library-item:focus-visible,
.row-handle:focus-visible,
.surface-tabs button:focus-visible {
outline: 2px solid var(--ch-accent);
outline-offset: 2px;
}
.library-item > svg {
width: 36px;
height: 36px;
flex: 0 0 36px;
}
.library-item > span {
min-width: 0;
}
.library-item strong {
display: block;
font-size: calc(18px * var(--ch-font-scale));
font-weight: 500;
line-height: 1.5;
}
.component-description {
display: block;
color: var(--ch-text-secondary);
font-size: calc(14px * var(--ch-font-scale));
line-height: 1.5;
}
.message-library-title {
color: var(--ch-text-tertiary);
font-size: 12px;
font-weight: 400;
margin: 20px 8px 4px;
}
.message-options .library-item {
min-height: 64px;
}
.message-options .library-item strong {
font-size: 15px;
}
.message-options .library-item > svg {
width: 26px;
height: 26px;
flex-basis: 26px;
}
.editor-tip {
display: flex;
align-items: center;
gap: 14px;
padding: 12px 16px;
min-height: 60px;
border: 1px solid var(--ch-border-strong);
border-radius: 5px;
background: var(--editor-card, var(--ch-card-subtle));
font-size: 14px;
}
.editor-tip > span {
flex: 1;
line-height: 1.6;
}
.tip-icon {
color: var(--ch-accent);
font-size: 22px;
}
.dismiss-tip {
border: 0;
color: var(--ch-text);
background: transparent;
font-size: 26px;
cursor: pointer;
margin-left: auto;
padding: 0 8px;
}
.drag-ghost {
position: fixed;
z-index: 10000;
pointer-events: none;
padding: 10px 16px;
background: var(--ch-layer-solid);
border: 1px solid var(--ch-accent);
border-radius: 6px;
box-shadow: var(--ch-shadow-flyout);
color: var(--ch-text);
font-size: 14px;
}
.inspector-tabs {
margin-bottom: 20px;
}
.row-actions {
display: flex;
gap: 6px;
flex-wrap: wrap;
margin-top: 20px;
}
.row-actions .el-button {
margin: 0;
}
@media (max-width: 1150px) {
.component-options {
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 8px;
}
.component-heading {
gap: 16px;
}
.heading-copy {
flex-basis: 300px;
}
.scheme-tools {
flex-basis: 300px;
}
}
@media (max-width: 800px) {
.component-options {
grid-template-columns: repeat(2, minmax(0, 1fr));
}
.component-heading .page-title {
margin-bottom: 10px;
}
.scheme-tools {
flex: 1 1 100%;
}
.editor-tip {
flex-wrap: wrap;
}
.preview-toolbar .hint {
display: none;
}
}
@media (max-width: 520px) {
.component-options {
grid-template-columns: 1fr;
}
.island-editor-page {
padding-right: 16px;
padding-left: 16px;
}
.component-library {
margin-right: -16px;
margin-left: -16px;
padding-right: 16px;
padding-left: 16px;
}
.save-status {
display: none;
}
}
@@ -1,5 +1,6 @@
<script setup lang="ts"> <script setup lang="ts">
import { computed, onMounted, onUnmounted, ref } from 'vue'; import { countDates } from '@classhelper/ui';
import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
import { ElMessage } from 'element-plus'; import { ElMessage } from 'element-plus';
import { import {
COURSEWARE_CATEGORIES, COURSEWARE_CATEGORIES,
@@ -12,6 +13,18 @@ import { fetchWithCache } from '../cache/index.js';
import { getCacheScope } from '../cache/scope.js'; import { getCacheScope } from '../cache/scope.js';
import { useRealtimeStore } from '../stores/realtime.js'; import { useRealtimeStore } from '../stores/realtime.js';
const realtime = useRealtimeStore(); const realtime = useRealtimeStore();
const localItems = ref<CoursewareDto[]>([]),
library = ref<'shared' | 'local'>('shared'),
teacher = ref('');
const source = computed(() => (library.value === 'local' ? localItems.value : items.value));
const teachers = computed(() => [...new Set(source.value.map((item) => item.teacher.name))]);
async function refreshLocal() {
localItems.value = (await window.desktop?.listLocalCourseware()) || [];
}
// 两个来源的教师与目录不通用,切换时清空,避免看到空列表却找不到原因。
watch(library, () => {
teacher.value = '';
});
const items = ref<CoursewareDto[]>([]), const items = ref<CoursewareDto[]>([]),
loading = ref(false), loading = ref(false),
offline = ref(false), offline = ref(false),
@@ -21,16 +34,21 @@ const query = ref(''),
date = ref(''), date = ref(''),
busy = ref<string[]>([]), busy = ref<string[]>([]),
transfer = ref<CoursewareTransfer | null>(null); transfer = ref<CoursewareTransfer | null>(null);
const filtered = computed(() => const dateSource = computed(() =>
items.value.filter( source.value.filter(
(item) => (item) =>
(!query.value || `${item.name} ${item.teacher.name}`.includes(query.value)) && (!query.value || `${item.name} ${item.teacher.name}`.includes(query.value)) &&
(!category.value || item.category === category.value) && (!category.value || item.category === category.value) &&
(!date.value || item.archiveDate === date.value), (!teacher.value || item.teacher.name === teacher.value),
), ),
); );
const dateMarks = computed(() => countDates(dateSource.value, (item) => item.archiveDate));
const filtered = computed(() =>
dateSource.value.filter((item) => !date.value || item.archiveDate === date.value),
);
let disposed = false; let disposed = false;
async function refresh() { async function refresh() {
await refreshLocal();
const scope = getCacheScope(); const scope = getCacheScope();
loading.value = true; loading.value = true;
try { try {
@@ -53,6 +71,7 @@ async function download(item: CoursewareDto) {
busy.value.push(item.id); busy.value.push(item.id);
try { try {
await window.desktop.downloadCourseware(item.id); await window.desktop.downloadCourseware(item.id);
await refreshLocal();
ElMessage.success('课件已下载,可打开所在文件夹'); ElMessage.success('课件已下载,可打开所在文件夹');
} catch (e) { } catch (e) {
ElMessage.error(e instanceof Error ? e.message : String(e)); ElMessage.error(e instanceof Error ? e.message : String(e));
@@ -77,6 +96,7 @@ onMounted(() => {
timer = setInterval(() => void refresh(), 30000); timer = setInterval(() => void refresh(), 30000);
offProgress = window.desktop?.onCoursewareTransfer((value) => { offProgress = window.desktop?.onCoursewareTransfer((value) => {
transfer.value = value; transfer.value = value;
if (value?.stage === 'completed') void refreshLocal();
}); });
void window.desktop?.getCoursewareTransfer().then((value) => { void window.desktop?.getCoursewareTransfer().then((value) => {
if (!disposed) transfer.value = value; if (!disposed) transfer.value = value;
@@ -122,15 +142,26 @@ onUnmounted(() => {
<p v-if="transfer.error">{{ transfer.error }}</p> <p v-if="transfer.error">{{ transfer.error }}</p>
</el-card> </el-card>
<div class="filters"> <div class="filters">
<el-radio-group v-model="library">
<el-radio-button value="shared">班级共享</el-radio-button>
<el-radio-button value="local">本机归档</el-radio-button>
</el-radio-group>
<el-select v-model="teacher" clearable placeholder="全部教师">
<el-option v-for="name in teachers" :key="name" :label="name" :value="name" />
</el-select>
<el-input v-model="query" clearable placeholder="搜索课件或教师" /> <el-input v-model="query" clearable placeholder="搜索课件或教师" />
<el-select v-model="category" clearable placeholder="全部类型"> <el-select v-model="category" clearable placeholder="全部类型">
<el-option v-for="(label, key) in COURSEWARE_CATEGORIES" :key="key" :label="label" :value="key" /> <el-option v-for="(label, key) in COURSEWARE_CATEGORIES" :key="key" :label="label" :value="key" />
</el-select> </el-select>
<el-date-picker v-model="date" value-format="YYYY-MM-DD" placeholder="归档日期" /> <ch-date-picker v-model="date" :marks="dateMarks" value-format="YYYY-MM-DD" placeholder="归档日期" />
</div> </div>
<el-card shadow="never" class="table-card" v-loading="loading"> <el-card shadow="never" class="table-card" v-loading="loading">
<el-table :data="filtered" empty-text="老师还没有向本班共享课件"> <el-table
:data="filtered"
:empty-text="library === 'local' ? '本机还没有已归档的课件' : '老师还没有向本班共享课件'"
>
<el-table-column prop="name" label="课件名称" min-width="200" show-overflow-tooltip /> <el-table-column prop="name" label="课件名称" min-width="200" show-overflow-tooltip />
<el-table-column prop="archivePath" label="归档路径" min-width="250" show-overflow-tooltip />
<el-table-column label="类型" min-width="110"> <el-table-column label="类型" min-width="110">
<template #default="{ row }"> <template #default="{ row }">
{{ COURSEWARE_CATEGORIES[(row as CoursewareDto).category] }} · {{ row.extension || '无扩展名' }} {{ COURSEWARE_CATEGORIES[(row as CoursewareDto).category] }} · {{ row.extension || '无扩展名' }}
@@ -143,7 +174,13 @@ onUnmounted(() => {
</el-table-column> </el-table-column>
<el-table-column label="操作" min-width="200"> <el-table-column label="操作" min-width="200">
<template #default="{ row }"> <template #default="{ row }">
<el-button link type="primary" :loading="busy.includes(row.id)" @click="download(row)"> <el-button
v-if="library === 'shared'"
link
type="primary"
:loading="busy.includes(row.id)"
@click="download(row)"
>
下载 下载
</el-button> </el-button>
<el-button link @click="reveal(row.id)">打开文件夹</el-button> <el-button link @click="reveal(row.id)">打开文件夹</el-button>
@@ -1,4 +1,6 @@
<script setup lang="ts"> <script setup lang="ts">
import { getCacheScope } from '../cache/scope.js';
import type { CalendarRange } from '@classhelper/ui';
import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'; import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue';
import { useRoute, useRouter } from 'vue-router'; import { useRoute, useRouter } from 'vue-router';
import { ElMessage } from 'element-plus'; import { ElMessage } from 'element-plus';
@@ -60,19 +62,13 @@ const selectedDate = ref(
? route.query.date ? route.query.date
: dayKeyLocal(new Date()), : dayKeyLocal(new Date()),
); );
/** 有作业的日期(日期选择器高亮):来自 GET /homeworks/days */ const calendarRevision = ref(0);
const dayMarks = ref<Map<string, number>>(new Map());
/** 录入作业的科目下拉 */ /** 录入作业的科目下拉 */
const courses = ref<CourseDto[]>([]); const courses = ref<CourseDto[]>([]);
/** 选中的是否就是今天(标题与按钮文案用) */ /** 选中的是否就是今天(标题与按钮文案用) */
const isToday = computed(() => selectedDate.value === dayKeyLocal(now.value)); const isToday = computed(() => selectedDate.value === dayKeyLocal(now.value));
/** 日期选择器:给有作业的日期加高亮类 */
function dayCellClass(date: Date): string {
return dayMarks.value.has(dayKeyLocal(date)) ? 'day-has-homework' : '';
}
async function selectDate(value: string | null): Promise<void> { async function selectDate(value: string | null): Promise<void> {
if (!value || !isDayKey(value)) return; if (!value || !isDayKey(value)) return;
selectedDate.value = value; selectedDate.value = value;
@@ -279,6 +275,7 @@ function onResize(): void {
/* ------------------------------------------------------------ 数据加载 */ /* ------------------------------------------------------------ 数据加载 */
async function loadHomework(): Promise<void> { async function loadHomework(): Promise<void> {
calendarRevision.value++;
loading.value = true; loading.value = true;
try { try {
const classId = auth.classId ?? undefined; const classId = auth.classId ?? undefined;
@@ -294,7 +291,6 @@ async function loadHomework(): Promise<void> {
fromCache.value = result.fromCache; fromCache.value = result.fromCache;
updatedAt.value = result.updatedAt; updatedAt.value = result.updatedAt;
if (!result.fromCache) appStore.markSynced(); if (!result.fromCache) appStore.markSynced();
void loadDayMarks(classId);
if (current.value) { if (current.value) {
current.value = homeworks.value.find((item) => item.id === current.value?.id) ?? current.value; current.value = homeworks.value.find((item) => item.id === current.value?.id) ?? current.value;
} }
@@ -304,22 +300,15 @@ async function loadHomework(): Promise<void> {
} }
} }
/** async function calendarDays(range: CalendarRange) {
* 拉取"哪些天有作业"(日期选择器高亮)。 const result = await fetchWithCache(
* 'homeworks',
* 范围取当前查看日期前后各 45 天:教室电脑上翻月份也能看到有作业的日子。 `days:${JSON.stringify(range)}`,
*/ () => homeworkApi.days({ ...range, classId: auth.classId || undefined }),
async function loadDayMarks(classId: string | undefined): Promise<void> { { days: [] as { date: string; count: number }[] },
try { );
const from = shiftDayKey(selectedDate.value, -45); return result.data.days;
const to = shiftDayKey(selectedDate.value, 45);
const result = await homeworkApi.days({ classId, from, to });
dayMarks.value = new Map(result.days.map((item) => [item.date, item.count]));
} catch {
// 离线/失败时保留上一次的高亮,不打断展示
}
} }
/** 科目下拉(录入作业时可选) */ /** 科目下拉(录入作业时可选) */
async function loadCourses(): Promise<void> { async function loadCourses(): Promise<void> {
if (!auth.classId) return; if (!auth.classId) return;
@@ -569,15 +558,19 @@ onUnmounted(() => {
<el-button-group> <el-button-group>
<el-button :icon="'ArrowLeft'" @click="shiftDate(-1)">前一天</el-button> <el-button :icon="'ArrowLeft'" @click="shiftDate(-1)">前一天</el-button>
<el-button :disabled="isToday" @click="selectDate(dayKeyLocal(now))">今天</el-button> <el-button :disabled="isToday" @click="selectDate(dayKeyLocal(now))">今天</el-button>
<el-button @click="shiftDate(1)">后一天<el-icon class="ml-4"><ArrowRight /></el-icon></el-button> <el-button @click="shiftDate(1)">
后一天
<el-icon class="ml-4"><ArrowRight /></el-icon>
</el-button>
</el-button-group> </el-button-group>
<el-date-picker <ch-date-picker
:model-value="selectedDate" :model-value="selectedDate"
type="date" type="date"
value-format="YYYY-MM-DD" value-format="YYYY-MM-DD"
placeholder="选择日期" placeholder="选择日期"
class="day-picker" class="day-picker"
:cell-class-name="dayCellClass" :load-marks="calendarDays"
:scope-key="JSON.stringify([getCacheScope(), selectedDate, calendarRevision])"
@update:model-value="(value: string | null) => selectDate(value)" @update:model-value="(value: string | null) => selectDate(value)"
/> />
<el-radio-group v-model="viewMode" @change="saveBoardSettings"> <el-radio-group v-model="viewMode" @change="saveBoardSettings">
@@ -765,11 +758,12 @@ onUnmounted(() => {
<el-dialog v-model="createVisible" title="录入作业" width="620px"> <el-dialog v-model="createVisible" title="录入作业" width="620px">
<el-form label-width="90px"> <el-form label-width="90px">
<el-form-item label="所属日期"> <el-form-item label="所属日期">
<el-date-picker <ch-date-picker
:model-value="selectedDate" :model-value="selectedDate"
type="date" type="date"
value-format="YYYY-MM-DD" value-format="YYYY-MM-DD"
:cell-class-name="dayCellClass" :load-marks="calendarDays"
:scope-key="JSON.stringify([getCacheScope(), calendarRevision])"
@update:model-value="(value: string | null) => selectDate(value)" @update:model-value="(value: string | null) => selectDate(value)"
/> />
<span class="text-muted ml-8">默认就是当前正在查看的这一天</span> <span class="text-muted ml-8">默认就是当前正在查看的这一天</span>
@@ -810,7 +804,9 @@ onUnmounted(() => {
> >
{{ item }} {{ item }}
</el-tag> </el-tag>
<span class="text-muted">点一下追加到「{{ lastFocused === 'title' ? '标题' : '作业要求' }}」</span> <span class="text-muted">
点一下追加到「{{ lastFocused === 'title' ? '标题' : '作业要求' }}」
</span>
</div> </div>
</el-form-item> </el-form-item>
</el-form> </el-form>
@@ -880,19 +876,6 @@ onUnmounted(() => {
</template> </template>
<style scoped> <style scoped>
/* 日期选择器:有作业的日子加一个圆点,翻月份时一眼看出哪天有作业 */
:deep(.day-has-homework .el-date-table-cell__text)::after {
content: '';
position: absolute;
left: 50%;
bottom: 2px;
width: 4px;
height: 4px;
margin-left: -2px;
border-radius: 50%;
background: currentColor;
}
.day-picker { .day-picker {
width: 168px; width: 168px;
} }
@@ -1,5 +1,11 @@
<script setup lang="ts"> <script setup lang="ts">
import { computed, onMounted, onUnmounted, ref } from 'vue'; import { notificationApi } from '../api/index.js';
import { fetchWithCache } from '../cache/index.js';
import { getCacheScope } from '../cache/scope.js';
import { useAuthStore } from '../stores/auth.js';
import type { CalendarRange } from '@classhelper/ui';
import { countDates } from '@classhelper/ui';
import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
import { ElMessage } from 'element-plus'; import { ElMessage } from 'element-plus';
import { import {
NOTIFICATION_PRIORITIES, NOTIFICATION_PRIORITIES,
@@ -22,21 +28,70 @@ const filter = ref<'all' | 'unread'>('all');
const detailVisible = ref(false); const detailVisible = ref(false);
const current = ref<NotificationDto | null>(null); const current = ref<NotificationDto | null>(null);
const marking = ref(false); const marking = ref(false);
const auth = useAuthStore();
const calendarRevision = ref(0);
const dayItems = ref<NotificationDto[] | null>(null);
let calendarRequest = 0,
disposed = false;
async function calendarDays(range: CalendarRange) {
const params = {
...range,
classId: auth.classId || undefined,
createdBy: creatorFilter.value || undefined,
priority: priorityFilter.value || undefined,
unreadOnly: filter.value === 'unread',
};
const result = await fetchWithCache(
'notifications',
'days:' + JSON.stringify(params),
() => notificationApi.days(params),
{ days: dateMarks.value },
);
return result.data.days;
}
async function loadDay(): Promise<void> {
const request = ++calendarRequest,
scope = getCacheScope();
if (!dayFilter.value) {
dayItems.value = null;
return;
}
const params = {
date: dayFilter.value,
classId: auth.classId || undefined,
createdBy: creatorFilter.value || undefined,
priority: priorityFilter.value || undefined,
unreadOnly: filter.value === 'unread',
};
const fallback = store.items.filter((item) => assignDay(item) === params.date);
dayItems.value = [];
const result = await fetchWithCache<NotificationDto[]>(
'notifications',
'date:' + JSON.stringify(params),
() => notificationApi.list(params),
fallback,
);
if (!disposed && request === calendarRequest && scope === getCacheScope()) dayItems.value = result.data;
}
const visibleItems = computed(() => const visibleItems = computed(() =>
filter.value === 'unread' ? store.items.filter((item) => !item.read) : store.items, filter.value === 'unread'
? (dayItems.value ?? store.items).filter((item) => !item.read)
: (dayItems.value ?? store.items),
); );
/* ------------------------------------------------------- 按天归档 / 按发布人 / 按类型 */ watch(
/** () => store.items,
* 三个筛选都在**已加载的列表**上做,不再请求服务端: () => {
* 客户端是离线优先的(AGENTS.md 的现行工程约定),断网回退缓存时归档功能必须照常可用。 calendarRevision.value++;
* 口径与服务端一致:按 `assignDate`(本地日期)分组 —— 用 createdAt 的 UTC 切片会把晚上 },
* 发出来的通知算到第二天(AGENTS.md 的现行工程约定)。 );
*/
const dayFilter = ref(''); const dayFilter = ref('');
const creatorFilter = ref(''); const creatorFilter = ref('');
const priorityFilter = ref(''); const priorityFilter = ref('');
watch([dayFilter, creatorFilter, priorityFilter, filter, () => store.items], () => {
void loadDay();
});
/** /**
* 一条通知归到哪一天。 * 一条通知归到哪一天。
@@ -47,16 +102,17 @@ function assignDay(item: NotificationDto): string {
return item.assignDate || dayKeyLocal(new Date(item.createdAt)); return item.assignDate || dayKeyLocal(new Date(item.createdAt));
} }
const dayOptions = computed(() => { const dateMarks = computed(() =>
const map = new Map<string, number>(); countDates(
for (const item of store.items) { store.items.filter(
const day = assignDay(item); (item) =>
map.set(day, (map.get(day) ?? 0) + 1); (filter.value !== 'unread' || !item.read) &&
} (!creatorFilter.value || item.createdBy === creatorFilter.value) &&
return [...map.entries()] (!priorityFilter.value || item.priority === priorityFilter.value),
.sort((a, b) => b[0].localeCompare(a[0])) ),
.map(([date, count]) => ({ date, count })); assignDay,
}); ),
);
const creatorOptions = computed(() => { const creatorOptions = computed(() => {
const map = new Map<string, { name: string; count: number }>(); const map = new Map<string, { name: string; count: number }>();
@@ -117,6 +173,7 @@ async function markRead(item: NotificationDto): Promise<void> {
marking.value = true; marking.value = true;
try { try {
await store.markRead(item.id); await store.markRead(item.id);
item.read = true;
if (current.value?.id === item.id) current.value = { ...item, read: true }; if (current.value?.id === item.id) current.value = { ...item, read: true };
} catch (error) { } catch (error) {
ElMessage.error(error instanceof Error ? error.message : '标记已读失败'); ElMessage.error(error instanceof Error ? error.message : '标记已读失败');
@@ -147,6 +204,8 @@ onMounted(async () => {
}); });
onUnmounted(() => { onUnmounted(() => {
disposed = true;
++calendarRequest;
// store 是全局的,这里无需清理;保留钩子以便将来取消订阅 // store 是全局的,这里无需清理;保留钩子以便将来取消订阅
}); });
</script> </script>
@@ -175,16 +234,14 @@ onUnmounted(() => {
</div> </div>
<el-card v-loading="store.loading" shadow="never"> <el-card v-loading="store.loading" shadow="never">
<!-- 按天归档 + 按发布人 + 按类型;都在本地已加载的列表上筛(离线也能用) -->
<div class="notice-filters"> <div class="notice-filters">
<el-select v-model="dayFilter" placeholder="按天归档" clearable size="small" style="width: 150px"> <ch-date-picker
<el-option v-model="dayFilter"
v-for="item in dayOptions" :load-marks="calendarDays"
:key="item.date" :scope-key="JSON.stringify([creatorFilter, priorityFilter, filter, calendarRevision])"
:label="`${item.date}(${item.count})`" placeholder="日期"
:value="item.date" clearable
/> />
</el-select>
<el-select <el-select
v-model="creatorFilter" v-model="creatorFilter"
placeholder="全部发布人" placeholder="全部发布人"
@@ -75,7 +75,6 @@ onMounted(async () => {
<div class="page-header"> <div class="page-header">
<div> <div>
<h2 class="page-title">关于</h2> <h2 class="page-title">关于</h2>
<p class="page-subtitle">版本、诊断信息与鸣谢</p>
</div> </div>
</div> </div>
@@ -27,7 +27,6 @@ async function logout(): Promise<void> {
<div class="page-header"> <div class="page-header">
<div> <div>
<h2 class="page-title">账号</h2> <h2 class="page-title">账号</h2>
<p class="page-subtitle">本机登录的班级账号</p>
</div> </div>
</div> </div>
@@ -26,7 +26,6 @@ async function selectTheme(value: 'light' | 'dark'): Promise<void> {
<div class="page-header"> <div class="page-header">
<div> <div>
<h2 class="page-title">外观</h2> <h2 class="page-title">外观</h2>
<p class="page-subtitle">黑夜与白天模式,切换立即生效并自动保存</p>
</div> </div>
</div> </div>
@@ -50,7 +49,10 @@ async function selectTheme(value: 'light' | 'dark'): Promise<void> {
</span> </span>
</span> </span>
<span class="theme-name"> <span class="theme-name">
<el-icon><Sunny v-if="option.value === 'light'" /><Moon v-else /></el-icon> <el-icon>
<Sunny v-if="option.value === 'light'" />
<Moon v-else />
</el-icon>
{{ option.label }} {{ option.label }}
</span> </span>
<span class="theme-desc">{{ option.desc }}</span> <span class="theme-desc">{{ option.desc }}</span>
Loaded 100 of 312 files, more files were not shown because too many files have changed in this diff. Show more