5 Commits
Author SHA1 Message Date
LoveChengke 195ee3b90a fix(ai): 修复追问与删除确认并支持删除对话 2026-11-08 11:13:43 +08:00
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
202 changed files with 11949 additions and 3014 deletions

No files matched your search

+5 -1
View File
@@ -26,6 +26,10 @@ on:
required: false
default: true
type: boolean
source_ref:
description: '同版本重建的源码提交;留空按 tag 检出'
required: false
type: string
push:
tags:
- 'v*'
@@ -53,7 +57,7 @@ jobs:
- name: 检出代码
uses: actions/checkout@v4
with:
ref: ${{ steps.ref.outputs.tag }}
ref: ${{ inputs.source_ref || steps.ref.outputs.tag }}
- name: 安装 Node 22
uses: actions/setup-node@v4
+5 -1
View File
@@ -11,6 +11,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
| 目录 | 用途 |
| -------------------------- | --------------------------------------------------------- |
| `packages/ui/src/` | Web 与桌面端共享 Vue 控件、主题、日期选择器与全屏引导 |
| `packages/shared/src/` | 三端共享类型、权限、常量、动效、岛方案与课件契约 |
| `packages/server/` | Express、Prisma、Socket.IO;API 前缀 `/api` |
| `packages/web-admin/` | Vue Web 管理端,PWA |
@@ -39,7 +40,8 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
- 作业和通知按本地 `assignDate` 归类,使用 `dayKeyLocal/isDayKey/shiftDayKey`,不用 UTC 日期切片。
- 批量通知/作业逐班返回结果;跨班作业按科目名匹配既有课程,找不到则该班失败,不自动把发布者设为任课老师。
- 两个登录接口共用登录限流。附件链接校验 scheme;表格文件上限 8 MB、JSON 请求体 12 MB,超限映射 413。
- AI 助手只解析待确认动作,前端确认后调既有发布接口;参数重新校验,Key 加密存储且不回传。自动化用 mock,不访问外网。
- AI 查询和模型上下文按原业务权限读取;写操作由动作目录生成计划,用户确认后调用既有业务接口,入口绑定操作者、参数和步骤并持久去重。数据库维护、服务器运维与密钥操作不注册为 AI 动作。密码经专用表单提交,计划参数加密保存;自动化用 mock,不访问外网。
- AI 可管理客户端安装包缓存:写入仅 ADMIN + `client:update`,要求专门确认,固定复用 `/update/client/fetch` 和 `/update/client/releases`。预览和执行核对版本、文件及已有登记;不开放服务器更新或任意下载地址,不自动推送或运行安装器。
## 3. 课表、周次、成绩与学年
@@ -77,6 +79,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
- 事件名与房间名取 shared 常量。班级房间为 `class:{id}:{channel}`,教师按每域读键及范围订阅,班级端仅本班全部通道;握手回查数据库身份。业务用 `emitToClass/emitToSession`,由总线选择事件域。
- 会话房间为 `session:{id}`;教师/管理员 id 为账号 id,班级端为班级 id。`students` 是班级端广播房间,不是个人学生账号房间。
- 新实时事件同步服务端、Web 订阅、客户端订阅。成绩实时载荷不可泄漏个人成绩。
- 两端基础控件、主题、日期圆点与全屏引导维护在 `packages/ui`。日期统计跟随当前筛选和日历可见范围,缓存按服务器与班级隔离;业务日期使用本地日期工具。
- Web 菜单分组在 `config/navigation.ts`,标题/图标/权限取路由;守卫与服务端都检查权限,前端隐藏不能代替鉴权。
- 侧栏折叠用 CSS 保持 DOM,关怀模式放大字号/控件,不改变几何令牌。使用语义色,动效统一 shared 令牌;图标新增后检查注册表。
- 图标源是 `build/classhelper.png` 与设计导出的 `.ico`,`pnpm icons` 派生其余资源。ICO 原样透传,客户端兜底 `build/icon.*` 同步保留。
@@ -112,6 +115,7 @@ Prisma 使用 driver adapter;本机优先应用已有迁移,不用 `migrate
| `pnpm lint` / `pnpm typecheck` / `pnpm check:icons` | 代码静态门禁;按改动范围执行 |
| `pnpm docs:check` | 文档严格构建,警告即失败 |
| `pnpm verify:e2e` | 自动创建临时 SQLite 和账号,无需先开开发服务,禁止外网 |
| `pnpm verify:ai` | AI 白名单、计划确认、权限与附件隔离验收 |
| `pnpm verify:authz` / `pnpm verify:audit` | 隔离授权攻击矩阵;审计事务、竞态、模型操作计数和 PWA |
| `pnpm verify:web:isolated` | 构建 Web 后运行隔离服务和隐藏 UI 回归 |
| `pnpm verify:courseware` / `pnpm verify:v14` | 课件/课表等隔离专项 |
+1 -1
View File
@@ -23,7 +23,7 @@ services:
context: ..
dockerfile: deploy/Dockerfile
target: runtime
image: classhelper-server:${APP_VERSION:-1.4.3}
image: classhelper-server:${APP_VERSION:-1.4.5}
restart: unless-stopped
environment:
NODE_ENV: production
+1 -1
View File
@@ -60,7 +60,7 @@ services:
context: ..
dockerfile: deploy/Dockerfile
target: runtime
image: classhelper-server:${APP_VERSION:-1.4.3}
image: classhelper-server:${APP_VERSION:-1.4.5}
restart: unless-stopped
environment:
NODE_ENV: production
+2 -1
View File
@@ -1,6 +1,6 @@
{
"name": "classhelper-server-runtime",
"version": "1.4.3",
"version": "1.4.5",
"private": true,
"type": "module",
"description": "ClassHelper 服务端运行时(安装包 / 容器内置)",
@@ -21,6 +21,7 @@
"socket.io": "^4.8.3",
"typescript": "~5.9.3",
"xlsx": "0.18.5",
"yaml": "^2.9.1",
"zod": "^4.6.2"
}
}
+11 -9
View File
@@ -7,7 +7,7 @@ description: 深浅色主题、界面风格、设计令牌与动效语言,以
## 深浅色主题
**两端都有深色主题,机制完全一致**:在 `<html>` 上挂 `.dark` 类,由各自的样式表覆盖**语义色令牌**,
**两端都有深色主题,机制完全一致**:在 `<html>` 上挂 `.dark` 类,由共享 UI 主题覆盖**语义色令牌**,
Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts` 都在挂载之前就把主题落好,
所以深色用户打开时不会"先白后黑"闪一下。
@@ -19,7 +19,7 @@ Element Plus 的深色变量提供组件层的默认值。两端的 `main.ts`
| 切换效果 | 从点击位置**扩散的圆**铺满整页换肤 |
**刻意不随主题的区域**:登录页的深色渐变底、桌面端的启动过渡页与全屏作业看板、灵动岛自身、
Web 管理端的侧边栏(本来就是深色),以及深色底上的白色文字。
以及深色底上的白色文字。
Web 端还会同步 `<meta name="theme-color">`,并设 `color-scheme` 让**原生控件**
(滚动条、日期选择器弹层、自动填充底色)也跟着走 —— 只改 CSS 变量的话它们会仍是浅色。
@@ -44,13 +44,15 @@ Web 端还会同步 `<meta name="theme-color">`,并设 `color-scheme` 让**原
## 界面风格
- 浅色底 `#f3f3f3` + 半透明卡片(`rgba(255,255,255,.7)` + `backdrop-filter: blur(20px)`);
- 强调色 `#0F6CBD`(悬停 `#115EA3`);选中的导航项 = 强调色淡底 + 左侧 3px 强调条;
- 圆角统一:卡片 8px / 控件 4px;描边用半透明黑代替灰线;阴影极轻;
- 字体 `Segoe UI Variable / 微软雅黑 UI`;Element Plus 的变量整体对齐这套规范。
Web 和桌面主窗口共用简洁的管理界面:浅灰底、实色卡片、统一描边与紫蓝强调色。标题、筛选、操作栏和表单按同一套控件与间距规范呈现;深浅色切换保持相同几何。
Web 管理端走的是另一套(1Panel 风格:深色侧边栏 + 白色圆角卡片),
圆角与投影集中定义在它的 `:root` 令牌里。
共享主题和控件由 UI 包维护,灵动岛只引入共用语义令牌,保留透明窗口和各模式的布局规则。
日期统一通过日历选择。有记录的日期下方显示圆点,统计随当前筛选和可见月份更新。日期目录与日期下拉列表已改为日历,教师和文件夹仍可独立筛选。
Web 的作业、通知日期统计保留在当前会话缓存中,按服务器、操作者、权限范围和筛选条件隔离;退出或收到授权失败时清理。桌面端复用按服务器和班级隔离的离线缓存。只有网络不可达时才回退缓存,缓存故障不阻断在线读取。
首次进入新版会显示全屏分步引导,可以返回、跳过或完成;账号菜单、客户端登录页和通用设置保留重看入口。引导中的内容为示意,不创建业务数据。
## 动效语言
@@ -94,6 +96,6 @@ beUI 的组件本身是 React,用不到这里,但它的动效语言与框架
| 灵动岛 | 尺寸、字号、主题色、视觉风格、停靠、边距、空闲细缝(详见[灵动岛](island.md)) |
| 提醒 | 本机课程等提醒开关与行为 |
| 账号 | 当前班级信息、退出登录 |
| 关于 | 版本 / Electron / Chromium / Node、诊断信息、检查更新、鸣谢 |
| 关于 | 版本 / Electron / Chromium / Node、诊断信息、云端下发更新的进度、鸣谢 |
`/settings` 会自动跳到「通用」。设置页的改动会**立刻生效并写进本机配置**,重启后仍保留。
+40 -12
View File
@@ -1,26 +1,54 @@
---
title: AI 助手
description: 将自然语言解析成待确认动作,核对后通过现有业务接口发布。
description: 多轮对话、文件处理与操作计划,核对后通过现有业务接口执行。
---
# AI 助手
AI 助手位于 Web 管理端工作台。输入要发布的作业、通知或叫人请求,助手会展示解析出的班级、科目、内容与提醒级别;核对并确认后才发布。内容仍通过原有业务接口,继续校验当前账号的功能权限、班级范围及任课关系。
在 Web 管理端描述任务、补充条件或添加文件,助手会查询所需信息并生成操作计划。查询直接显示结果;任何发布、修改、导入和设备操作,都要核对计划并确认后执行。
## 配置与使用
## 使用
管理员在大模型设置中开启助手,选择服务地址和模型并保存 API Key。密钥加密存储,读取设置只返回是否已配置及末尾提示,不返回完整密钥。修改服务端 JWT 密钥后,原有加密 Key 需要重新配置。
1. 可先选择目标班级,再输入任务;文件也可以直接拖入对话区。
2. 信息不足时补充说明。核对目标、文件、修改前内容和本次变更;表格导入可调整字段对应。
3. 确认执行后逐步显示结果。跨班发布按班显示进度,成功班级不会重复执行。失败时只重试尚未成功的步骤;结果不明时先在对应业务页面核对。
1. 在助手页面描述操作与目标班级,等待解析预览。
2. 核对班级、科目、标题、正文和提醒级别;有歧义时修改后重新解析。
3. 点击确认发布。紧急通知在上课期间仍需完成额外确认;批量操作逐班返回结果。
文件推送复用课件上传、哈希校验和设备回执,普通课件上限 512 MB。结构化导入支持现有 CSV、Excel、JSON、YAML 格式,上限 8 MB,先解析预览,确认后才写入业务数据。
解析成功不代表已经发布,也不代表拥有对应班级或科目的写权限。缺少任课关系时,请由管理员配置;助手不能替用户建立授权。
## 权限
## 离线示例与审计
助手权限跟随操作者。教学业务、课表时间表、名单成绩、账号岗位和设备操作均使用原业务接口的授权规则;管理员专用功能仍限管理员。确认期间撤权、调班或任课关系变化后会重新校验。
`mock` 提供确定性的离线示例解析,用于自动化验收,不访问外网;预览会提示当前为示例结果。真实模型调用失败时页面保留可操作的错误说明,不会自动改用发布接口。
数据库备份、恢复、清空、切换、SQL,以及服务器配置、启停、升级和密钥维护不向助手开放。删除、权限调整、升学和远控保留专门确认;上课时的紧急通知仍需二次确认。
有管理权限的账号可查看助手审计。审计记录解析意图和状态,不代替作业、通知或叫人的最终发布结果;请结合对应业务页面核对。
管理员可让助手抓取、登记或删除客户端安装包缓存,核对版本、文件与替换信息并专门确认后执行。缓存管理不会自动推送、运行安装器或升级服务器。助手也可按设备权限处理远控、更新推送和移除设备登记。
相关规则:[作业](homeworks.md)、[通知](notifications.md)、[叫人](calls.md)、[角色与权限](../dev/permissions.md)。
密码通过操作卡片中的专用表单输入,不提供给模型。用户指令与任务所需的已授权业务信息由学校配置的模型服务解析;普通课件只提供文件元数据。
任务提交后在服务端后台运行,切换页面或关闭浏览器不取消规划及已确认的执行。重新进入助手可恢复最近任务、处理过程和结果;未确认的变更始终等待确认。停止按钮才会主动停止任务;已经发出的当前业务请求可能完成,后续步骤停止。服务重启后保留任务及步骤状态,核对后继续,未知执行结果不会自动重做。
附件须先上传完整并通过 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)。
## 对话与轮次
对话历史按账号保存在服务器。每次发送是一轮,右侧横条可跳转轮次,新对话独立保存。助手缺少必要信息时会弹出提问窗口,可选答案或自由回答。关闭窗口后可通过历史消息中的“回答问题”再次打开,刷新页面也能恢复待回答的问题;追问阶段不执行写入。格式自动修正每轮至多一次,失败后保留明确的重试入口。
勾选“本轮明确替换当前待确认计划”后,新计划形成时只使选中的旧计划失效,历史记录保留。不勾选时保留旧计划;新建对话不影响其他对话的计划。
删除课表等危险操作时,目标明确后会先生成变更预览,点击“确认执行”才弹出危险操作确认窗口。聊天中的“确认”回答只用于继续生成预览,不代替最终执行确认。
在对话历史中选择对话后,可点击“删除对话”。确认后清除该对话的轮次和暂存附件,未完成计划失效;已执行的业务操作及审计记录保留。仍有后台任务时,请先停止或等待完成再删除。
+4
View File
@@ -40,3 +40,7 @@
使用反向代理时,需允许课件上传大小和足够的读写超时。仓库的 Nginx 样例单独为 `/api/courseware/` 配置 512 MB 和 1800 秒超时,其他接口维持原有大小限制。
开发验收:`pnpm verify:courseware` 自动使用隔离数据库和临时文件目录,不读取或向真实班级发送课件。
## 文件夹浏览
课件默认按文件夹逐层浏览,只显示当前层文件和直属子目录。使用面包屑或返回上级切换目录;多位教师的目录按教师身份区分。上传与新建目录默认使用当前位置,未分类文件位于根目录。日期归档视图仍可用于按日期查找文件。
+33 -2
View File
@@ -16,13 +16,13 @@ description: 表格预览、名单与成绩校验,以及完整离线档案导
- 学生成绩按学号匹配,姓名兜底要求同班唯一;转出学生不参与匹配,重复记录和写入模式由服务校验。
- 学生模板使用学号、姓名、班级、性别、家长电话,无密码;学号 1–32 位字母/数字/._-,在 Student 表查重。
- 教师模板使用工号、姓名、手机号、初始密码、角色;学生/教师名单导入仍要求管理员和导入权限。
- 教师模板使用工号、姓名、手机号、角色;每个新建教师分别生成随机初始密码,导入结果提供一次性查看和 CSV 下载,关闭前请保存分发。重复导入已有教师不修改密码,旧表格中的密码列不再用于设置密码。任课关系导入中新建的教师采用相同规则;学生/教师名单导入仍要求管理员和导入权限。
- 成绩表格导入当前先要求管理员或本班班主任,再校验每行科目任课关系;科任老师的单条/批量成绩写入权限不代表能走表格导入。
- 任课关系导入用于既有班级、科目和教师的对应关系,不把档案中的 TeacherName 当账号授权。
## 完整 ClassIsland 档案
在“课表档案 → 导入档案”选择或粘贴 JSON,先预览再导入。
在“课表档案 → 导入/导出 → 导入课表(JSON / YAML)”选择或粘贴 JSON,先预览再导入。
完整输入包含 TimeLayouts、ClassPlans、Subjects 字典,可包含 ClassPlanGroups 和 OrderedSchedules 等配置。
JSON 只作为离线文件导入,不依赖在线联动插件。
@@ -44,6 +44,37 @@ JSON 只作为离线文件导入,不依赖在线联动插件。
不完整展示群组/空课/停用等结构;提交直接调用完整导入,不能把预览的单双周列当作实际数据模型。
完整导入失败时事务回滚;部分缺失引用可能返回 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,现行写入同步关系化时间点。
+5 -5
View File
@@ -37,7 +37,7 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
“设置 → 灵动岛 → 自定义 → 编辑岛内组件”进入主窗口设置页。
页面上方排列当前组件,右上角选择配置方案;刷新图标重置当前方案,加号新建方案,文件夹菜单提供方案设置、复制、删除及 JSON 导入导出。
下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器,并保留班级通知、作业和叫人组件。
下方组件库常驻显示文本、分割线、课程表、日期、时钟、天气简报、倒计时和组合容器。通知、作业和叫人通过岛内铃铛及共用消息面板展示,组件库不再提供这些消息选项;已有方案中的消息节点仍兼容。
从组件库拖入上方的行或容器以添加,拖动已有组件调整顺序或跨行移动;也可点击组件库添加到选中的容器或当前行。
分别编辑常态 rows 与无消息展开 expandedRows,点选组件打开内容、外观、尺寸与隐藏条件设置;行可以新增、排序、设为主要行或删除。
“进入编辑模式”切换为实际内容预览,支持预览缩放;退出后回到组件标签排列。轮播和滚动容器在编辑时展示全部子组件,便于选择和排列。
@@ -50,7 +50,7 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
## 外观、位置与输入
经典模式可调宽高、字号、主题色、黑色/半透明/渐变、停靠与边距;自定义内容根据实际测量适配工作区。
自定义方案可配置缩放、圆角、颜色和行间距,默认值与范围在 shared/island-layout.ts。
自定义方案可配置缩放、圆角、颜色和行间距,默认值与范围在 shared/island-layout.ts。外观页的圆角滑块同步修改当前自定义方案的常态圆角,与编辑器设置一致。
左右边距只在左/右停靠时生效,居中锚点仍在屏幕中线。
触摸屏自动进入触摸模式,保留触摸命中和失焦宽限;鼠标模式按光标控制输入穿透。
自定义常驻内容支持鼠标避让淡化及反转,交互入口、展开/编辑和触摸操作按实现暂停避让。
@@ -65,9 +65,9 @@ description: 经典提醒、自定义常驻方案、课程与课件传输。
自定义常驻岛的「课程表」组件可选「当前时间点 / 下一节课 / 今日时间点」:
「今日时间点」显示当天全部时间点,只有当前项展开显示起止时间,其余折叠只显示课程名;
课间休息与「默认隐藏」的上课时间点折叠时完全隐藏,轮到它们时才展开;分割线显示一条竖线,行动不显示。
课中课程表不再常驻显示倒计时,只在最后一分钟由既有的「下课提醒」页显示「距下课还剩」;
倒计时阈值沿用本机提醒设置(默认 60 秒)。没有时间点数据时退回按课表条目显示课程。
经典 fixed 岛的课中提醒条保持原有倒计时行为。
临近下课时,当前课程名右侧显示蓝色圆形秒数徽标,例如剩余一秒显示 `-1`,不显示“即将下课”遮罩,也不替换自定义岛的常态组件。
倒计时阈值沿用本机提醒设置(默认 60 秒),关闭即将下课倒数后不显示徽标。没有时间点数据时退回按课表条目显示课程。
经典 fixed 岛的临近下课提醒也使用课程名右侧的秒数徽标,其余上下课提醒保留。
课件接收时显示文件名、类型、教师、字节和进度,覆盖当前固定/自定义内容;完成后校验 SHA256 并回执。
客户端不会自动执行收到的文件,见[课件](courseware.md)。
+8
View File
@@ -18,6 +18,8 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编
完整档案可在页头「导入/导出」中导入或导出 JSON,保留轮换、时间点类型、空课、停用、群组和预定。月视图提供日期导航,点击日期后由服务端解析教学周并进入周视图。
「导入课表(JSON / YAML)」还支持简化的 YAML 课表,包含星期、单双周、科目和起止时间;字段与示例见[表格与课表导入](imports.md)。
## 日课表与时间表
时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。
@@ -49,3 +51,9 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编
离线导入完整 ClassIsland 档案可创建班级自有作息,不依赖在线联动插件。
完整导入保留 1–9 周轮换、空课、停用、群组和预定;旧预览界面的单双周展示不代表新模型只能表达双周。
见[表格与课表导入](imports.md)。修改后广播 schedule:updated,客户端刷新。
## 每日作息差异
导入的每日作息不一致时,时间表按日期生成独立子表,同日单双周也可分别维护。子表独立保存完整作息,父级用于归组。周视图按课时对齐;点击日期或课程后,时间列显示对应日期的作息,点击时间列标题清除选择后显示带星期标记的差异时间。切换子表保留可对应的课程,节数不足时阻止切换并保留原草稿。
导入或保存时间表时自动补齐两节课之间的空白,包括午休。已有命名休息、活动及显式空课保留,不在最后一节之后追加休息。旧混合时间表请使用原文件预览后重新导入,不自动猜测空课归属。
+32 -2
View File
@@ -28,7 +28,7 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
## 教学与文件
| 路径/动作 | 行为及边界 |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| /courses | 班级科目与任课关系 |
| GET /schedules、/grid、/current、/active-week | 新关系模型的兼容投影,按班级范围读取 |
| POST/PATCH/DELETE /schedules[/:id] | 兼容 CRUD,写新模型,不双写旧 Schedule |
@@ -43,6 +43,7 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
| /grades、/grades/bulk、/stats、/levels、/my、/overview、/collective、/student/:studentNo、/exams、/ranking | [成绩与隐私](../app/grades.md),查询列表参数用 studentId,写入仍按科目 |
| /imports/template、/table/preview、/table/commit | 表格导入,按 kind 再检查对应导入键、管理键、班级和科目 |
| /imports/class-plan/preview、/imports/class-plan | 预览与提交均需 import:schedule + schedule:write;提交走关系化导入 |
| 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 /courseware、/courseware/:id、/:id/download | 课件目录/详情/下载;员工需 courseware:read,班级端按可见范围 |
@@ -68,7 +69,7 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
| /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;目标空库、快照及换库子进程保护 |
| /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 | 按范围读取看板与周次 |
探针 /healthz 和 /readyz 不带 API 前缀;/api/health 提供版本与模块详情。
@@ -117,3 +118,32 @@ API 前缀 /api,JWT 使用 Authorization: Bearer。成功/失败结构以 `lib
成绩 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。
+1
View File
@@ -71,6 +71,7 @@ gh release upload v<版本> <三个已按上传名暂存的EXE> releases/SHA256S
推送 v* tag 触发 release-linux-server.yml,按 tag 检出,在 Ubuntu 构建并上传 Linux 包、独立 .sha256,合并跨组件清单。
等待 Actions 成功,再下载 Linux 文件和最终 SHA256SUMS 同步回本地;检查清单的 Windows 行仍与本次文件一致。
如需重跑,可手动运行该 workflow,指定准确 tag 和 attach=true。master 修复不会自动改变旧 tag 指向。
用户明确要求同版本更新远端服务端资产时,可额外指定 `source_ref` 为经过验证的完整提交 SHA;版本仍须与目标 tag 一致。保留原标签,在发布说明注明服务端重建提交及客户端沿用原批次,更新两个平台的服务端包与摘要。
官网和文档站由 pages.yml 拼装同一个站点:官网根、文档 /docs/。文档版本徽标读根 package.json,
官网和下载页兜底版本由 version 脚本维护。Linux workflow 与 Pages 是独立流水线,分别确认结果。
+2 -2
View File
@@ -308,7 +308,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
## 五、环境变量清单
| 变量 | 默认 | 说明 |
| --------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
| --------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `NODE_ENV` | `development` | `production` 会启用生产校验、HSTS、更严的限流 |
| `HOST` / `PORT` | `0.0.0.0` / `4000` | 监听地址与端口 |
| `DATABASE_PROVIDER` | `sqlite` | `sqlite` 或 `mysql` |
@@ -318,7 +318,7 @@ pnpm --filter @classhelper/server start # 或 node packages/server/dist/ind
| `JWT_EXPIRES_IN` | `7d` | 令牌有效期 |
| `CORS_ORIGIN` | `*` | 允许来源,多个用逗号分隔;生产建议写具体域名 |
| `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` | 启动校验数据库;生产不可用时直接退出 |
| `PID_FILE` | — | PID 文件路径(安装包启停脚本依赖),相对 `server` 根 |
| `WEB_DIST_DIR` | 自动探测 | Web 管理端产物目录(`../web-admin/dist` 或 `./web`) |
+6 -13
View File
@@ -18,17 +18,11 @@ description: 检查更新与各形态的升级步骤、Linux 的升级回滚链
## 检查更新
| 端 | 入口 | 检查路径 |
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
| ------------------- | ---------------------------------------------- | ------------------------------------------------ |
| 服务端 / Web 管理端 | 顶栏用户菜单 →「检查更新」 | 浏览器 → 服务端 `GET /api/update/check` → GitHub |
| 桌面客户端 | 启动后自动一次(延迟 5 秒)+「设置 → 关于」里的「检查更新」按钮 | 主进程 → GitHub(不经后端) |
| 桌面客户端 | 管理端「客户端管理」登记安装包并向班级下发更新 | 客户端只从当前服务端领取更新策略与安装包 |
两端的路径不同是**被约束逼出来的**:
- **Web 端不能直连 GitHub**。服务端下发的 CSP 里 `connect-src` 只放行 `'self'` 与 WebSocket,
浏览器发往 `api.github.com` 的请求会直接被拦掉。走服务端转发还有个好处:所有管理员共享同一份缓存
(GitHub 匿名限流是 60 次/小时/IP)。
- **客户端在主进程做**。渲染进程的 CSP 与导航防线是安全模型里最要紧的一层,
不让它去连外部域名、解析外部 JSON。
Web 管理端经服务端查询 GitHub Release。客户端不再主动检查 GitHub,也不提供手动检查入口;更新由管理端统一下发,仍校验 SHA256 并遵循本机自动更新开关和服务端策略。
### "查不到"是设计内的结果
@@ -39,12 +33,11 @@ description: 检查更新与各形态的升级步骤、Linux 的升级回滚链
失败结果同样进缓存 —— 否则断网时每点一次按钮都要白等一个超时。
| 细节 | 说明 |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| 缓存 | 两端各缓存 30 分钟;`?force=1` 绕过服务端缓存,但**仅管理员生效**(否则任意登录用户都能刷爆匿名限流) |
| ---- | ----------------------------------------------------------------------------------------------------- |
| 缓存 | 服务端缓存 30 分钟;`?force=1` 绕过服务端缓存,但**仅管理员生效**(否则任意登录用户都能刷爆匿名限流) |
| 权限 | 任何已登录用户都能查(信息来自公开仓库);`force` 除外 |
| 只提示一次 | 客户端启动检查发现新版才推提示;点「忽略此版本」记进配置,同一版本不再提示 |
更新**只提示,不自动下载、不自动安装**。安装包仍由人从 [Releases](https://github.com/LoveChengke/classhelper/releases)
服务端的更新检查只提示,不自动安装。管理员可从 [Releases](https://github.com/LoveChengke/classhelper/releases)
页面取,可用 `SHA256SUMS-<版本>.txt` 核对。
## 升级步骤
Binary file not shown.

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 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.

Before

Width:  |  Height:  |  Size: 73 KiB

After

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 108 KiB

After

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 129 KiB

After

Width:  |  Height:  |  Size: 133 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 101 KiB

After

Width:  |  Height:  |  Size: 96 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 135 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: 93 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

+4 -1
View File
@@ -1,6 +1,6 @@
{
"name": "class-helper",
"version": "1.4.3",
"version": "1.4.5",
"private": true,
"description": "ClassHelper - 班级信息管理系统(Web 管理端 + 后端服务 + 桌面客户端)",
"packageManager": "pnpm@11.8.0",
@@ -29,6 +29,7 @@
"db:switch:mysql": "node scripts/use-database.mjs mysql",
"db:switch:sqlite": "node scripts/use-database.mjs sqlite",
"verify:e2e": "node scripts/verify-e2e-isolated.mjs",
"verify:ai": "node scripts/verify-ai.mjs",
"verify:courseware": "node scripts/verify-courseware.mjs",
"verify:v14": "node scripts/verify-v14.mjs",
"verify:lifecycle": "node scripts/verify-lifecycle.mjs",
@@ -37,6 +38,8 @@
"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:panel-security": "node scripts/verify-panel-security.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",
+3 -2
View File
@@ -1,6 +1,6 @@
{
"name": "@classhelper/desktop-client",
"version": "1.4.3",
"version": "1.4.5",
"private": true,
"description": "ClassHelper EXE 客户端(Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存)",
"author": "Class Helper",
@@ -24,7 +24,8 @@
"pinia": "^4.0.3",
"socket.io-client": "^4.8.3",
"vue": "^3.5.42",
"vue-router": "^5.3.1"
"vue-router": "^5.3.1",
"@classhelper/ui": "workspace:*"
},
"devDependencies": {
"@types/node": "^22.20.2",
+2 -2
View File
@@ -84,8 +84,8 @@ function launchSmoke(extraEnv) {
child.kill();
resolve(124);
},
// 快速套件已包含本地 HTTP、校验下载和布局编辑;保留冷启动余量,单项断言不放宽。
mode === 'visual' ? 360_000 : 90_000,
// 快速套件包含两种布局的完整上下课时序、本地下载和编辑;总时限保留冷启动余量。
mode === 'visual' ? 360_000 : 120_000,
);
child.once('exit', (code) => {
clearTimeout(deadline);
@@ -37,8 +37,8 @@ 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));
function timeAt(time: string) {
const d = new Date(props.now);
const [h, m] = time.split(':').map(Number);
d.setHours(h!, m!, 0, 0);
const [h, m, s = 0] = time.split(':').map(Number);
d.setHours(h!, m!, s, 0);
return d.getTime();
}
/**
@@ -106,6 +106,7 @@ const remaining = computed(() =>
currentLesson.value ? Math.max(0, Math.ceil((timeAt(currentLesson.value.endTime) - props.now) / 1000)) : 0,
);
const hidden = computed(
// 临近下课仍使用真实时间点,不因提醒切换而替换课程组件。
() =>
!props.editing &&
((['notification', 'homework', 'call'].includes(props.node.kind) &&
@@ -256,6 +257,13 @@ const style = computed<CSSProperties>(() => {
: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>
@@ -352,8 +360,11 @@ const style = computed<CSSProperties>(() => {
transform-origin: left;
transition: transform 1s linear;
}
.schedule > .lesson-line + .lesson-line {
margin-top: 8px;
.schedule {
display: flex;
flex-direction: column;
align-items: center;
gap: 8px;
}
.separator > span {
display: block;
@@ -441,3 +452,5 @@ strong,
}
}
</style>
<style src="./lesson-ending.css"></style>
<style src="./lesson-ending.css"></style>
@@ -27,7 +27,10 @@ const props = defineProps<{
}>();
const scheme = computed(() => props.settings.schemes.find((s) => s.id === props.settings.activeSchemeId)!);
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);
watch(
lesson,
@@ -283,7 +286,15 @@ watch(
{ deep: true, flush: 'post' },
);
watch(
[fit, motion, expanded, lesson, () => props.appearance.radius, () => props.appearance.speed],
[
fit,
motion,
expanded,
lesson,
() => scheme.value.radius,
() => props.appearance.radius,
() => props.appearance.speed,
],
() => {
animate();
trackHit();
@@ -10,7 +10,7 @@ const props = defineProps<{
}>();
const root = ref<HTMLElement>();
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(
() =>
({
@@ -140,15 +140,14 @@ onUnmounted(() => {
aria-live="polite"
>
<div class="ci-lesson-info">
<span
v-if="reminder.kind === 'prepare' || reminder.kind === 'ending' || reminder.kind === 'in-class'"
class="ci-countdown"
>
<span v-if="reminder.kind === 'prepare' || reminder.kind === 'in-class'" class="ci-countdown">
{{ reminder.kind === 'prepare' ? '距上课还剩' : '距下课还剩' }}
<strong>{{ leftSeconds }}</strong>
秒
</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>
{{
@@ -158,6 +157,13 @@ onUnmounted(() => {
}}
</span>
<strong>{{ course || '今日课程已结束' }}</strong>
<span
v-if="reminder.kind === 'ending'"
class="lesson-ending-badge"
:aria-label="`距下课${leftSeconds}秒`"
>
-{{ leftSeconds }}
</span>
<small v-if="course">{{ time }}</small>
</span>
</div>
@@ -309,3 +315,4 @@ onUnmounted(() => {
transition: transform 50ms linear;
}
</style>
<style src="./lesson-ending.css"></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 IslandApp from './LayoutIslandApp.vue';
import { applyMotionTokens } from '../renderer/composables/motion.js';
@@ -19,8 +19,6 @@ export const IPC_CHANNELS = {
clearConfig: 'classhelper:config:clear',
appInfo: 'classhelper:app:info',
openExternal: 'classhelper:shell:open-external',
updateCheck: 'classhelper:update:check',
updateIgnore: 'classhelper:update:ignore',
getAutoLaunch: 'classhelper:app:get-autolaunch',
setAutoLaunch: 'classhelper:app:set-autolaunch',
openLogDir: 'classhelper:app:open-log-dir',
@@ -28,6 +26,3 @@ export const IPC_CHANNELS = {
clientStatus: 'classhelper:client:status',
clientBeatNow: 'classhelper:client:beat-now',
} as const;
/** 主进程 → 渲染进程的单向推送:有可用更新(同理,供 preload 与主进程共用) */
export const UPDATE_AVAILABLE_CHANNEL = 'classhelper:update:available';
+10 -1
View File
@@ -38,11 +38,12 @@ interface PersistedConfig {
homeworkPhrases?: string[];
/** 是否已看过初次启动引导(向后兼容:旧配置没有该字段视为没看过,首启弹一次) */
onboardingDone?: boolean;
onboardingVersion?: number;
/** 界面主题(向后兼容:旧配置没有该字段用浅色) */
theme?: 'light' | 'dark';
/** 主侧边栏是否折叠(向后兼容:旧配置没有该字段视为展开) */
sidebarCollapsed?: boolean;
/** 用户选择「忽略此版本」的版本号(向后兼容:旧配置没有该字段视为没忽略过任何版本) */
/** 旧版主动更新检查的兼容字段;统一云端下发更新后不再参与更新决策。 */
ignoredUpdateVersion?: string;
/** 本机设备标识(向后兼容:旧配置没有该字段时首次读取生成并落盘,之后永不变) */
deviceKey?: string;
@@ -69,6 +70,7 @@ const DEFAULT_CONFIG: PersistedConfig = {
homeworkBoard: { ...DEFAULT_HOMEWORK_BOARD },
homeworkPhrases: [...HOMEWORK_PHRASE_DEFAULTS],
onboardingDone: false,
onboardingVersion: 0,
theme: 'light',
sidebarCollapsed: false,
ignoredUpdateVersion: '',
@@ -210,6 +212,7 @@ function readPersistedFromDisk(): PersistedConfig {
homeworkBoard: normalizeHomeworkBoard(parsed.homeworkBoard),
homeworkPhrases: normalizeHomeworkPhrases(parsed.homeworkPhrases),
onboardingDone: parsed.onboardingDone === true,
onboardingVersion: Number.isInteger(parsed.onboardingVersion) ? Number(parsed.onboardingVersion) : 0,
theme: normalizeTheme(parsed.theme),
sidebarCollapsed: parsed.sidebarCollapsed === true,
ignoredUpdateVersion:
@@ -373,6 +376,7 @@ function toDesktopConfig(state: ConfigCache): DesktopStoredConfig {
homeworkBoard: normalizeHomeworkBoard(persisted.homeworkBoard),
homeworkPhrases: normalizeHomeworkPhrases(persisted.homeworkPhrases),
onboardingDone: persisted.onboardingDone === true,
onboardingVersion: persisted.onboardingVersion ?? 0,
theme: normalizeTheme(persisted.theme),
sidebarCollapsed: persisted.sidebarCollapsed === true,
ignoredUpdateVersion: persisted.ignoredUpdateVersion ?? '',
@@ -460,6 +464,11 @@ export function saveConfig(patch: Partial<DesktopStoredConfig>): DesktopStoredCo
if (patch.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) {
persisted.theme = normalizeTheme(patch.theme);
}
@@ -10,7 +10,6 @@ import { island, registerIslandIpc } from './island.js';
import { logger } from './logger.js';
import { runSmokeTest } from './smoke.js';
import { createTray, destroyTray, isTrayReady } from './tray.js';
import { scheduleStartupUpdateCheck } from './update.js';
// 主进程由 esbuild 打包为 CommonJS,因此这里可以直接使用 __dirname
// (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}`);
}
// 启动后自动查一次更新(延迟几秒,不跟首屏抢带宽);冒烟模式下自动跳过,见 main/update.ts
scheduleStartupUpdateCheck(() => mainWindow);
// 服务端统一下发:定时上报本机状态并领取「待执行命令 / 统一更新」(冒烟默认不上报)
startClientAgent();
-17
View File
@@ -9,12 +9,10 @@ import { island } from './island.js';
import { getIslandWeather } from './island-weather.js';
import { getUpdateProgress } from './auto-update.js';
import { app, BrowserWindow, ipcMain, shell } from 'electron';
import type { UpdateInfo } from '@classhelper/shared';
import { IPC_CHANNELS } from './channels.js';
import { beatNow, getClientAgentStatus } from './client-agent.js';
import { clearConfig, getConfig, getConfigPath, saveConfig } from './config.js';
import { logger } from './logger.js';
import { checkForUpdates, ignoreUpdateVersion } from './update.js';
import type { DesktopAppInfo, DesktopStoredConfig } from '../types/desktop.js';
// 通道名定义搬到了叶子模块 `channels.ts`(原因见那里的注释:preload 在沙箱里不能碰 node 内建模块);
@@ -65,21 +63,6 @@ export function registerIpcHandlers(): void {
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 => {
try {
+5 -1
View File
@@ -171,6 +171,7 @@ class IslandController {
private lessonTimer: ReturnType<typeof setInterval> | null = null;
private lessonTestTime: number | null = null;
private get lessonShowing(): boolean {
if (this.customLayout && this.lessonCue?.kind === 'ending') return false;
return Boolean(
this.lessonCue &&
!this.editingLayout &&
@@ -649,7 +650,10 @@ class IslandController {
return {
...this.state,
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],
};
}
@@ -265,7 +265,7 @@ export async function verifyLayoutSmoke(
await editor.webContents.executeJavaScript(`document.querySelector('[aria-label="新建方案"]').click()`);
await pause();
await editor.webContents.executeJavaScript(
`(() => { const input=document.querySelector('.el-message-box__input input'); input.value='组件方案验收';input.dispatchEvent(new Event('input',{bubbles:true}));document.querySelector('.el-message-box__btns .el-button--primary').click(); })()`,
`(() => { 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('新建方案没有保存');
@@ -274,7 +274,7 @@ export async function verifyLayoutSmoke(
);
await pause();
await editor.webContents.executeJavaScript(
`document.querySelector('.el-message-box__btns .el-button--primary').click()`,
`[...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()`);
@@ -284,14 +284,26 @@ export async function verifyLayoutSmoke(
);
await pause();
await editor.webContents.executeJavaScript(
`document.querySelector('.el-message-box__btns .el-button--primary').click()`,
`[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click()`,
);
await pause();
return (
const restored =
getConfig().islandLayout.schemes.length === 1 &&
getConfig().islandLayout.activeSchemeId === 'default' &&
getConfig().islandLayout.schemes[0]!.rows.length === 2
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()`);
@@ -329,10 +341,22 @@ export async function verifyLayoutSmoke(
);
await pause();
await editor.webContents.executeJavaScript(
`document.querySelector('.el-message-box__btns .el-button--primary').click()`,
`[...document.querySelectorAll('.el-message-box__btns .el-button--primary')].filter(e=>e.getBoundingClientRect().width>0).at(-1).click()`,
);
await pause();
return preserved && getConfig().islandLayout.schemes.length === 1;
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) {
await editor.webContents.executeJavaScript(`document.querySelector('.main').scrollTop=0`);
@@ -83,6 +83,59 @@ export async function runQuickSmoke(win: BrowserWindow): Promise<void> {
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 verifyLayoutSmoke(check);
await verifyCoursewareSmoke(check);
@@ -527,7 +527,7 @@ export async function verifyResidentSmoke(
await pause(700);
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 recorded: Array<{ at: number; image: Electron.NativeImage }> = [];
const start = Date.now();
@@ -642,17 +642,33 @@ export async function verifyResidentSmoke(
throw new Error('自动倒计时未切到本节下课');
}
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();
}
await setTime(9, 44);
await pause(700);
await pause(1100);
if (island.getState().lessonReminder?.kind !== 'ending')
throw new Error(layout + '下课倒数状态错误:' + JSON.stringify(island.getState().lessonReminder));
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 + '下课倒数未渲染');
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 setTime(9, 45);
island.setClassState({ inClass: false });
+4 -43
View File
@@ -17,7 +17,6 @@ import {
ISLAND_URGENT_SIZE,
} from './island.js';
import { destroyTray, getTrayState, isTrayReady } from './tray.js';
import { checkForUpdates, wasStartupCheckSkipped } from './update.js';
interface SmokeResult {
name: string;
@@ -3078,7 +3077,9 @@ async function runIslandChecks(
`${islandStateSummary()}`,
);
// 10.7) 视觉风格:纯黑 / 毛玻璃(亚克力)/ 主题色渐变,切换立即生效
// 消息使用实色底;先清空消息,单独验证用户设置的三种基础风格。
await drainIsland();
await sleep(260);
const probeStyle = async (style: IslandAppearance['style']): Promise<{ fill: string; stroke: string }> => {
island.setAppearance({ ...appearanceBefore, style });
await sleep(260);
@@ -3102,7 +3103,7 @@ async function runIslandChecks(
const glassStyle = await probeStyle('glass');
const tintedStyle = await probeStyle('tinted');
record(
'视觉风格切换立刻生效(纯黑 / 毛玻璃半透明 / 主题色)',
'无消息时视觉风格切换立刻生效(纯黑 / 毛玻璃半透明 / 主题色)',
blackStyle.fill === 'rgb(0, 0, 0)' &&
glassStyle.fill.startsWith('rgba(32, 32, 36') &&
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 ?? ''));
// 更新检查(新功能回归):主进程直连 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<{
ok: boolean;
-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;
}
+2 -11
View File
@@ -3,7 +3,7 @@ import type {
CoursewareTransfer,
} from '@classhelper/shared';
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 {
DesktopAppInfo,
@@ -12,7 +12,7 @@ import type {
IslandClassStatePayload,
IslandPushContext,
} from '../types/desktop.js';
import type { IslandNotification, UpdateInfo } from '@classhelper/shared';
import type { IslandNotification } from '@classhelper/shared';
/**
* 预加载脚本:在开启了 contextIsolation + sandbox 的前提下,
@@ -65,15 +65,6 @@ const bridge: DesktopBridge = {
getAppInfo: (): Promise<DesktopAppInfo> => ipcRenderer.invoke(IPC_CHANNELS.appInfo),
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 => {
ipcRenderer.send('island:push', payload);
},
+5 -55
View File
@@ -1,8 +1,6 @@
<script setup lang="ts">
import { h, onMounted, onUnmounted, ref } from 'vue';
import { onMounted, onUnmounted, ref } from 'vue';
import { useRouter } from 'vue-router';
import { ElButton, ElNotification } from 'element-plus';
import type { UpdateInfo } from '@classhelper/shared';
import {
replayMissedNotifications,
startIslandBridge,
@@ -13,6 +11,7 @@ import {
import OnboardingWelcome from './components/OnboardingWelcome.vue';
import { useAppStore } from './stores/app.js';
import { useAuthStore } from './stores/auth.js';
import { ONBOARDING_VERSION } from '@classhelper/ui';
import { useOnboardingStore } from './stores/onboarding.js';
import { useRealtimeStore } from './stores/realtime.js';
import { useUiStore } from './stores/ui.js';
@@ -27,56 +26,10 @@ const realtime = useRealtimeStore();
const booting = ref(true);
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)。
*
* **为什么订阅放在 App.vue**:与 `onUpdateAvailable` 同一条理由 —— App.vue 整个应用生命周期
* **为什么订阅放在 App.vue**:App.vue 整个应用生命周期
* 只挂载一次,而 `ClientLayout` 会随"登出 → 登录"反复挂载。而且恢复事件本身是"可达性由不可达
* 变为可达"的那一刻,一次会话里可能发生多次,处理器必须是**幂等**的(`replayMissedNotifications`
* 推完就清掉离线起点,重复触发时第二次读到空值、直接返回 0)。
@@ -117,19 +70,16 @@ onMounted(async () => {
// 离线期间收到的消息:可达性恢复的那一刻补弹到灵动岛(App.vue 常驻,所以每次恢复只跑一次)
appStore.onServerRecovered(handleServerRecovered);
// 启动自动检查发现新版本时由主进程推过来(订阅只挂一次,理由见 showUpdateAvailable)
window.desktop?.onUpdateAvailable?.(showUpdateAvailable);
if (auth.isAuthenticated) await router.replace('/schedule');
else await router.replace('/login');
// 初次启动引导:配置里没记「已看过」就自动弹一次(完成/跳过后由引导组件写入配置)。
// 引导按版本展示,完成或跳过后记住当前版本。
// 稍等一拍再弹:让登录页/主界面先渲染完,避免和启动过渡的收尾抢帧。
window.setTimeout(() => {
void window.desktop
?.getConfig()
.then((config) => {
if (config.onboardingDone !== true) onboarding.open();
if ((config.onboardingVersion ?? 0) < ONBOARDING_VERSION) onboarding.open();
})
.catch(() => undefined);
}, 400);
@@ -61,7 +61,10 @@ http.interceptors.response.use(
const status = error.response.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('登录状态已失效,请重新登录');
unauthorizedHandler();
} else {
@@ -67,8 +67,15 @@ export const homeworkApi = {
date?: string;
}): Promise<HomeworkDto[]> => api.get(API_PATHS.homeworks, params),
/** 哪些天有作业(日期选择器高亮) */
days: (params: { classId?: string; from?: string; to?: string; days?: number }): Promise<HomeworkDaysDto> =>
api.get(`${API_PATHS.homeworks}/days`, params),
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: {
classId: string;
@@ -88,8 +95,21 @@ export const homeworkApi = {
};
export const notificationApi = {
list: (params?: { classId?: string; unreadOnly?: boolean }): Promise<NotificationDto[]> =>
api.get(API_PATHS.notifications, params),
days: (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`),
// id 来自服务端或灵动岛(作业卡是本地合成的 `homework-…`),一律 encodeURIComponent:
// 否则含 `/` 或 `..` 的 id 会改变实际请求的路径
+12 -21
View File
@@ -885,14 +885,7 @@ export async function islandHomeworkSuppressionCheck(): Promise<SmokeCheckResult
}
}
/**
* 冒烟自检(不需要后端):**初次启动引导**。
*
* 冒烟每次都用全新配置目录(等于"首次启动"),因此引导必须自动弹出;
* 这里真实点击把它一步步走完,断言:遮罩关闭 + `onboardingDone` 已写入配置。
* 关闭判据用「元素从 DOM 消失」——引导是 v-if 自绘遮罩(特意不用 el-dialog,
* 避免"关闭后 DOM 残留在文档里"的误报,见 AGENTS §7 第 22 条)。
*/
/** 全新配置首次展示全屏引导,完成后保存版本标记。 */
export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
try {
// 引导在启动后延迟 ~400ms 弹出,这里轮询等它出现
@@ -908,7 +901,10 @@ export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
};
}
// 逐页「下一步」到最后一页再点「开始使用」(按钮由 data-action 标识,不依赖文案)
const guide = document.querySelector<HTMLElement>('.ch-guide')!;
const bounds = guide.getBoundingClientRect();
const fullscreen = Math.abs(bounds.width - innerWidth) < 2 && Math.abs(bounds.height - innerHeight) < 2;
const focused = guide.contains(document.activeElement);
const clicks: string[] = [];
for (let attempt = 0; attempt < 12; attempt += 1) {
const action = document.querySelector('.onboarding-welcome [data-action="finish"]') ? 'finish' : 'next';
@@ -928,10 +924,11 @@ export async function onboardingSelfTest(): Promise<SmokeCheckResult> {
}
const config = await window.desktop?.getConfig?.();
const done = config?.onboardingDone === true;
const { ONBOARDING_VERSION } = await import('@classhelper/ui');
const done = config?.onboardingDone === true && config.onboardingVersion === ONBOARDING_VERSION;
return {
ok: closed && done,
detail: `步骤点击=[${clicks.join(',')}] 已关闭=${closed} onboardingDone=${config?.onboardingDone ?? '-'}`,
ok: closed && done && fullscreen && focused,
detail: `步骤点击=[${clicks.join(',')}] 全屏=${fullscreen} 焦点=${focused} 已关闭=${closed} 引导版本=${config?.onboardingVersion ?? '-'}`,
};
} catch (error) {
return {
@@ -1171,18 +1168,12 @@ export async function aboutPageSelfTest(): Promise<SmokeCheckResult> {
const hasDiagnostics = text.includes('诊断信息');
const info = await window.desktop?.getAppInfo?.();
const hasConfigPath = Boolean(info?.configPath);
// 检查更新入口(新功能回归):关于页要有这一块,且按钮可点。
// 这里只断言"入口存在"——是否真有新版本取决于 GitHub,不该绑进冒烟(见 main/update.ts)
const updateBlock = document.querySelector('[data-test="update-check"]');
const updateButton = document.querySelector('[data-test="update-check-button"]');
const hasUpdateCheck = Boolean(document.querySelector('[data-test="update-check"]'));
await router.push('/schedule');
return {
ok: hasThanks && hasDiagnostics && hasConfigPath && Boolean(updateBlock) && Boolean(updateButton),
detail:
`鸣谢=${hasThanks} 诊断=${hasDiagnostics} configPath=${hasConfigPath ? '有' : '无'} ` +
`检查更新块=${updateBlock ? '有' : '无'} 按钮=${updateButton ? '有' : '无'}`,
ok: hasThanks && hasDiagnostics && hasConfigPath && !hasUpdateCheck,
detail: `鸣谢=${hasThanks} 诊断=${hasDiagnostics} configPath=${hasConfigPath ? '有' : '无'}`,
};
} catch (error) {
return {
@@ -52,7 +52,7 @@ const containers = ['group', 'stack', 'slide', 'rolling'] as const;
<el-input v-model="node.settings.countdownTitle" :maxlength="64" @change="emit('change')" />
</el-form-item>
<el-form-item label="目标日期">
<el-date-picker
<ch-date-picker
v-model="node.settings.targetDate"
type="date"
value-format="YYYY-MM-DD"
@@ -54,7 +54,7 @@ const container = computed(() => ['group', 'stack', 'slide', 'rolling'].includes
display: flex;
align-items: center;
flex-shrink: 0;
border-radius: 5px;
border-radius: var(--ch-radius-control);
}
.component-chip {
display: flex;
@@ -62,9 +62,9 @@ const container = computed(() => ['group', 'stack', 'slide', 'rolling'].includes
gap: 5px;
min-height: 36px;
padding: 5px 9px;
border: 1px solid transparent;
border-radius: 5px;
background: transparent;
border: 1px solid var(--ch-border);
border-radius: var(--ch-radius-control);
background: var(--ch-surface);
color: inherit;
font: inherit;
white-space: nowrap;
@@ -1,309 +1,59 @@
<script setup lang="ts">
import { computed, onUnmounted, ref, watch } from 'vue';
import { FullScreenGuide, ONBOARDING_VERSION } from '@classhelper/ui';
import { useOnboardingStore } from '../stores/onboarding.js';
/**
* 初次启动引导(六步向导)。
*
* - 首次启动自动弹出(App.vue 按 `onboardingDone` 判定);完成 / 跳过(右上角按钮 / Esc)
* 都算看过,由这里写入主进程配置,之后不再自动弹出。
* - 登录页与设置页的「使用引导」入口可随时重看(重看关闭时再写一次也无副作用)。
* - **用 v-if 自绘遮罩而不是 el-dialog**:关闭即从 DOM 卸载。冒烟断言"引导已关闭"时
* 不会踩 el-dialog「DOM 残留在文档里」的坑(AGENTS §7 第 22 条)。
* - 操作按钮用 `data-action` 标识(prev/next/finish/skip),冒烟点击不依赖按钮文案。
*/
import { BRAND_LOGO_URL } from '../config.js';
const onboarding = useOnboardingStore();
const steps = [
{
icon: 'School',
title: '欢迎使用 ClassHelper',
lines: [
'这台电脑将以「班级」的身份使用 ClassHelper:实时接收课表、作业、通知与成绩。',
'第一次使用,先花半分钟看看怎么开始。',
],
id: 'server',
title: '连接学校服务器',
text: '填写管理员提供的服务器地址,测试连接后继续。',
example: ['服务器地址', '测试连接', '连接成功'],
},
{
icon: 'Link',
title: '第一步 · 连接服务器',
lines: [
'在登录页填写老师或管理员提供的服务器地址(通常形如 http://192.168.x.x:4000)。',
'点「测试连接」确认可达;以后也能在「设置」里随时修改。',
],
id: 'login',
title: '登录班级',
text: '使用班级码和班级密码登录,这台设备将代表本班。',
example: ['班级码', '班级密码', '登录'],
},
{
icon: 'Key',
title: '第二步 · 登录班级',
lines: [
'使用班级码 + 班级密码登录(向老师或管理员索取)。',
'登录后这台设备就代表全班:作业完成、通知已读都会按全班记录,不需要每个学生单独登录。',
],
id: 'teaching',
title: '查看课表与作业',
text: '从菜单切换页面,用日历查找记录;断网时可查看已缓存的内容。',
example: ['今日课表', '作业看板', '日期下方的圆点 ·'],
},
{
icon: 'Calendar',
title: '登录之后',
lines: [
'左侧菜单切换「课表 / 作业 / 通知 / 成绩」四个页面,作业支持看板全屏展示。',
'断网时自动显示最近同步的缓存数据,联网后自动更新。',
],
id: 'files',
title: '接收通知与课件',
text: '新内容自动同步,课件下载后由你选择如何打开。',
example: ['班级通知', '课件传输进度', '打开所在文件夹'],
},
{
icon: 'Bell',
title: '灵动岛提醒',
lines: [
'屏幕上方会有一条「灵动岛」浮窗:新通知、叫人、作业都会在那里弹出。',
'上课时段自动隐藏、下课自动弹出;外观与位置可在「设置 → 灵动岛」调整。',
],
id: 'island',
title: '选择灵动岛模式',
text: '经典模式自动呈现提醒;常驻模式先显示消息数量,由你展开查看。',
example: ['经典模式', '自定义常驻模式', '设置 → 灵动岛'],
},
{
icon: 'CircleCheckFilled',
id: 'settings',
title: '准备好了',
lines: [
'按上面的步骤登录就可以开始使用了。',
'侧边栏「设置」分组里有通用、外观(深色模式)、灵动岛等页面;这份引导可以在登录页或「设置 → 通用 → 使用引导」随时重看。',
],
text: '在设置中调整外观和关怀模式,也可以随时重看引导。',
example: ['通用设置', '外观', '使用引导'],
},
];
const index = ref(0);
const current = computed(() => steps[index.value] ?? steps[0]);
const isFirst = computed(() => index.value === 0);
const isLast = computed(() => index.value === steps.length - 1);
/** 每次打开都从第一步开始(重看入口也走完整流程) */
watch(
() => onboarding.visible,
(visible) => {
if (visible) index.value = 0;
},
);
function goNext(): void {
if (isLast.value) finish();
else index.value += 1;
}
function goPrev(): void {
if (!isFirst.value) index.value -= 1;
}
/** 完成 / 跳过统一走这里:记「已看过」并关闭(重看时重复写一次无副作用) */
function finish(): void {
const bridge = window.desktop;
// 桥接不可用(浏览器调试)也要能正常关掉引导
if (!bridge) {
async function finish(): Promise<void> {
try {
await window.desktop?.saveConfig({ onboardingDone: true, onboardingVersion: ONBOARDING_VERSION });
} finally {
onboarding.close();
return;
}
void bridge
.saveConfig({ onboardingDone: true })
.then(() => onboarding.close())
.catch(() => onboarding.close());
}
function onKeydown(event: KeyboardEvent): void {
if (onboarding.visible && event.key === 'Escape') finish();
}
if (typeof window !== 'undefined') {
window.addEventListener('keydown', onKeydown);
}
onUnmounted(() => {
window.removeEventListener('keydown', onKeydown);
});
</script>
<template>
<Transition name="onboarding-fade">
<div
v-if="onboarding.visible"
class="onboarding-mask"
role="dialog"
aria-modal="true"
aria-label="初次启动引导"
>
<div class="onboarding-card onboarding-welcome">
<div class="onboarding-head">
<span class="onboarding-logo">
<el-icon :size="18"><School /></el-icon>
</span>
<div class="onboarding-heading">
<h2 class="onboarding-title">ClassHelper</h2>
<p class="onboarding-sub">初次启动引导 · 第 {{ index + 1 }} / {{ steps.length }} 步</p>
</div>
<el-button link class="onboarding-skip" data-action="skip" @click="finish">跳过引导</el-button>
</div>
<div class="onboarding-body">
<span class="onboarding-icon">
<el-icon :size="30"><component :is="current.icon" /></el-icon>
</span>
<h3 class="onboarding-step-title">{{ current.title }}</h3>
<p v-for="(line, lineIndex) in current.lines" :key="lineIndex" class="onboarding-line">
{{ line }}
</p>
</div>
<div class="onboarding-foot">
<div class="onboarding-dots">
<span
v-for="(step, dotIndex) in steps"
:key="dotIndex"
class="dot"
:class="{ active: dotIndex === index }"
<FullScreenGuide
:model-value="onboarding.visible"
:steps="steps"
:brand-logo="BRAND_LOGO_URL"
@finish="finish"
/>
</div>
<div class="onboarding-actions">
<el-button v-if="!isFirst" data-action="prev" @click="goPrev">上一步</el-button>
<el-button v-if="!isLast" type="primary" data-action="next" @click="goNext">下一步</el-button>
<el-button v-else type="primary" data-action="finish" @click="finish">开始使用</el-button>
</div>
</div>
</div>
</div>
</Transition>
</template>
<style scoped>
.onboarding-mask {
position: fixed;
inset: 0;
z-index: 3000;
display: flex;
align-items: center;
justify-content: center;
padding: 24px;
background: rgba(15, 30, 50, 0.55);
}
.onboarding-card {
width: 520px;
max-width: 92vw;
max-height: 86vh;
overflow-y: auto;
background: var(--ch-layer-solid);
border-radius: 16px;
padding: 22px 24px 18px;
box-shadow: 0 24px 64px rgba(15, 30, 50, 0.35);
}
.onboarding-head {
display: flex;
align-items: center;
gap: 10px;
}
.onboarding-logo {
display: inline-flex;
align-items: center;
justify-content: center;
width: 34px;
height: 34px;
border-radius: 9px;
color: #fff;
background: linear-gradient(135deg, var(--ch-accent) 0%, #4d94d1 100%);
}
.onboarding-heading {
flex: 1;
min-width: 0;
}
.onboarding-title {
margin: 0;
font-size: 15px;
line-height: 1.3;
}
.onboarding-sub {
margin: 2px 0 0;
font-size: 12px;
color: var(--ch-text-tertiary);
}
.onboarding-body {
display: flex;
flex-direction: column;
align-items: flex-start;
padding: 18px 4px 6px;
}
.onboarding-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 58px;
height: 58px;
border-radius: 16px;
margin-bottom: 14px;
color: var(--ch-accent);
background: var(--ch-accent-soft);
}
.onboarding-step-title {
margin: 0 0 10px;
font-size: 18px;
}
.onboarding-line {
margin: 0 0 8px;
font-size: 13px;
line-height: 1.8;
color: var(--ch-text-secondary);
}
.onboarding-foot {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
margin-top: 14px;
padding-top: 14px;
border-top: 1px solid var(--ch-divider);
}
.onboarding-dots {
display: flex;
align-items: center;
gap: 6px;
}
.dot {
width: 7px;
height: 7px;
border-radius: 999px;
background: var(--ch-border-strong);
transition: all 0.2s ease;
}
.dot.active {
width: 20px;
background: var(--ch-accent);
}
.onboarding-actions {
display: flex;
align-items: center;
gap: 8px;
}
/* 进出场:淡入 + 轻微上浮,跟随系统"动画"开关无强依赖 */
.onboarding-fade-enter-active,
.onboarding-fade-leave-active {
transition: opacity 0.22s ease;
}
.onboarding-fade-enter-active .onboarding-card,
.onboarding-fade-leave-active .onboarding-card {
transition: transform 0.22s ease;
}
.onboarding-fade-enter-from,
.onboarding-fade-leave-to {
opacity: 0;
}
.onboarding-fade-enter-from .onboarding-card,
.onboarding-fade-leave-to .onboarding-card {
transform: translateY(10px) scale(0.98);
}
</style>
@@ -11,6 +11,8 @@ import router from './router/index.js';
import { registerAppIcons } from './icons.js';
import { applyMotionTokens } from './composables/motion.js';
import './styles/index.css';
import { registerSharedUi } from '@classhelper/ui';
import '@classhelper/ui/theme.css';
const app = createApp(App);
@@ -20,6 +22,7 @@ registerAppIcons(app);
app.use(createPinia());
app.use(router);
app.use(ElementPlus, { locale: zhCn });
registerSharedUi(app);
// 冒烟验证模式:把缓存自检钩子暴露给主进程调用(正常运行时不存在)。
//
@@ -1,14 +1,7 @@
import { ref } from 'vue';
import { defineStore } from 'pinia';
/**
* 初次启动引导的显示状态。
*
* 首次启动由 App.vue 按「配置里是否记过 onboardingDone」自动弹出;
* 登录页与设置页的「使用引导」入口调用 open() 随时重看。
* 单独一个 store 而不是组件内部 ref:触发入口(登录页 / 设置页)与
* 渲染点(App.vue 顶层)分处两棵互不相干的子树。
*/
/** App.vue 按引导版本自动展示;登录页和设置页可随时重看。 */
export const useOnboardingStore = defineStore('onboarding', () => {
const visible = ref(false);
@@ -6,7 +6,7 @@
min-width: 0;
color: var(--ch-text);
padding: 12px 24px 16px;
background: var(--editor-background, var(--ch-bg));
background: var(--ch-bg);
}
:global(.main:has(> .island-editor-page)) {
display: flex;
@@ -16,11 +16,6 @@
.island-editor-page > * {
flex-shrink: 0;
}
:global(html.dark) .island-editor-page {
--editor-background: #262626;
--editor-divider: #3a3a3a;
--editor-card: #2c2c2c;
}
.editor-actions {
display: flex;
align-items: center;
@@ -77,7 +72,8 @@
}
.scheme-controls :deep(.el-select__wrapper) {
min-height: 38px;
background: var(--ch-card-subtle);
background: var(--ch-surface);
border-radius: var(--ch-radius-control);
}
.icon-button {
width: 34px;
@@ -139,7 +135,7 @@
display: flex;
align-items: center;
min-height: 54px;
border-radius: 6px;
border-radius: var(--ch-radius-control);
gap: 12px;
padding: 4px;
border: 1px solid transparent;
@@ -180,7 +176,7 @@
background: transparent;
color: var(--ch-text-tertiary);
padding: 10px 24px;
border-radius: 5px;
border-radius: var(--ch-radius-control);
font: inherit;
font-size: 12px;
cursor: pointer;
@@ -251,7 +247,7 @@
font-size: 12px;
}
.component-library {
border-top: 6px solid var(--editor-divider, var(--ch-divider));
border-top: 1px solid var(--ch-border);
margin: 0 -24px;
padding: 14px 24px 24px;
flex: 1 0 auto;
@@ -288,9 +284,9 @@
text-align: left;
min-height: 76px;
padding: 10px 8px;
border: 1px solid transparent;
border-radius: 6px;
background: transparent;
border: 1px solid var(--ch-border);
border-radius: var(--ch-radius-control);
background: var(--ch-surface);
color: inherit;
font: inherit;
cursor: grab;
@@ -332,51 +328,6 @@
font-size: calc(14px * var(--ch-font-scale));
line-height: 1.5;
}
.message-library-title {
color: var(--ch-text-tertiary);
font-size: 12px;
font-weight: 400;
margin: 20px 8px 4px;
}
.message-options .library-item {
min-height: 64px;
}
.message-options .library-item strong {
font-size: 15px;
}
.message-options .library-item > svg {
width: 26px;
height: 26px;
flex-basis: 26px;
}
.editor-tip {
display: flex;
align-items: center;
gap: 14px;
padding: 12px 16px;
min-height: 60px;
border: 1px solid var(--ch-border-strong);
border-radius: 5px;
background: var(--editor-card, var(--ch-card-subtle));
font-size: 14px;
}
.editor-tip > span {
flex: 1;
line-height: 1.6;
}
.tip-icon {
color: var(--ch-accent);
font-size: 22px;
}
.dismiss-tip {
border: 0;
color: var(--ch-text);
background: transparent;
font-size: 26px;
cursor: pointer;
margin-left: auto;
padding: 0 8px;
}
.drag-ghost {
position: fixed;
z-index: 10000;
@@ -392,6 +343,22 @@
.inspector-tabs {
margin-bottom: 20px;
}
:global(.island-inspector) {
color: var(--ch-text);
background: var(--ch-surface);
}
:global(.island-inspector .el-drawer__header) {
color: var(--ch-text);
}
:global(.island-inspector .el-input-number),
:global(.island-inspector .el-select) {
width: 100%;
}
:global(.island-inspector .el-input__wrapper),
:global(.island-inspector .el-select__wrapper) {
background: var(--ch-surface);
border-radius: var(--ch-radius-control);
}
.row-actions {
display: flex;
gap: 6px;
@@ -426,9 +393,6 @@
.scheme-tools {
flex: 1 1 100%;
}
.editor-tip {
flex-wrap: wrap;
}
.preview-toolbar .hint {
display: none;
}
@@ -1,4 +1,5 @@
<script setup lang="ts">
import { countDates, CoursewareFolders } from '@classhelper/ui';
import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
import { ElMessage } from 'element-plus';
import {
@@ -14,45 +15,47 @@ import { useRealtimeStore } from '../stores/realtime.js';
const realtime = useRealtimeStore();
const localItems = ref<CoursewareDto[]>([]),
library = ref<'shared' | 'local'>('shared'),
teacher = ref(''),
archive = ref('');
teacher = ref('');
const source = computed(() => (library.value === 'local' ? localItems.value : items.value));
const teachers = computed(() => [...new Set(source.value.map((item) => item.teacher.name))]);
const archiveFolders = computed(() => [
...new Set(
source.value
.filter((item) => !teacher.value || item.teacher.name === teacher.value)
.map((item) => item.archivePath?.split('/').slice(0, -1).join('/') || item.archiveDate),
),
]);
async function refreshLocal() {
localItems.value = (await window.desktop?.listLocalCourseware()) || [];
}
// 两个来源的教师与目录不通用,切换时清空,避免看到空列表却找不到原因。
watch(library, () => {
teacher.value = '';
archive.value = '';
folderPath.value = '';
folderOwner.value = '';
});
const items = ref<CoursewareDto[]>([]),
loading = ref(false),
offline = ref(false),
error = ref('');
const folderPath = ref(''),
folderOwner = ref(''),
grouping = ref('folder');
const query = ref(''),
category = ref(''),
date = ref(''),
busy = ref<string[]>([]),
transfer = ref<CoursewareTransfer | null>(null);
const filtered = computed(() =>
const dateSource = computed(() =>
source.value.filter(
(item) =>
(!query.value || `${item.name} ${item.teacher.name}`.includes(query.value)) &&
(grouping.value !== 'folder' ||
((item.folderPath || '') === folderPath.value &&
(folderOwner.value
? item.teacher.id === folderOwner.value
: new Set(items.value.map((i) => i.teacher.id)).size <= 1))) &&
(!category.value || item.category === category.value) &&
(!teacher.value || item.teacher.name === teacher.value) &&
(!archive.value ||
(item.archivePath?.startsWith(archive.value + '/') ?? item.archiveDate === archive.value)) &&
(!date.value || item.archiveDate === date.value),
(!teacher.value || item.teacher.name === teacher.value),
),
);
const dateMarks = computed(() => countDates(dateSource.value, (item) => item.archiveDate));
const filtered = computed(() =>
dateSource.value.filter((item) => !date.value || item.archiveDate === date.value),
);
let disposed = false;
async function refresh() {
await refreshLocal();
@@ -119,6 +122,16 @@ onUnmounted(() => {
</script>
<template>
<div class="page courseware-page">
<el-radio-group v-model="grouping">
<el-radio-button value="folder">文件夹</el-radio-button>
<el-radio-button value="date">日期归档</el-radio-button>
</el-radio-group>
<CoursewareFolders
v-if="grouping === 'folder'"
v-model:path="folderPath"
v-model:owner="folderOwner"
:items="source"
/>
<header class="page-header">
<div>
<h2 class="page-title">课件</h2>
@@ -153,17 +166,14 @@ onUnmounted(() => {
<el-radio-button value="shared">班级共享</el-radio-button>
<el-radio-button value="local">本机归档</el-radio-button>
</el-radio-group>
<el-select v-model="teacher" clearable placeholder="全部教师" @change="archive = ''">
<el-select v-model="teacher" clearable placeholder="全部教师">
<el-option v-for="name in teachers" :key="name" :label="name" :value="name" />
</el-select>
<el-select v-model="archive" clearable filterable placeholder="年 / 月 / 日 / 时间">
<el-option v-for="folder in archiveFolders" :key="folder" :label="folder" :value="folder" />
</el-select>
<el-input v-model="query" clearable placeholder="搜索课件或教师" />
<el-select v-model="category" clearable placeholder="全部类型">
<el-option v-for="(label, key) in COURSEWARE_CATEGORIES" :key="key" :label="label" :value="key" />
</el-select>
<el-date-picker v-model="date" value-format="YYYY-MM-DD" placeholder="归档日期" />
<ch-date-picker v-model="date" :marks="dateMarks" value-format="YYYY-MM-DD" placeholder="归档日期" />
</div>
<el-card shadow="never" class="table-card" v-loading="loading">
<el-table
@@ -1,4 +1,6 @@
<script setup lang="ts">
import { getCacheScope } from '../cache/scope.js';
import type { CalendarRange } from '@classhelper/ui';
import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue';
import { useRoute, useRouter } from 'vue-router';
import { ElMessage } from 'element-plus';
@@ -60,19 +62,13 @@ const selectedDate = ref(
? route.query.date
: dayKeyLocal(new Date()),
);
/** 有作业的日期(日期选择器高亮):来自 GET /homeworks/days */
const dayMarks = ref<Map<string, number>>(new Map());
const calendarRevision = ref(0);
/** 录入作业的科目下拉 */
const courses = ref<CourseDto[]>([]);
/** 选中的是否就是今天(标题与按钮文案用) */
const isToday = computed(() => selectedDate.value === dayKeyLocal(now.value));
/** 日期选择器:给有作业的日期加高亮类 */
function dayCellClass(date: Date): string {
return dayMarks.value.has(dayKeyLocal(date)) ? 'day-has-homework' : '';
}
async function selectDate(value: string | null): Promise<void> {
if (!value || !isDayKey(value)) return;
selectedDate.value = value;
@@ -279,6 +275,7 @@ function onResize(): void {
/* ------------------------------------------------------------ 数据加载 */
async function loadHomework(): Promise<void> {
calendarRevision.value++;
loading.value = true;
try {
const classId = auth.classId ?? undefined;
@@ -294,7 +291,6 @@ async function loadHomework(): Promise<void> {
fromCache.value = result.fromCache;
updatedAt.value = result.updatedAt;
if (!result.fromCache) appStore.markSynced();
void loadDayMarks(classId);
if (current.value) {
current.value = homeworks.value.find((item) => item.id === current.value?.id) ?? current.value;
}
@@ -304,22 +300,15 @@ async function loadHomework(): Promise<void> {
}
}
/**
* 拉取"哪些天有作业"(日期选择器高亮)。
*
* 范围取当前查看日期前后各 45 天:教室电脑上翻月份也能看到有作业的日子。
*/
async function loadDayMarks(classId: string | undefined): Promise<void> {
try {
const from = shiftDayKey(selectedDate.value, -45);
const to = shiftDayKey(selectedDate.value, 45);
const result = await homeworkApi.days({ classId, from, to });
dayMarks.value = new Map(result.days.map((item) => [item.date, item.count]));
} catch {
// 离线/失败时保留上一次的高亮,不打断展示
}
async function calendarDays(range: CalendarRange) {
const result = await fetchWithCache(
'homeworks',
`days:${JSON.stringify(range)}`,
() => homeworkApi.days({ ...range, classId: auth.classId || undefined }),
{ days: [] as { date: string; count: number }[] },
);
return result.data.days;
}
/** 科目下拉(录入作业时可选) */
async function loadCourses(): Promise<void> {
if (!auth.classId) return;
@@ -569,15 +558,19 @@ onUnmounted(() => {
<el-button-group>
<el-button :icon="'ArrowLeft'" @click="shiftDate(-1)">前一天</el-button>
<el-button :disabled="isToday" @click="selectDate(dayKeyLocal(now))">今天</el-button>
<el-button @click="shiftDate(1)">后一天<el-icon class="ml-4"><ArrowRight /></el-icon></el-button>
<el-button @click="shiftDate(1)">
后一天
<el-icon class="ml-4"><ArrowRight /></el-icon>
</el-button>
</el-button-group>
<el-date-picker
<ch-date-picker
:model-value="selectedDate"
type="date"
value-format="YYYY-MM-DD"
placeholder="选择日期"
class="day-picker"
:cell-class-name="dayCellClass"
:load-marks="calendarDays"
:scope-key="JSON.stringify([getCacheScope(), selectedDate, calendarRevision])"
@update:model-value="(value: string | null) => selectDate(value)"
/>
<el-radio-group v-model="viewMode" @change="saveBoardSettings">
@@ -765,11 +758,12 @@ onUnmounted(() => {
<el-dialog v-model="createVisible" title="录入作业" width="620px">
<el-form label-width="90px">
<el-form-item label="所属日期">
<el-date-picker
<ch-date-picker
:model-value="selectedDate"
type="date"
value-format="YYYY-MM-DD"
:cell-class-name="dayCellClass"
:load-marks="calendarDays"
:scope-key="JSON.stringify([getCacheScope(), calendarRevision])"
@update:model-value="(value: string | null) => selectDate(value)"
/>
<span class="text-muted ml-8">默认就是当前正在查看的这一天</span>
@@ -810,7 +804,9 @@ onUnmounted(() => {
>
{{ item }}
</el-tag>
<span class="text-muted">点一下追加到「{{ lastFocused === 'title' ? '标题' : '作业要求' }}」</span>
<span class="text-muted">
点一下追加到「{{ lastFocused === 'title' ? '标题' : '作业要求' }}」
</span>
</div>
</el-form-item>
</el-form>
@@ -880,19 +876,6 @@ onUnmounted(() => {
</template>
<style scoped>
/* 日期选择器:有作业的日子加一个圆点,翻月份时一眼看出哪天有作业 */
:deep(.day-has-homework .el-date-table-cell__text)::after {
content: '';
position: absolute;
left: 50%;
bottom: 2px;
width: 4px;
height: 4px;
margin-left: -2px;
border-radius: 50%;
background: currentColor;
}
.day-picker {
width: 168px;
}
@@ -1,5 +1,11 @@
<script setup lang="ts">
import { computed, onMounted, onUnmounted, ref } from 'vue';
import { notificationApi } from '../api/index.js';
import { fetchWithCache } from '../cache/index.js';
import { getCacheScope } from '../cache/scope.js';
import { useAuthStore } from '../stores/auth.js';
import type { CalendarRange } from '@classhelper/ui';
import { countDates } from '@classhelper/ui';
import { computed, onMounted, onUnmounted, ref, watch } from 'vue';
import { ElMessage } from 'element-plus';
import {
NOTIFICATION_PRIORITIES,
@@ -22,21 +28,70 @@ const filter = ref<'all' | 'unread'>('all');
const detailVisible = ref(false);
const current = ref<NotificationDto | null>(null);
const marking = ref(false);
const auth = useAuthStore();
const calendarRevision = ref(0);
const dayItems = ref<NotificationDto[] | null>(null);
let calendarRequest = 0,
disposed = false;
async function calendarDays(range: CalendarRange) {
const params = {
...range,
classId: auth.classId || undefined,
createdBy: creatorFilter.value || undefined,
priority: priorityFilter.value || undefined,
unreadOnly: filter.value === 'unread',
};
const result = await fetchWithCache(
'notifications',
'days:' + JSON.stringify(params),
() => notificationApi.days(params),
{ days: dateMarks.value },
);
return result.data.days;
}
async function loadDay(): Promise<void> {
const request = ++calendarRequest,
scope = getCacheScope();
if (!dayFilter.value) {
dayItems.value = null;
return;
}
const params = {
date: dayFilter.value,
classId: auth.classId || undefined,
createdBy: creatorFilter.value || undefined,
priority: priorityFilter.value || undefined,
unreadOnly: filter.value === 'unread',
};
const fallback = store.items.filter((item) => assignDay(item) === params.date);
dayItems.value = [];
const result = await fetchWithCache<NotificationDto[]>(
'notifications',
'date:' + JSON.stringify(params),
() => notificationApi.list(params),
fallback,
);
if (!disposed && request === calendarRequest && scope === getCacheScope()) dayItems.value = result.data;
}
const visibleItems = computed(() =>
filter.value === 'unread' ? store.items.filter((item) => !item.read) : store.items,
filter.value === 'unread'
? (dayItems.value ?? store.items).filter((item) => !item.read)
: (dayItems.value ?? store.items),
);
/* ------------------------------------------------------- 按天归档 / 按发布人 / 按类型 */
/**
* 三个筛选都在**已加载的列表**上做,不再请求服务端:
* 客户端是离线优先的(AGENTS.md 的现行工程约定),断网回退缓存时归档功能必须照常可用。
* 口径与服务端一致:按 `assignDate`(本地日期)分组 —— 用 createdAt 的 UTC 切片会把晚上
* 发出来的通知算到第二天(AGENTS.md 的现行工程约定)。
*/
watch(
() => store.items,
() => {
calendarRevision.value++;
},
);
const dayFilter = ref('');
const creatorFilter = ref('');
const priorityFilter = ref('');
watch([dayFilter, creatorFilter, priorityFilter, filter, () => store.items], () => {
void loadDay();
});
/**
* 一条通知归到哪一天。
@@ -47,16 +102,17 @@ function assignDay(item: NotificationDto): string {
return item.assignDate || dayKeyLocal(new Date(item.createdAt));
}
const dayOptions = computed(() => {
const map = new Map<string, number>();
for (const item of store.items) {
const day = assignDay(item);
map.set(day, (map.get(day) ?? 0) + 1);
}
return [...map.entries()]
.sort((a, b) => b[0].localeCompare(a[0]))
.map(([date, count]) => ({ date, count }));
});
const dateMarks = computed(() =>
countDates(
store.items.filter(
(item) =>
(filter.value !== 'unread' || !item.read) &&
(!creatorFilter.value || item.createdBy === creatorFilter.value) &&
(!priorityFilter.value || item.priority === priorityFilter.value),
),
assignDay,
),
);
const creatorOptions = computed(() => {
const map = new Map<string, { name: string; count: number }>();
@@ -117,6 +173,7 @@ async function markRead(item: NotificationDto): Promise<void> {
marking.value = true;
try {
await store.markRead(item.id);
item.read = true;
if (current.value?.id === item.id) current.value = { ...item, read: true };
} catch (error) {
ElMessage.error(error instanceof Error ? error.message : '标记已读失败');
@@ -147,6 +204,8 @@ onMounted(async () => {
});
onUnmounted(() => {
disposed = true;
++calendarRequest;
// store 是全局的,这里无需清理;保留钩子以便将来取消订阅
});
</script>
@@ -175,16 +234,14 @@ onUnmounted(() => {
</div>
<el-card v-loading="store.loading" shadow="never">
<!-- 按天归档 + 按发布人 + 按类型;都在本地已加载的列表上筛(离线也能用) -->
<div class="notice-filters">
<el-select v-model="dayFilter" placeholder="按天归档" clearable size="small" style="width: 150px">
<el-option
v-for="item in dayOptions"
:key="item.date"
:label="`${item.date}(${item.count})`"
:value="item.date"
<ch-date-picker
v-model="dayFilter"
:load-marks="calendarDays"
:scope-key="JSON.stringify([creatorFilter, priorityFilter, filter, calendarRevision])"
placeholder="日期"
clearable
/>
</el-select>
<el-select
v-model="creatorFilter"
placeholder="全部发布人"
@@ -1,14 +1,12 @@
<script setup lang="ts">
import UpdateProgress from '../../components/UpdateProgress.vue';
import { onMounted, ref } from 'vue';
import { ElMessage } from 'element-plus';
import type { UpdateInfo } from '@classhelper/shared';
import type { DesktopAppInfo } from '../../../types/desktop.js';
import { useAppStore } from '../../stores/app.js';
/**
* 关于(ClassIsland 同款折叠卡片式):
* 应用信息(版本/运行时/常用链接/检查更新)→ 诊断信息(排查问题用)→ 鸣谢。
* 应用信息(版本/运行时/常用链接)→ 诊断信息(排查问题用)→ 鸣谢。
* 所有外链走主进程 openExternal(只放行 http/https,见 main/ipc.ts 的白名单)。
*/
const appStore = useAppStore();
@@ -17,10 +15,6 @@ const appInfo = ref<DesktopAppInfo | null>(null);
/** 折叠面板默认展开第一项(应用信息),诊断信息默认收起 */
const expandedNames = ref(['app']);
/** 检查更新:结果由主进程直连 GitHub 得到(见 main/update.ts) */
const checking = ref(false);
const updateInfo = ref<UpdateInfo | null>(null);
const PROJECT_URL = 'https://github.com/LoveChengke/ClassHelper';
const ISSUES_URL = 'https://github.com/LoveChengke/ClassHelper/issues';
@@ -38,44 +32,19 @@ async function openExternal(url: string): Promise<void> {
window.open(url, '_blank');
}
/**
* 检查更新。
*
* @param force true = 用户主动点击(绕过主进程缓存);false = 进页面时带出启动自动检查的结果
*/
async function checkUpdate(force: boolean): Promise<void> {
if (!window.desktop?.checkForUpdates) return;
checking.value = true;
try {
updateInfo.value = await window.desktop.checkForUpdates(force);
} finally {
checking.value = false;
}
}
/** 忽略这个版本:写进配置,启动自动检查不再提示它 */
async function ignoreVersion(): Promise<void> {
const version = updateInfo.value?.latestVersion;
if (!version) return;
await window.desktop?.ignoreUpdateVersion(version);
ElMessage.success(`已忽略 v${version} 的更新提示`);
}
onMounted(async () => {
if (!window.desktop) return;
appInfo.value = await window.desktop.getAppInfo().catch(() => null);
// 带出启动自动检查的结果(命中主进程缓存,不会再发一次请求)
void checkUpdate(false);
});
</script>
<template>
<div class="page">
<UpdateProgress />
<p class="text-muted">客户端更新由管理端统一下发。</p>
<div class="page-header">
<div>
<h2 class="page-title">关于</h2>
<p class="page-subtitle">版本、诊断信息与鸣谢</p>
</div>
</div>
@@ -108,51 +77,6 @@ onMounted(async () => {
</el-descriptions-item>
<el-descriptions-item label="平台">{{ appInfo?.platform ?? '-' }}</el-descriptions-item>
</el-descriptions>
<!-- 检查更新:直连 GitHub 看最新的 Release 是不是比本机新 -->
<div class="about-update" data-test="update-check">
<div class="about-update-head">
<span class="about-update-label">检查更新</span>
<el-button
size="small"
:loading="checking"
data-test="update-check-button"
@click="checkUpdate(true)"
>
检查更新
</el-button>
</div>
<div class="about-update-body">
<template v-if="checking">正在检查…</template>
<template v-else-if="!updateInfo">尚未检查</template>
<template v-else-if="!updateInfo.ok">
<!-- 教室机器没有外网是常态,这里只是"查不到",不是错误 -->
<span class="about-update-muted">{{ updateInfo.error ?? '暂时无法检查更新' }}</span>
</template>
<template v-else-if="updateInfo.hasUpdate">
<el-tag size="small" type="success" effect="light">
发现新版本 v{{ updateInfo.latestVersion }}
</el-tag>
<span class="about-update-muted">当前 v{{ updateInfo.currentVersion }}</span>
<el-button
link
type="primary"
size="small"
data-test="update-download"
@click="openExternal(updateInfo.releaseUrl)"
>
前往下载
</el-button>
<el-button link size="small" @click="ignoreVersion">忽略此版本</el-button>
</template>
<template v-else>
<el-tag size="small" type="info" effect="plain">已是最新版本</el-tag>
<span class="about-update-muted">
v{{ updateInfo.currentVersion }} · {{ updateInfo.latestVersion }}
</span>
</template>
</div>
</div>
</div>
</el-collapse-item>
@@ -220,7 +144,7 @@ onMounted(async () => {
}
.about-extra {
margin-left: auto;
margin-left: 12px;
margin-right: 12px;
font-size: 12px;
font-weight: 400;
@@ -249,55 +173,4 @@ onMounted(async () => {
color: var(--ch-text-secondary);
margin-right: 4px;
}
/* 检查更新:颜色一律走 --ch-* 变量(深色主题下不能写死浅色底/深色字) */
.about-update {
margin-top: 12px;
padding: 10px 12px;
border: 1px solid var(--ch-border);
border-radius: var(--ch-radius-card);
background: var(--ch-layer-alt);
}
.about-update-head {
display: flex;
align-items: center;
justify-content: space-between;
gap: 8px;
}
.about-update-label {
font-size: 12.5px;
font-weight: 600;
color: var(--ch-text-secondary);
}
.about-update-body {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 8px;
margin-top: 8px;
font-size: 12.5px;
color: var(--ch-text);
}
.about-update-muted {
color: var(--ch-text-tertiary);
}
.about-thanks {
margin: 0;
padding-left: 18px;
line-height: 2;
font-size: 12.5px;
color: var(--ch-text-secondary);
}
.about-quote {
margin: 18px 0 4px;
text-align: center;
font-size: 12px;
color: var(--ch-text-tertiary);
}
</style>
@@ -27,7 +27,6 @@ async function logout(): Promise<void> {
<div class="page-header">
<div>
<h2 class="page-title">账号</h2>
<p class="page-subtitle">本机登录的班级账号</p>
</div>
</div>
@@ -26,7 +26,6 @@ async function selectTheme(value: 'light' | 'dark'): Promise<void> {
<div class="page-header">
<div>
<h2 class="page-title">外观</h2>
<p class="page-subtitle">黑夜与白天模式,切换立即生效并自动保存</p>
</div>
</div>
@@ -50,7 +49,10 @@ async function selectTheme(value: 'light' | 'dark'): Promise<void> {
</span>
</span>
<span class="theme-name">
<el-icon><Sunny v-if="option.value === 'light'" /><Moon v-else /></el-icon>
<el-icon>
<Sunny v-if="option.value === 'light'" />
<Moon v-else />
</el-icon>
{{ option.label }}
</span>
<span class="theme-desc">{{ option.desc }}</span>
@@ -2,7 +2,7 @@
import { confirmAction } from '../../composables/confirm.js';
import { computed, onMounted, ref } from 'vue';
import { ElMessage } from 'element-plus';
import { formatDate, relativeTime, type UpdateInfo } from '@classhelper/shared';
import { formatDate, relativeTime } from '@classhelper/shared';
import type { ClientAgentStatus, DesktopAppInfo } from '../../../types/desktop.js';
import { useAppStore } from '../../stores/app.js';
import { useUiStore } from '../../stores/ui.js';
@@ -42,7 +42,6 @@ async function loadAll(): Promise<void> {
try {
await loadAppInfo();
await refreshAgent();
await loadIgnoredVersion();
await appStore.refreshCacheStats();
} finally {
loading.value = false;
@@ -110,51 +109,6 @@ async function openLogDir(): Promise<void> {
if (!ok) ElMessage.warning('打开日志目录失败,请按上面的路径手动前往');
}
/* ------------------------------------------------------------ 更新 */
/**
* 更新检查。
*
* 「立即检查」走 `checkForUpdates(true)`:**强制绕过主进程那 30 分钟缓存**。
* 这是本页与「关于」页的区别 —— 那边用户点检查也可能是缓存结果(省流量),
* 这边维护者要的是"现在到底拿得到什么",所以按钮默认就是强制的。
*/
const checking = ref(false);
const updateInfo = ref<UpdateInfo | null>(null);
const ignoredUpdateVersion = ref('');
async function checkUpdate(force: boolean): Promise<void> {
if (!window.desktop?.checkForUpdates) return;
checking.value = true;
try {
updateInfo.value = await window.desktop.checkForUpdates(force);
} finally {
checking.value = false;
}
}
async function loadIgnoredVersion(): Promise<void> {
if (!window.desktop?.getConfig) return;
const stored = await window.desktop.getConfig().catch(() => null);
ignoredUpdateVersion.value = stored?.ignoredUpdateVersion ?? '';
}
async function ignoreVersion(): Promise<void> {
const version = updateInfo.value?.latestVersion;
if (!version || !window.desktop?.ignoreUpdateVersion) return;
await window.desktop.ignoreUpdateVersion(version);
ignoredUpdateVersion.value = version;
ElMessage.success(`已忽略 v${version}:启动时的自动检查不再提示它`);
}
/** 忽略是可逆的(排查线上"用户说不再提示"时经常要把它清掉),顺手给一个恢复入口 */
async function clearIgnoredVersion(): Promise<void> {
if (!window.desktop?.saveConfig) return;
const saved = await window.desktop.saveConfig({ ignoredUpdateVersion: '' });
ignoredUpdateVersion.value = saved.ignoredUpdateVersion;
ElMessage.success('已恢复该版本的更新提示');
}
/* ------------------------------------------------------------ 调试工具 */
const openingDevTools = ref(false);
@@ -211,8 +165,6 @@ async function clearCache(): Promise<void> {
onMounted(async () => {
await loadAll();
// 带出启动自动检查的结果(这次命中主进程缓存,不会真的再发一次请求)
void checkUpdate(false);
});
</script>
@@ -221,7 +173,6 @@ onMounted(async () => {
<div class="page-header">
<div>
<h2 class="page-title">开发者</h2>
<p class="page-subtitle">版本与平台、设备上报、日志、更新与调试工具</p>
</div>
<el-button :loading="loading" data-test="dev-refresh" @click="loadAll">
<el-icon><Refresh /></el-icon>
@@ -327,56 +278,6 @@ onMounted(async () => {
</div>
</el-card>
<!-- 更新 -->
<el-card shadow="never" class="mt-12">
<template #header><span>更新</span></template>
<div class="toolbar">
<el-button :loading="checking" data-test="dev-check-update" @click="checkUpdate(true)">
强制检查更新
</el-button>
<span class="text-muted">绕过主进程 30 分钟缓存,直接问 GitHub</span>
</div>
<el-descriptions :column="1" border size="small" class="mt-12">
<el-descriptions-item label="本次结果">
<template v-if="checking">正在检查…</template>
<template v-else-if="!updateInfo">尚未检查</template>
<template v-else-if="!updateInfo.ok">
<span class="text-muted">{{ updateInfo.error ?? '暂时无法检查更新' }}</span>
</template>
<template v-else-if="updateInfo.hasUpdate">
<el-tag size="small" type="success" effect="light">
有新版本 v{{ updateInfo.latestVersion }}
</el-tag>
<span class="text-muted">当前 v{{ updateInfo.currentVersion }}</span>
</template>
<template v-else>
<el-tag size="small" type="info" effect="plain">已是最新版本</el-tag>
<span class="text-muted">v{{ updateInfo.currentVersion }}</span>
</template>
</el-descriptions-item>
<el-descriptions-item label="检查时间">
{{ updateInfo?.checkedAt ? formatDate(updateInfo.checkedAt, true) : '—' }}
</el-descriptions-item>
<el-descriptions-item label="已忽略的版本">
<template v-if="ignoredUpdateVersion">
<span class="mono">v{{ ignoredUpdateVersion }}</span>
<el-button link type="primary" size="small" @click="clearIgnoredVersion">恢复提示</el-button>
</template>
<span v-else class="text-muted">无</span>
</el-descriptions-item>
</el-descriptions>
<div class="toolbar mt-12">
<el-button
:disabled="!updateInfo?.latestVersion"
data-test="dev-ignore-version"
@click="ignoreVersion"
>
不再提示该版本
</el-button>
<span class="text-muted">写入配置后,启动时的自动检查会跳过它</span>
</div>
</el-card>
<!-- 调试工具 -->
<el-card shadow="never" class="mt-12">
<template #header><span>调试工具</span></template>
@@ -308,7 +308,6 @@ onBeforeUnmount(() => {
<div class="page-header">
<div>
<h2 class="page-title">通用</h2>
<p class="page-subtitle">服务器连接、离线缓存与作业录入</p>
</div>
<!-- 重看初次启动引导(首启时由 App.vue 自动弹出过一次) -->
<el-button @click="onboarding.open()">
@@ -37,7 +37,6 @@ const selectedId = ref(''),
rowId = ref(''),
inspectorOpen = ref(false),
editMode = ref(false),
showTip = ref(true),
zoom = ref(1),
importInput = ref<HTMLInputElement>();
const scheme = computed(() =>
@@ -69,11 +68,6 @@ const library: { kind: IslandComponentKind; description: string }[] = [
{ kind: 'group', description: '将多个组件组合到一个组件中显示。' },
{ kind: 'stack', description: '将多个容器堆叠显示。' },
];
const messageLibrary: { kind: IslandComponentKind; description: string }[] = [
{ kind: 'notification', description: '显示班级收到的通知。' },
{ kind: 'homework', description: '显示班级作业提醒。' },
{ kind: 'call', description: '显示教师的叫人提醒。' },
];
const containers: readonly string[] = ['group', 'stack', 'slide', 'rolling'];
function id() {
return crypto.randomUUID();
@@ -773,34 +767,7 @@ function dropPreview(event: PointerEvent) {
</span>
</button>
</div>
<h4 class="message-library-title">班级消息</h4>
<div class="component-options message-options">
<button
v-for="item in messageLibrary"
:key="item.kind"
class="library-item"
:data-library-kind="item.kind"
:aria-label="`添加${ISLAND_COMPONENT_LABELS[item.kind]}`"
@pointerdown="beginDrag($event, { kind: item.kind, label: ISLAND_COMPONENT_LABELS[item.kind] })"
@click="add(item.kind)"
>
<ComponentIcon :kind="item.kind" />
<span>
<strong>{{ ISLAND_COMPONENT_LABELS[item.kind] }}</strong>
<span class="component-description">{{ item.description }}</span>
</span>
</button>
</div>
</section>
<div v-if="showTip" class="editor-tip" role="note">
<el-icon class="tip-icon"><InfoFilled /></el-icon>
<span>
<strong>编辑提示:</strong>
现在可以使用「编辑模式」更加直观地编辑主界面上的组件!
</span>
<el-button @click="editMode = !editMode">{{ editMode ? '退出编辑模式' : '进入编辑模式' }}</el-button>
<button class="dismiss-tip" aria-label="关闭编辑提示" @click="showTip = false">×</button>
</div>
</template>
<el-skeleton v-else :rows="8" animated />
<input ref="importInput" type="file" accept="application/json,.json" hidden @change="importScheme" />
@@ -5,6 +5,7 @@ import { ElMessage } from 'element-plus';
import { useRouter } from 'vue-router';
import {
DEFAULT_ISLAND_APPEARANCE,
defaultIslandLayouts,
ISLAND_APPEARANCE_RANGES as RANGES,
ISLAND_POSITION_LABELS,
ISLAND_POSITIONS,
@@ -30,6 +31,13 @@ function editLayout() {
void router.push('/settings/island/editor');
}
const layoutMode = ref<'fixed' | 'custom'>('fixed');
const layoutSettings = ref(defaultIslandLayouts());
const activeScheme = computed(() =>
layoutSettings.value.schemes.find((s) => s.id === layoutSettings.value.activeSchemeId)!,
);
const currentRadius = computed(() =>
layoutMode.value === 'custom' ? activeScheme.value.radius : island.value.radius,
);
const residentEnabled = ref(false);
const pointerFadeEnabled = ref(true);
const pointerFadeReversed = ref(false);
@@ -65,6 +73,7 @@ async function changePointerFade(
}
async function loadLayout() {
const settings = (await window.desktop?.getConfig())?.islandLayout;
if (settings) layoutSettings.value = settings;
layoutMode.value = settings?.layout ?? 'fixed';
residentEnabled.value = settings?.residentEnabled ?? false;
pointerFadeEnabled.value = settings?.pointerFadeEnabled ?? true;
@@ -103,6 +112,12 @@ async function loadIslandAppearance(): Promise<void> {
/** 改动即生效:属性变化时先应用(实时预览),点"保存"再落盘 */
function applyIslandAppearance(patch: Partial<IslandAppearance> = {}): void {
island.value = { ...island.value, ...patch };
if (layoutMode.value === 'custom' && patch.radius !== undefined) {
activeScheme.value.radius = patch.radius;
void window.desktop
?.saveConfig({ islandLayout: JSON.parse(JSON.stringify(layoutSettings.value)) })
.catch(() => ElMessage.error('圆角保存失败,请重试'));
}
window.desktop?.islandSetAppearance({ ...island.value });
}
@@ -149,7 +164,6 @@ onMounted(async () => {
<div class="page-header">
<div>
<h2 class="page-title">灵动岛</h2>
<p class="page-subtitle">自定义组件与 ClassIsland 提醒,共用停靠位置、动画开关与通知规则</p>
</div>
</div>
@@ -231,9 +245,9 @@ onMounted(async () => {
@input="(value: number) => applyIslandAppearance({ width: value })"
/>
</el-form-item>
<el-form-item :label="`圆角 ${island.radius}px`">
<el-form-item :label="`圆角 ${currentRadius}px`">
<el-slider
:model-value="island.radius"
:model-value="currentRadius"
:min="RANGES.radius.min"
:max="RANGES.radius.max"
:step="1"
@@ -49,14 +49,13 @@ onMounted(loadGradeQuery);
<div class="page-header">
<div>
<h2 class="page-title">提醒</h2>
<p class="page-subtitle">通知提醒与成绩查询状态</p>
</div>
</div>
<el-card shadow="never" class="lesson-channel-settings">
<template #header>上下课提醒</template>
<p class="text-muted">
沿用 ClassIsland 的遮罩、课前倒计时、上下课提示及下节课预告;课中显示课程进度,临近下课显示倒数。
课前倒计时、上下课提示及下节课预告保留遮罩;课中显示课程进度,临近下课在课程名右侧显示蓝色圆形秒数倒计时。
</p>
<div
v-for="channel in [
+4 -28
View File
@@ -9,7 +9,7 @@ import type {
* 主进程与渲染进程之间的桥接契约(preload 通过 contextBridge 暴露)。
* 渲染进程只依赖这些最小 API,不接触 Node.js。
*/
import type { IslandAppearance, IslandNotification, IslandState, UpdateInfo } from '@classhelper/shared';
import type { IslandAppearance, IslandNotification, IslandState } from '@classhelper/shared';
import type { ClientAgentStatus } from '../main/client-agent.js';
import type { IslandBridge } from '../preload/island.js';
@@ -48,23 +48,14 @@ export interface DesktopStoredConfig {
* 录入作业时点一下就追加到标题/内容里,少打字(例如 P、大本、背诵)。
*/
homeworkPhrases: string[];
/**
* 是否已看过「初次启动引导」。
*
* 首次启动自动弹出一次(完成或跳过即记为看过并写入配置,之后不再自动弹出);
* 登录页与设置页的「使用引导」入口可随时重看(重看不改变该值)。
*/
/** 兼容旧配置;新版引导是否展示由 onboardingVersion 决定。 */
onboardingDone: boolean;
onboardingVersion: number;
/** 界面主题:light=浅色(默认)/ dark=深色(黑夜模式) */
theme: 'light' | 'dark';
/** 主侧边栏是否折叠成图标栏(可由顶栏汉堡按钮切换) */
sidebarCollapsed: boolean;
/**
* 用户点过「忽略此版本」的版本号(空串 = 没忽略过)。
*
* 启动时的自动检查会跳过这个版本,避免每次开客户端都弹一次同样的提示;
* 在「关于」页手动检查时仍会正常显示结果。
*/
/** 旧版主动更新检查的兼容字段,不再影响云端下发更新。 */
ignoredUpdateVersion: string;
/**
* 本机设备标识(UUID):这台机器在服务端的身份。
@@ -163,21 +154,6 @@ export interface DesktopBridge {
getAppInfo(): Promise<DesktopAppInfo>;
openExternal(url: string): Promise<boolean>;
/* 更新检查 */
/**
* 检查 GitHub 上有没有新版本(主进程直连,不经后端)。
*
* @param force true = 绕过主进程缓存(对应「关于」页里用户主动点的那次检查)
*
* 返回的 `ok:false` 是**正常结果**(教室机器没有外网 / GitHub 限流 / 超时),不是异常,
* 界面按"暂时查不到更新"呈现即可。
*/
checkForUpdates(force?: boolean): Promise<UpdateInfo>;
/** 忽略某个版本的更新提示(写入 config.json,启动自动检查不再提示它) */
ignoreUpdateVersion(version: string): Promise<void>;
/** 订阅"启动自动检查发现新版本"(仅新版本且未被忽略时触发一次) */
onUpdateAvailable(handler: (info: UpdateInfo) => void): void;
/* 灵动岛 */
getIslandWeather(coordinates: { latitude: number; longitude: number }): Promise<IslandWeather>;
/** 把一条通知投递到灵动岛(payload 必须是纯数据,说明见 saveConfig) */
+3 -1
View File
@@ -1,8 +1,9 @@
{
"name": "@classhelper/server",
"version": "1.4.3",
"version": "1.4.5",
"private": true,
"description": "ClassHelper后端服务:REST API + Socket.IO 实时推送 + Prisma 数据访问",
"//": "yaml:课表 YAML 导入的解析器(yaml@2,自带类型、无子依赖);仓库只有传递依赖 js-yaml,不要直接引用",
"type": "module",
"main": "dist/index.js",
"scripts": {
@@ -38,6 +39,7 @@
"socket.io": "^4.8.3",
"typescript": "~5.9.3",
"xlsx": "0.18.5",
"yaml": "^2.9.1",
"zod": "^4.6.2"
},
"devDependencies": {
@@ -0,0 +1,13 @@
CREATE TABLE "AiPlanStep" (
"id" TEXT NOT NULL PRIMARY KEY,
"auditId" TEXT NOT NULL,
"userId" TEXT NOT NULL,
"ordinal" INTEGER NOT NULL,
"payload" TEXT NOT NULL,
"state" TEXT NOT NULL DEFAULT 'draft',
"result" TEXT NOT NULL DEFAULT '',
"createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updatedAt" DATETIME NOT NULL
);
CREATE UNIQUE INDEX "AiPlanStep_auditId_ordinal_key" ON "AiPlanStep"("auditId", "ordinal");
CREATE INDEX "AiPlanStep_userId_createdAt_idx" ON "AiPlanStep"("userId", "createdAt");
@@ -0,0 +1,12 @@
CREATE TABLE "AiTask" (
"id" TEXT NOT NULL PRIMARY KEY,
"userId" TEXT NOT NULL,
"state" TEXT NOT NULL DEFAULT 'preparing',
"input" TEXT NOT NULL,
"result" TEXT NOT NULL DEFAULT '',
"events" TEXT NOT NULL DEFAULT '',
"error" TEXT NOT NULL DEFAULT '',
"createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
"updatedAt" DATETIME NOT NULL
);
CREATE INDEX "AiTask_userId_createdAt_idx" ON "AiTask"("userId", "createdAt");
@@ -0,0 +1,8 @@
ALTER TABLE "TimeLayout" ADD COLUMN "parentId" TEXT;
ALTER TABLE "TimeLayoutItem" ADD COLUMN "slotKey" TEXT NOT NULL DEFAULT '';
ALTER TABLE "TimeLayoutItem" ADD COLUMN "isAutoBreak" BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE "AiTask" ADD COLUMN "conversationId" TEXT;
ALTER TABLE "AiTask" ADD COLUMN "turnNumber" INTEGER NOT NULL DEFAULT 1;
CREATE UNIQUE INDEX "AiTask_conversationId_turnNumber_key" ON "AiTask"("conversationId", "turnNumber");
CREATE TABLE "AiConversation" ("id" TEXT NOT NULL PRIMARY KEY, "userId" TEXT NOT NULL, "title" TEXT NOT NULL DEFAULT '', "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, "updatedAt" DATETIME NOT NULL);
CREATE INDEX "AiConversation_userId_updatedAt_idx" ON "AiConversation"("userId", "updatedAt");
+47
View File
@@ -401,6 +401,7 @@ model NotificationRead {
/// 课表时间配置(ClassIsland 同款 JSON 导入后的节次时间表)
model TimeLayout {
parentId String?
id String @id @default(cuid())
classId String?
name String
@@ -648,6 +649,8 @@ model Exam {
/// 服务端不用单机 Profile:全校共享时间表 + 班级日课表替代档案。
model TimeLayoutItem {
slotKey String @default("")
isAutoBreak Boolean @default(false)
id String @id @default(cuid())
timeLayoutId String
position Int
@@ -813,3 +816,47 @@ model CoursewareReceipt {
device ClientDevice @relation(fields: [deviceId], references: [id], onDelete: Cascade)
@@id([pushId, deviceId])
}
/// AI 确认计划与执行去重;payload 加密保存,不保存明文凭据。
model AiPlanStep {
id String @id @default(cuid())
auditId String
userId String
ordinal Int
payload String
state String @default("draft")
result String @default("")
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@unique([auditId, ordinal])
@@index([userId, createdAt])
}
/// 持久化后台任务;输入、结果和阶段消息加密,连接断开不取消任务。
model AiTask {
conversationId String?
turnNumber Int @default(1)
@@unique([conversationId, turnNumber])
id String @id @default(cuid())
userId String
state String @default("preparing")
input String
result String @default("")
events String @default("")
error String @default("")
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([userId, createdAt])
}
/// 账号所属对话;内容仍使用 AiTask 的加密输入与结果。
model AiConversation {
id String @id @default(cuid())
userId String
title String @default("")
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([userId, updatedAt])
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,88 @@
import { readFileSync } from 'node:fs';
/** 由隔离 E2E 启动器调用,在独立临时班级验收 YAML 写入及权限。 */
export async function verifyClassPlanYamlApi({
api,
record,
adminToken,
teacherToken,
teacher2Token,
teacher1Id,
}) {
const created = await api('/classes', {
method: 'POST',
token: adminToken,
body: { grade: '高一', enrollmentYear: 2026, classIndex: 98, teacherId: teacher1Id },
});
const classId = created.payload?.data?.id;
record('YAML 验收使用独立临时班级', created.status === 201 && Boolean(classId));
if (!classId) return;
const text = readFileSync(new URL('../../../yml导入格式示例.yml', import.meta.url), 'utf8');
const call = (suffix, source = text, mode = 'merge', token = teacherToken) =>
api(`/imports/class-plan/yaml${suffix}`, {
method: 'POST',
token,
body: { classId, text: source, mode },
});
try {
const preview = await call('/preview');
const before = await api(`/class-plans?classId=${classId}`, { token: teacherToken });
record(
'YAML 示例预览:6 节、3 张课表、只读不写库',
preview.status === 200 &&
preview.payload?.data?.entries.length === 6 &&
preview.payload?.data?.planCount === 3 &&
preview.payload?.data?.errors.length === 0 &&
before.payload?.data?.length === 0,
);
const first = await call('');
const list = await api(`/class-plans?classId=${classId}`, { token: teacherToken });
const plans = list.payload?.data ?? [];
const ids = plans.map((plan) => plan.id).sort();
record(
'YAML 示例落库并保留单双周',
first.status === 200 &&
plans.length === 3 &&
plans.some((plan) => plan.weekCountDiv === 1 && plan.weekCountDivTotal === 2) &&
plans.some((plan) => plan.weekCountDiv === 2 && plan.weekCountDivTotal === 2),
);
const entries = plans.flatMap((plan) => plan.entries ?? []);
record(
'YAML 教室写入课次地点',
entries.length === 6 && entries.every((entry) => ['101', '102', '103', '104'].includes(entry.location)),
);
const courses = await api(`/courses?classId=${classId}`, { token: teacherToken });
record(
'YAML 简称落库且教师字段不改变任课授权',
courses.payload?.data?.length === 4 &&
courses.payload.data.every((course) => course.teacherId === teacher1Id && course.initial),
);
const again = await call('');
const merged = await api(`/class-plans?classId=${classId}`, { token: teacherToken });
record(
'YAML 重复合并更新原对象,不产生重复课表',
again.status === 200 &&
JSON.stringify(merged.payload?.data?.map((plan) => plan.id).sort()) === JSON.stringify(ids),
);
const rejected = await call('', 'version: 1\nschedules: broken', 'replace');
const after = await api(`/class-plans?classId=${classId}`, { token: teacherToken });
record(
'YAML 非法覆盖返回 400 且原课表保留',
rejected.status === 400 &&
JSON.stringify(after.payload?.data?.map((plan) => plan.id).sort()) === JSON.stringify(ids),
);
const denied = await call('', text, 'replace', teacher2Token);
record('YAML 导入拒绝跨班教师', denied.status === 403);
const tooLarge = await call('/preview', '#中文'.repeat(1_200_000));
record('YAML 按 UTF-8 字节限制 8 MB,超限返回 413', tooLarge.status === 413);
const replacement = await call('', text, 'replace');
const replaced = await api(`/class-plans?classId=${classId}`, { token: teacherToken });
record(
'YAML 覆盖导入成功且保留三张课表',
replacement.status === 200 && replaced.payload?.data?.length === 3,
);
} finally {
const removed = await api(`/classes/${classId}`, { method: 'DELETE', token: adminToken });
record('YAML 临时班级验收数据清理', removed.status === 200);
}
}
@@ -0,0 +1,62 @@
/** 纯解析回归,不访问业务库。用 node --import tsx scripts/verify-class-plan-yaml.ts 执行。 */
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { CLASS_PLAN_YAML_SAMPLE } from '@classhelper/shared';
import {
buildClassIslandProfile,
parseClassPlanYaml,
} from '../src/modules/imports/class-plan-yaml.service.js';
const example = readFileSync(new URL('../../../yml导入格式示例.yml', import.meta.url), 'utf8');
const parsed = parseClassPlanYaml(example);
assert.deepEqual(parsed.errors, []);
assert.equal(parsed.entries.length, 6);
assert.equal(parsed.planCount, 3);
assert.deepEqual(
parsed.entries.map((entry) => entry.weekParity),
['ALL', 'ALL', 'ODD', 'ODD', 'EVEN', 'EVEN'],
);
assert.equal(parsed.entries[0]?.startTime, '08:00');
assert.equal(parsed.entries[0]?.location, '101');
assert.equal(parsed.subjects[0]?.initial, '数');
const profile = buildClassIslandProfile(parsed, 30);
assert.equal(Object.keys(profile.ClassPlans as object).length, 3);
assert.equal(Object.keys(profile.TimeLayouts as object).length, 1);
console.log('[PASS] 用户示例:省略冒号、HHMMSS、简称、教室及单双周');
assert.deepEqual(parseClassPlanYaml(CLASS_PLAN_YAML_SAMPLE).errors, []);
const standard = `version: 1
subjects:
- name: 数学
schedules:
- name: 周日
enable_day: 7
weeks: all
classes:
- subject: 数学
start_time: 080000
end_time: '090000'
`;
assert.deepEqual(parseClassPlanYaml(standard).errors, []);
assert.equal(parseClassPlanYaml(standard).entries[0]?.dayOfWeek, 7);
assert.deepEqual(
parseClassPlanYaml(standard.replace('080000', "'08:00'").replace('090000', '09:00:00')).errors,
[],
);
console.log('[PASS] 标准 YAML:六位数字/字符串、冒号时间、周日映射');
for (const [name, invalid] of [
['空文件', ''],
['不支持的版本', standard.replace('version: 1', 'version: 2')],
['小数星期', standard.replace('enable_day: 7', 'enable_day: 1.5')],
['非法小时', standard.replace('080000', '250000')],
['非法分钟', standard.replace('080000', '086000')],
['非零秒', standard.replace('080000', '080001')],
['反向时间', standard.replace('090000', '070000')],
['未知单双周', standard.replace('weeks: all', 'weeks: unknown')],
['重复字段', standard.replace('version: 1', 'version: 1\nversion: 1')],
['同日相位冲突', standard + standard.slice(standard.indexOf(' - name: 周日'))],
] as const) {
assert.ok(parseClassPlanYaml(invalid).errors.length > 0, name);
}
console.log('[PASS] 错误输入被拒绝,避免部分导入或丢失时间精度');
+10 -1
View File
@@ -437,11 +437,20 @@ try {
coursewareCategory('a.7z') === 'archive',
);
await restoreSnapshot(prisma, 'sqlite', snapshot);
const restoredFolders = await prisma.coursewareFolder.findMany();
check(
'恢复数据库后保留课件共享和回执数据',
(await prisma.courseware.count()) === 3 &&
(await prisma.coursewareReceipt.count()) === 1 &&
(await prisma.coursewareFolder.count()) === 1,
restoredFolders.length === snapshot.data.CoursewareFolder.length &&
snapshot.data.CoursewareFolder.every((expected) =>
restoredFolders.some(
(actual) =>
actual.id === expected.id &&
actual.path === expected.path &&
actual.teacherId === expected.teacherId,
),
),
);
console.log(`=== 课件隔离验收:${count}/${count} 项通过 ===`);
} finally {
+50 -7
View File
@@ -15,6 +15,7 @@ import { readFileSync } from 'node:fs';
* VERIFY_BASE_URL 默认 http://127.0.0.1:4000
*/
import { io } from 'socket.io-client';
import { verifyClassPlanYamlApi } from './verify-class-plan-yaml-api.mjs';
const BASE_URL = process.env.VERIFY_BASE_URL ?? `http://127.0.0.1:${process.env.PORT ?? 4000}`;
const TIME_LIMIT_MS = 5000;
@@ -442,6 +443,8 @@ async function main() {
`删除课表 ${removedSchedules} 条、课程 ${removedImportedCourses} 门`,
);
await verifyClassPlanYamlApi({ api, record, adminToken, teacherToken, teacher2Token, teacher1Id });
// ---------------------------------------------------------------- 3. WebSocket 连接
const socket = io(BASE_URL, {
auth: { token: studentToken, clientType: 'desktop' },
@@ -2212,7 +2215,9 @@ async function main() {
mergeImport.status === 200 &&
mergeData?.merged === 1 &&
mergeData?.replaced === 1 &&
mergeData?.layout?.items?.length === 4,
mergeData?.layout?.items?.length === 5 &&
mergeData.layout.items.filter((item) => item.type === 'class').length === 3 &&
mergeData.layout.items.filter((item) => item.type === 'break').length === 2,
`合并=${mergeData?.merged} 新增=${mergeData?.replaced} 共=${mergeData?.layout?.items?.length}`,
);
@@ -3218,7 +3223,8 @@ async function main() {
// 教师名单表格导入:教师预览 403;管理员预览 + 提交(教师与班级无关,classId 可省略)
const teacherCsv =
'\ufeff工号,姓名,初始密码,角色\n' +
`imp_t_${Date.now().toString().slice(-8)},冒烟导入教师,import123456,教师\n`;
`imp_t_${Date.now().toString().slice(-8)},冒烟导入教师,import123456,教师\n` +
`imp_t_${Date.now().toString().slice(-8)}_b,冒烟导入教师乙,import123456,教师\n`;
const teacherCsvBase64 = Buffer.from(teacherCsv, 'utf8').toString('base64');
const importedTeacherUsername = teacherCsv.split('\n')[1]?.split(',')[0] ?? '';
@@ -3245,7 +3251,10 @@ async function main() {
});
const importedTeacherLogin = await api('/auth/login', {
method: 'POST',
body: { username: importedTeacherUsername, password: 'import123456' },
body: {
username: importedTeacherUsername,
password: adminTeacherCommit.payload?.data?.credentials?.[0]?.password ?? '',
},
});
record(
'教师名单表格导入(教师 403 / 管理员预览+导入成功,且导入账号可登录)',
@@ -3253,13 +3262,47 @@ async function main() {
adminTeacherPreview.status === 200 &&
Boolean(adminTeacherPreview.payload?.data?.suggestedMapping?.username) &&
adminTeacherCommit.status === 200 &&
adminTeacherCommit.payload?.data?.inserted === 1 &&
adminTeacherCommit.payload?.data?.inserted === 2 &&
adminTeacherCommit.payload?.data?.credentials?.[0]?.password !== 'import123456' &&
importedTeacherLogin.status === 200,
`教师预览=${teacherPreviewDenied.status} 管理员预览=${adminTeacherPreview.status} ` +
`建议映射=${JSON.stringify(adminTeacherPreview.payload?.data?.suggestedMapping ?? {})} ` +
`导入新增=${adminTeacherCommit.payload?.data?.inserted ?? '-'} 登录=${importedTeacherLogin.status}`,
);
const importedCredentials = adminTeacherCommit.payload?.data?.credentials ?? [];
const repeatedImport = await api('/imports/table/commit', {
method: 'POST',
token: adminToken,
body: {
kind: 'teachers',
fileName: 'teachers.csv',
contentBase64: teacherCsvBase64,
mapping: { username: '工号', name: '姓名', role: '角色' },
mode: 'upsert',
},
});
const repeatLogin = await api('/auth/login', {
method: 'POST',
body: { username: importedTeacherUsername, password: importedCredentials[0]?.password ?? '' },
});
const importAudits = await api('/permissions/audit?pageSize=100', { token: adminToken });
const teacherImportAudits = (importAudits.payload?.data?.items ?? []).filter(
(item) => item.action === 'import-commitTeachers',
);
record(
'教师导入逐人生成随机密码,重复导入不重置且审计不含凭据',
importedCredentials.length === 2 &&
new Set(importedCredentials.map((c) => c.password)).size === 2 &&
importedCredentials.every((c) => c.password.length >= 16 && c.password !== 'import123456') &&
repeatedImport.payload?.data?.updated === 2 &&
repeatedImport.payload?.data?.credentials?.length === 0 &&
repeatLogin.status === 200 &&
teacherImportAudits.length > 0 &&
teacherImportAudits.every((item) => !/password|credentials/.test(item.afterJson)),
`凭据=${importedCredentials.length} 重复更新=${repeatedImport.payload?.data?.updated ?? '-'} 登录=${repeatLogin.status}`,
);
// 删除护栏:还是班主任的账号不允许删除;没有班级职责的可以删
const deleteHeadTeacher = teacher1
? await api(`/teachers/${teacher1.id}`, { method: 'DELETE', token: adminToken })
@@ -3656,10 +3699,10 @@ async function main() {
await api(`/classes/${probeClassId}`, { method: 'DELETE', token: adminToken });
}
}
const importedTeacherRow = (await api('/teachers', { token: adminToken })).payload?.data?.find(
(item) => item.username === importedTeacherUsername,
const importedTeacherRows = (await api('/teachers', { token: adminToken })).payload?.data?.filter((item) =>
importedCredentials.some((credential) => credential.username === item.username),
);
if (importedTeacherRow) {
for (const importedTeacherRow of importedTeacherRows ?? []) {
await api(`/teachers/${importedTeacherRow.id}`, { method: 'DELETE', token: adminToken });
}
const isProbeAccount = (username) =>
+5
View File
@@ -33,6 +33,11 @@ export type ApiErrorCode =
| 'AI_TIMEOUT'
/** 大模型:返回的内容不是可用的结构化动作(已记日志,不把原始回复回传给前端) */
| 'AI_INVALID_OUTPUT'
| 'AI_TASK_INCOMPLETE'
| 'AI_MODELS_UNAVAILABLE'
| 'AI_PROVIDER_ERROR'
| 'AI_READ_FAILED'
| 'AI_RESULT_UNCERTAIN'
| 'TOO_MANY_REQUESTS'
/** 上课时间段发布紧急通知需要二次确认(前端据此弹出全屏警告 + 3 秒倒计时) */
| 'URGENT_DURING_CLASS'
+1
View File
@@ -15,6 +15,7 @@ export const SETTING_KEYS = {
aiProvider: 'ai.provider',
aiBaseUrl: 'ai.baseUrl',
aiModel: 'ai.model',
aiReasoningEffort: 'ai.reasoningEffort',
/** 加密后的 API Key(见 lib/secrets.ts;接口只进不出) */
aiApiKey: 'ai.apiKey',
/** 追加到系统提示词末尾的学校自定义要求(可空) */
+12 -1
View File
@@ -72,6 +72,9 @@ export const SNAPSHOT_TABLES = [
'ClientCommand',
'ClientRelease',
'AiAudit',
'AiPlanStep',
'AiConversation',
'AiTask',
] as const;
export type SnapshotTable = (typeof SNAPSHOT_TABLES)[number];
@@ -143,7 +146,15 @@ export function assertValidSnapshot(value: unknown): asserts value is DatabaseSn
for (const table of SNAPSHOT_TABLES) {
const rows = (snapshot.data as Record<string, unknown>)[table];
// 旧版本快照没有课件表;允许恢复,文件实体仍需单独备份。
if (rows === undefined && (table.startsWith('Courseware') || table === 'PermissionAudit')) continue;
if (
rows === undefined &&
(table.startsWith('Courseware') ||
table === 'PermissionAudit' ||
table === 'AiPlanStep' ||
table === 'AiTask' ||
table === 'AiConversation')
)
continue;
if (!Array.isArray(rows)) {
throw new Error(`快照缺少表 ${table} 的数据`);
}
+5 -1
View File
@@ -14,7 +14,7 @@ import { extractBearerToken, verifyToken, type TokenPayload } from '../lib/jwt.j
* 角色判据换成权限键判据(`requirePermission`),角色只用来决定"没有分组时的默认模板"。
*/
export function authenticate(): RequestHandler {
return async (req, _res, next) => {
return async (req, res, next) => {
try {
const token = extractBearerToken(req.headers.authorization);
if (!token) throw ApiError.unauthorized('缺少 Authorization 头');
@@ -23,6 +23,10 @@ export function authenticate(): RequestHandler {
const user = await loadSessionUser(payload);
req.auth = { token, user, permissions: (await loadAuthPrincipal(user)).permissions };
if (req.get('x-classhelper-ai-step')) {
const { guardAiExecution } = await import('../modules/ai/execution-guard.js');
if (!(await guardAiExecution(req, res))) return;
}
next();
} catch (error) {
next(error);
+38 -13
View File
@@ -1,6 +1,6 @@
import type { RequestHandler } from 'express';
import helmet from 'helmet';
import { rateLimit } from 'express-rate-limit';
import { ipKeyGenerator, rateLimit } from 'express-rate-limit';
import { env } from '../config/env.js';
import { logger } from '../lib/logger.js';
@@ -78,25 +78,50 @@ export function apiRateLimiter(): RequestHandler {
return limiter;
}
/** 登录接口专用限流:防暴力破解 */
/** 两种登录入口共用来源 IP:连续五次密码错误,从第五次失败起封禁五分钟。 */
export function loginRateLimiter(): RequestHandler {
return rateLimit({
windowMs: 10 * 60 * 1000,
limit: env.isProduction ? 20 : 200,
standardHeaders: 'draft-7',
legacyHeaders: false,
skipSuccessfulRequests: true,
skip: () => !env.rateLimitEnabled,
handler: (req, res) => {
logger.warn(`登录尝试过于频繁:${req.ip ?? '-'}`);
const duration = 5 * 60 * 1000;
const attempts = new Map<string, { failures: number; expiresAt: number; blockedUntil: number }>();
let sweepAt = 0;
return (req, res, next) => {
if (!env.rateLimitEnabled) return next();
const now = Date.now();
if (now >= sweepAt) {
for (const [key, attempt] of attempts) {
if (attempt.expiresAt <= now) attempts.delete(key);
}
sweepAt = now + 60_000;
}
const key = ipKeyGenerator(req.ip ?? req.socket.remoteAddress ?? 'unknown');
let attempt = attempts.get(key);
if (attempt && attempt.expiresAt <= now) {
attempts.delete(key);
attempt = undefined;
}
if (attempt && attempt.blockedUntil > now) {
res.setHeader('Retry-After', Math.ceil((attempt.blockedUntil - now) / 1000));
res.status(429).json({
success: false,
data: null,
message: '登录尝试过于频繁,请 10 分钟后再试',
message: '连续五次密码错误,已封禁登录 5 分钟,请稍后再试',
code: 'TOO_MANY_REQUESTS',
});
},
return;
}
res.once('finish', () => {
if (res.statusCode >= 200 && res.statusCode < 300) {
attempts.delete(key);
} else if (res.statusCode === 401) {
const finishedAt = Date.now();
const previous = attempts.get(key);
const failures = (previous && previous.expiresAt > finishedAt ? previous.failures : 0) + 1;
const blockedUntil = failures >= 5 ? previous?.blockedUntil || finishedAt + duration : 0;
attempts.set(key, { failures, blockedUntil, expiresAt: blockedUntil || finishedAt + duration });
if (failures === 5) logger.warn(`连续五次登录失败,封禁五分钟:${req.ip ?? '-'}`);
}
});
next();
};
}
/**
File diff suppressed because it is too large. Load diff
+221 -11
View File
@@ -1,5 +1,12 @@
import { Router } from 'express';
import { API_PATHS } from '@classhelper/shared';
import { capabilities } from './actions.js';
import { interpretConversation } from './conversation.js';
import { sanitizePrompt } from './model-planner.js';
import { prisma } from '../../lib/db.js';
import { ApiError } from '../../lib/http.js';
import { getPlan, preparePlan, confirmPlan, discardPlan } from './plans.js';
import { planIdSchema, preparePlanSchema, confirmPlanSchema } from './ai.schemas.js';
import { API_PATHS, type AiAgentEvent } from '@classhelper/shared';
import { sendOk } from '../../lib/http.js';
import { authenticate, getAuthUser, requirePermission } from '../../middleware/auth.js';
import { validate, validatedBody, validatedQuery } from '../../middleware/validate.js';
@@ -13,17 +20,170 @@ import {
type UpdateAiSettingsInput,
} from './ai.schemas.js';
import * as aiService from './ai.service.js';
import { discoverModelsSchema, taskAttachmentSchema } from './ai.schemas.js';
import { discoverModels } from './model-transport.js';
import * as tasks from './tasks.js';
import { setTimeout as delay } from 'node:timers/promises';
const router = Router();
router.use(authenticate());
router.delete(
'/conversations/:id',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
sendOk(res, await tasks.deleteConversation(getAuthUser(req), String(req.params.id)));
},
);
router.post('/conversations', requirePermission('ai:use'), async (req, res) => {
sendOk(res, await tasks.createConversation(getAuthUser(req)));
});
router.get('/conversations', requirePermission('ai:use'), async (req, res) => {
sendOk(
res,
await tasks.conversations(
getAuthUser(req),
typeof req.query.before === 'string' ? req.query.before : undefined,
),
);
});
router.get(
'/conversations/:id',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
const before = Number(req.query.before);
if (req.query.before !== undefined && (!Number.isInteger(before) || before < 1))
throw ApiError.badRequest('轮次游标无效');
sendOk(res, await tasks.conversationTurns(getAuthUser(req), String(req.params.id), before || undefined));
},
);
router.get(
'/tasks/:id/events',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
const user = getAuthUser(req),
id = String(req.params.id);
await tasks.task(user, id);
res.status(200).set({
'content-type': 'text/event-stream; charset=utf-8',
'cache-control': 'no-cache, no-transform',
'x-accel-buffering': 'no',
});
res.flushHeaders();
const connection = new AbortController();
res.on('close', () => connection.abort());
const send = (event: AiAgentEvent) => {
if (!res.destroyed) res.write(`data: ${JSON.stringify(event)}\n\n`);
};
const sent = new Set<string>();
let lastText = '';
try {
while (!connection.signal.aborted) {
const current = await tasks.task(user, id);
for (const event of current.events) {
if (event.type === 'message') {
if (event.text !== lastText) {
send(event);
lastText = event.text;
}
} else if (!sent.has(JSON.stringify(event))) {
send(event);
sent.add(JSON.stringify(event));
}
}
if (['ready', 'succeeded', 'waiting_input'].includes(current.state) && current.result) {
send({ type: 'result', result: current.result });
break;
}
if (['failed', 'stopped'].includes(current.state)) {
send({
type: 'error',
code: 'AI_TASK_INCOMPLETE',
message: current.error || '任务已暂停,可继续处理。',
retryable: true,
});
break;
}
res.write(': heartbeat\n\n');
await delay(350, undefined, { signal: connection.signal });
}
} catch (error) {
if (!connection.signal.aborted)
send({
type: 'error',
code: 'AI_READ_FAILED',
message: error instanceof ApiError ? error.message : '连接暂时中断,后台任务继续运行。',
retryable: true,
});
} finally {
res.end();
}
},
);
router.get('/tasks', requirePermission('ai:use'), async (req, res) =>
sendOk(res, await tasks.listTasks(getAuthUser(req))),
);
router.post('/tasks', requirePermission('ai:use'), validate({ body: aiInterpretSchema }), async (req, res) =>
sendOk(res, await tasks.createTask(getAuthUser(req), req.body)),
);
router.get('/tasks/:id', requirePermission('ai:use'), validate({ params: planIdSchema }), async (req, res) =>
sendOk(res, await tasks.task(getAuthUser(req), String(req.params.id))),
);
router.put(
'/tasks/:id/files/:attachmentId',
requirePermission('ai:use'),
validate({ params: taskAttachmentSchema }),
async (req, res) => {
await tasks.stageAttachment(
getAuthUser(req),
String(req.params.id),
String(req.params.attachmentId),
req,
);
sendOk(res, null);
},
);
router.post(
'/tasks/:id/start',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
await tasks.startTask(getAuthUser(req), String(req.params.id));
sendOk(res, null);
},
);
router.post(
'/tasks/:id/execute',
requirePermission('ai:use'),
validate({ params: planIdSchema, body: confirmPlanSchema }),
async (req, res) => {
await tasks.executeTask(getAuthUser(req), String(req.params.id), req.body, req.socket.localPort!);
sendOk(res, null);
},
);
router.post(
'/tasks/:id/stop',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
await tasks.stopTask(getAuthUser(req), String(req.params.id));
sendOk(res, null);
},
);
router.post(
'/models',
requirePermission('ai:manage'),
validate({ body: discoverModelsSchema }),
async (req, res) => {
sendOk(res, await discoverModels(getAuthUser(req), req.body));
},
);
/**
* 大模型助手。
*
* 权限分成两把:`ai:manage`(设置,默认只有管理员)与 `ai:use`(用一句话办事,默认教师也有)。
* **`/interpret` 只解析、绝不落库**:真正发布由前端确认后调既有端点,权限与上课时段保护
* 都在那条路径上(AGENTS.md 的现行工程约定)。
*/
router.get('/settings', requirePermission('ai:manage'), async (_req, res) => {
sendOk(res, await aiService.getAiSettings(), '获取大模型设置成功');
});
@@ -46,14 +206,64 @@ router.post(
async (req, res) => {
const user = getAuthUser(req);
const input = validatedBody<AiInterpretInput>(req);
sendOk(res, await aiService.interpret(user, input), '助手已解析,请确认后发布');
try {
sendOk(res, await interpretConversation(user, input), '任务已解析');
} catch (error) {
await prisma.aiAudit.create({
data: {
userId: user.sub,
prompt: sanitizePrompt(input.text),
intent: 'rejected',
status: 'rejected',
message: error instanceof ApiError ? error.message : '任务参数或解析失败',
},
});
throw error;
}
},
);
router.get('/audit', requirePermission('ai:manage'), validate({ query: aiAuditQuerySchema }), async (req, res) => {
router.get(
'/audit',
requirePermission('ai:manage'),
validate({ query: aiAuditQuerySchema }),
async (req, res) => {
const query = validatedQuery<AiAuditQuery>(req);
sendOk(res, await aiService.listAudit(query.limit ?? 50), '获取助手使用记录成功');
});
},
);
router.get('/capabilities', requirePermission('ai:use'), async (req, res) =>
sendOk(res, await capabilities(getAuthUser(req))),
);
router.get('/plans/:id', requirePermission('ai:use'), validate({ params: planIdSchema }), async (req, res) =>
sendOk(res, await getPlan(getAuthUser(req), String(req.params.id))),
);
router.post(
'/plans/:id/prepare',
requirePermission('ai:use'),
validate({ params: planIdSchema, body: preparePlanSchema }),
async (req, res) =>
sendOk(
res,
await preparePlan(getAuthUser(req), String(req.params.id), req.body.files, req.body.mappings),
),
);
router.post(
'/plans/:id/confirm',
requirePermission('ai:use'),
validate({ params: planIdSchema, body: confirmPlanSchema }),
async (req, res) => sendOk(res, await confirmPlan(getAuthUser(req), String(req.params.id), req.body)),
);
router.delete(
'/plans/:id',
requirePermission('ai:use'),
validate({ params: planIdSchema }),
async (req, res) => {
await discardPlan(getAuthUser(req), String(req.params.id));
sendOk(res, null);
},
);
export const aiModule = defineModule({
name: 'ai',
+49 -1
View File
@@ -2,6 +2,7 @@ import { z } from 'zod';
/** 大模型服务端实现:openai=真接口 / mock=离线确定性结果(自动化验收用,不联网) */
export const AI_PROVIDERS = ['openai', 'mock'] as const;
const reasoningEffortSchema = z.enum(['auto', 'none', 'low', 'medium', 'high', 'max']);
/** `PUT /api/ai/settings`:字段都可选;`apiKey` 传字符串=换新、null=清除、不传=保持 */
export const updateAiSettingsSchema = z.object({
@@ -9,13 +10,40 @@ export const updateAiSettingsSchema = z.object({
provider: z.enum(AI_PROVIDERS).optional(),
baseUrl: z.string().trim().max(300).optional(),
model: z.string().trim().max(120).optional(),
reasoningEffort: reasoningEffortSchema.optional(),
apiKey: z.string().trim().max(300).nullable().optional(),
systemPromptExtra: z.string().trim().max(1000).optional(),
});
export const discoverModelsSchema = updateAiSettingsSchema.pick({ baseUrl: true, apiKey: true });
/** `POST /api/ai/interpret`:一句中文原话 */
export const aiInterpretSchema = z.object({
text: z.string().trim().min(1, '请说一句要做的事').max(500, '一句话最多 500 个字'),
supersedesTaskId: z.string().min(1).max(100).optional(),
conversationId: z.string().min(1).max(100).optional(),
text: z.string().trim().min(1, '请说明要做的事').max(8000),
messages: z
.array(z.object({ role: z.enum(['user', 'assistant']), content: z.string().max(8000) }).strict())
.max(20)
.optional(),
attachments: z
.array(
z
.object({
id: z.string().min(1).max(100),
name: z.string().min(1).max(180),
size: z
.number()
.int()
.min(1)
.max(512 * 1024 * 1024),
sha256: z.string().regex(/^[a-f0-9]{64}$/),
})
.strict(),
)
.max(8)
.refine((items) => new Set(items.map((item) => item.id)).size === items.length, '附件标识重复')
.optional(),
classId: z.string().min(1).optional(),
});
@@ -26,3 +54,23 @@ export const aiAuditQuerySchema = z.object({
export type UpdateAiSettingsInput = z.infer<typeof updateAiSettingsSchema>;
export type AiInterpretInput = z.infer<typeof aiInterpretSchema>;
export type AiAuditQuery = z.infer<typeof aiAuditQuerySchema>;
export const planIdSchema = z.object({ id: z.string().min(1).max(100) });
export const taskAttachmentSchema = z.object({
id: z.string().min(1).max(100),
attachmentId: z.string().min(1).max(100),
});
export const preparePlanSchema = z
.object({
files: z.record(z.string(), z.object({ contentBase64: z.string().max(12 * 1024 * 1024) }).strict()),
mappings: z.record(z.string(), z.record(z.string(), z.string().max(200))).optional(),
})
.strict();
export const confirmPlanSchema = z
.object({
confirmed: z.literal(true),
extraConfirmed: z.boolean().optional(),
urgentConfirmed: z.boolean().optional(),
secrets: z.record(z.string(), z.record(z.string(), z.string().max(128))).optional(),
})
.strict();
+14 -353
View File
@@ -1,72 +1,19 @@
import type { PermissionKey } from '@classhelper/shared';
import { assertAdmin, assertPermission, classIdsFor } from '../../lib/authz/index.js';
import { activeStudentWhere } from '../../lib/students.js';
import {
dayKeyLocal,
type AiActionKind,
type AiAuditDto,
type AiInterpretResult,
type AiSettingsDto,
} from '@classhelper/shared';
import { z } from 'zod';
import { getAccessibleClassIds, assertClassAccess } from '../../lib/access.js';
import type { AiAuditDto, AiSettingsDto } from '@classhelper/shared';
import { assertAdmin } from '../../lib/authz/index.js';
import { prisma } from '../../lib/db.js';
import { ApiError } from '../../lib/http.js';
import type { TokenPayload } from '../../lib/jwt.js';
import { logger } from '../../lib/logger.js';
import { decryptSecret, encryptSecret } from '../../lib/secrets.js';
import { SETTING_KEYS, getSetting, getSettings, setSetting } from '../../lib/settings.js';
import { createHomeworkSchema } from '../homeworks/homeworks.schemas.js';
import { createNotificationSchema } from '../notifications/notifications.schemas.js';
import { SETTING_KEYS, getSettings, setSetting } from '../../lib/settings.js';
import type { AiInterpretInput, UpdateAiSettingsInput } from './ai.schemas.js';
/**
* 大模型助手:**只解析、不落库**。
*
* 设计边界(照 approved 计划):
* 1. 模型只输出结构化意图(`{action, params, confidence}`),服务端用**与手动入口同一份 zod**
* 二次校验后返回预览;真正落库由前端确认后调既有端点(`POST /homeworks` 等),
* 于是权限断言、上课时段紧急通知保护全部自动复用(AGENTS.md 的现行工程约定);
* 2. **密钥只进不出**:`AppSetting` 里存的是 `encryptSecret()` 的密文,任何 GET 都不回传;
* 3. `provider: 'mock'` 用确定性规则离线解析 —— 自动化验收**绝不访问外网**(§5 第 52 条),
* 真实模型走 `provider: 'openai'` 时的 `{baseUrl}/chat/completions`。
*/
const DEFAULT_TIMEOUT_MS = 20_000;
/** 与手动入口同源的参数校验(助手不得放宽任何字段约束) */
const homeworkParamsSchema = createHomeworkSchema.pick({
classId: true,
courseId: true,
title: true,
content: true,
assignDate: true,
});
const notificationParamsSchema = createNotificationSchema.pick({
classId: true,
title: true,
content: true,
priority: true,
});
const callParamsSchema = z.object({
classId: z.string().min(1),
studentId: z.string().min(1).optional(),
studentName: z.string().trim().max(40).optional(),
message: z.string().trim().max(200).optional(),
});
const modelReplySchema = z.object({
action: z.enum(['create_homework', 'create_notification', 'call_student', 'unknown']),
params: z.record(z.string(), z.unknown()).default({}),
confidence: z.number().min(0).max(1).optional(),
reason: z.string().max(200).optional(),
});
export async function getAiSettings(): Promise<AiSettingsDto> {
const values = await getSettings([
SETTING_KEYS.aiEnabled,
SETTING_KEYS.aiProvider,
SETTING_KEYS.aiBaseUrl,
SETTING_KEYS.aiModel,
SETTING_KEYS.aiReasoningEffort,
SETTING_KEYS.aiApiKey,
SETTING_KEYS.aiSystemPromptExtra,
]);
@@ -76,6 +23,11 @@ export async function getAiSettings(): Promise<AiSettingsDto> {
provider: values[SETTING_KEYS.aiProvider] === 'mock' ? 'mock' : 'openai',
baseUrl: values[SETTING_KEYS.aiBaseUrl] ?? '',
model: values[SETTING_KEYS.aiModel] ?? '',
reasoningEffort: (['none', 'low', 'medium', 'high', 'max'].includes(
values[SETTING_KEYS.aiReasoningEffort] ?? '',
)
? values[SETTING_KEYS.aiReasoningEffort]
: 'auto') as AiSettingsDto['reasoningEffort'],
hasApiKey: apiKey.length > 0,
keyHint: apiKey.length >= 4 ? apiKey.slice(-4) : '',
systemPromptExtra: values[SETTING_KEYS.aiSystemPromptExtra] ?? '',
@@ -87,6 +39,8 @@ export async function updateAiSettings(
input: UpdateAiSettingsInput,
): Promise<AiSettingsDto> {
assertAdmin(user);
if (input.reasoningEffort !== undefined)
await setSetting(SETTING_KEYS.aiReasoningEffort, input.reasoningEffort);
if (input.enabled !== undefined) await setSetting(SETTING_KEYS.aiEnabled, input.enabled ? 'true' : 'false');
if (input.provider !== undefined) await setSetting(SETTING_KEYS.aiProvider, input.provider);
if (input.baseUrl !== undefined) await setSetting(SETTING_KEYS.aiBaseUrl, input.baseUrl.trim());
@@ -102,304 +56,11 @@ export async function updateAiSettings(
return getAiSettings();
}
interface AssistantContext {
classes: { id: string; name: string }[];
courses: { id: string; name: string }[];
export async function interpret(user: TokenPayload, input: AiInterpretInput) {
const { interpretConversation } = await import('./conversation.js');
return interpretConversation(user, input);
}
async function resolveContext(user: TokenPayload, classId?: string): Promise<AssistantContext> {
if (classId) await assertClassAccess(user, classId, 'ai:use');
await assertPermission(user, 'ai:use');
const candidates = new Set(
(
await Promise.all(
['notification:publish', 'homework:write', 'call:create'].map((key) =>
classIdsFor(user, key as PermissionKey),
),
)
).flat(),
);
const classIds = (await getAccessibleClassIds(user, 'ai:use')).filter((id) => candidates.has(id));
const classes = await prisma.class.findMany({
where: {
id: { in: classIds },
...(user.role !== 'ADMIN'
? { OR: [{ teacherId: user.sub }, { courses: { some: { teacherId: user.sub } } }] }
: {}),
},
select: { id: true, name: true },
orderBy: { name: 'asc' },
take: 80,
});
const courses =
classId && classIds.includes(classId)
? await prisma.course.findMany({ where: { classId }, select: { id: true, name: true } })
: [];
return { classes, courses };
}
function buildSystemPrompt(context: AssistantContext, extra: string): string {
return [
'你是班级管理系统的指令解析器。把老师的一句中文转成严格 JSON,不要输出任何解释。',
'可选动作(action):create_homework(布置作业)、create_notification(发通知)、call_student(叫学生来)、unknown(看不懂)。',
'输出格式:{"action":"…","params":{…},"confidence":0~1}。',
'create_homework 的 params:{classId, courseId?, title, content, assignDate?(YYYY-MM-DD)}。',
'create_notification 的 params:{classId, title, content, priority?(LOW|NORMAL|HIGH|URGENT)}。',
'call_student 的 params:{classId, studentName, message?}。',
`今天日期:${dayKeyLocal(new Date())}。`,
`可用班级:${context.classes.map((item) => `${item.name}(${item.id})`).join('、') || '无'}。`,
context.courses.length
? `候选班级的科目:${context.courses.map((item) => `${item.name}(${item.id})`).join('、')}。`
: '未指定班级时 courseId 留空。',
'信息不足时把 confidence 压低并在 reason 里说明缺什么;不要编造不存在于上面的班级/科目 id。',
extra ? `学校额外要求:${extra}` : '',
]
.filter(Boolean)
.join('\n');
}
/** 离线确定性解析(provider=mock):只做关键词判断,供自动化与"没配模型时试跑"用 */
function mockInterpret(text: string, context: AssistantContext): z.infer<typeof modelReplySchema> {
// 优先用句子里**真正提到的**班级(「给2026级1班布置作业」);都没提到才退回按名称升序的第一个。
// (曾经只取第一个,结果本机取到了已归档的 2023级1班,与句子里说的班级无关。)
const mentioned = context.classes.find((item) => text.includes(item.name));
const classId = mentioned?.id ?? context.classes[0]?.id ?? '';
if (!classId) return { action: 'unknown', params: {}, confidence: 0.1, reason: '当前账号没有可发布的班级' };
const course = context.courses.find((item) => text.includes(item.name));
if (/作业|布置|卷子|练习|预习|背诵/.test(text)) {
return {
action: 'create_homework',
params: {
classId,
courseId: course?.id ?? null,
title: text.length <= 40 ? text : `${text.slice(0, 38)}…`,
content: text,
assignDate: dayKeyLocal(new Date()),
},
confidence: 0.55,
};
}
if (/通知|告知|提醒|传达/.test(text)) {
return {
action: 'create_notification',
params: {
classId,
title: text.length <= 40 ? text : `${text.slice(0, 38)}…`,
content: text,
priority: /紧急|立即|马上/.test(text) ? 'URGENT' : 'NORMAL',
},
confidence: 0.55,
};
}
if (/叫|找|来一趟|办公室/.test(text)) {
const matched = /\S{2,4}(?=同学|来|到)/.exec(text);
return {
action: 'call_student',
params: { classId, studentName: matched?.[0] ?? '', message: text },
confidence: 0.4,
reason: '离线示例解析只按关键词猜测学生姓名',
};
}
return { action: 'unknown', params: {}, confidence: 0.2, reason: '没听懂要做什么' };
}
async function callOpenAi(
input: AiInterpretInput,
extension: { baseUrl: string; model: string; apiKey: string; prompt: string },
): Promise<z.infer<typeof modelReplySchema>> {
let response: Response;
try {
response = await fetch(`${extension.baseUrl.replace(/\/+$/, '')}/chat/completions`, {
method: 'POST',
headers: {
'content-type': 'application/json',
authorization: `Bearer ${extension.apiKey}`,
},
body: JSON.stringify({
model: extension.model || 'gpt-4o-mini',
temperature: 0.2,
response_format: { type: 'json_object' },
messages: [
{ role: 'system', content: extension.prompt },
{ role: 'user', content: input.text },
],
}),
signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
});
} catch (error) {
throw new ApiError(
504,
'AI_TIMEOUT',
`无法连接大模型服务:${error instanceof Error ? error.message : String(error)}`,
);
}
if (!response.ok) {
throw ApiError.badRequest(`大模型服务返回 HTTP ${response.status}(请检查服务地址、模型名与密钥)`);
}
const body = (await response.json()) as { choices?: { message?: { content?: string } }[] };
const content = body.choices?.[0]?.message?.content ?? '';
try {
return modelReplySchema.parse(JSON.parse(content));
} catch {
logger.warn(`大模型返回无法解析:${content.slice(0, 200)}`);
throw new ApiError(502, 'AI_INVALID_OUTPUT', '大模型返回的内容不是可用的指令,请换一种说法');
}
}
/** 把校验通过的参数解析成"给人看的预览"(班级/科目/学生名都换成中文) */
async function buildPreview(
action: AiActionKind,
params: Record<string, unknown>,
): Promise<AiInterpretResult['preview']> {
const warnings: string[] = [];
const classId = typeof params.classId === 'string' ? params.classId : '';
const classRecord = classId
? await prisma.class.findUnique({ where: { id: classId }, select: { name: true } })
: null;
if (action === 'create_homework') {
const courseId = typeof params.courseId === 'string' ? params.courseId : '';
const course = courseId
? await prisma.course.findUnique({ where: { id: courseId }, select: { name: true } })
: null;
if (!course) warnings.push('没有指定科目:只有班主任/管理员能发不指定科目的作业');
return {
summary: `给${classRecord?.name ?? '未知班级'}布置作业:${String(params.title ?? '')}`,
className: classRecord?.name ?? null,
courseName: course?.name ?? null,
warnings,
};
}
if (action === 'create_notification') {
return {
summary: `给${classRecord?.name ?? '未知班级'}发通知:${String(params.title ?? '')}`,
className: classRecord?.name ?? null,
warnings,
};
}
if (action === 'call_student') {
const studentName = typeof params.studentName === 'string' ? params.studentName : '';
const student =
studentName && classId
? await prisma.student.findFirst({
where: { classId, name: studentName, ...activeStudentWhere() },
select: { id: true, name: true },
})
: null;
if (!student) warnings.push(studentName ? `没找到学生「${studentName}」` : '没识别出学生姓名');
return {
summary: `叫${student?.name ?? (studentName || '某位同学')}到老师这里`,
className: classRecord?.name ?? null,
studentName: student?.name ?? (studentName || null),
warnings,
};
}
return { summary: '没听懂要做什么,请换一种说法', warnings: ['助手没有解析出可用动作'] };
}
/**
* POST /api/ai/interpret - 解析一句中文,返回**待确认**的结构化动作。
* 绝不写业务表;只写一条 `AiAudit`(谁在什么时候让助手做了什么)。
*/
export async function interpret(user: TokenPayload, input: AiInterpretInput): Promise<AiInterpretResult> {
const settings = await getAiSettings();
if (!settings.enabled) {
throw new ApiError(400, 'AI_NOT_CONFIGURED', '助手功能还没开启,请管理员在「大模型设置」里打开');
}
if (settings.provider === 'openai' && (!settings.hasApiKey || !settings.baseUrl)) {
throw new ApiError(
400,
'AI_NOT_CONFIGURED',
'还没配置大模型服务地址或密钥,请管理员在「大模型设置」里填写',
);
}
const context = await resolveContext(user, input.classId);
const reply =
settings.provider === 'mock'
? mockInterpret(input.text, context)
: await callOpenAi(input, {
baseUrl: settings.baseUrl,
model: settings.model,
apiKey: decryptSecret(await getSetting(SETTING_KEYS.aiApiKey)),
prompt: buildSystemPrompt(context, settings.systemPromptExtra),
});
// 用与手动入口同一份 zod 再校验一次:模型给的东西**不可信**
let action: AiActionKind = 'unknown';
let params: Record<string, unknown> = {};
const warnings: string[] = [];
try {
if (reply.action === 'create_homework') {
const parsed = homeworkParamsSchema.parse({
...reply.params,
classId: reply.params.classId ?? input.classId,
});
action = 'create_homework';
params = parsed as unknown as Record<string, unknown>;
} else if (reply.action === 'create_notification') {
const parsed = notificationParamsSchema.parse({
...reply.params,
classId: reply.params.classId ?? input.classId,
});
action = 'create_notification';
params = parsed as unknown as Record<string, unknown>;
} else if (reply.action === 'call_student') {
const parsed = callParamsSchema.parse({
...reply.params,
classId: reply.params.classId ?? input.classId,
});
action = 'call_student';
params = parsed as unknown as Record<string, unknown>;
}
} catch (error) {
warnings.push('助手给出的参数不完整,请手动补全后再发布');
logger.warn(`助手参数校验失败:${error instanceof Error ? error.message : String(error)}`);
}
if (typeof params.classId === 'string') {
await assertClassAccess(user, params.classId, 'ai:use');
if (typeof params.courseId === 'string') {
const course = await prisma.course.findFirst({
where: { id: params.courseId, classId: params.classId },
select: { id: true },
});
if (!course) throw ApiError.badRequest('科目不属于所选班级');
}
}
const preview = await buildPreview(action, params);
preview.warnings = [...preview.warnings, ...warnings];
if (settings.provider === 'mock') preview.warnings.push('当前是离线示例解析(未配置真实模型),请仔细核对');
await prisma.aiAudit.create({
data: {
userId: user.sub,
prompt: input.text,
intent: action,
// 审计只记录解析,不代表前端确认后的业务操作已执行。
status: action === 'unknown' ? 'unrecognized' : 'interpreted',
message: preview.summary,
rawReply: JSON.stringify(reply).slice(0, 2000),
},
});
return {
action,
params,
preview,
confidence: reply.confidence ?? 0.5,
needConfirm: true,
rawReply: null,
};
}
/** GET /api/ai/audit - 助手使用审计(最近 N 条) */
export async function listAudit(limit = 50): Promise<AiAuditDto[]> {
const rows = await prisma.aiAudit.findMany({ orderBy: { createdAt: 'desc' }, take: limit });
// `AiAudit.userId` 是普通字符串列(schema 里没有建 User 关系),所以姓名另外查一次
@@ -0,0 +1,123 @@
import express, { type ErrorRequestHandler } from 'express';
import { IncomingMessage, ServerResponse } from 'node:http';
import { Socket } from 'node:net';
import { signToken, type TokenPayload } from '../../lib/jwt.js';
import { ApiError } from '../../lib/http.js';
/** 这里的每个入口都不修改业务数据。方法和路径不能由模型或调用方提供。 */
export const READ_ROUTES = {
'classes.list': ['/classes', '班级列表'],
'classes.detail': ['/classes/:id', '班级详情'],
'classes.students': ['/classes/:id/students', '班级名单'],
'courses.list': ['/courses', '课程列表'],
'students.list': ['/students', '学生列表'],
'students.transfers': ['/students/transfers', '调班记录'],
'teachers.list': ['/teachers', '教师列表'],
'homeworks.list': ['/homeworks', '作业列表'],
'homeworks.detail': ['/homeworks/:id', '作业详情'],
'homeworks.submissions': ['/homeworks/:id/submissions', '作业提交名单'],
'notifications.list': ['/notifications', '通知列表'],
'courseware.list': ['/courseware', '课件列表'],
'courseware.classes': ['/courseware/classes', '可推送班级'],
'courseware.folders': ['/courseware/folders', '课件文件夹'],
'courseware.detail': ['/courseware/:id', '课件详情'],
'grades.list': ['/grades', '成绩列表'],
'grades.stats': ['/grades/stats', '成绩统计'],
'grades.exams': ['/grades/exams', '考试列表'],
'grades.ranking': ['/grades/ranking', '考试排名'],
'grades.student': ['/grades/student/:studentNo', '学生成绩'],
'plans.list': ['/class-plans', '课表列表'],
'plans.profile': ['/class-plans/profile', '完整课表档案'],
'plans.export': ['/class-plans/:id/export', '课表内容'],
'schedules.grid': ['/schedules/grid', '当前周课表'],
'schedules.scheduled': ['/schedules/scheduled', '预定和临时课表'],
'layouts.list': ['/time-layouts', '时间表列表'],
'groups.list': ['/class-plan-groups', '课表群组'],
'groups.selection': ['/class-plan-groups/selection', '当前课表选择'],
'term.weeks': ['/term', '学期周次'],
'promotion.status': ['/term/promotion', '升学计划'],
'promotion.preview': ['/term/promotion', '升级影响预览'],
'archives.list': ['/archives', '毕业档案'],
'archives.detail': ['/archives/:id', '档案详情'],
'archives.transferred': ['/archives/transferred', '转出名单'],
'archives.content': ['/archives/:id/classes/:classId/content', '历史班级内容'],
'clients.list': ['/clients/devices', '客户端设备'],
'clients.releases': ['/update/client/releases', '客户端安装包缓存'],
'permissions.catalog': ['/permissions/catalog', '权限目录'],
'permissions.groups': ['/permissions/groups', '岗位模板'],
'permissions.users': ['/permissions/users', '账号权限'],
'permissions.effective': ['/permissions/users/:id/effective', '账号有效权限'],
'permissions.members': ['/permissions/groups/:id/members', '岗位成员'],
'permissions.scopes': ['/permissions/scopes', '可分配范围'],
'dashboard.summary': ['/dashboard', '工作台概览'],
} as const;
export type ReadAction = keyof typeof READ_ROUTES;
export function readPath(action: ReadAction, target: Record<string, string>): string {
return READ_ROUTES[action][0].replace(/:([A-Za-z]+)/g, (_match, key: string) => {
if (!target[key] || !/^[\p{L}\p{N}_-]+$/u.test(target[key]))
throw ApiError.badRequest(`请明确目标 ${key}`);
return encodeURIComponent(target[key]);
});
}
/** 仅 GET 白名单,在进程内经过原路由的鉴权和校验,不监听端口。 */
export async function readBusinessAction(
user: TokenPayload,
action: string,
target: Record<string, string> = {},
query: Record<string, unknown> = {},
): Promise<unknown> {
if (!Object.hasOwn(READ_ROUTES, action)) throw ApiError.forbidden('此动作不是允许的查询');
const path = readPath(action as ReadAction, target);
const { apiModules } = await import('../registry.js');
const module = apiModules.find((item) => path === item.basePath || path.startsWith(`${item.basePath}/`));
if (
!module ||
['ai', 'auth', 'database', 'system'].includes(module.name) ||
(module.name === 'update' && (action !== 'clients.releases' || path !== '/update/client/releases'))
)
throw ApiError.forbidden('禁止助手访问此模块');
const app = express();
app.use(`/api${module.basePath}`, module.router);
return new Promise((resolve, reject) => {
const onError: ErrorRequestHandler = (error, _req, _res, _next) => reject(error);
app.use(onError);
const req = new IncomingMessage(new Socket());
const search = new URLSearchParams();
for (const [key, value] of Object.entries(query))
if (value !== undefined && value !== null) search.set(key, String(value));
req.url = `/api${path}${search.size ? `?${search}` : ''}`;
req.method = 'GET';
req.headers = { authorization: `Bearer ${signToken(user)}` };
const res = new ServerResponse(req);
res.end = ((chunk?: unknown) => {
try {
const response = JSON.parse(String(chunk ?? '{}')) as {
data?: unknown;
message?: string;
code?: string;
};
if (res.statusCode >= 400)
reject(new ApiError(res.statusCode, 'AI_READ_FAILED', response.message ?? '读取失败'));
else resolve(response.data);
} catch (error) {
reject(error);
}
return res;
}) as typeof res.end;
app(req, res);
});
}
export function redact(value: unknown): unknown {
if (value instanceof Date) return value.toISOString();
if (Array.isArray(value)) return value.map(redact);
if (value && typeof value === 'object')
return Object.fromEntries(
Object.entries(value)
.filter(([key]) => !/password|token|secret|api.?key|passwordHash|storagePath/i.test(key))
.map(([key, item]) => [key, redact(item)]),
);
return value;
}
Loaded 100 of 202 files, more files were not shown because too many files have changed in this diff. Show more