21 Commits
Author SHA1 Message Date
LoveChengke 0b57e926bd fix(release): 发布1.4.5并加固登录与灵动岛体验
登录连续五次失败封禁五分钟,修复两端错误提示;教师导入逐人生成随机密码并提供一次性清单。统一自定义岛外观与控件,修复圆角配置和全天课表对齐,临近下课显示课程旁秒数徽标;客户端更新改为云端统一下发。同步发布版本、帮助文档及隔离回归。
2026-11-08 09:55:33 +08:00
LoveChengke 9351203deb feat: 完善 AI 对话、每日作息与课件目录体验
新增持久化对话、追问卡片和轮次导航;支持每日子时间表、切换保留课程与自动课间;完善课件逐层目录、学期周次同步及两端自适应。同步迁移、文档和回归截图。

验证:后端 262/262、AI 55 项、Web 81/81、桌面 71/71、授权 23 项;构建、类型、Lint 与文档检查通过。
2026-11-08 09:07:10 +08:00
LoveChengke cdb64c5499 fix: 完善AI流式后台任务与模型配置 2026-11-07 22:25:39 +08:00
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
335 changed files with 27034 additions and 7093 deletions

No files matched your search

+5 -1
View File
@@ -26,6 +26,10 @@ on:
required: false required: false
default: true default: true
type: boolean type: boolean
source_ref:
description: '同版本重建的源码提交;留空按 tag 检出'
required: false
type: string
push: push:
tags: tags:
- 'v*' - 'v*'
@@ -53,7 +57,7 @@ jobs:
- name: 检出代码 - name: 检出代码
uses: actions/checkout@v4 uses: actions/checkout@v4
with: with:
ref: ${{ steps.ref.outputs.tag }} ref: ${{ inputs.source_ref || steps.ref.outputs.tag }}
- name: 安装 Node 22 - name: 安装 Node 22
uses: actions/setup-node@v4 uses: actions/setup-node@v4
+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.1} image: classhelper-server:${APP_VERSION:-1.4.5}
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.1} image: classhelper-server:${APP_VERSION:-1.4.5}
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.1", "version": "1.4.5",
"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"
} }
} }
+11 -9
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 的作业、通知日期统计保留在当前会话缓存中,按服务器、操作者、权限范围和筛选条件隔离;退出或收到授权失败时清理。桌面端复用按服务器和班级隔离的离线缓存。只有网络不可达时才回退缓存,缓存故障不阻断在线读取。
首次进入新版会显示全屏分步引导,可以返回、跳过或完成;账号菜单、客户端登录页和通用设置保留重看入口。引导中的内容为示意,不创建业务数据。
## 动效语言 ## 动效语言
@@ -94,6 +96,6 @@ beUI 的组件本身是 React,用不到这里,但它的动效语言与框架
| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝(详见[灵动岛](island.md)) | | 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝(详见[灵动岛](island.md)) |
| 提醒 | 本机课程等提醒开关与行为 | | 提醒 | 本机课程等提醒开关与行为 |
| 账号 | 当前班级信息、退出登录 | | 账号 | 当前班级信息、退出登录 |
| 关于 | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢 | | 关于 | 版本 / Electron / Chromium / Node、诊断信息、云端下发更新的进度、鸣谢 |
`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**,重启后仍保留。 `/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**,重启后仍保留。
+50
View File
@@ -0,0 +1,50 @@
---
title: AI 助手
description: 多轮对话、文件处理与操作计划,核对后通过现有业务接口执行。
---
# AI 助手
在 Web 管理端描述任务、补充条件或添加文件,助手会查询所需信息并生成操作计划。查询直接显示结果;任何发布、修改、导入和设备操作,都要核对计划并确认后执行。
## 使用
1. 可先选择目标班级,再输入任务;文件也可以直接拖入对话区。
2. 信息不足时补充说明。核对目标、文件、修改前内容和本次变更;表格导入可调整字段对应。
3. 确认执行后逐步显示结果。跨班发布按班显示进度,成功班级不会重复执行。失败时只重试尚未成功的步骤;结果不明时先在对应业务页面核对。
文件推送复用课件上传、哈希校验和设备回执,普通课件上限 512 MB。结构化导入支持现有 CSV、Excel、JSON、YAML 格式,上限 8 MB,先解析预览,确认后才写入业务数据。
## 权限
助手权限跟随操作者。教学业务、课表时间表、名单成绩、账号岗位和设备操作均使用原业务接口的授权规则;管理员专用功能仍限管理员。确认期间撤权、调班或任课关系变化后会重新校验。
数据库备份、恢复、清空、切换、SQL,以及服务器配置、启停、升级和密钥维护不向助手开放。删除、权限调整、升学和远控保留专门确认;上课时的紧急通知仍需二次确认。
管理员可让助手抓取、登记或删除客户端安装包缓存,核对版本、文件与替换信息并专门确认后执行。缓存管理不会自动推送、运行安装器或升级服务器。助手也可按设备权限处理远控、更新推送和移除设备登记。
密码通过操作卡片中的专用表单输入,不提供给模型。用户指令与任务所需的已授权业务信息由学校配置的模型服务解析;普通课件只提供文件元数据。
任务提交后在服务端后台运行,切换页面或关闭浏览器不取消规划及已确认的执行。重新进入助手可恢复最近任务、处理过程和结果;未确认的变更始终等待确认。停止按钮才会主动停止任务;已经发出的当前业务请求可能完成,后续步骤停止。服务重启后保留任务及步骤状态,核对后继续,未知执行结果不会自动重做。
附件须先上传完整并通过 SHA256 校验,之后才进入后台。关闭页面会中断尚未完成的本地上传,此时重新选择原文件;暂存不发布课件。临时附件在完成后清理,过期一天的暂存会在创建新任务时回收。后台输入、结果和进度加密保存;恢复查询时重新检查当前权限。计划与执行结果记入服务端审计。
处理过程实时显示权限检查、查询、自动校正、预览和执行阶段。空白或截断回复自动重试,兼容 JSON 代码块包装;业务参数仍须通过原接口校验。若模型持续不可用,任务保留为未完成并提供重试,不伪报成功或自动执行未确认操作。
## 模型配置与验收
管理员在大模型设置中配置服务地址、模型和 API Key。Key 加密保存且不回传;改变服务器 JWT 密钥后需重新配置 Key。
服务地址既可填写基础地址(如 `https://api.deepseek.com`、`https://api.openai.com/v1`),也可填写完整 `/chat/completions` 端点,系统不会重复拼接路径。DeepSeek 例如填写 `https://api.deepseek.com/chat/completions`,模型名须使用该服务实际支持的模型。
填好地址和密钥后自动获取可用模型,也可点击“获取模型”刷新或手动填写。推理强度支持自动及模型提供的档位;服务未提供能力信息时使用通用档位,自动不附加推理参数。模型列表和强度遵循[服务商接口](https://api-docs.deepseek.com/api/list-models/),不会把密钥返回浏览器。
`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、明细与错误。快照失败不升级,失败事务回滚后可修正重试。
撤销归档只清标记并将毕业生恢复在读,转出/停用不变;不回滚年级、不删除新班、不恢复已清空周次,整学年恢复需管理员手工使用快照。
+4
View File
@@ -40,3 +40,7 @@
使用反向代理时,需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时,其他接口维持原有大小限制。 使用反向代理时,需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时,其他接口维持原有大小限制。
开发验收:`pnpm verify:courseware` 自动使用隔离数据库和临时文件目录,不读取或向真实班级发送课件。 开发验收:`pnpm verify:courseware` 自动使用隔离数据库和临时文件目录,不读取或向真实班级发送课件。
## 文件夹浏览
课件默认按文件夹逐层浏览,只显示当前层文件和直属子目录。使用面包屑或返回上级切换目录;多位教师的目录按教师身份区分。上传与新建目录默认使用当前位置,未分类文件位于根目录。日期归档视图仍可用于按日期查找文件。
+3 -1
View File
@@ -6,11 +6,13 @@ description: 录入、按学号查询、排名与关闭个人查询后的集体
# 成绩 # 成绩
Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。 Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。 科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。新增科目及任课关系由管理员配置。
成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查: 成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查:
管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。 管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。
表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。 表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。
整班批量录入在同一事务中校验学生、授权并写入成绩;任意一行无效或写入失败时整批回滚,不留下部分成绩。等级批量修改按每个班级与科目组合独立检查授权。
## 查看、排名与隐私 ## 查看、排名与隐私
班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。 班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。
+33 -2
View File
@@ -16,13 +16,13 @@ description: 表格预览、名单与成绩校验,以及完整离线档案导
- 学生成绩按学号匹配,姓名兜底要求同班唯一;转出学生不参与匹配,重复记录和写入模式由服务校验。 - 学生成绩按学号匹配,姓名兜底要求同班唯一;转出学生不参与匹配,重复记录和写入模式由服务校验。
- 学生模板使用学号、姓名、班级、性别、家长电话,无密码;学号 1–32 位字母/数字/._-,在 Student 表查重。 - 学生模板使用学号、姓名、班级、性别、家长电话,无密码;学号 1–32 位字母/数字/._-,在 Student 表查重。
- 教师模板使用工号、姓名、手机号、初始密码、角色;学生/教师名单导入仍要求管理员和导入权限。 - 教师模板使用工号、姓名、手机号、角色;每个新建教师分别生成随机初始密码,导入结果提供一次性查看和 CSV 下载,关闭前请保存分发。重复导入已有教师不修改密码,旧表格中的密码列不再用于设置密码。任课关系导入中新建的教师采用相同规则;学生/教师名单导入仍要求管理员和导入权限。
- 成绩表格导入当前先要求管理员或本班班主任,再校验每行科目任课关系;科任老师的单条/批量成绩写入权限不代表能走表格导入。 - 成绩表格导入当前先要求管理员或本班班主任,再校验每行科目任课关系;科任老师的单条/批量成绩写入权限不代表能走表格导入。
- 任课关系导入用于既有班级、科目和教师的对应关系,不把档案中的 TeacherName 当账号授权。 - 任课关系导入用于既有班级、科目和教师的对应关系,不把档案中的 TeacherName 当账号授权。
## 完整 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) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
+16 -3
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,不增加服务端同步。
编辑预览不创建额外桌面窗口;打开编辑页不自动切布局,应用后启用自定义方案。 编辑预览不创建额外桌面窗口;打开编辑页不自动切布局,应用后启用自定义方案。
保存按序进行,失败可重试,主题与关怀模式沿用客户端设置。 保存按序进行,失败可重试,主题与关怀模式沿用客户端设置。
@@ -45,7 +50,7 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
## 外观、位置与输入 ## 外观、位置与输入
经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距;自定义内容根据实际测量适配工作区。 经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距;自定义内容根据实际测量适配工作区。
自定义方案可配置缩放、圆角、颜色和行间距,默认值与范围在 shared/island-layout.ts。 自定义方案可配置缩放、圆角、颜色和行间距,默认值与范围在 shared/island-layout.ts。外观页的圆角滑块同步修改当前自定义方案的常态圆角,与编辑器设置一致。
左右边距只在左/右停靠时生效,居中锚点仍在屏幕中线。 左右边距只在左/右停靠时生效,居中锚点仍在屏幕中线。
触摸屏自动进入触摸模式,保留触摸命中和失焦宽限;鼠标模式按光标控制输入穿透。 触摸屏自动进入触摸模式,保留触摸命中和失焦宽限;鼠标模式按光标控制输入穿透。
自定义常驻内容支持鼠标避让淡化及反转,交互入口、展开/编辑和触摸操作按实现暂停避让。 自定义常驻内容支持鼠标避让淡化及反转,交互入口、展开/编辑和触摸操作按实现暂停避让。
@@ -56,6 +61,14 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
## 课程与课件 ## 课程与课件
准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关,课程依据服务端解析后的课表。 准备、上课、下课、下课前倒数和课中进度等提醒在本机配置独立开关,课程依据服务端解析后的课表。
自定义常驻岛的「课程表」组件可选「当前时间点 / 下一节课 / 今日时间点」:
「今日时间点」显示当天全部时间点,只有当前项展开显示起止时间,其余折叠只显示课程名;
课间休息与「默认隐藏」的上课时间点折叠时完全隐藏,轮到它们时才展开;分割线显示一条竖线,行动不显示。
临近下课时,当前课程名右侧显示蓝色圆形秒数徽标,例如剩余一秒显示 `-1`,不显示“即将下课”遮罩,也不替换自定义岛的常态组件。
倒计时阈值沿用本机提醒设置(默认 60 秒),关闭即将下课倒数后不显示徽标。没有时间点数据时退回按课表条目显示课程。
经典 fixed 岛的临近下课提醒也使用课程名右侧的秒数徽标,其余上下课提醒保留。
课件接收时显示文件名、类型、教师、字节和进度,覆盖当前固定/自定义内容;完成后校验 SHA256 并回执。 课件接收时显示文件名、类型、教师、字节和进度,覆盖当前固定/自定义内容;完成后校验 SHA256 并回执。
客户端不会自动执行收到的文件,见[课件](courseware.md)。 客户端不会自动执行收到的文件,见[课件](courseware.md)。
+18 -2
View File
@@ -8,14 +8,24 @@ description: 日课表、共享作息、轮换、临时换课和教学周。
Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表,客户端提供“今天”时间轴和“本周”视图。 Web 管理端统一从「教学事务 → 课表档案」查看周课表并编辑时间表与日课表,客户端提供“今天”时间轴和“本周”视图。
上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。 上课状态、灵动岛课程提醒和紧急通知确认共用服务端的课表判定。
编辑工作区参照 [CsesWebEditor](https://github.com/SmartTeachCN/CsesWebEditor) 的资源列表、设置卡片、课时列表与快速选科布局实现。左侧集中切换课程表、时间表、科目、群组与预定、整周预览和文件预览。旧管理页地址 `/schedules` 自动进入同一工作区。 编辑工作区参照 [ClassIsland 档案编辑器](https://github.com/ClassIsland/ClassIsland/blob/master/ClassIsland/Views/ProfileSettingsWindow.axaml) 的课表交互实现,作为管理端内的普通页面展示,沿用全站的导航、间距、控件及浅色/深色主题。顶部切换课表、时间表、科目和调课;课表页默认进入单表编辑:左侧按课表群分组的课表列表,中间逐节选择科目,右侧切换「科目 / 课表信息」。底部仍可切换列表、周和月视图。旧管理页地址 `/schedules` 自动进入同一页面,侧栏和顶部导航始终可用。
点击课时后可用右侧科目按钮快速填充;拖动课时交换课程,拖动时间点调整时间表顺序,完成后保存。时间表支持任意分钟输入;设置的课程/课间分钟数会用于新建时间点的默认起止时间。完整档案可在页头导入或导出 JSON,保留轮换、时间点类型、空课、停用、群组和预定。 点击每天列头的「新课表」选择时间表并创建日课表。周视图点击网格中的课时后可用右侧科目按钮快速填充,支持选择是否自动移动到下一节;方向键可移动焦点,Delete 可清空选中课程。课表名称、时间表、启用星期、轮换规则、生效周次与群组在右侧「课表信息」中维护。列表视图提供批量排课、复制粘贴、拖动交换课程等操作。
时间表页采用 ClassIsland 式编辑器:左侧时间表列表(新建、复制、搜索),顶部按类型添加上课、课间休息、分割线、行动,中间可在列表视图与时间轴视图之间切换,右侧编辑选中时间点,左下设置默认上课/课间时长,右下缩放。时间轴视图可按分钟拖动时间点的开始/结束把柄,并按 1 分钟取整;列表视图可拖动排序。保存仍走页面顶部「保存」或 Ctrl+S;切周与实时刷新保留草稿,切换班级和离开页面时提醒未保存的修改。
上课时间点可以设置一个默认课程。日课表里**没有单独条目**的课时会回退到该默认课程;已有条目(包括显式空课)不会被覆盖。「覆盖现有课程」会把这门课写入所有引用该时间表的日课表。默认隐藏的上课时间点只在轮到时才在主界面显示;课间休息类型代表下课时间,折叠时完全隐藏,轮到它时才展开。
完整档案可在页头「导入/导出」中导入或导出 JSON,保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航,点击日期后由服务端解析教学周并进入周视图。
「导入课表(JSON / YAML)」还支持简化的 YAML 课表,包含星期、单双周、科目和起止时间;字段与示例见[表格与课表导入](imports.md)。
## 日课表与时间表 ## 日课表与时间表
时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。 时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。
可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。 可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
新增科目会建立任课关系,仅管理员可执行;课表维护者可以使用已配置的科目排课,需要新增或更换任课老师时联系管理员。
时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。 时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。
日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。 日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。
@@ -41,3 +51,9 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编
离线导入完整 ClassIsland 档案可创建班级自有作息,不依赖在线联动插件。 离线导入完整 ClassIsland 档案可创建班级自有作息,不依赖在线联动插件。
完整导入保留 1–9 周轮换、空课、停用、群组和预定;旧预览界面的单双周展示不代表新模型只能表达双周。 完整导入保留 1–9 周轮换、空课、停用、群组和预定;旧预览界面的单双周展示不代表新模型只能表达双周。
见[表格与课表导入](imports.md)。修改后广播 schedule:updated,客户端刷新。 见[表格与课表导入](imports.md)。修改后广播 schedule:updated,客户端刷新。
## 每日作息差异
导入的每日作息不一致时,时间表按日期生成独立子表,同日单双周也可分别维护。子表独立保存完整作息,父级用于归组。周视图按课时对齐;点击日期或课程后,时间列显示对应日期的作息,点击时间列标题清除选择后显示带星期标记的差异时间。切换子表保留可对应的课程,节数不足时阻止切换并保留原草稿。
导入或保存时间表时自动补齐两节课之间的空白,包括午休。已有命名休息、活动及显式空课保留,不在最后一节之后追加休息。旧混合时间表请使用原文件预览后重新导入,不自动猜测空课归属。
+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}`))));
}); });
+86 -14
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 | 本班名单及维护,受名单功能权限和班级关系约束 |
@@ -28,22 +28,23 @@ 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,提交复用完整档案事务 |
| /imports/time-layout[/:id]、/time-layout/preview | 时间配置兼容入口,导入需 import:schedule + timetable:manage,删除需 timetable:manage |
| GET /class-plans/profile?classId= | 完整档案导出,按班级范围读取,保留时间点与课表关联 | | GET /class-plans/profile?classId= | 完整档案导出,按班级范围读取,保留时间点与课表关联 |
| GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载;员工需 courseware:read,班级端按可见范围 | | GET /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载;员工需 courseware:read,班级端按可见范围 |
| POST /courseware/upload、/:id/push;PATCH /courseware/:id/visibility;DELETE /courseware/:id | 写入 courseware:write + 员工身份;本人文件、任课班级与可见范围限制 | | POST /courseware/upload、/:id/push;PATCH /courseware/:id/visibility;DELETE /courseware/:id | 写入 courseware:write + 员工身份;本人文件、任课班级与可见范围限制 |
@@ -53,25 +54,96 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
## 设备、系统与运维 ## 设备、系统与运维
| 路径/动作 | 行为及边界 | | 路径/动作 | 行为及边界 |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执,校验 deviceKey 和归属 | | POST /clients/heartbeat、/clients/commands/:id/ack | 登录设备心跳/回执,校验 deviceKey 和归属 |
| POST /clients/update-progress | 设备上传下载、校验、等待、安装和失败状态,校验设备班级归属 | | POST /clients/update-progress | 设备上传下载、校验、等待、安装和失败状态,校验设备班级归属 |
| GET /clients/devices;DELETE /clients/devices/:id | 设备读取/维护,分别检查功能键和范围 | | GET /clients/devices;DELETE /clients/devices/:id | 设备读取/维护,分别检查功能键和范围 |
| POST /clients/commands | remote:control + 对应范围,白名单动作 | | POST /clients/commands | remote:control + 对应范围,白名单动作 |
| POST /clients/updates | client:update,安装策略 immediate/after-school/idle | | POST /clients/updates | client:update-push,安装策略 immediate/after-school/idle |
| GET /update/check | 员工需 update:check;强制刷新另检查 update:force | | GET /update/check | 员工需 update:check;强制刷新另检查 update:force |
| GET /update/client/releases | 缓存版本读取,按路由允许的读取权限 | | GET /update/client/releases | 缓存版本读取,按路由允许的读取权限 |
| POST /update/client/fetch、/update/client/releases;DELETE /update/client/releases/:version | 安装包写入口统一 client:update | | POST /update/client/fetch、/update/client/releases;DELETE /update/client/releases/:version | 安装包写入口仅管理员 client:update |
| GET /update/client/download/:version | 已登录下载,不挂员工权限键,供班级端更新 | | GET /update/client/download/:version | 本班 CLASS_DEVICE 或 client:read + 有效班级范围 |
| /term;POST /term/auto;GET /term/holidays | 学期读取/编辑/假日建议,term:read/term:write | | /term;POST /term/auto;GET /term/holidays | 学期读取/编辑/假日建议,term:read/term:write |
| GET/PUT /term/promotion;POST /term/promotion/run | 升级计划、预览和执行,system:manage,执行还做业务校验 | | GET/PUT /term/promotion;POST /term/promotion/run | 升级计划与执行,promotion:manage + 全校范围,执行要求确认与计划哈希 |
| /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档与撤回转出,archive:manage;不提供创建归档代替年度升级的入口 | | /archives、/archives/transferred、/archives/transferred/:id/restore | 历史归档需 archive:manage 全校范围;撤回转出需 roster:manage;不提供手动创建归档 |
| /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage;目标空库、快照及换库子进程保护 | | /database/status、/test-connection、/backups、/export、/import、/sqlite-file、/backup-schedule、/switch | database:manage;目标空库、快照及换库子进程保护 |
| /system/settings、/autostart、/diagnostics | system:manage,非安装形态自启动返回不可用原因 | | /system/settings、/autostart、/diagnostics | system:manage,非安装形态自启动返回不可用原因 |
| /ai/settings、/interpret、/audit | ai:manage/ai:use;只解析待确认动作,密钥只进不出 | | /ai/settings、/interpret、/audit、/capabilities、/plans/:id | ai:manage/ai:use;查询遵循业务权限,写入计划确认后调用原接口,密钥只进不出 |
| /dashboard/summary、/dashboard/term | 按范围读取看板与周次 | | /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;普通课件内容不发送给模型。
`POST /ai/models` 仅管理员可用,接收可选 `baseUrl/apiKey`(未传时使用已保存配置),通过兼容 `/models` 获取模型及支持的推理档位,密钥不回传。设置增加 `reasoningEffort`:`auto/none/low/medium/high/max`,`auto` 不附加推理参数。
后台任务接口均要求 `ai:use`,并校验归属及实际业务权限:
- `POST /ai/tasks` 创建任务;`PUT /ai/tasks/:id/files/:attachmentId` 以二进制暂存已声明附件,校验大小与 SHA256,不发布课件。
- `POST /ai/tasks/:id/start` 提交后台规划,完整附件上传后才允许开始。
- `GET /ai/tasks` 列出本人最近任务;`GET /ai/tasks/:id` 读取状态并重新授权结果数据。
- `GET /ai/tasks/:id/events` 以 SSE 返回 `status/message/result/error`,关闭连接仅停止订阅,不取消任务。
- `POST /ai/tasks/:id/execute` 接收与计划确认相同的确认字段,后台逐步调用白名单业务接口,使用持久步骤去重。失败停止后续依赖项,重试不重做成功步骤。
- `POST /ai/tasks/:id/stop` 主动停止后台任务;已发出的业务请求可完成,后续步骤停止。
后台任务保存在 `AiTask`,输入、结果与进度加密,纳入快照并兼容旧快照缺表。助手页面统一使用后台任务接口。服务重启保留任务,未知业务执行结果须核对后继续。
- `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`。
+24 -4
View File
@@ -11,10 +11,10 @@ description: 现行模型职责、迁移与快照边界。
## 模型职责 ## 模型职责
| 模型 | 职责 | | 模型 | 职责 |
| ---------------------- | -------------------------------------------------- | | ---------------------- | --------------------------------------------------- |
| `User` | 教师与管理员账号;学生不在此表,班级凭据在 Class | | `User` | 教师与管理员账号;学生不在此表,班级凭据在 Class |
| `Student` | 学生名单、学号、在读/转出/毕业状态,无密码和角色 | | `Student` | 学生名单、学号、在读/转出/毕业状态,无密码和角色 |
| `StudentClassTransfer` | 调班与转出历史,保留班级/姓名快照 | | `StudentClassTransfer` | 生命周期历史,kind/batchId/学年/班级年级及学校快照 |
| `ArchivedYear` | 毕业届别与统计快照 | | `ArchivedYear` | 毕业届别与统计快照 |
| `TermWeek` | 逐周日期区间,classId 空串为全校默认 | | `TermWeek` | 逐周日期区间,classId 空串为全校默认 |
| `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 | | `Class` | 班级、班级码/密码、班主任、周数与成绩查询开关 |
@@ -26,9 +26,10 @@ description: 现行模型职责、迁移与快照边界。
| `NotificationRead` | 按 studentId 记录已读 | | `NotificationRead` | 按 studentId 记录已读 |
| `TimeLayout` | 共享或班级自有时间表;旧 items JSON 保留迁移审计 | | `TimeLayout` | 共享或班级自有时间表;旧 items JSON 保留迁移审计 |
| `Grade` | studentId、课程、考试、分数和等级 | | `Grade` | studentId、课程、考试、分数和等级 |
| `PermissionGroup` | 默认/自定义/岗位组及 scope/scopeValue | | `PermissionAudit` | 权限与人工升级审计,操作人和前后 JSON,不建账号外键 |
| `PermissionGroup` | 岗位模板与建议 scope/scopeValue |
| `PermissionGroupItem` | 组内权限键 | | `PermissionGroupItem` | 组内权限键 |
| `UserPermissionGroup` | 账号与组的多对多分配 | | `UserPermissionGroup` | 账号与模板的分配及实际 scope/scopeValue |
| `AppSetting` | 周次、升级、AI 和系统设置 | | `AppSetting` | 周次、升级、AI 和系统设置 |
| `ClientDevice` | deviceKey、心跳、更新目标与状态 | | `ClientDevice` | deviceKey、心跳、更新目标与状态 |
| `ClientCommand` | 白名单远控、有效期与执行回执 | | `ClientCommand` | 白名单远控、有效期与执行回执 |
@@ -73,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 验证接管班级、管理员提权、跨键借范围、科目改挂、跨班时间表/周次/导入、成绩隐私、通道订阅、设备冒用和旧快照等攻击场景。其他专项回归保留生命周期、课表、课件、设备与升级覆盖。验证不触及真实班级、不访问外网、不执行系统指令。
+8 -5
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}`,后者逐通道校验,有任一无权则拒绝整次请求。握手回查账号与角色,权限变更断开旧订阅。
+4 -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 或解包副本当交付物保留。
@@ -69,6 +71,7 @@ gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256S
推送 v* tag 触发 release-linux-server.yml,按 tag 检出,在 Ubuntu 构建并上传 Linux 包、独立 .sha256,合并跨组件清单。 推送 v* tag 触发 release-linux-server.yml,按 tag 检出,在 Ubuntu 构建并上传 Linux 包、独立 .sha256,合并跨组件清单。
等待 Actions 成功,再下载 Linux 文件和最终 SHA256SUMS 同步回本地;检查清单的 Windows 行仍与本次文件一致。 等待 Actions 成功,再下载 Linux 文件和最终 SHA256SUMS 同步回本地;检查清单的 Windows 行仍与本次文件一致。
如需重跑,可手动运行该 workflow,指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。 如需重跑,可手动运行该 workflow,指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
用户明确要求同版本更新远端服务端资产时,可额外指定 `source_ref` 为经过验证的完整提交 SHA;版本仍须与目标 tag 一致。保留原标签,在发布说明注明服务端重建提交及客户端沿用原批次,更新两个平台的服务端包与摘要。
官网和文档站由 pages.yml 拼装同一个站点:官网根、文档 /docs/。文档版本徽标读根 package.json, 官网和文档站由 pages.yml 拼装同一个站点:官网根、文档 /docs/。文档版本徽标读根 package.json,
官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线,分别确认结果。 官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线,分别确认结果。
+12 -2
View File
@@ -11,18 +11,21 @@ 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:lifecycle | 临时 SQLite 验证权限治理、事务故障回滚、状态机、历史、多轨道、计划哈希和快照 |
| pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 | | pnpm verify:v14 | 临时库验证关系课表、周次、范围、隐私与升级等 |
| pnpm verify:courseware | 临时库和文件目录的课件专项,不向真实班级推送 | | pnpm verify:courseware | 临时库和文件目录的课件专项,不向真实班级推送 |
| pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 | | pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 |
| pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 | | pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 |
| pnpm verify:review-client | 无窗口逻辑回归 | | pnpm verify:review-client | 无窗口逻辑回归 |
| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务,使用 VERIFY_BASE_URL 等脚本参数 | | pnpm verify:review-api / pnpm verify:clients-api | 包装器自动创建临时 SQLite、账号和随机端口服务,无需手动准备服务 |
| pnpm verify:authz | 隔离授权攻击矩阵,覆盖按键范围、身份、任课与实时订阅 |
| pnpm verify:audit | 隔离事务故障、任课自授权、并发已读、模型操作计数和 Service Worker 回归 |
| pnpm verify:desktop | 先 pnpm build:desktop;隐藏快速检查,独立 userData | | pnpm verify:desktop | 先 pnpm build:desktop;隐藏快速检查,独立 userData |
| pnpm verify:desktop:online | 显式联网,需要测试管理员并创建临时教师/班级 | | pnpm verify:desktop:online | 显式联网,需要测试管理员并创建临时教师/班级 |
| pnpm verify:desktop:visual | 显式使用桌面,完整岛几何/动画/透明度/截图检查 | | pnpm verify:desktop:visual | 显式使用桌面,完整岛几何/动画/透明度/截图检查 |
@@ -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 以获得新的安装助手;服务端推送安装包不能替换旧客户端中已经损坏的交接逻辑。
+8 -4
View File
@@ -13,15 +13,15 @@ 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 -2
View File
@@ -308,7 +308,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
## 五、环境变量清单 ## 五、环境变量清单
| 变量 | 默认 | 说明 | | 变量 | 默认 | 说明 |
| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- | | --------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `NODE_ENV` | `development` | `production` 会启用生产校验、HSTS、更严的限流 | | `NODE_ENV` | `development` | `production` 会启用生产校验、HSTS、更严的限流 |
| `HOST` / `PORT` | `0.0.0.0` / `4000` | 监听地址与端口 | | `HOST` / `PORT` | `0.0.0.0` / `4000` | 监听地址与端口 |
| `DATABASE_PROVIDER` | `sqlite` | `sqlite` 或 `mysql` | | `DATABASE_PROVIDER` | `sqlite` | `sqlite` 或 `mysql` |
@@ -318,7 +318,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
| `JWT_EXPIRES_IN` | `7d` | 令牌有效期 | | `JWT_EXPIRES_IN` | `7d` | 令牌有效期 |
| `CORS_ORIGIN` | `*` | 允许来源,多个用逗号分隔;生产建议写具体域名 | | `CORS_ORIGIN` | `*` | 允许来源,多个用逗号分隔;生产建议写具体域名 |
| `TRUST_PROXY` | `false` | 反向代理层数(Nginx 填 `1`),影响限流与日志中的真实 IP | | `TRUST_PROXY` | `false` | 反向代理层数(Nginx 填 `1`),影响限流与日志中的真实 IP |
| `RATE_LIMIT_ENABLED` | `true` | 通用限流(生产 600 次/5 分钟)+ 登录限流(20 次/10 分钟) | | `RATE_LIMIT_ENABLED` | `true` | 通用限流(生产 600 次/5 分钟);同一来源 IP 连续五次登录失败后封禁 5 分钟,成功登录清零,两种登录入口共用计数 |
| `STARTUP_DB_CHECK` | `true` | 启动校验数据库;生产不可用时直接退出 | | `STARTUP_DB_CHECK` | `true` | 启动校验数据库;生产不可用时直接退出 |
| `PID_FILE` | — | PID 文件路径(安装包启停脚本依赖),相对 `server` 根 | | `PID_FILE` | — | PID 文件路径(安装包启停脚本依赖),相对 `server` 根 |
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录(`../web-admin/dist` 或 `./web`) | | `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录(`../web-admin/dist` 或 `./web`) |
+6 -13
View File
@@ -18,17 +18,11 @@ description: 检查更新与各形态的升级步骤、Linux 的升级回滚链
## 检查更新 ## 检查更新
| 端 | 入口 | 检查路径 | | 端 | 入口 | 检查路径 |
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------ | | ------------------- | ---------------------------------------------- | ------------------------------------------------ |
| 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」 | 浏览器 → 服务端 `GET /api/update/check` → GitHub | | 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」 | 浏览器 → 服务端 `GET /api/update/check` → GitHub |
| 桌面客户端 | 启动后自动一次(延迟 5 秒)+「设置 → 关于」里的「检查更新」按钮 | 主进程 → GitHub(不经后端) | | 桌面客户端 | 管理端「客户端管理」登记安装包并向班级下发更新 | 客户端只从当前服务端领取更新策略与安装包 |
两端的路径不同是**被约束逼出来的**: Web 管理端经服务端查询 GitHub Release。客户端不再主动检查 GitHub,也不提供手动检查入口;更新由管理端统一下发,仍校验 SHA256 并遵循本机自动更新开关和服务端策略。
- **Web 端不能直连 GitHub**。服务端下发的 CSP 里 `connect-src` 只放行 `'self'` 与 WebSocket,
浏览器发往 `api.github.com` 的请求会直接被拦掉。走服务端转发还有个好处:所有管理员共享同一份缓存
(GitHub 匿名限流是 60 次/小时/IP)。
- **客户端在主进程做**。渲染进程的 CSP 与导航防线是安全模型里最要紧的一层,
不让它去连外部域名、解析外部 JSON。
### "查不到"是设计内的结果 ### "查不到"是设计内的结果
@@ -39,12 +33,11 @@ description: 检查更新与各形态的升级步骤、Linux 的升级回滚链
失败结果同样进缓存 —— 否则断网时每点一次按钮都要白等一个超时。 失败结果同样进缓存 —— 否则断网时每点一次按钮都要白等一个超时。
| 细节 | 说明 | | 细节 | 说明 |
| ---------- | ----------------------------------------------------------------------------------------------------- | | ---- | ----------------------------------------------------------------------------------------------------- |
| 缓存 | 两端各缓存 30 分钟;`?force=1` 绕过服务端缓存,但**仅管理员生效**(否则任意登录用户都能刷爆匿名限流) | | 缓存 | 服务端缓存 30 分钟;`?force=1` 绕过服务端缓存,但**仅管理员生效**(否则任意登录用户都能刷爆匿名限流) |
| 权限 | 任何已登录用户都能查(信息来自公开仓库);`force` 除外 | | 权限 | 任何已登录用户都能查(信息来自公开仓库);`force` 除外 |
| 只提示一次 | 客户端启动检查发现新版才推提示;点「忽略此版本」记进配置,同一版本不再提示 |
更新**只提示,不自动下载、不自动安装**。安装包仍由人从 [Releases](https://github.com/LoveChengke/classhelper/releases) 服务端的更新检查只提示,不自动安装。管理员可从 [Releases](https://github.com/LoveChengke/classhelper/releases)
页面取,可用 `SHA256SUMS-<版本>.txt` 核对。 页面取,可用 `SHA256SUMS-<版本>.txt` 核对。
## 升级步骤 ## 升级步骤
+3 -2
View File
@@ -9,12 +9,13 @@ 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/` |
| AI 助手 | [解析与确认发布](app/assistant.md) | `server/src/modules/ai/`、`web-admin/src/views/AssistantView.vue` |
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` | | 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` | | 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` | | 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 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: 71 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 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: 133 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 96 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 108 KiB

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 139 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 94 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

+17 -6
View File
@@ -1,6 +1,6 @@
{ {
"name": "class-helper", "name": "class-helper",
"version": "1.4.1", "version": "1.4.5",
"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,19 @@
"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:panel-security": "node scripts/verify-panel-security.mjs",
"verify:clients-api": "node scripts/verify-clients-api.mjs", "verify:island-editor": "node scripts/verify-island-editor.mjs",
"verify:review-api": "node scripts/verify-e2e-isolated.mjs --review-api",
"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 +60,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.1", "version": "1.4.5",
"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 },
);
}
+2 -2
View File
@@ -84,8 +84,8 @@ function launchSmoke(extraEnv) {
child.kill(); child.kill();
resolve(124); resolve(124);
}, },
// 快速套件已包含本地 HTTP、校验下载和布局编辑;保留冷启动余量,单项断言不放宽。 // 快速套件包含两种布局的完整上下课时序、本地下载和编辑;总时限保留冷启动余量。
mode === 'visual' ? 360_000 : 90_000, mode === 'visual' ? 360_000 : 120_000,
); );
child.once('exit', (code) => { child.once('exit', (code) => {
clearTimeout(deadline); clearTimeout(deadline);
@@ -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;
@@ -34,26 +37,76 @@ const current = computed(() => today.value.find((s) => s.id === status.value.cur
const next = computed(() => today.value.find((s) => s.id === status.value.next?.scheduleId)); const next = computed(() => today.value.find((s) => s.id === status.value.next?.scheduleId));
function timeAt(time: string) { function timeAt(time: string) {
const d = new Date(props.now); const d = new Date(props.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 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(
// 临近下课仍使用真实时间点,不因提醒切换而替换课程组件。
() => () =>
!props.editing && !props.editing &&
((['notification', 'homework', 'call'].includes(props.node.kind) && ((['notification', 'homework', 'call'].includes(props.node.kind) &&
@@ -62,11 +115,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 +148,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 +176,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 +235,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,27 +247,41 @@ 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>
<small v-if="node.settings.showProgress && current?.id === s.id" class="lesson-remaining">
距下课 {{ Math.floor(remaining / 60) }}:{{ String(remaining % 60).padStart(2, '0') }}
</small>
</div>
<span v-if="!lessons.length">暂无课程</span>
<div <div
v-if="current && node.settings.showProgress && node.settings.display !== 'next'" v-else
class="lesson-line"
:class="{ current: p.id === currentPoint?.id, break: p.timeType === 'BREAK' }"
>
<strong>{{ p.courseName || p.name || '—' }}</strong>
<span
v-if="p.id === currentLesson?.id && state.lessonReminder?.kind === 'ending' && remaining > 0"
class="lesson-ending-badge"
:aria-label="`距下课${remaining}秒`"
>
-{{ remaining }}
</span>
<small v-if="p.id === currentPoint?.id && node.settings.showPeriod" class="lesson-time">
{{ p.startTime }}–{{ p.endTime }}
</small>
<span
v-if="p.id === currentPoint?.id && p.timeType === 'LESSON' && node.settings.showProgress"
class="lesson-progress" class="lesson-progress"
role="progressbar" role="progressbar"
:aria-valuenow="Math.round(elapsed * 100)" :aria-valuenow="Math.round(elapsed * 100)"
:aria-valuemin="0" aria-valuemin="0"
:aria-valuemax="100" aria-valuemax="100"
:aria-label="`${current.course?.name}课程进度,距下课${remaining}秒`" :aria-label="`${p.courseName || '课程'}课程进度,距下课${remaining}秒`"
> >
<i :style="{ transform: `scaleX(${elapsed})` }" /> <i :style="{ transform: `scaleX(${elapsed})` }" />
</span>
</div> </div>
</template> </template>
<span v-if="!schedulePoints.length">暂无课程</span>
</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" />
<span v-else-if="editing">{{ ISLAND_COMPONENT_LABELS[node.kind] }}内容组件</span> <span v-else-if="editing">{{ ISLAND_COMPONENT_LABELS[node.kind] }}内容组件</span>
@@ -238,11 +311,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 +325,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 +347,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;
@@ -269,14 +360,11 @@ const style = computed<CSSProperties>(() => {
transform-origin: left; transform-origin: left;
transition: transform 1s linear; transition: transform 1s linear;
} }
.schedule > .lesson-line + .lesson-line { .schedule {
margin-top: 8px; display: flex;
} flex-direction: column;
.lesson-remaining { align-items: center;
font-size: var(--secondary, 14px); gap: 8px;
font-variant-numeric: tabular-nums;
opacity: 0.8;
white-space: nowrap;
} }
.separator > span { .separator > span {
display: block; display: block;
@@ -299,6 +387,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;
@@ -361,3 +452,5 @@ strong,
} }
} }
</style> </style>
<style src="./lesson-ending.css"></style>
<style src="./lesson-ending.css"></style>
@@ -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,12 +21,16 @@ 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;
}>(); }>();
const scheme = computed(() => props.settings.schemes.find((s) => s.id === props.settings.activeSchemeId)!); const scheme = computed(() => props.settings.schemes.find((s) => s.id === props.settings.activeSchemeId)!);
const expanded = computed(() => props.state.mode === 'expanded'); const expanded = computed(() => props.state.mode === 'expanded');
const lesson = computed(() => props.state.lessonReminder ?? null); // 即将下课只在当前课程旁显示秒数,保留常驻组件与消息入口。
const lesson = computed(() =>
props.state.lessonReminder?.kind === 'ending' ? null : (props.state.lessonReminder ?? null),
);
const lastLesson = ref<IslandLessonReminder | null>(null); const lastLesson = ref<IslandLessonReminder | null>(null);
watch( watch(
lesson, lesson,
@@ -267,12 +272,29 @@ function visibility() {
void nextTick(reportHit); void nextTick(reportHit);
} }
// 不深度监听整份状态;只在目标内容/几何变化时测量,时钟每秒只改文本。 // 不深度监听整份状态;只在目标内容/几何变化时测量,时钟每秒只改文本。
watch([expanded, scheme, lesson, () => props.state.listExpanded, messages], measure, {
deep: true,
flush: 'post',
});
watch( watch(
[fit, motion, expanded, lesson, () => props.appearance.radius, () => props.appearance.speed], [
expanded,
scheme,
lesson,
() => props.state.listExpanded,
messages,
() => props.timePoints,
() => Math.floor(now.value / 60_000),
],
measure,
{ deep: true, flush: 'post' },
);
watch(
[
fit,
motion,
expanded,
lesson,
() => scheme.value.radius,
() => props.appearance.radius,
() => props.appearance.speed,
],
() => { () => {
animate(); animate();
trackHit(); trackHit();
@@ -388,6 +410,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 +492,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=""
@@ -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>
@@ -10,7 +10,7 @@ const props = defineProps<{
}>(); }>();
const root = ref<HTMLElement>(); const root = ref<HTMLElement>();
const width = ref(480); const width = ref(480);
const mask = computed(() => props.now < props.reminder.maskUntil); const mask = computed(() => props.reminder.kind !== 'ending' && props.now < props.reminder.maskUntil);
const title = computed( const title = computed(
() => () =>
({ ({
@@ -140,15 +140,14 @@ onUnmounted(() => {
aria-live="polite" aria-live="polite"
> >
<div class="ci-lesson-info"> <div class="ci-lesson-info">
<span <span v-if="reminder.kind === 'prepare' || reminder.kind === 'in-class'" class="ci-countdown">
v-if="reminder.kind === 'prepare' || reminder.kind === 'ending' || reminder.kind === 'in-class'"
class="ci-countdown"
>
{{ reminder.kind === 'prepare' ? '距上课还剩' : '距下课还剩' }} {{ reminder.kind === 'prepare' ? '距上课还剩' : '距下课还剩' }}
<strong>{{ leftSeconds }}</strong> <strong>{{ leftSeconds }}</strong>
秒 秒
</span> </span>
<span v-else class="ci-countdown">{{ reminder.kind === 'on-class' ? '开始上课' : '课间休息' }}</span> <span v-else-if="reminder.kind !== 'ending'" class="ci-countdown">
{{ reminder.kind === 'on-class' ? '开始上课' : '课间休息' }}
</span>
<span class="ci-lesson-course"> <span class="ci-lesson-course">
<span> <span>
{{ {{
@@ -158,6 +157,13 @@ onUnmounted(() => {
}} }}
</span> </span>
<strong>{{ course || '今日课程已结束' }}</strong> <strong>{{ course || '今日课程已结束' }}</strong>
<span
v-if="reminder.kind === 'ending'"
class="lesson-ending-badge"
:aria-label="`距下课${leftSeconds}秒`"
>
-{{ leftSeconds }}
</span>
<small v-if="course">{{ time }}</small> <small v-if="course">{{ time }}</small>
</span> </span>
</div> </div>
@@ -309,3 +315,4 @@ onUnmounted(() => {
transition: transform 50ms linear; transition: transform 50ms linear;
} }
</style> </style>
<style src="./lesson-ending.css"></style>
@@ -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>
@@ -0,0 +1,16 @@
/* 两种岛共用临近下课徽标;固定正圆,数字使用等宽字形。 */
.lesson-ending-badge {
display: inline-flex;
align-items: center;
justify-content: center;
flex: 0 0 auto;
width: 30px;
height: 30px;
border-radius: 50%;
color: #fff;
background: #0a84ff;
font-size: 12px;
font-weight: 600;
font-variant-numeric: tabular-nums;
line-height: 1;
}
@@ -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';
+40 -29
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,
@@ -15,6 +14,7 @@ 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 { connectionEvents } from './config-events.js';
import { prepareUpdateInstaller } from './update-installer.js';
let updateEpoch = 0; let updateEpoch = 0;
let downloadAbort = new AbortController(); let downloadAbort = new AbortController();
@@ -43,15 +43,17 @@ connectionEvents.on('changed', () => {
* 空闲安装要求不在上课且主窗口隐藏满五分钟; * 空闲安装要求不在上课且主窗口隐藏满五分钟;
* 2. **下完先校验 sha256**:服务端给的哈希对不上就删掉文件、记 error,**不做任何信任放行** * 2. **下完先校验 sha256**:服务端给的哈希对不上就删掉文件、记 error,**不做任何信任放行**
* (宁可这次更新失败,也不能把一个来源不明的 exe 装到教室里); * (宁可这次更新失败,也不能把一个来源不明的 exe 装到教室里);
* 3. **安装脚本脱离本进程**:PowerShell 等旧进程退出、安装器完成后重新拉起应用, * 3. **独立安装助手**:助手就绪后才退出旧进程,由助手执行安装并确认新版启动;
* 本进程随即走既有退出路径退出(重启应用这件事交给安装脚本,而不是自己 `relaunch`, * 助手从更新目录运行,不锁住正在被安装器替换的应用文件。
* 否则会与"安装器正在覆盖自己"撞车 —— Windows 上正在运行的程序文件是删不掉的)。
*/ */
let policy: let policy:
| (Pick<ClientHeartbeatResponse, 'updateTargetVersion' | 'updateMode' | 'updateNotBefore'> & { | (Pick<ClientHeartbeatResponse, 'updateTargetVersion' | 'updateMode' | 'updateNotBefore'> & {
serverUrl: string; serverUrl: string;
username: string; username: string;
updateSha256: string;
updateSize: number;
updateFileName: string;
}) })
| null = null; | null = null;
function policyPath(): string { function policyPath(): string {
@@ -107,6 +109,9 @@ export function syncUpdatePolicy(next: ClientHeartbeatResponse): void {
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');
@@ -458,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;
@@ -520,33 +533,29 @@ export async function maybeInstallPendingUpdate(): Promise<void> {
logger.info(`开始静默安装更新 ${version}:${installer}`); logger.info(`开始静默安装更新 ${version}:${installer}`);
try { try {
const exe = process.env.PORTABLE_EXECUTABLE_FILE || app.getPath('exe'); const exe = process.env.PORTABLE_EXECUTABLE_FILE || app.getPath('exe');
const quote = (value: string): string => "'" + value.replaceAll("'", "''") + "'";
const config = getConfig(); const config = getConfig();
const resultFile = path.join(pendingUpdateDir(), 'install-result.json'); const helper = await prepareUpdateInstaller({
// 上一次失败的结果不能冒充这一次:安装开始时先清掉,只有本轮失败才重新写入。 directory: pendingUpdateDir(),
fs.rmSync(resultFile, { force: true }); installer,
const script = version,
`$ErrorActionPreference = 'Stop'; try { Wait-Process -Id ${process.pid} -ErrorAction SilentlyContinue; ` + sha256: active.updateSha256,
`$installer = Start-Process -FilePath ${quote(installer)} -ArgumentList '/S','--updated','--force-run' -WindowStyle Hidden -Wait -PassThru; ` + size: active.updateSize,
`if ($installer.ExitCode -ne 0) { throw ('安装器退出码:' + $installer.ExitCode) } ` + serverUrl: config.serverUrl,
`} catch { @{ version=${quote(version)}; serverUrl=${quote(config.serverUrl)}; username=${quote(config.username)}; error=$_.Exception.Message } | ConvertTo-Json -Compress | Set-Content -LiteralPath ${quote(resultFile)} -Encoding UTF8; ` + username: config.username,
`if (Test-Path -LiteralPath ${quote(exe)}) { Start-Process -FilePath ${quote(exe)} -WindowStyle Hidden } }`; restartExe: exe,
const encoded = Buffer.from(script, 'utf16le').toString('base64'); portable: Boolean(process.env.PORTABLE_EXECUTABLE_FILE),
const child = spawn(
'powershell.exe',
['-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-EncodedCommand', encoded],
{
detached: true,
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 {
@@ -555,6 +564,8 @@ 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) }); 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)}`,
@@ -19,8 +19,6 @@ export const IPC_CHANNELS = {
clearConfig: 'classhelper:config:clear', clearConfig: 'classhelper:config:clear',
appInfo: 'classhelper:app:info', appInfo: 'classhelper:app:info',
openExternal: 'classhelper:shell:open-external', openExternal: 'classhelper:shell:open-external',
updateCheck: 'classhelper:update:check',
updateIgnore: 'classhelper:update:ignore',
getAutoLaunch: 'classhelper:app:get-autolaunch', getAutoLaunch: 'classhelper:app:get-autolaunch',
setAutoLaunch: 'classhelper:app:set-autolaunch', setAutoLaunch: 'classhelper:app:set-autolaunch',
openLogDir: 'classhelper:app:open-log-dir', openLogDir: 'classhelper:app:open-log-dir',
@@ -28,6 +26,3 @@ export const IPC_CHANNELS = {
clientStatus: 'classhelper:client:status', clientStatus: 'classhelper:client:status',
clientBeatNow: 'classhelper:client:beat-now', clientBeatNow: 'classhelper:client:beat-now',
} as const; } as const;
/** 主进程 → 渲染进程的单向推送:有可用更新(同理,供 preload 与主进程共用) */
export const UPDATE_AVAILABLE_CHANNEL = 'classhelper:update:available';
+10 -1
View File
@@ -38,11 +38,12 @@ interface PersistedConfig {
homeworkPhrases?: string[]; homeworkPhrases?: string[];
/** 是否已看过初次启动引导(向后兼容:旧配置没有该字段视为没看过,首启弹一次) */ /** 是否已看过初次启动引导(向后兼容:旧配置没有该字段视为没看过,首启弹一次) */
onboardingDone?: boolean; onboardingDone?: boolean;
onboardingVersion?: number;
/** 界面主题(向后兼容:旧配置没有该字段用浅色) */ /** 界面主题(向后兼容:旧配置没有该字段用浅色) */
theme?: 'light' | 'dark'; theme?: 'light' | 'dark';
/** 主侧边栏是否折叠(向后兼容:旧配置没有该字段视为展开) */ /** 主侧边栏是否折叠(向后兼容:旧配置没有该字段视为展开) */
sidebarCollapsed?: boolean; sidebarCollapsed?: boolean;
/** 用户选择「忽略此版本」的版本号(向后兼容:旧配置没有该字段视为没忽略过任何版本) */ /** 旧版主动更新检查的兼容字段;统一云端下发更新后不再参与更新决策。 */
ignoredUpdateVersion?: string; ignoredUpdateVersion?: string;
/** 本机设备标识(向后兼容:旧配置没有该字段时首次读取生成并落盘,之后永不变) */ /** 本机设备标识(向后兼容:旧配置没有该字段时首次读取生成并落盘,之后永不变) */
deviceKey?: string; deviceKey?: string;
@@ -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);
} }
@@ -10,7 +10,6 @@ import { island, registerIslandIpc } from './island.js';
import { logger } from './logger.js'; import { logger } from './logger.js';
import { runSmokeTest } from './smoke.js'; import { runSmokeTest } from './smoke.js';
import { createTray, destroyTray, isTrayReady } from './tray.js'; import { createTray, destroyTray, isTrayReady } from './tray.js';
import { scheduleStartupUpdateCheck } from './update.js';
// 主进程由 esbuild 打包为 CommonJS,因此这里可以直接使用 __dirname // 主进程由 esbuild 打包为 CommonJS,因此这里可以直接使用 __dirname
// (dist/main/index.js -> dist/preload/index.js 与 dist/renderer/index.html) // (dist/main/index.js -> dist/preload/index.js 与 dist/renderer/index.html)
@@ -259,9 +258,6 @@ if (!gotLock) {
logger.warn(`系统托盘初始化失败(不影响主功能):${error instanceof Error ? error.message : error}`); logger.warn(`系统托盘初始化失败(不影响主功能):${error instanceof Error ? error.message : error}`);
} }
// 启动后自动查一次更新(延迟几秒,不跟首屏抢带宽);冒烟模式下自动跳过,见 main/update.ts
scheduleStartupUpdateCheck(() => mainWindow);
// 服务端统一下发:定时上报本机状态并领取「待执行命令 / 统一更新」(冒烟默认不上报) // 服务端统一下发:定时上报本机状态并领取「待执行命令 / 统一更新」(冒烟默认不上报)
startClientAgent(); startClientAgent();
+2 -17
View File
@@ -6,14 +6,13 @@ import {
listLocalCourseware, listLocalCourseware,
} from './courseware.js'; } 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 { IPC_CHANNELS } from './channels.js'; import { IPC_CHANNELS } from './channels.js';
import { beatNow, getClientAgentStatus } from './client-agent.js'; import { beatNow, getClientAgentStatus } from './client-agent.js';
import { clearConfig, getConfig, getConfigPath, saveConfig } from './config.js'; import { clearConfig, getConfig, getConfigPath, saveConfig } from './config.js';
import { logger } from './logger.js'; import { logger } from './logger.js';
import { checkForUpdates, ignoreUpdateVersion } from './update.js';
import type { DesktopAppInfo, DesktopStoredConfig } from '../types/desktop.js'; import type { DesktopAppInfo, DesktopStoredConfig } from '../types/desktop.js';
// 通道名定义搬到了叶子模块 `channels.ts`(原因见那里的注释:preload 在沙箱里不能碰 node 内建模块); // 通道名定义搬到了叶子模块 `channels.ts`(原因见那里的注释:preload 在沙箱里不能碰 node 内建模块);
@@ -21,6 +20,7 @@ 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:local-list', () => listLocalCourseware()); ipcMain.handle('courseware:local-list', () => listLocalCourseware());
@@ -63,21 +63,6 @@ export function registerIpcHandlers(): void {
return true; return true;
}); });
/**
* 检查更新(走主进程直连 GitHub,见 main/update.ts 的说明)。
*
* `force` 为 true 时绕过主进程缓存 —— 对应「关于」页里用户主动点的那次检查;
* 启动自动检查一律用缓存(避免同一分钟内重复请求打满匿名限流)。
*/
ipcMain.handle(IPC_CHANNELS.updateCheck, (_event, force?: boolean): Promise<UpdateInfo> => {
return checkForUpdates(force === true);
});
/** 忽略某个版本的更新提示(记入 config.json,启动自动检查不再提示它) */
ipcMain.handle(IPC_CHANNELS.updateIgnore, (_event, version: string): void => {
if (typeof version === 'string') ignoreUpdateVersion(version);
});
/** 开机自启:读的是系统登录项,不是配置文件里的值(两者可能被外部改过) */ /** 开机自启:读的是系统登录项,不是配置文件里的值(两者可能被外部改过) */
ipcMain.handle(IPC_CHANNELS.getAutoLaunch, (): boolean => { ipcMain.handle(IPC_CHANNELS.getAutoLaunch, (): boolean => {
try { try {
@@ -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;
}
+30 -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;
@@ -167,6 +171,7 @@ class IslandController {
private lessonTimer: ReturnType<typeof setInterval> | null = null; private lessonTimer: ReturnType<typeof setInterval> | null = null;
private lessonTestTime: number | null = null; private lessonTestTime: number | null = null;
private get lessonShowing(): boolean { private get lessonShowing(): boolean {
if (this.customLayout && this.lessonCue?.kind === 'ending') return false;
return Boolean( return Boolean(
this.lessonCue && this.lessonCue &&
!this.editingLayout && !this.editingLayout &&
@@ -364,14 +369,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);
@@ -618,6 +624,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;
@@ -634,12 +641,19 @@ 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 {
...this.state, ...this.state,
coursewareTransfer: this.coursewareShowing ? this.state.coursewareTransfer : null, coursewareTransfer: this.coursewareShowing ? this.state.coursewareTransfer : null,
lessonReminder: this.lessonShowing ? this.lessonCue : null, lessonReminder:
this.lessonShowing || (this.customLayout && this.lessonCue?.kind === 'ending')
? this.lessonCue
: null,
queued: [...this.state.queued], queued: [...this.state.queued],
}; };
} }
@@ -860,6 +874,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;
@@ -2320,6 +2339,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;
@@ -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 });
@@ -83,6 +83,59 @@ export async function runQuickSmoke(win: BrowserWindow): Promise<void> {
return result.detail; return result.detail;
}); });
} }
await check('主窗口最小与常规尺寸、深浅主题及关怀字号无页面横向溢出', async () => {
const bounds = win.getContentBounds();
const appearance = await win.webContents.executeJavaScript(
`({className:document.documentElement.className,style:document.documentElement.getAttribute('style')})`,
);
const shots = path.resolve(app.getAppPath(), '../../docs/screenshots/desktop-responsive');
fs.mkdirSync(shots, { recursive: true });
await win.webContents.executeJavaScript('window.__classhelperSmoke__.islandEditorSmoke(true)');
try {
for (const [width, height] of [
[1000, 540],
[1242, 582],
[1920, 1080],
])
for (const theme of ['light', 'dark']) {
win.setContentSize(width!, height!);
await win.webContents.executeJavaScript(
`document.documentElement.classList.toggle('dark',${theme === 'dark'});document.documentElement.classList.toggle('care-mode',${theme === 'dark'});document.documentElement.style.setProperty('--ch-font-scale',${JSON.stringify(theme === 'dark' ? '1.5' : '1')})`,
);
for (const route of [
'/schedule',
'/homeworks',
'/notifications',
'/grades',
'/courseware',
'/settings/general',
'/settings/appearance',
'/settings/island',
'/settings/island/editor',
'/settings/reminder',
'/settings/account',
'/settings/about',
]) {
await win.webContents.executeJavaScript(`location.hash=${JSON.stringify('#' + route)}`);
await new Promise((resolve) => setTimeout(resolve, 150));
if (
!(await win.webContents.executeJavaScript('document.documentElement.scrollWidth<=innerWidth+1'))
)
throw new Error(`${route} ${width} ${theme} 页面溢出`);
}
fs.writeFileSync(
path.join(shots, `main-${width}-${theme}.png`),
(await win.webContents.capturePage()).toPNG(),
);
}
} finally {
await win.webContents.executeJavaScript(
`document.documentElement.className=${JSON.stringify(appearance.className)};document.documentElement.setAttribute('style',${JSON.stringify(appearance.style || '')});window.__classhelperSmoke__.islandEditorSmoke(false)`,
);
win.setContentSize(bounds.width, bounds.height);
}
return '1000×540、1242×582、1920×1080,截图保存在 docs/screenshots/desktop-responsive';
});
await verifyAgentSmoke(check); await verifyAgentSmoke(check);
await verifyLayoutSmoke(check); await verifyLayoutSmoke(check);
await verifyCoursewareSmoke(check); await verifyCoursewareSmoke(check);
@@ -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>();
@@ -519,7 +527,7 @@ export async function verifyResidentSmoke(
await pause(700); await pause(700);
return Math.abs(immediate - opacity) < 0.01 && Math.abs(after - opacity) < 0.01; return Math.abs(immediate - opacity) < 0.01 && Math.abs(after - opacity) < 0.01;
}); });
await check('两种布局均弹出ClassIsland课前/上下课提醒,倒计时与右侧时间正确且不写入通知队列', async () => { await check('两种布局的上下课提醒、课程旁下课倒数与右侧时间正确且不写入通知队列', async () => {
const capture = process.env.ISLAND_MOTION_CAPTURE === '1' && process.env.ELECTRON_SMOKE_MODE === 'visual'; const capture = process.env.ISLAND_MOTION_CAPTURE === '1' && process.env.ELECTRON_SMOKE_MODE === 'visual';
const recorded: Array<{ at: number; image: Electron.NativeImage }> = []; const recorded: Array<{ at: number; image: Electron.NativeImage }> = [];
const start = Date.now(); const start = Date.now();
@@ -607,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(
@@ -632,17 +642,33 @@ export async function verifyResidentSmoke(
throw new Error('自动倒计时未切到本节下课'); throw new Error('自动倒计时未切到本节下课');
} }
if (layout === 'custom') { if (layout === 'custom') {
saveConfig({ islandLayout: { ...fixture, layout } }); const endingLayout = JSON.parse(JSON.stringify(fixture));
endingLayout.schemes[0].rows[0].nodes = [islandNode('schedule', 'lesson-ending-course')];
saveConfig({ islandLayout: endingLayout });
island.syncCustomLayout(); island.syncCustomLayout();
} }
await setTime(9, 44); await setTime(9, 44);
await pause(700); await pause(1100);
if (island.getState().lessonReminder?.kind !== 'ending') if (island.getState().lessonReminder?.kind !== 'ending')
throw new Error(layout + '下课倒数状态错误:' + JSON.stringify(island.getState().lessonReminder)); throw new Error(layout + '下课倒数状态错误:' + JSON.stringify(island.getState().lessonReminder));
const ending = await win.webContents.executeJavaScript( const ending = await win.webContents.executeJavaScript(
`document.querySelector('${layout === 'custom' ? '.resident-lesson-page' : '.ci-fixed-lesson'}')?.textContent.includes('距下课还剩')`, `(() => {
const root=document.querySelector('${layout === 'custom' ? '.resident-compact' : '.ci-fixed-lesson'}');
const badge=root?.querySelector('.lesson-ending-badge');
const course=root?.querySelector('${layout === 'custom' ? '.lesson-line.current strong' : '.ci-lesson-course strong'}');
const rect=badge?.getBoundingClientRect(),name=course?.getBoundingClientRect();
return Boolean(badge?.textContent.trim()==='-60'&&rect&&name&&rect.left>=name.right&&Math.abs(rect.width-rect.height)<1&&!root?.querySelector('.ci-mask-active'));
})()`,
); );
if (!ending) throw new Error(layout + '下课倒数未渲染'); if (!ending) throw new Error(layout + '下课倒数未渲染');
await setTime(9, 44, 59);
await pause(1100);
if (
!(await win.webContents.executeJavaScript(
`document.querySelector('${layout === 'custom' ? '.resident-compact' : '.ci-fixed-lesson'} .lesson-ending-badge')?.textContent.trim()==='-1'`,
))
)
throw new Error(layout + '最后一秒徽标错误');
await shot('lesson-ending-' + layout); await shot('lesson-ending-' + layout);
await setTime(9, 45); await setTime(9, 45);
island.setClassState({ inClass: false }); island.setClassState({ inClass: false });
@@ -679,6 +705,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));
@@ -743,15 +850,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 的触摸形状延时;尺寸稳定前不要断言。
const hit = island.getHitRect(); let settled = false;
return Boolean( const deadline = Date.now() + 3500;
hit && while (Date.now() < deadline) {
await pause(100);
const current = island.getHitRect();
if (
current &&
shape.length === 1 && shape.length === 1 &&
shape[0]!.width <= hit.width + 18 && shape[0]!.width <= current.width + 18 &&
shape[0]!.height <= hit.height + 18 && shape[0]!.height <= current.height + 18
JSON.stringify(box) === JSON.stringify(win.getBounds()), ) {
); settled = true;
break;
}
}
const hit = island.getHitRect();
const ok = Boolean(settled && hit && JSON.stringify(box) === JSON.stringify(win.getBounds()));
if (!ok) throw new Error(JSON.stringify({ hit, shape, bounds: win.getBounds(), box, settled }));
return true;
} finally { } finally {
win.setShape = original; win.setShape = original;
island.setTouchMode(false); island.setTouchMode(false);
+4 -43
View File
@@ -17,7 +17,6 @@ import {
ISLAND_URGENT_SIZE, ISLAND_URGENT_SIZE,
} from './island.js'; } from './island.js';
import { destroyTray, getTrayState, isTrayReady } from './tray.js'; import { destroyTray, getTrayState, isTrayReady } from './tray.js';
import { checkForUpdates, wasStartupCheckSkipped } from './update.js';
interface SmokeResult { interface SmokeResult {
name: string; name: string;
@@ -3078,7 +3077,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 +3103,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)',
@@ -4476,46 +4477,6 @@ export async function runSmokeTest(win: BrowserWindow): Promise<void> {
); );
record('关于页渲染(应用信息/诊断信息/鸣谢)', Boolean(aboutPage?.ok), String(aboutPage?.detail ?? '')); record('关于页渲染(应用信息/诊断信息/鸣谢)', Boolean(aboutPage?.ok), String(aboutPage?.detail ?? ''));
// 更新检查(新功能回归):主进程直连 GitHub 取最新 Release。
//
// **刻意不断言"一定有新版本"**:那会把冒烟绑死在外网可达上,而教室机器常常没有外网
// (`ok=false` 是设计内的降级结果,不是失败)。因此两种结果都算通过,验的是:
// 结构完整、失败时有可读原因、以及缓存真的生效。
const updateFirst = await checkForUpdates(true);
const isVersionLike = (value: unknown): boolean => typeof value === 'string' && /^\d/.test(value);
const updateShapeOk =
isVersionLike(updateFirst.currentVersion) &&
typeof updateFirst.ok === 'boolean' &&
typeof updateFirst.hasUpdate === 'boolean' &&
(updateFirst.ok
? isVersionLike(updateFirst.latestVersion) &&
Array.isArray(updateFirst.assets) &&
/^https:\/\//.test(updateFirst.releaseUrl) &&
updateFirst.error === null
: typeof updateFirst.error === 'string' && updateFirst.error.length > 0);
record(
'更新检查返回结构正确(无外网时降级为 ok=false 且带原因)',
updateShapeOk,
`ok=${updateFirst.ok} 本机=${updateFirst.currentVersion} 最新=${updateFirst.latestVersion ?? '-'} ` +
`有新版本=${updateFirst.hasUpdate} 附件=${updateFirst.assets.length}` +
`${updateFirst.error ? ` 原因=${updateFirst.error}` : ''}`,
);
// 缓存:紧接着再查一次(不传 force)应命中缓存 —— checkedAt 不变即说明没有二次请求
const updateSecond = await checkForUpdates();
record(
'更新检查结果带缓存(不重复请求 GitHub)',
updateSecond.checkedAt === updateFirst.checkedAt,
`两次 checkedAt 相同=${updateSecond.checkedAt === updateFirst.checkedAt}`,
);
// 启动自动检查在冒烟模式下必须被跳过,否则每次验证都会产生一次真实网络请求与提示条
record(
'冒烟模式下跳过启动自动检查(验证不依赖外网)',
wasStartupCheckSkipped(),
`skipped=${wasStartupCheckSkipped()}`,
);
// 未读红点必须挂在"通知"图标右上方(用户反馈:原来挂在文字后面,位置不对) // 未读红点必须挂在"通知"图标右上方(用户反馈:原来挂在文字后面,位置不对)
const readBadgeGeometry = async (): Promise<{ const readBadgeGeometry = async (): Promise<{
ok: boolean; ok: boolean;
@@ -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'),
};
}
-216
View File
@@ -1,216 +0,0 @@
import { app, type BrowserWindow } from 'electron';
import {
GITHUB_RELEASES_LATEST_API,
GITHUB_RELEASES_PAGE,
UPDATE_CHECK_CACHE_TTL_MS,
UPDATE_CHECK_TIMEOUT_MS,
UPDATE_CHECK_USER_AGENT,
isNewerVersion,
normalizeVersion,
type UpdateAssetDto,
type UpdateInfo,
} from '@classhelper/shared';
import { UPDATE_AVAILABLE_CHANNEL } from './channels.js';
import { getConfig, saveConfig } from './config.js';
import { logger } from './logger.js';
/**
* 更新检查(桌面客户端)。
*
* **为什么在主进程做**:渲染进程通过 preload 能拿到 `getConfig()` 的明文 token(代表全班身份),
* 它的 CSP 与导航防线是整个安全模型里最要紧的一层;让它额外去连一个外部域名、
* 解析外部 JSON,等于把"外部数据"请进最有价值的那一侧。主进程本来就在做网络与文件,
* 放这里也顺带复用 Node 的 fetch(无需额外依赖)。
*
* 与 Web 管理端的差别:Web 端受服务端 CSP 的 `connect-src` 限制,只能走 `/api/update/check` 转发;
* 客户端没有这个限制,按用户选择**直连 GitHub**。两边归一化出的 `UpdateInfo` 结构一致。
*/
/** 主进程 → 渲染进程:发现新版本(渲染进程据此弹一次性提示);定义在叶子模块 `channels.ts` */
export { UPDATE_AVAILABLE_CHANNEL };
/** 启动后多久自动查一次:等窗口与登录流程就绪,也不跟首屏请求抢带宽 */
const STARTUP_DELAY_MS = 5_000;
interface GithubReleasePayload {
tag_name?: unknown;
name?: unknown;
published_at?: unknown;
body?: unknown;
html_url?: unknown;
assets?: unknown;
}
let cache: { at: number; info: UpdateInfo } | null = null;
let startupTimer: ReturnType<typeof setTimeout> | null = null;
/** 冒烟断言用:启动自动检查是否被跳过(冒烟模式下必须是 true) */
let startupCheckSkipped = false;
/** 失败的统一出口:结构完整,界面不必做 null 判断 */
function failure(error: string): UpdateInfo {
return {
ok: false,
error,
currentVersion: app.getVersion(),
latestVersion: null,
hasUpdate: false,
releaseUrl: GITHUB_RELEASES_PAGE,
releaseName: null,
publishedAt: null,
notes: null,
assets: [],
checkedAt: new Date().toISOString(),
};
}
function toAssets(raw: unknown): UpdateAssetDto[] {
if (!Array.isArray(raw)) return [];
return raw
.map((item) => item as { name?: unknown; browser_download_url?: unknown; size?: unknown })
.filter(
(item): item is { name: string; browser_download_url: string; size?: unknown } =>
typeof item.name === 'string' && typeof item.browser_download_url === 'string',
)
.map((item) => ({
name: item.name,
downloadUrl: item.browser_download_url,
size: typeof item.size === 'number' && Number.isFinite(item.size) ? item.size : 0,
}));
}
function toInfo(payload: GithubReleasePayload, currentVersion: string): UpdateInfo {
const latestVersion = normalizeVersion(typeof payload.tag_name === 'string' ? payload.tag_name : '');
if (!latestVersion) {
logger.warn('更新检查:GitHub 返回的 Release 里没有可识别的 tag_name');
return failure('GitHub 返回的版本号无法识别');
}
return {
ok: true,
error: null,
currentVersion,
latestVersion,
hasUpdate: isNewerVersion(currentVersion, latestVersion),
releaseUrl:
typeof payload.html_url === 'string' && payload.html_url ? payload.html_url : GITHUB_RELEASES_PAGE,
releaseName: typeof payload.name === 'string' ? payload.name : null,
publishedAt: typeof payload.published_at === 'string' ? payload.published_at : null,
notes: typeof payload.body === 'string' ? payload.body : null,
assets: toAssets(payload.assets),
checkedAt: new Date().toISOString(),
};
}
/** 把各种失败翻译成一句用户能看懂的话(教室里最常见的就是"这台机器没有外网") */
function describeFailure(error: unknown): string {
const message = error instanceof Error ? error.message : String(error);
if (error instanceof Error && error.name === 'TimeoutError') {
return `连接 GitHub 超时(${UPDATE_CHECK_TIMEOUT_MS / 1000} 秒),本机可能没有外网`;
}
if (/fetch failed|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|certificate|net::/i.test(message)) {
return '无法连接 GitHub,本机可能没有外网';
}
return `检查更新失败:${message}`;
}
/**
* 检查 GitHub 上有没有比本机新的版本(结果带缓存)。
*
* 缓存的意义:匿名调用 GitHub API 的限流是 60 次/小时/IP,而「关于」页的按钮可以随便点。
* 失败结果同样进缓存 —— 否则离线时每点一次都要白等一个超时。
*/
export async function checkForUpdates(force = false): Promise<UpdateInfo> {
const currentVersion = app.getVersion();
const now = Date.now();
if (!force && cache && now - cache.at < UPDATE_CHECK_CACHE_TTL_MS) {
return cache.info;
}
let info: UpdateInfo;
try {
const response = await fetch(GITHUB_RELEASES_LATEST_API, {
headers: {
// GitHub API 强制要求 User-Agent,不带会直接 403
'User-Agent': UPDATE_CHECK_USER_AGENT,
Accept: 'application/vnd.github+json',
},
signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
});
if (!response.ok) {
info =
response.status === 403 || response.status === 429
? failure('GitHub 暂时拒绝了请求(匿名查询次数过多),请过一会儿再试')
: failure(`GitHub 返回 HTTP ${response.status}`);
logger.warn(`更新检查失败:HTTP ${response.status}(本机版本 ${currentVersion})`);
} else {
info = toInfo((await response.json()) as GithubReleasePayload, currentVersion);
logger.info(
`更新检查:本机 ${currentVersion} / 最新 ${info.latestVersion ?? '-'}` +
`${info.hasUpdate ? '(有新版本)' : '(已是最新)'}`,
);
}
} catch (error) {
info = failure(describeFailure(error));
logger.warn(`更新检查失败:${info.error}(本机版本 ${currentVersion})`);
}
cache = { at: now, info };
return info;
}
/** 「知道了 / 忽略此版本」:记到配置里,同一个版本不再重复弹提示 */
export function ignoreUpdateVersion(version: string): void {
const normalized = normalizeVersion(version);
if (!normalized) return;
saveConfig({ ignoredUpdateVersion: normalized });
logger.info(`已忽略版本 ${normalized} 的更新提示`);
}
/** 该版本是否已被用户忽略 */
export function isUpdateIgnored(version: string): boolean {
return normalizeVersion(getConfig().ignoredUpdateVersion) === normalizeVersion(version);
}
/**
* 启动后的自动检查:延迟 `STARTUP_DELAY_MS` 查一次,有新版本(且没被忽略)就通知渲染进程弹提示。
*
* **冒烟模式直接跳过**:自动化验证不该每次都发真实网络请求(既抖动又依赖外网),
* 而且凭空多出来的提示条会撞坏既有 UI 断言。冒烟用例改为直接调 IPC 验证返回结构。
*/
export function scheduleStartupUpdateCheck(getWindow: () => BrowserWindow | null): void {
if (process.env.ELECTRON_SMOKE_TEST === '1') {
startupCheckSkipped = true;
logger.info('更新检查:冒烟模式下跳过启动自动检查');
return;
}
if (startupTimer) clearTimeout(startupTimer);
startupTimer = setTimeout(() => {
startupTimer = null;
void (async () => {
try {
const info = await checkForUpdates();
if (!info.ok || !info.hasUpdate || !info.latestVersion) return;
if (isUpdateIgnored(info.latestVersion)) {
logger.info(`更新检查:${info.latestVersion} 已被用户忽略,本次不提示`);
return;
}
const win = getWindow();
if (!win || win.isDestroyed()) return;
win.webContents.send(UPDATE_AVAILABLE_CHANNEL, info);
logger.info(`更新检查:已提示新版本 ${info.latestVersion}`);
} catch (error) {
// 自动检查失败不该打扰用户(手动检查才需要看到原因)
logger.warn(`启动自动检查更新失败:${error instanceof Error ? error.message : error}`);
}
})();
}, STARTUP_DELAY_MS);
// 不阻止进程退出:这个定时器只是"顺便查一下"
startupTimer.unref?.();
}
/** 冒烟断言用:启动自动检查是否被跳过(冒烟模式下应为 true —— 否则每次验证都会发真实网络请求) */
export function wasStartupCheckSkipped(): boolean {
return startupCheckSkipped;
}
+3 -11
View File
@@ -3,7 +3,7 @@ import type {
CoursewareTransfer, CoursewareTransfer,
} from '@classhelper/shared'; } 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 } from '../main/channels.js';
import type { ClientAgentStatus } from '../main/client-agent.js'; import type { ClientAgentStatus } from '../main/client-agent.js';
import type { import type {
DesktopAppInfo, DesktopAppInfo,
@@ -12,7 +12,7 @@ import type {
IslandClassStatePayload, IslandClassStatePayload,
IslandPushContext, IslandPushContext,
} from '../types/desktop.js'; } from '../types/desktop.js';
import type { IslandNotification, UpdateInfo } from '@classhelper/shared'; import type { IslandNotification } from '@classhelper/shared';
/** /**
* 预加载脚本:在开启了 contextIsolation + sandbox 的前提下, * 预加载脚本:在开启了 contextIsolation + sandbox 的前提下,
@@ -23,6 +23,7 @@ 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'), listLocalCourseware: () => ipcRenderer.invoke('courseware:local-list'),
@@ -64,15 +65,6 @@ const bridge: DesktopBridge = {
getAppInfo: (): Promise<DesktopAppInfo> => ipcRenderer.invoke(IPC_CHANNELS.appInfo), getAppInfo: (): Promise<DesktopAppInfo> => ipcRenderer.invoke(IPC_CHANNELS.appInfo),
openExternal: (url: string): Promise<boolean> => ipcRenderer.invoke(IPC_CHANNELS.openExternal, url), openExternal: (url: string): Promise<boolean> => ipcRenderer.invoke(IPC_CHANNELS.openExternal, url),
/* 更新检查(主进程直连 GitHub,见 main/update.ts) */
checkForUpdates: (force = false): Promise<UpdateInfo> =>
ipcRenderer.invoke(IPC_CHANNELS.updateCheck, force),
ignoreUpdateVersion: (version: string): Promise<void> =>
ipcRenderer.invoke(IPC_CHANNELS.updateIgnore, version),
onUpdateAvailable: (handler: (info: UpdateInfo) => void): void => {
ipcRenderer.on(UPDATE_AVAILABLE_CHANNEL, (_event, info: UpdateInfo) => handler(info));
},
islandPush: (payload: { notification: IslandNotification; context?: IslandPushContext }): void => { islandPush: (payload: { notification: IslandNotification; context?: IslandPushContext }): void => {
ipcRenderer.send('island:push', payload); ipcRenderer.send('island:push', payload);
}, },
@@ -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));
+5 -55
View File
@@ -1,8 +1,6 @@
<script setup lang="ts"> <script setup lang="ts">
import { h, onMounted, onUnmounted, ref } from 'vue'; import { onMounted, onUnmounted, ref } from 'vue';
import { useRouter } from 'vue-router'; import { useRouter } from 'vue-router';
import { ElButton, ElNotification } from 'element-plus';
import type { UpdateInfo } from '@classhelper/shared';
import { import {
replayMissedNotifications, replayMissedNotifications,
startIslandBridge, startIslandBridge,
@@ -13,6 +11,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';
@@ -27,56 +26,10 @@ const realtime = useRealtimeStore();
const booting = ref(true); const booting = ref(true);
const bootText = ref('正在读取本地配置...'); const bootText = ref('正在读取本地配置...');
/**
* 启动自动检查发现新版本时的提示(主进程查出后推过来,见 main/update.ts)。
*
* **为什么订阅放在 App.vue**:`onUpdateAvailable` 底层是 `ipcRenderer.on`,
* 桥接层没有对应的 off —— 挂在会随"登出 → 登录"反复挂载的 ClientLayout 里,
* 处理器会越堆越多(与灵动岛订阅同一个坑)。App.vue 整个应用生命周期只挂载一次。
*
* 提示是**一次性**且可永久消音:点「忽略此版本」写进 config.json,同一版本不再提示;
* 「关于」页里仍可随时手动检查。
*/
function showUpdateAvailable(info: UpdateInfo): void {
if (!info.latestVersion) return;
ElNotification({
title: `发现新版本 v${info.latestVersion}`,
type: 'info',
// 不自动消失:这是需要用户决定的事(去下载 / 忽略),滑过去就只能靠「关于」页再想起来
duration: 0,
message: h('div', { style: 'line-height: 1.7' }, [
h('p', { style: 'margin: 0 0 10px' }, `当前版本 ${info.currentVersion},可前往下载更新。`),
h('div', { style: 'display: flex; gap: 8px' }, [
h(
ElButton,
{
size: 'small',
type: 'primary',
onClick: () => {
void window.desktop?.openExternal(info.releaseUrl);
},
},
() => '前往下载',
),
h(
ElButton,
{
size: 'small',
onClick: () => {
void window.desktop?.ignoreUpdateVersion(info.latestVersion ?? '');
},
},
() => '忽略此版本',
),
]),
]),
});
}
/** /**
* 上线补弹「离线期间收到的消息」(需求 11)。 * 上线补弹「离线期间收到的消息」(需求 11)。
* *
* **为什么订阅放在 App.vue**:与 `onUpdateAvailable` 同一条理由 —— App.vue 整个应用生命周期 * **为什么订阅放在 App.vue**:App.vue 整个应用生命周期
* 只挂载一次,而 `ClientLayout` 会随"登出 → 登录"反复挂载。而且恢复事件本身是"可达性由不可达 * 只挂载一次,而 `ClientLayout` 会随"登出 → 登录"反复挂载。而且恢复事件本身是"可达性由不可达
* 变为可达"的那一刻,一次会话里可能发生多次,处理器必须是**幂等**的(`replayMissedNotifications` * 变为可达"的那一刻,一次会话里可能发生多次,处理器必须是**幂等**的(`replayMissedNotifications`
* 推完就清掉离线起点,重复触发时第二次读到空值、直接返回 0)。 * 推完就清掉离线起点,重复触发时第二次读到空值、直接返回 0)。
@@ -117,19 +70,16 @@ onMounted(async () => {
// 离线期间收到的消息:可达性恢复的那一刻补弹到灵动岛(App.vue 常驻,所以每次恢复只跑一次) // 离线期间收到的消息:可达性恢复的那一刻补弹到灵动岛(App.vue 常驻,所以每次恢复只跑一次)
appStore.onServerRecovered(handleServerRecovered); appStore.onServerRecovered(handleServerRecovered);
// 启动自动检查发现新版本时由主进程推过来(订阅只挂一次,理由见 showUpdateAvailable)
window.desktop?.onUpdateAvailable?.(showUpdateAvailable);
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);
@@ -61,7 +61,10 @@ http.interceptors.response.use(
const status = error.response.status; const status = error.response.status;
const message = error.response.data?.message ?? `请求失败(${status})`; const message = error.response.data?.message ?? `请求失败(${status})`;
if (status === 401) { const loginAttempt =
error.config?.method?.toLowerCase() === 'post' &&
/\/auth\/(?:class-)?login\/?(?:\?|$)/.test(error.config?.url ?? '');
if (status === 401 && !loginAttempt) {
ElMessage.warning('登录状态已失效,请重新登录'); ElMessage.warning('登录状态已失效,请重新登录');
unauthorizedHandler(); unauthorizedHandler();
} else { } else {
@@ -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 会改变实际请求的路径
Loaded 100 of 335 files, more files were not shown because too many files have changed in this diff. Show more