Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
79a31ebe9d | ||
|
|
8bd5bcb9ff | ||
|
|
3a7aed0800 | ||
|
|
3d7e551838 | ||
|
|
ff55c95ea0 | ||
|
|
81c96eebaf | ||
|
|
a0a6b50485 | ||
|
|
f60114af85 | ||
|
|
ff33d163e3 | ||
|
|
e49dd0bc39 |
No files matched your search
@@ -15,6 +15,8 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
|
||||
| `packages/server/` | Express、Prisma、Socket.IO;API 前缀 `/api` |
|
||||
| `packages/web-admin/` | Vue Web 管理端,PWA |
|
||||
| `packages/desktop-client/` | Electron 主进程、preload、主窗口与独立灵动岛渲染进程 |
|
||||
| `packages/data/` | 运行期课件、安装包等数据;不是 workspace 包,不作源码清理 |
|
||||
| `prompts/` | 可执行任务提示词;历史 `*.result.md` 仅为当时交付记录 |
|
||||
| `scripts/` | 版本、构建、验证、打包、图标与 Pages 脚本 |
|
||||
| `deploy/` | Windows/Linux/Docker 部署与运维模板 |
|
||||
| `docs/` | docfx 文档;`images/` 为展示图,`screenshots/` 为回归截图 |
|
||||
@@ -29,6 +31,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
|
||||
- 路由用 `middleware/validate.ts` 与 zod;响应复用 `lib/http.ts`,错误交给统一中间件。
|
||||
- 学生是 `Student` 名单记录,没有账号、角色或密码。教师/管理员存 `User`;班级登录读取 `Class.code/passwordHash`,会话角色 `CLASS_DEVICE`,主体 id 为班级 id。
|
||||
- 任课关系只在 `Course(classId, name, teacherId)`。班主任不自动获得别的科目的作业、成绩写权限,统一走 `lib/authz/assert.ts` 的 `assertContentWrite`。班级端可录作业,不可写成绩;员工还须对应功能权限。
|
||||
- 新建课程会建立任课关系,仅管理员可执行;课表维护范围不能用来给自己任课。现有课程的排课与外观维护仍按 `schedule:write` 和班级管理关系校验。
|
||||
- 功能、范围、关系统一由 `lib/authz/` 判定,所有服务显式传权限键。ADMIN 固定全部能力;TEACHER 永久忽略管理员专用键;CLASS_DEVICE 为空集,接口明确允许并校验本班。权限管理仅 ADMIN。
|
||||
- 岗位模板只管能力与建议范围,生效范围存 `UserPermissionGroup.scope/scopeValue`,使用 TEACHING/HEAD/GRADE/DIVISION/ALL。无显式分配的教师使用默认模板与固定 TEACHING;空或未知年级拒绝。按键独立合并范围,无键查询为空集;班级账号/学期设置永远要求本班班主任,科目写检查原/目标科目。具体断言和迁移见 `docs/dev/permissions.md`。
|
||||
- 只有一份 `prisma/schema.prisma`,切库改 provider;保持 SQLite/MySQL 通用,不加 Prisma enum 或 `@db.*`。模型变动同步迁移、`lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 与旧库兼容逻辑。
|
||||
@@ -95,6 +98,7 @@ pnpm monorepo,根 `package.json` 是版本单一来源。文档、注释、界
|
||||
$env:PATH = 'C:\Users\hck16\AppData\Local\deepseek-harness\bin;' + $env:PATH
|
||||
$env:DSH_NODE = 'D:\Node.js\node.exe'
|
||||
$env:DSH_PNPM_BIN = 'C:\Users\hck16\AppData\Local\node\corepack\v1\pnpm\11.8.0\bin\pnpm.cjs'
|
||||
$env:DSH_PREFER_BUNDLED_PNPM = '1'
|
||||
Remove-Item Env:DSH_PNPM -ErrorAction SilentlyContinue
|
||||
pnpm --version
|
||||
```
|
||||
@@ -108,6 +112,7 @@ Prisma 使用 driver adapter;本机优先应用已有迁移,不用 `migrate
|
||||
| `pnpm lint` / `pnpm typecheck` / `pnpm check:icons` | 代码静态门禁;按改动范围执行 |
|
||||
| `pnpm docs:check` | 文档严格构建,警告即失败 |
|
||||
| `pnpm verify:e2e` | 自动创建临时 SQLite 和账号,无需先开开发服务,禁止外网 |
|
||||
| `pnpm verify:authz` / `pnpm verify:audit` | 隔离授权攻击矩阵;审计事务、竞态、模型操作计数和 PWA |
|
||||
| `pnpm verify:web:isolated` | 构建 Web 后运行隔离服务和隐藏 UI 回归 |
|
||||
| `pnpm verify:courseware` / `pnpm verify:v14` | 课件/课表等隔离专项 |
|
||||
| `pnpm verify:desktop` / `pnpm verify:packaged --exe <路径>` | 默认后台快速检查,不创建可见岛或托盘 |
|
||||
@@ -116,7 +121,7 @@ Prisma 使用 driver adapter;本机优先应用已有迁移,不用 `migrate
|
||||
|
||||
禁止为验收回退到真实班级、重置其密码或发送测试通知。验收数量只记录本次实际输出。
|
||||
仅文档修改做格式、链接、构建检查,不为此反复占用桌面或重打安装包。
|
||||
Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化源码。
|
||||
Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化源码。根 `typecheck` 按包串行以限制峰值内存;若 Node 22 出现 V8 原生内存错误,记录失败并使用符合 engines 的已安装 Node LTS 复验,不删断言或依赖。
|
||||
改 Linux 交付脚本还要 bash 语法检查和 Linux 真机/CI 验证;改打包逻辑需打包后副本复验。
|
||||
|
||||
## 7. 发布与工作区清理
|
||||
@@ -125,7 +130,7 @@ Prettier 用 LF,只格式化本次改动;不要为旧基线批量格式化
|
||||
- 本地 `pnpm dist:all` 产出 Windows 服务端和客户端;Linux 正式包由 `release-linux-server.yml` 在 Linux runner 构建,非 Linux 交叉构建仅供验证。
|
||||
- 本地文件名与 Release 的 ASCII 上传名不同,校验清单应明确映射;保留当前版本清单、更新日志及最新包。
|
||||
- `releases/` 只放交付物及少量构建信息,不留 win-unpacked、服务端 staging、解包副本;staging 在 `.cache/server-staging/`,成功后脚本删除。
|
||||
- 2026-10-18 按用户要求清除 1.4.0 旧重构建归档,只保留 `client/1.4.0`、`server/1.4.0` 与当前清单/说明。以后同号重构建可临时留回滚副本,最新包验证完成且用户要求清理时再删除。
|
||||
- 各版本交付物以 `releases/` 现场目录为准,不沿用历史清理记录推断当前版本。同号重构建可临时留回滚副本,最新包验证完成且用户要求清理时再删除。
|
||||
- 递归删除/移动前核实绝对路径在指定工作区,禁止误删源代码、真实数据库、配置、凭据、工具缓存或其他版本交付物。
|
||||
- 不清理 `node_modules`、`.pnpm-store`、`.cache/{nuget,npm-cache,dotnet-home,mingit}`、`packages/*/dist`、生成的 Prisma Client,除非任务明确要求。
|
||||
- 保留已有未提交工作;提交前查看 diff,中文 Conventional Commits 描述。只有用户要求发布/同步时才执行远端发布链。
|
||||
@@ -161,7 +161,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。<br/>
|
||||
| 教室机器 / 学生电脑 | **学生客户端** | `ClassHelper-<版本>-x64-client-setup.exe`,或 `-client-portable.exe` 免安装 |
|
||||
|
||||
也可以在官网的[下载页](https://lovechengke.github.io/ClassHelper/download.html)上挑:
|
||||
选一个版本,四个包排成四张卡,文件名、体积与 SHA256 清单都在那儿 ——
|
||||
选一个版本,按客户端、Windows 服务端和 Linux 服务端展示下载卡片,文件名、体积与 SHA256 清单都在那儿 ——
|
||||
那一页的清单是**当场**读 GitHub Releases 的,显示什么就能下什么。
|
||||
|
||||
服务端**装上就算跑起来了**:双击安装程序,建库、建号、开机自启都由它自己办,
|
||||
@@ -180,7 +180,7 @@ curl -fsSL -o /tmp/classhelper-install.sh https://raw.githubusercontent.com/Love
|
||||
## 获取帮助
|
||||
|
||||
- **使用文档**:[docs/](docs/index.md) —— 分四块:第一次装、已经在用了、负责运维、要改代码
|
||||
- **完整参考**:[docs/reference.md](docs/reference.md) —— 功能口径、REST API、权限矩阵、验收证据
|
||||
- **功能与源码索引**:[docs/reference.md](docs/reference.md) —— 各帮助章节、开发契约与源码入口
|
||||
- **遇到问题 / 想提需求**:[提交 Issue](https://github.com/LoveChengke/ClassHelper/issues/new/choose)
|
||||
|
||||
## 开发
|
||||
@@ -198,11 +198,11 @@ cp packages/server/.env.example packages/server/.env # 至少改 JWT_SECRET
|
||||
pnpm db:generate
|
||||
pnpm --filter @classhelper/server db:deploy # 根 scripts 里没有 db:deploy
|
||||
pnpm build:shared # 三端与 seed 的前置产物
|
||||
pnpm db:seed
|
||||
# 仅新建演示库时按需执行 pnpm db:seed(会清空业务表)
|
||||
pnpm dev # 后端 4000 + Web 端 5173
|
||||
```
|
||||
|
||||
`pnpm db:seed` 会写一套演示数据(1 管理员 / 2 教师 / 3 个班 / 15 名学生 / 课表 / 作业 / 通知 / 成绩):
|
||||
`pnpm db:seed` 会清空并写入演示账号、班级、学生、课表与教学内容,仅用于独立演示库:
|
||||
|
||||
| 角色 | 账号 | 密码 |
|
||||
| -------------------------- | ------------- | ------------ |
|
||||
|
||||
@@ -23,7 +23,7 @@ services:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
image: classhelper-server:${APP_VERSION:-1.4.2}
|
||||
image: classhelper-server:${APP_VERSION:-1.4.3}
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
|
||||
@@ -60,7 +60,7 @@ services:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
image: classhelper-server:${APP_VERSION:-1.4.2}
|
||||
image: classhelper-server:${APP_VERSION:-1.4.3}
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
NODE_ENV: production
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "classhelper-server-runtime",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"description": "ClassHelper 服务端运行时(安装包 / 容器内置)",
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: AI 助手
|
||||
description: 将自然语言解析成待确认动作,核对后通过现有业务接口发布。
|
||||
---
|
||||
|
||||
# AI 助手
|
||||
|
||||
AI 助手位于 Web 管理端工作台。输入要发布的作业、通知或叫人请求,助手会展示解析出的班级、科目、内容与提醒级别;核对并确认后才发布。内容仍通过原有业务接口,继续校验当前账号的功能权限、班级范围及任课关系。
|
||||
|
||||
## 配置与使用
|
||||
|
||||
管理员在大模型设置中开启助手,选择服务地址和模型并保存 API Key。密钥加密存储,读取设置只返回是否已配置及末尾提示,不返回完整密钥。修改服务端 JWT 密钥后,原有加密 Key 需要重新配置。
|
||||
|
||||
1. 在助手页面描述操作与目标班级,等待解析预览。
|
||||
2. 核对班级、科目、标题、正文和提醒级别;有歧义时修改后重新解析。
|
||||
3. 点击确认发布。紧急通知在上课期间仍需完成额外确认;批量操作逐班返回结果。
|
||||
|
||||
解析成功不代表已经发布,也不代表拥有对应班级或科目的写权限。缺少任课关系时,请由管理员配置;助手不能替用户建立授权。
|
||||
|
||||
## 离线示例与审计
|
||||
|
||||
`mock` 提供确定性的离线示例解析,用于自动化验收,不访问外网;预览会提示当前为示例结果。真实模型调用失败时页面保留可操作的错误说明,不会自动改用发布接口。
|
||||
|
||||
有管理权限的账号可查看助手审计。审计记录解析意图和状态,不代替作业、通知或叫人的最终发布结果;请结合对应业务页面核对。
|
||||
|
||||
相关规则:[作业](homeworks.md)、[通知](notifications.md)、[叫人](calls.md)、[角色与权限](../dev/permissions.md)。
|
||||
@@ -32,6 +32,8 @@ Student 存学号、姓名、班级、性别、家长电话和状态,没有密
|
||||
科任关系唯一存于 Course(classId, name, teacherId),分配任课关系由班级管理权限及服务端断言限制。
|
||||
班主任不任教某科就不能修改该科作业/成绩;科任老师有相应权限时可以管理自己任教科目。
|
||||
|
||||
新建科目同时建立任课关系,只对管理员开放。教师需要增加科目或改变任课老师时,请联系管理员;年级、部或全校课表维护范围不能用来给自己任课。
|
||||
|
||||
删除教师前,服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件;仍有业务内容则返回冲突,避免级联丢失。
|
||||
教师本人改密码、管理员修改教师密码、班级账号密码是不同入口;学生没有密码接口。
|
||||
|
||||
|
||||
+3
-1
@@ -6,11 +6,13 @@ description: 录入、按学号查询、排名与关闭个人查询后的集体
|
||||
# 成绩
|
||||
|
||||
Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。
|
||||
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。
|
||||
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。新增科目及任课关系由管理员配置。
|
||||
成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查:
|
||||
管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。
|
||||
表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。
|
||||
|
||||
整班批量录入在同一事务中校验学生、授权并写入成绩;任意一行无效或写入失败时整批回滚,不留下部分成绩。等级批量修改按每个班级与科目组合独立检查授权。
|
||||
|
||||
## 查看、排名与隐私
|
||||
|
||||
班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。
|
||||
|
||||
@@ -10,6 +10,7 @@ description: ClassHelper每一项功能怎么用:课表、作业、通知、
|
||||
|
||||
| 页面 | 讲什么 |
|
||||
| --------------------------------- | ---------------------------------------------------------- |
|
||||
| [AI 助手](assistant.md) | 自然语言解析、核对确认、业务权限与离线示例 |
|
||||
| [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 |
|
||||
| [课件](courseware.md) | 上传、班级可见范围、推送与逐设备接收 |
|
||||
| [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
|
||||
|
||||
@@ -22,6 +22,8 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编
|
||||
|
||||
时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。
|
||||
可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
|
||||
|
||||
新增科目会建立任课关系,仅管理员可执行;课表维护者可以使用已配置的科目排课,需要新增或更换任课老师时联系管理员。
|
||||
时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。
|
||||
|
||||
日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
- name: 应用帮助
|
||||
href: index.md
|
||||
- name: AI 助手
|
||||
href: assistant.md
|
||||
- name: 课表
|
||||
href: schedules.md
|
||||
- name: 作业
|
||||
|
||||
+2
-2
@@ -34,7 +34,7 @@ function readVersion() {
|
||||
|
||||
/** 找不到 docfx 时给出可照抄的安装命令,而不是一句 spawn ENOENT */
|
||||
function ensureDocfx() {
|
||||
const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' });
|
||||
const probe = spawnSync('docfx', ['--version'], { encoding: 'utf8' });
|
||||
if (probe.status === 0) return probe.stdout.trim();
|
||||
|
||||
console.error('[docs] 找不到 docfx。docfx 是 .NET 工具,安装方式:');
|
||||
@@ -50,7 +50,7 @@ function ensureDocfx() {
|
||||
|
||||
function run(command, args, options = {}) {
|
||||
return new Promise((resolve, reject) => {
|
||||
const child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32', ...options });
|
||||
const child = spawn(command, args, { stdio: 'inherit', ...options });
|
||||
child.on('error', reject);
|
||||
child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${command} 退出码 ${code}`))));
|
||||
});
|
||||
|
||||
@@ -25,6 +25,8 @@ ClassHelper 是 pnpm workspace:Express/Prisma/Socket.IO 服务端、Vue Web
|
||||
| `packages/desktop-client/src/island/` | 经典岛、自定义运行时、课程与课件提醒 |
|
||||
| `packages/desktop-client/src/renderer/` | 主窗口页面、状态、IndexedDB 与岛桥接 |
|
||||
| `scripts/` / `deploy/` | 验证、版本、打包、部署与运维 |
|
||||
| `packages/data/` | 运行期数据,非 workspace 包 |
|
||||
| `prompts/` | 任务提示词与历史交付记录 |
|
||||
| `docs/` / `website/` | 文档站与官网,Pages 构建时拼接 |
|
||||
|
||||
## 模块与数据流
|
||||
|
||||
+3
-3
@@ -5,9 +5,9 @@ description: ClassHelper的架构、接口、数据模型、权限、动效层
|
||||
|
||||
# 开发文档
|
||||
|
||||
ClassHelper是一个 **pnpm monorepo**,一份代码产出四个交付物:
|
||||
ClassHelper 是一个 **pnpm monorepo**,应用包含后端服务、Web 管理端与桌面客户端;共享契约是内部依赖包:
|
||||
|
||||
| 交付物 | 位置 | 形态 |
|
||||
| 组成 | 位置 | 形态 |
|
||||
| ---------- | ------------------------- | --------------------------------------------------------------- |
|
||||
| 后端服务 | `packages/server` | Express 5 + Prisma 7 + Socket.IO,接口前缀 `/api` |
|
||||
| Web 管理端 | `packages/web-admin` | Vue 3 + Vite + Element Plus(教师 / 管理员用,PWA 可安装) |
|
||||
@@ -23,7 +23,7 @@ ClassHelper是一个 **pnpm monorepo**,一份代码产出四个交付物:
|
||||
后端服务(Express + Prisma)
|
||||
│ 写库 + 按班级房间广播
|
||||
▼
|
||||
Socket.IO ──► class:{classId} 房间 ──► 学生桌面客户端实时更新 UI(含灵动岛)
|
||||
Socket.IO ──► class:{classId}:{channel} 房间 ──► 班级桌面客户端实时更新 UI(含灵动岛)
|
||||
|
||||
▲ │
|
||||
└──── 老师下发的提醒 ◄──────┘
|
||||
|
||||
@@ -55,6 +55,8 @@ description: 能力目录、岗位模板、分配范围与业务关系的授权
|
||||
|
||||
ALL 也不能替代班主任、任课、发布者关系,只有 ADMIN 无条件绕过关系。班级端可代录作业,不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接,不能因事务路径省略授权。
|
||||
|
||||
`POST /courses` 会建立任课关系,仅管理员可新建。教师的日课表维护范围不授予建课或自分配任课资格;已有课程仍可按课表权限排课及维护外观。离线档案导入复用既有科目,新增占位科目按班主任归属,不采信导入文件中的教师姓名作为授权。
|
||||
|
||||
成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后,本班设备仍可获得集体聚合,个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护,服务端执行稀疏样本和补集抑制。
|
||||
|
||||
## 实时与设备
|
||||
|
||||
+1
-1
@@ -30,7 +30,7 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版
|
||||
|
||||
以上按发布改动范围执行;显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
|
||||
完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本,最新包核验完成后按用户要求清理旧归档。
|
||||
2026-10-18 工作区清理后,1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
|
||||
版本目录与清单以本次实际构建结果为准;历史清理记录不代表当前保留的版本。
|
||||
|
||||
## 产物与文件名
|
||||
|
||||
|
||||
+4
-1
@@ -23,7 +23,9 @@ description: 隔离 API、隐藏 UI、后台客户端与显式视觉验收。
|
||||
| pnpm verify:client-agent | 假系统适配器验证命令、回执和更新策略 |
|
||||
| pnpm verify:client-migrations | 临时旧库验证迁移、联动退役与默认组持久化 |
|
||||
| pnpm verify:review-client | 无窗口逻辑回归 |
|
||||
| pnpm verify:review-api / pnpm verify:clients-api | 需明确准备的隔离测试服务,使用 VERIFY_BASE_URL 等脚本参数 |
|
||||
| pnpm verify:review-api / pnpm verify:clients-api | 包装器自动创建临时 SQLite、账号和随机端口服务,无需手动准备服务 |
|
||||
| pnpm verify:authz | 隔离授权攻击矩阵,覆盖按键范围、身份、任课与实时订阅 |
|
||||
| pnpm verify:audit | 隔离事务故障、任课自授权、并发已读、模型操作计数和 Service Worker 回归 |
|
||||
| pnpm verify:desktop | 先 pnpm build:desktop;隐藏快速检查,独立 userData |
|
||||
| pnpm verify:desktop:online | 显式联网,需要测试管理员并创建临时教师/班级 |
|
||||
| pnpm verify:desktop:visual | 显式使用桌面,完整岛几何/动画/透明度/截图检查 |
|
||||
@@ -62,6 +64,7 @@ pnpm verify:web:isolated
|
||||
- 视觉用例需要真实桌面与稳定帧,先区分状态未稳定、窗口遮挡和实际回归,再针对原因重跑。
|
||||
- Element Plus dialog 关闭后 DOM 仍保留,应检查 overlay 的可见状态。
|
||||
- 本地 HTTP 探测绕过代理;Prisma 生成物和 shared/dist 缺失时先补前置构建。
|
||||
- 根类型检查按包串行控制峰值内存;Node 22 若出现 V8 原生内存错误,保留失败日志,使用满足 engines 的已安装 Node LTS 复验,记录实际版本。
|
||||
|
||||
## 截图
|
||||
|
||||
|
||||
@@ -25,6 +25,7 @@ Web 管理端有一个「数据库管理」页(`/database`,**仅管理员可
|
||||
|
||||
- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出;
|
||||
- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联,表清单与恢复顺序由 `lib/snapshot.ts` 统一维护;
|
||||
- 清空与重新写入属于同一事务;中途写入失败时回滚并保留原库。MySQL 的外键开关在该事务的同一连接上恢复,SQLite 在事务前后切换;
|
||||
- 分批 `createMany` 写入。
|
||||
|
||||
相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复;格式与缺失表由快照校验器检查。
|
||||
|
||||
+3
-2
@@ -9,12 +9,13 @@ description: 当前功能说明、开发契约与实现入口,避免重复维
|
||||
旧任务书、历史审查结论和旧构建验收数字不作为当前功能依据。
|
||||
|
||||
| 主题 | 文档 | 工作区源码入口 |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| 架构与模块 | [架构总览](dev/architecture.md) | `server/src/modules/registry.ts` |
|
||||
| 日课表、作息与轮换 | [课表](app/schedules.md) | `server/src/lib/class-plan.ts`、`modules/class-plans/` |
|
||||
| 学生、教师、班级 | [班级、学生与教师](app/classes.md) | `server/src/lib/access.ts`、`modules/students/` |
|
||||
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/permission-scope.ts` |
|
||||
| 权限组与岗位范围 | [角色与权限](dev/permissions.md) | `shared/src/permissions.ts`、`server/src/lib/authz/`、`server/src/lib/permissions.ts` |
|
||||
| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` |
|
||||
| AI 助手 | [解析与确认发布](app/assistant.md) | `server/src/modules/ai/`、`web-admin/src/views/AssistantView.vue` |
|
||||
| 通知与叫人 | [通知](app/notifications.md)、[叫人](app/calls.md) | `server/src/modules/notifications/`、`calls/` |
|
||||
| 课件 | [课件上传与传输](app/courseware.md) | 三端 `courseware` 模块与 `shared/src/courseware.ts` |
|
||||
| 成绩与隐私 | [成绩](app/grades.md) | `server/src/modules/grades/` |
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "class-helper",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"description": "ClassHelper - 班级信息管理系统(Web 管理端 + 后端服务 + 桌面客户端)",
|
||||
"packageManager": "pnpm@11.8.0",
|
||||
@@ -16,7 +16,7 @@
|
||||
"build": "pnpm build:shared && pnpm --filter @classhelper/server build && pnpm --filter @classhelper/web-admin build && pnpm --filter @classhelper/desktop-client build",
|
||||
"build:desktop": "pnpm build:shared && pnpm --filter @classhelper/desktop-client build",
|
||||
"check:icons": "node scripts/check-icons.mjs",
|
||||
"typecheck": "pnpm build:shared && pnpm -r --no-bail typecheck",
|
||||
"typecheck": "pnpm build:shared && pnpm -r --workspace-concurrency=1 --no-bail typecheck",
|
||||
"lint": "node scripts/check-authz.mjs && eslint .",
|
||||
"lint:fix": "eslint . --fix",
|
||||
"format": "prettier --write \"**/*.{ts,js,mjs,cjs,vue,json,md,yaml,yml,css,scss,html}\"",
|
||||
@@ -59,6 +59,7 @@
|
||||
"verify:desktop:visual": "node packages/desktop-client/scripts/smoke.mjs --visual",
|
||||
"verify:desktop:online": "node packages/desktop-client/scripts/smoke.mjs --online",
|
||||
"verify:authz": "node scripts/verify-authz.mjs",
|
||||
"verify:audit": "node scripts/verify-authz.mjs --audit && node scripts/verify-web-worker.mjs",
|
||||
"check:authz": "node scripts/check-authz.mjs",
|
||||
"verify:server-bootstrap": "node scripts/verify-server-bootstrap.mjs"
|
||||
},
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/desktop-client",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"description": "ClassHelper EXE 客户端(Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存)",
|
||||
"author": "Class Helper",
|
||||
|
||||
@@ -392,7 +392,9 @@ export async function verifyResidentSmoke(
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const immediate = (await waitForCourse()) && Date.now() - started < 600;
|
||||
const ready = await waitForCourse();
|
||||
const latencyMs = Date.now() - started;
|
||||
const immediate = ready && latencyMs < 600;
|
||||
const aligned = await win.webContents.executeJavaScript(`(() => {
|
||||
const name=document.querySelector('.resident-compact .schedule strong')?.getBoundingClientRect(), time=document.querySelector('.resident-compact .lesson-time')?.getBoundingClientRect();
|
||||
return Boolean(name&&time&&time.left>=name.right&&Math.abs(time.top+time.height/2-name.top-name.height/2)<=2);
|
||||
@@ -405,7 +407,12 @@ export async function verifyResidentSmoke(
|
||||
island.syncCustomLayout();
|
||||
await pause(800);
|
||||
island.setClassState({ inClass: true, currentPeriodEnd: null, week: 1, schedules: [] });
|
||||
return immediate && aligned && restored && snapshot[0]?.course?.name === '实时课程';
|
||||
const snapshotMatches = snapshot[0]?.course?.name === '实时课程';
|
||||
if (!immediate || !aligned || !restored || !snapshotMatches)
|
||||
throw new Error(
|
||||
`课表同步检查:${JSON.stringify({ ready, latencyMs, aligned, restored, snapshotMatches })}`,
|
||||
);
|
||||
return true;
|
||||
});
|
||||
await check('常驻岛开合复用固定画布,动画中没有滚动容器或旧胶囊形变', async () => {
|
||||
const bounds = new Set<string>();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/server",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"description": "ClassHelper后端服务:REST API + Socket.IO 实时推送 + Prisma 数据访问",
|
||||
"type": "module",
|
||||
|
||||
@@ -0,0 +1,271 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { prisma } from '../src/lib/db.js';
|
||||
import { env } from '../src/config/env.js';
|
||||
import type { TokenPayload } from '../src/lib/jwt.js';
|
||||
import { ensureDefaultGroups } from '../src/lib/permissions.js';
|
||||
import { createCourse } from '../src/modules/courses/courses.service.js';
|
||||
import { bulkCreateGrades, createGrade, updateGradeLevels } from '../src/modules/grades/grades.service.js';
|
||||
import { pushUpdate } from '../src/modules/clients/clients.service.js';
|
||||
import { markAsRead } from '../src/modules/notifications/notifications.service.js';
|
||||
import { exportSnapshot, restoreSnapshot, SNAPSHOT_TABLES } from '../src/lib/snapshot.js';
|
||||
import { heartbeat } from '../src/modules/clients/clients.service.js';
|
||||
|
||||
if (!process.env.DATABASE_URL?.includes('authz-verification')) throw new Error('审计验收只能使用隔离数据库');
|
||||
Reflect.set(env, 'serverRoot', path.join(path.dirname(process.env.DATABASE_URL.slice(5)), 'server'));
|
||||
|
||||
const counters: Record<string, number> = {};
|
||||
const restorers: Array<() => void> = [];
|
||||
for (const model of [
|
||||
'permissionGroup',
|
||||
'class',
|
||||
'course',
|
||||
'student',
|
||||
'grade',
|
||||
'classPlan',
|
||||
'scheduledClassPlan',
|
||||
'termWeek',
|
||||
'timeLayout',
|
||||
'timeLayoutItem',
|
||||
'appSetting',
|
||||
]) {
|
||||
const delegate = Reflect.get(prisma, model) as object;
|
||||
for (const method of ['findUnique', 'findFirst', 'findMany', 'count', 'upsert', 'create', 'update']) {
|
||||
const original: unknown = Reflect.get(delegate, method);
|
||||
if (typeof original !== 'function') continue;
|
||||
const key = `${model}.${method}`;
|
||||
Reflect.set(delegate, method, (...args: unknown[]) => {
|
||||
counters[key] = (counters[key] ?? 0) + 1;
|
||||
return Reflect.apply(original, delegate, args);
|
||||
});
|
||||
restorers.push(() => Reflect.set(delegate, method, original));
|
||||
}
|
||||
}
|
||||
const metrics: Record<string, unknown> = {};
|
||||
const failures: string[] = [];
|
||||
let passed = 0;
|
||||
async function check(name: string, run: () => Promise<void>) {
|
||||
try {
|
||||
await run();
|
||||
console.log(`通过 ${++passed}:${name}`);
|
||||
} catch (error) {
|
||||
failures.push(name);
|
||||
console.error(`失败:${name}:${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
}
|
||||
function resetCounts() {
|
||||
for (const key of Object.keys(counters)) delete counters[key];
|
||||
}
|
||||
async function account(name: string, role: TokenPayload['role']): Promise<TokenPayload> {
|
||||
const row = await prisma.user.create({ data: { name, username: name, role, passwordHash: '隔离夹具' } });
|
||||
return { sub: row.id, name, username: name, role, classId: null };
|
||||
}
|
||||
try {
|
||||
await check('快照清单覆盖 schema 与迁移后实际业务表', async () => {
|
||||
const schema = fs.readFileSync(new URL('../prisma/schema.prisma', import.meta.url), 'utf8');
|
||||
const models = [...schema.matchAll(/^model\s+(\w+)\s*\{/gm)].map((match) => match[1]);
|
||||
const tables = await prisma.$queryRawUnsafe<Array<{ name: string }>>(
|
||||
"SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_prisma_migrations'",
|
||||
);
|
||||
assert.deepEqual([...SNAPSHOT_TABLES].sort(), models.sort());
|
||||
assert.deepEqual([...SNAPSHOT_TABLES].sort(), tables.map((row) => row.name).sort());
|
||||
});
|
||||
const admin = await account('audit-admin', 'ADMIN');
|
||||
const head = await account('audit-head', 'TEACHER');
|
||||
const lead = await account('audit-lead', 'TEACHER');
|
||||
const cls = await prisma.class.create({
|
||||
data: {
|
||||
name: '审计班级',
|
||||
grade: '高一',
|
||||
enrollmentYear: 2026,
|
||||
classIndex: 91,
|
||||
code: 'AUDIT91',
|
||||
teacherId: head.sub,
|
||||
},
|
||||
});
|
||||
const other = await prisma.class.create({
|
||||
data: {
|
||||
name: '审计外班',
|
||||
grade: '高二',
|
||||
enrollmentYear: 2026,
|
||||
classIndex: 92,
|
||||
code: 'AUDIT92',
|
||||
teacherId: head.sub,
|
||||
},
|
||||
});
|
||||
const course = await prisma.course.create({ data: { classId: cls.id, name: '数学', teacherId: head.sub } });
|
||||
const students = await Promise.all(
|
||||
Array.from({ length: 50 }, (_, i) =>
|
||||
prisma.student.create({ data: { classId: cls.id, name: `临时${i}`, studentNo: `AUDIT-${i}` } }),
|
||||
),
|
||||
);
|
||||
const outsider = await prisma.student.create({
|
||||
data: { classId: other.id, name: '外班', studentNo: 'AUDIT-OUT' },
|
||||
});
|
||||
await ensureDefaultGroups();
|
||||
await check('默认组成功初始化后不重复写库', async () => {
|
||||
resetCounts();
|
||||
await ensureDefaultGroups();
|
||||
await ensureDefaultGroups();
|
||||
const operations = Object.values(counters).reduce((sum, n) => sum + n, 0);
|
||||
metrics.defaultGroupOperationsForTwoCalls = operations;
|
||||
assert.equal(operations, 0);
|
||||
});
|
||||
const group = await prisma.permissionGroup.create({
|
||||
data: {
|
||||
name: '审计年级岗',
|
||||
items: { create: ['schedule:write', 'grade:write'].map((key) => ({ key })) },
|
||||
},
|
||||
});
|
||||
await prisma.userPermissionGroup.create({
|
||||
data: { userId: lead.sub, groupId: group.id, scope: 'GRADE', scopeValue: '高一' },
|
||||
});
|
||||
await check('年级课表维护者不能通过建课取得任课关系', async () => {
|
||||
let created;
|
||||
try {
|
||||
created = await createCourse(lead, { classId: cls.id, name: '自授权科目' });
|
||||
} catch (error) {
|
||||
assert.equal(Reflect.get(error as object, 'status'), 403);
|
||||
return;
|
||||
}
|
||||
await createGrade(lead, {
|
||||
classId: cls.id,
|
||||
courseId: created.id,
|
||||
studentId: students[0]!.id,
|
||||
examName: '攻击链',
|
||||
score: 99,
|
||||
});
|
||||
assert.fail('仅有年级课表维护范围的教师已自建任课并写入成绩');
|
||||
});
|
||||
await check('批量成绩的末行越班不会留下首行', async () => {
|
||||
await assert.rejects(
|
||||
bulkCreateGrades(admin, {
|
||||
classId: cls.id,
|
||||
courseId: course.id,
|
||||
examName: '末行无效',
|
||||
items: [
|
||||
{ studentId: students[0]!.id, score: 80 },
|
||||
{ studentId: outsider.id, score: 90 },
|
||||
],
|
||||
}),
|
||||
);
|
||||
assert.equal(await prisma.grade.count({ where: { examName: '末行无效' } }), 0);
|
||||
});
|
||||
await check('批量成绩中途数据库失败整批回滚', async () => {
|
||||
await prisma.$executeRawUnsafe(
|
||||
`CREATE TRIGGER audit_grade_failure BEFORE INSERT ON Grade WHEN NEW.examName = '事务失败' AND NEW.studentId = '${students[1]!.id}' BEGIN SELECT RAISE(ABORT, 'audit injected failure'); END`,
|
||||
);
|
||||
try {
|
||||
await assert.rejects(
|
||||
bulkCreateGrades(admin, {
|
||||
classId: cls.id,
|
||||
courseId: course.id,
|
||||
examName: '事务失败',
|
||||
items: students.slice(0, 2).map((s) => ({ studentId: s.id, score: 80 })),
|
||||
}),
|
||||
);
|
||||
assert.equal(await prisma.grade.count({ where: { examName: '事务失败' } }), 0);
|
||||
} finally {
|
||||
await prisma.$executeRawUnsafe('DROP TRIGGER audit_grade_failure');
|
||||
}
|
||||
});
|
||||
await check('同班同科50条等级修改只授权一次', async () => {
|
||||
const rows = await bulkCreateGrades(admin, {
|
||||
classId: cls.id,
|
||||
courseId: course.id,
|
||||
examName: '性能测量',
|
||||
items: students.map((s) => ({ studentId: s.id, score: 80 })),
|
||||
});
|
||||
resetCounts();
|
||||
await updateGradeLevels({ ...head }, { items: rows.map((r) => ({ id: r.id, level: 'A' })) });
|
||||
const calls = counters['course.findUnique'] ?? 0;
|
||||
metrics.gradeLevelCourseLookupsFor50Rows = calls;
|
||||
assert.equal(calls, 1);
|
||||
assert.equal(await prisma.grade.count({ where: { examName: '性能测量', level: 'A' } }), 50);
|
||||
});
|
||||
await check('同班20设备放学更新仅解析一次课表', async () => {
|
||||
const version = 'audit-1.0.0';
|
||||
const fileName = 'audit-fixture.exe';
|
||||
const dir = path.join(env.serverRoot, '..', 'data', 'client-releases', version);
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
const file = path.join(dir, fileName);
|
||||
fs.writeFileSync(file, '隔离夹具,不是可执行安装器');
|
||||
try {
|
||||
await prisma.clientRelease.create({
|
||||
data: { version, fileName, size: fs.statSync(file).size, sha256: '0'.repeat(64) },
|
||||
});
|
||||
const devices = await Promise.all(
|
||||
Array.from({ length: 20 }, (_, i) =>
|
||||
prisma.clientDevice.create({ data: { deviceKey: `audit-device-${i}`, classId: cls.id } }),
|
||||
),
|
||||
);
|
||||
resetCounts();
|
||||
await pushUpdate(admin, {
|
||||
version,
|
||||
mode: 'after-school',
|
||||
afterSchoolTime: '17:00',
|
||||
deviceIds: devices.map((d) => d.id),
|
||||
});
|
||||
metrics.afterSchoolClassLookupsFor20Devices = counters['class.findUnique'] ?? 0;
|
||||
assert.equal(counters['class.findUnique'], 1);
|
||||
const updated = await prisma.clientDevice.findMany({ where: { classId: cls.id } });
|
||||
assert.equal(new Set(updated.map((d) => d.updateNotBefore?.toISOString())).size, 1);
|
||||
} finally {
|
||||
fs.unlinkSync(file);
|
||||
fs.rmdirSync(dir);
|
||||
}
|
||||
});
|
||||
await check('并发标记同一通知已读均成功且记录唯一', async () => {
|
||||
const notice = await prisma.notification.create({
|
||||
data: { classId: cls.id, title: '竞态', content: '临时', createdBy: head.sub },
|
||||
});
|
||||
const device: TokenPayload = {
|
||||
sub: cls.id,
|
||||
name: cls.name,
|
||||
username: cls.code,
|
||||
role: 'CLASS_DEVICE',
|
||||
classId: cls.id,
|
||||
classSession: true,
|
||||
};
|
||||
const results = await Promise.allSettled(
|
||||
Array.from({ length: 4 }, () => markAsRead({ ...device }, notice.id)),
|
||||
);
|
||||
assert.equal(results.filter((r) => r.status === 'rejected').length, 0);
|
||||
assert.equal(await prisma.notificationRead.count({ where: { notificationId: notice.id } }), 50);
|
||||
});
|
||||
await check('并发首次心跳保持设备归属并全部成功', async () => {
|
||||
const actor: TokenPayload = {
|
||||
sub: cls.id,
|
||||
name: cls.name,
|
||||
username: cls.code,
|
||||
role: 'CLASS_DEVICE',
|
||||
classId: cls.id,
|
||||
classSession: true,
|
||||
};
|
||||
const results = await Promise.allSettled(
|
||||
Array.from({ length: 4 }, () =>
|
||||
heartbeat({ ...actor }, { deviceKey: 'audit-first-heartbeat' }, '127.0.0.1'),
|
||||
),
|
||||
);
|
||||
assert.equal(results.filter((r) => r.status === 'rejected').length, 0);
|
||||
assert.equal(
|
||||
await prisma.clientDevice.count({ where: { deviceKey: 'audit-first-heartbeat', classId: cls.id } }),
|
||||
1,
|
||||
);
|
||||
});
|
||||
await check('快照恢复写入失败时原库完整保留', async () => {
|
||||
const before = await exportSnapshot(prisma, 'sqlite');
|
||||
const broken = structuredClone(before);
|
||||
broken.data.Grade[0]!.score = 'invalid-score';
|
||||
await assert.rejects(restoreSnapshot(prisma, 'sqlite', broken));
|
||||
assert.equal(await prisma.grade.count(), before.counts.Grade);
|
||||
assert.equal(await prisma.user.count(), before.counts.User);
|
||||
});
|
||||
console.log(`审计指标(Prisma 模型操作数,不等同底层 SQL 数):${JSON.stringify(metrics)}`);
|
||||
console.log(`审计专项:${passed} 通过,${failures.length} 失败`);
|
||||
if (failures.length) process.exitCode = 1;
|
||||
} finally {
|
||||
for (const restore of restorers) restore();
|
||||
await prisma.$disconnect();
|
||||
}
|
||||
@@ -697,11 +697,17 @@ async function main() {
|
||||
|
||||
const createdCourse = await api('/courses', {
|
||||
method: 'POST',
|
||||
token: teacherToken,
|
||||
token: adminToken,
|
||||
body: { name: `联调验证课程 ${Date.now()}`, classId },
|
||||
});
|
||||
const createdCourseId = createdCourse.payload?.data?.id;
|
||||
record('新增课程 POST /courses', createdCourse.status === 201, `status=${createdCourse.status}`);
|
||||
const deniedCourse = await api('/courses', {
|
||||
method: 'POST',
|
||||
token: teacherToken,
|
||||
body: { name: `禁止自授权课程 ${Date.now()}`, classId },
|
||||
});
|
||||
record('教师不能通过建课建立任课关系', deniedCourse.status === 403, `status=${deniedCourse.status}`);
|
||||
if (createdCourseId) {
|
||||
const removedCourse = await api(`/courses/${createdCourseId}`, { method: 'DELETE', token: teacherToken });
|
||||
record('删除课程 DELETE /courses/:id', removedCourse.status === 200, `status=${removedCourse.status}`);
|
||||
|
||||
@@ -11,11 +11,16 @@ import type { TokenPayload } from './jwt.js';
|
||||
let defaultGroupsReady: Promise<void> | null = null;
|
||||
export function ensureDefaultGroups(): Promise<void> {
|
||||
if (!defaultGroupsReady)
|
||||
defaultGroupsReady = createDefaultGroups().finally(() => {
|
||||
defaultGroupsReady = createDefaultGroups().catch((error: unknown) => {
|
||||
defaultGroupsReady = null;
|
||||
throw error;
|
||||
});
|
||||
return defaultGroupsReady;
|
||||
}
|
||||
/** 整库恢复后需要重新检查初始化;不缓存任何账号的实际权限。 */
|
||||
export function resetDefaultGroups(): void {
|
||||
defaultGroupsReady = null;
|
||||
}
|
||||
async function createDefaultGroups(): Promise<void> {
|
||||
for (const group of BUILTIN_TEACHER_GROUPS) {
|
||||
await prisma.permissionGroup.upsert({
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
import { refreshClassSubscriptions } from '../realtime/bus.js';
|
||||
import { invalidateAuthPrincipals } from './authz/principal.js';
|
||||
import { resetDefaultGroups } from './permissions.js';
|
||||
import { migratePermissionScope } from '@classhelper/shared';
|
||||
import type { PrismaClient } from '../generated/prisma/client.js';
|
||||
import type { Prisma, PrismaClient } from '../generated/prisma/client.js';
|
||||
import type { DatabaseProvider } from './db.js';
|
||||
|
||||
/**
|
||||
@@ -15,7 +16,7 @@ import type { DatabaseProvider } from './db.js';
|
||||
* 而 `Class.archivedYearId` / `Student.archivedYearId → ArchivedYear` 又是另一条;
|
||||
* 恢复时必须**临时关闭外键检查**再按序写入,否则任何排序都会被其中一侧卡死。
|
||||
* - SQLite:PRAGMA foreign_keys=OFF(libsql 连接级,进程内安全)
|
||||
* - MySQL:SET FOREIGN_KEY_CHECKS=0/1(会话级,连接池下同一客户端实例内生效)
|
||||
* - MySQL:SET FOREIGN_KEY_CHECKS=0/1(会话级,恢复事务使用同一连接)
|
||||
*/
|
||||
|
||||
export const SNAPSHOT_FORMAT = 'classhelper-snapshot';
|
||||
@@ -94,7 +95,7 @@ interface ModelDelegate {
|
||||
deleteMany(): Promise<unknown>;
|
||||
}
|
||||
|
||||
function delegatesOf(prisma: PrismaClient): Record<SnapshotTable, ModelDelegate> {
|
||||
function delegatesOf(prisma: Prisma.TransactionClient): Record<SnapshotTable, ModelDelegate> {
|
||||
return prisma as unknown as Record<SnapshotTable, ModelDelegate>;
|
||||
}
|
||||
|
||||
@@ -103,7 +104,7 @@ const CHUNK_SIZE = 200;
|
||||
|
||||
/** 导出全库快照(行内 DateTime 为 Date 对象,JSON.stringify 时自动转 ISO) */
|
||||
export async function exportSnapshot(
|
||||
prisma: PrismaClient,
|
||||
prisma: Prisma.TransactionClient,
|
||||
provider: DatabaseProvider,
|
||||
): Promise<DatabaseSnapshot> {
|
||||
const delegates = delegatesOf(prisma);
|
||||
@@ -150,7 +151,7 @@ export function assertValidSnapshot(value: unknown): asserts value is DatabaseSn
|
||||
}
|
||||
|
||||
async function setForeignKeys(
|
||||
prisma: PrismaClient,
|
||||
prisma: Prisma.TransactionClient,
|
||||
provider: DatabaseProvider,
|
||||
enabled: boolean,
|
||||
): Promise<void> {
|
||||
@@ -172,11 +173,16 @@ export async function restoreSnapshot(
|
||||
options: { clean?: boolean } = {},
|
||||
): Promise<{ counts: Record<string, number> }> {
|
||||
assertValidSnapshot(snapshot);
|
||||
const delegates = delegatesOf(prisma);
|
||||
const clean = options.clean !== false;
|
||||
const counts: Record<string, number> = {};
|
||||
|
||||
await setForeignKeys(prisma, provider, false);
|
||||
// SQLite 只能在事务外切换外键;MySQL 的会话设置必须使用事务固定的连接。
|
||||
if (provider === 'sqlite') await setForeignKeys(prisma, provider, false);
|
||||
try {
|
||||
await prisma.$transaction(
|
||||
async (tx) => {
|
||||
const delegates = delegatesOf(tx);
|
||||
if (provider === 'mysql') await setForeignKeys(tx, provider, false);
|
||||
try {
|
||||
if (clean) {
|
||||
// 反向清空,保证被引用的表最后清(外键关闭后只是防御性的,保持确定性)
|
||||
@@ -201,7 +207,10 @@ export async function restoreSnapshot(
|
||||
const group = snapshot.data.PermissionGroup.find((g) => g.id === row.groupId);
|
||||
return {
|
||||
...row,
|
||||
...migratePermissionScope(String(group?.scope ?? 'TEACHING'), String(group?.scopeValue ?? '')),
|
||||
...migratePermissionScope(
|
||||
String(group?.scope ?? 'TEACHING'),
|
||||
String(group?.scopeValue ?? ''),
|
||||
),
|
||||
};
|
||||
}
|
||||
if (table === 'StudentClassTransfer') {
|
||||
@@ -228,9 +237,16 @@ export async function restoreSnapshot(
|
||||
counts[table] = rows.length;
|
||||
}
|
||||
} finally {
|
||||
await setForeignKeys(prisma, provider, true).catch(() => undefined);
|
||||
if (provider === 'mysql') await setForeignKeys(tx, provider, true);
|
||||
}
|
||||
},
|
||||
{ timeout: 120_000 },
|
||||
);
|
||||
} finally {
|
||||
if (provider === 'sqlite') await setForeignKeys(prisma, provider, true);
|
||||
}
|
||||
invalidateAuthPrincipals();
|
||||
resetDefaultGroups();
|
||||
refreshClassSubscriptions();
|
||||
return { counts };
|
||||
}
|
||||
|
||||
@@ -462,17 +462,21 @@ export async function pushUpdate(
|
||||
if (devices.length === 0) throw ApiError.badRequest('没有匹配到任何客户端设备');
|
||||
|
||||
const results: ClientTargetResult[] = [];
|
||||
const notBeforeByClass = new Map<string | null, Date>();
|
||||
for (const device of devices) {
|
||||
let notBefore: Date | null = null;
|
||||
if (!clear && input.mode === 'after-school') {
|
||||
notBefore =
|
||||
notBeforeByClass.get(device.classId) ?? (await afterSchoolAt(device.classId, input.afterSchoolTime));
|
||||
notBeforeByClass.set(device.classId, notBefore);
|
||||
}
|
||||
await prisma.clientDevice.update({
|
||||
where: { id: device.id },
|
||||
data: {
|
||||
updateTargetVersion: target,
|
||||
updateProgress: '',
|
||||
updateMode: clear ? 'idle' : input.mode,
|
||||
updateNotBefore:
|
||||
!clear && input.mode === 'after-school'
|
||||
? await afterSchoolAt(device.classId, input.afterSchoolTime)
|
||||
: null,
|
||||
updateNotBefore: notBefore,
|
||||
},
|
||||
});
|
||||
results.push({ deviceId: device.id, deviceName: device.name, ok: true });
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
import { refreshClassSubscriptions } from '../../realtime/bus.js';
|
||||
import type { CourseDto } from '@classhelper/shared';
|
||||
import { assertCanManageSchedule, classScopeWhere, resolveClassScope } from '../../lib/access.js';
|
||||
import {
|
||||
assertCanAssignTeachers,
|
||||
assertCanManageSchedule,
|
||||
classScopeWhere,
|
||||
resolveClassScope,
|
||||
} from '../../lib/access.js';
|
||||
import { prisma } from '../../lib/db.js';
|
||||
import { ApiError } from '../../lib/http.js';
|
||||
import type { TokenPayload } from '../../lib/jwt.js';
|
||||
@@ -21,6 +26,9 @@ export async function listCourses(user: TokenPayload, classId?: string): Promise
|
||||
|
||||
export async function createCourse(user: TokenPayload, input: CreateCourseInput): Promise<CourseDto> {
|
||||
await assertCanManageSchedule(user, input.classId);
|
||||
// 建课同时建立任课关系,只能由管理员执行,不能凭课表维护范围自授权。
|
||||
if (user.role !== 'ADMIN') throw ApiError.forbidden('新建科目会建立任课关系,请联系管理员配置');
|
||||
await assertCanAssignTeachers(user, input.classId);
|
||||
|
||||
/*
|
||||
* 同名去重(一个班级里科目名唯一)。
|
||||
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
} from '../../lib/access.js';
|
||||
import { activeStudentWhere, isActiveStudent } from '../../lib/students.js';
|
||||
import { prisma } from '../../lib/db.js';
|
||||
import type { Prisma } from '../../generated/prisma/client.js';
|
||||
import { ApiError } from '../../lib/http.js';
|
||||
import type { TokenPayload } from '../../lib/jwt.js';
|
||||
import { logger } from '../../lib/logger.js';
|
||||
@@ -249,17 +250,29 @@ export async function createGrade(user: TokenPayload, input: CreateGradeInput):
|
||||
|
||||
/** 批量录入:同一个考试一次提交整班成绩 */
|
||||
export async function bulkCreateGrades(user: TokenPayload, input: BulkCreateGradeInput): Promise<GradeDto[]> {
|
||||
await assertContentWrite(user, 'grade:write', input.classId, input.courseId ?? null, '录入成绩');
|
||||
if (input.courseId) await assertCourseInClass(input.courseId, input.classId);
|
||||
|
||||
const publishedAt = parseOptionalDate(input.publishedAt) ?? new Date();
|
||||
const levelType: GradeLevelType = input.levelType ?? 'percent';
|
||||
const totalScore = input.totalScore ?? 100;
|
||||
const results: GradeDto[] = [];
|
||||
|
||||
const results = await prisma.$transaction(
|
||||
async (tx) => {
|
||||
await assertContentWrite(user, 'grade:write', input.classId, input.courseId ?? null, '录入成绩', {
|
||||
db: tx,
|
||||
});
|
||||
const students = await tx.student.findMany({
|
||||
where: { id: { in: [...new Set(input.items.map((item) => item.studentId))] } },
|
||||
select: { id: true, classId: true, status: true },
|
||||
});
|
||||
const byId = new Map(students.map((student) => [student.id, student]));
|
||||
for (const item of input.items) {
|
||||
await assertStudentInClass(item.studentId, input.classId);
|
||||
const dto = await upsertGrade({
|
||||
const student = byId.get(item.studentId);
|
||||
if (!student || !isActiveStudent(student)) throw ApiError.badRequest('学生不存在');
|
||||
if (student.classId !== input.classId) throw ApiError.badRequest('该学生不属于所选班级');
|
||||
}
|
||||
const rows: GradeDto[] = [];
|
||||
for (const item of input.items) {
|
||||
rows.push(
|
||||
await upsertGrade(
|
||||
{
|
||||
classId: input.classId,
|
||||
courseId: input.courseId ?? null,
|
||||
studentId: item.studentId,
|
||||
@@ -269,9 +282,15 @@ export async function bulkCreateGrades(user: TokenPayload, input: BulkCreateGrad
|
||||
levelType,
|
||||
level: resolveLevel(levelType, item.level, item.score, totalScore),
|
||||
publishedAt,
|
||||
});
|
||||
results.push(dto);
|
||||
},
|
||||
tx,
|
||||
),
|
||||
);
|
||||
}
|
||||
return rows;
|
||||
},
|
||||
{ timeout: 30_000 },
|
||||
);
|
||||
|
||||
if (results[0]) {
|
||||
await emitGradeUpdated(input.classId, {
|
||||
@@ -370,9 +389,13 @@ export async function updateGradeLevels(
|
||||
const byId = new Map(records.map((item) => [item.id, item]));
|
||||
|
||||
// 逐条判权限:可能跨多个班级/科目(管理员在成绩页多选修改时会这样)
|
||||
const checked = new Set<string>();
|
||||
for (const item of input.items) {
|
||||
const record = byId.get(item.id)!;
|
||||
const relation = JSON.stringify([record.classId, record.courseId]);
|
||||
if (checked.has(relation)) continue;
|
||||
await assertContentWrite(user, 'grade:write', record.classId, record.courseId, '修改成绩等级');
|
||||
checked.add(relation);
|
||||
}
|
||||
|
||||
await prisma.$transaction(
|
||||
@@ -518,7 +541,8 @@ function resolveLevel(
|
||||
* 同一学生 + 同一课程 + 同一考试名称视为同一条记录,
|
||||
* 重复录入时覆盖旧分数,避免教师"改分"产生重复行。
|
||||
*/
|
||||
async function upsertGrade(data: {
|
||||
async function upsertGrade(
|
||||
data: {
|
||||
classId: string;
|
||||
courseId: string | null;
|
||||
studentId: string;
|
||||
@@ -528,8 +552,10 @@ async function upsertGrade(data: {
|
||||
levelType: GradeLevelType;
|
||||
level: string;
|
||||
publishedAt: Date;
|
||||
}): Promise<GradeDto> {
|
||||
const existing = await prisma.grade.findFirst({
|
||||
},
|
||||
db: Prisma.TransactionClient = prisma,
|
||||
): Promise<GradeDto> {
|
||||
const existing = await db.grade.findFirst({
|
||||
where: {
|
||||
classId: data.classId,
|
||||
courseId: data.courseId,
|
||||
@@ -540,7 +566,7 @@ async function upsertGrade(data: {
|
||||
});
|
||||
|
||||
if (existing) {
|
||||
const updated = await prisma.grade.update({
|
||||
const updated = await db.grade.update({
|
||||
where: { id: existing.id },
|
||||
data: {
|
||||
score: data.score,
|
||||
@@ -554,7 +580,7 @@ async function upsertGrade(data: {
|
||||
return toGradeDto(updated);
|
||||
}
|
||||
|
||||
const created = await prisma.grade.create({ data, include });
|
||||
const created = await db.grade.create({ data, include });
|
||||
return toGradeDto(created);
|
||||
}
|
||||
|
||||
|
||||
@@ -271,23 +271,30 @@ export async function markAsRead(
|
||||
if (!notification) throw ApiError.notFound('通知不存在');
|
||||
await assertClassAccess(user, notification.classId, 'notification:read');
|
||||
|
||||
const personalIds = await resolvePersonalIds(user);
|
||||
// 先过滤已读过的记录再创建:SQLite 下 createMany 不支持 skipDuplicates,
|
||||
// 直接 createMany 遇到重复会整体失败。
|
||||
const marked = await createMissingReads(notificationId, await resolvePersonalIds(user));
|
||||
return { notificationId, readAt: new Date().toISOString(), marked };
|
||||
}
|
||||
|
||||
/** 唯一约束处理并发抢写;重读后只补缺项,兼容 SQLite/MySQL。 */
|
||||
async function createMissingReads(notificationId: string, personalIds: string[]): Promise<number> {
|
||||
for (let attempt = 0; ; attempt++) {
|
||||
const existing = await prisma.notificationRead.findMany({
|
||||
where: { notificationId, studentId: { in: personalIds } },
|
||||
select: { studentId: true },
|
||||
});
|
||||
const have = new Set(existing.map((item) => item.studentId));
|
||||
const missing = personalIds.filter((studentId) => !have.has(studentId));
|
||||
|
||||
if (missing.length > 0) {
|
||||
await prisma.notificationRead.createMany({
|
||||
if (!missing.length) return 0;
|
||||
try {
|
||||
const result = await prisma.notificationRead.createMany({
|
||||
data: missing.map((studentId) => ({ notificationId, studentId })),
|
||||
});
|
||||
return result.count;
|
||||
} catch (error) {
|
||||
if (attempt >= 3 || !error || typeof error !== 'object' || !('code' in error) || error.code !== 'P2002')
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
return { notificationId, readAt: new Date().toISOString(), marked: missing.length };
|
||||
}
|
||||
|
||||
/** 全部标为已读(可按班级限定) */
|
||||
@@ -304,18 +311,7 @@ export async function markAllAsRead(user: TokenPayload, classId?: string): Promi
|
||||
|
||||
let marked = 0;
|
||||
for (const item of pending) {
|
||||
const existing = await prisma.notificationRead.findMany({
|
||||
where: { notificationId: item.id, studentId: { in: personalIds } },
|
||||
select: { studentId: true },
|
||||
});
|
||||
const have = new Set(existing.map((row) => row.studentId));
|
||||
const missing = personalIds.filter((studentId) => !have.has(studentId));
|
||||
if (missing.length === 0) continue;
|
||||
|
||||
await prisma.notificationRead.createMany({
|
||||
data: missing.map((studentId) => ({ notificationId: item.id, studentId })),
|
||||
});
|
||||
marked += missing.length;
|
||||
marked += await createMissingReads(item.id, personalIds);
|
||||
}
|
||||
|
||||
return { marked };
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/shared",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"description": "ClassHelper - 三端共享的类型、常量与工具函数",
|
||||
"type": "module",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@classhelper/web-admin",
|
||||
"version": "1.4.2",
|
||||
"version": "1.4.3",
|
||||
"private": true,
|
||||
"description": "ClassHelper Web 管理端(Vue 3 + Vite + Element Plus)",
|
||||
"type": "module",
|
||||
|
||||
@@ -6,7 +6,8 @@
|
||||
* - 构建产物 /assets/*(带内容哈希):cache-first(文件名变化即自动失效)
|
||||
* - /api 与 /socket.io:完全透传,绝不缓存(避免脏数据与鉴权问题)
|
||||
*/
|
||||
const CACHE_NAME = 'classhelper-admin-v1';
|
||||
const CACHE_PREFIX = 'classhelper-admin-';
|
||||
const CACHE_NAME = `${CACHE_PREFIX}v2`;
|
||||
const APP_SHELL = ['/', '/index.html', '/manifest.webmanifest', '/icon-192.png', '/icon-512.png'];
|
||||
|
||||
self.addEventListener('install', (event) => {
|
||||
@@ -23,7 +24,13 @@ self.addEventListener('activate', (event) => {
|
||||
event.waitUntil(
|
||||
caches
|
||||
.keys()
|
||||
.then((keys) => Promise.all(keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))))
|
||||
.then((keys) =>
|
||||
Promise.all(
|
||||
keys
|
||||
.filter((key) => key.startsWith(CACHE_PREFIX) && key !== CACHE_NAME)
|
||||
.map((key) => caches.delete(key)),
|
||||
),
|
||||
)
|
||||
.then(() => self.clients.claim()),
|
||||
);
|
||||
});
|
||||
@@ -36,15 +43,25 @@ self.addEventListener('fetch', (event) => {
|
||||
// 只接管同源请求
|
||||
if (url.origin !== self.location.origin) return;
|
||||
// 接口与实时通道透传
|
||||
if (url.pathname.startsWith('/api/') || url.pathname.startsWith('/socket.io/')) return;
|
||||
if (
|
||||
['/api', '/socket.io'].some((prefix) => url.pathname === prefix || url.pathname.startsWith(`${prefix}/`))
|
||||
)
|
||||
return;
|
||||
|
||||
// 页面导航:网络优先,离线时用缓存外壳
|
||||
if (request.mode === 'navigate') {
|
||||
event.respondWith(
|
||||
fetch(request)
|
||||
.then((response) => {
|
||||
if (response.ok && response.headers.get('content-type')?.includes('text/html')) {
|
||||
const clone = response.clone();
|
||||
caches.open(CACHE_NAME).then((cache) => cache.put('/index.html', clone));
|
||||
event.waitUntil(
|
||||
caches
|
||||
.open(CACHE_NAME)
|
||||
.then((cache) => cache.put('/index.html', clone))
|
||||
.catch(() => undefined),
|
||||
);
|
||||
}
|
||||
return response;
|
||||
})
|
||||
.catch(() => caches.match('/index.html').then((cached) => cached ?? Response.error())),
|
||||
@@ -60,7 +77,12 @@ self.addEventListener('fetch', (event) => {
|
||||
.then((response) => {
|
||||
if (response.ok) {
|
||||
const clone = response.clone();
|
||||
caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
|
||||
event.waitUntil(
|
||||
caches
|
||||
.open(CACHE_NAME)
|
||||
.then((cache) => cache.put(request, clone))
|
||||
.catch(() => undefined),
|
||||
);
|
||||
}
|
||||
return response;
|
||||
})
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
import type { App } from 'vue';
|
||||
import {
|
||||
ElAlert,
|
||||
ElAside,
|
||||
ElBreadcrumb,
|
||||
ElBreadcrumbItem,
|
||||
ElButton,
|
||||
ElCard,
|
||||
ElCheckbox,
|
||||
ElCheckboxGroup,
|
||||
ElCol,
|
||||
ElContainer,
|
||||
ElDatePicker,
|
||||
ElDescriptions,
|
||||
ElDescriptionsItem,
|
||||
ElDialog,
|
||||
ElDivider,
|
||||
ElDrawer,
|
||||
ElDropdown,
|
||||
ElDropdownItem,
|
||||
ElDropdownMenu,
|
||||
ElEmpty,
|
||||
ElForm,
|
||||
ElFormItem,
|
||||
ElHeader,
|
||||
ElIcon,
|
||||
ElInput,
|
||||
ElInputNumber,
|
||||
ElLink,
|
||||
ElLoading,
|
||||
ElMain,
|
||||
ElMenu,
|
||||
ElMenuItem,
|
||||
ElOption,
|
||||
ElOptionGroup,
|
||||
ElPagination,
|
||||
ElPopover,
|
||||
ElProgress,
|
||||
ElRadio,
|
||||
ElRadioButton,
|
||||
ElRadioGroup,
|
||||
ElResult,
|
||||
ElRow,
|
||||
ElSelect,
|
||||
ElSlider,
|
||||
ElStep,
|
||||
ElSteps,
|
||||
ElSubMenu,
|
||||
ElSwitch,
|
||||
ElTabPane,
|
||||
ElTable,
|
||||
ElTableColumn,
|
||||
ElTabs,
|
||||
ElTag,
|
||||
ElText,
|
||||
ElTimeSelect,
|
||||
ElTooltip,
|
||||
ElTour,
|
||||
ElTourStep,
|
||||
ElUpload,
|
||||
provideGlobalConfig,
|
||||
} from 'element-plus';
|
||||
import zhCn from 'element-plus/es/locale/lang/zh-cn';
|
||||
|
||||
/** 按模板实际使用注册组件;完整主题样式仍由入口加载。 */
|
||||
export function registerElementPlus(app: App): void {
|
||||
for (const component of [
|
||||
ElAlert,
|
||||
ElAside,
|
||||
ElBreadcrumb,
|
||||
ElBreadcrumbItem,
|
||||
ElButton,
|
||||
ElCard,
|
||||
ElCheckbox,
|
||||
ElCheckboxGroup,
|
||||
ElCol,
|
||||
ElContainer,
|
||||
ElDatePicker,
|
||||
ElDescriptions,
|
||||
ElDescriptionsItem,
|
||||
ElDialog,
|
||||
ElDivider,
|
||||
ElDrawer,
|
||||
ElDropdown,
|
||||
ElDropdownItem,
|
||||
ElDropdownMenu,
|
||||
ElEmpty,
|
||||
ElForm,
|
||||
ElFormItem,
|
||||
ElHeader,
|
||||
ElIcon,
|
||||
ElInput,
|
||||
ElInputNumber,
|
||||
ElLink,
|
||||
ElLoading,
|
||||
ElMain,
|
||||
ElMenu,
|
||||
ElMenuItem,
|
||||
ElOption,
|
||||
ElOptionGroup,
|
||||
ElPagination,
|
||||
ElPopover,
|
||||
ElProgress,
|
||||
ElRadio,
|
||||
ElRadioButton,
|
||||
ElRadioGroup,
|
||||
ElResult,
|
||||
ElRow,
|
||||
ElSelect,
|
||||
ElSlider,
|
||||
ElStep,
|
||||
ElSteps,
|
||||
ElSubMenu,
|
||||
ElSwitch,
|
||||
ElTabPane,
|
||||
ElTable,
|
||||
ElTableColumn,
|
||||
ElTabs,
|
||||
ElTag,
|
||||
ElText,
|
||||
ElTimeSelect,
|
||||
ElTooltip,
|
||||
ElTour,
|
||||
ElTourStep,
|
||||
ElUpload,
|
||||
])
|
||||
app.use(component);
|
||||
provideGlobalConfig({ locale: zhCn }, app, true);
|
||||
}
|
||||
@@ -1,7 +1,6 @@
|
||||
import { createApp } from 'vue';
|
||||
import { createPinia } from 'pinia';
|
||||
import ElementPlus from 'element-plus';
|
||||
import zhCn from 'element-plus/es/locale/lang/zh-cn';
|
||||
import { registerElementPlus } from './element-plus';
|
||||
import 'element-plus/dist/index.css';
|
||||
// 深色主题:html.dark 下的 --el-* 变量(品牌侧的语义色覆盖在 styles/index.css 的 html.dark 块)
|
||||
import 'element-plus/theme-chalk/dark/css-vars.css';
|
||||
@@ -21,7 +20,7 @@ registerAppIcons(app);
|
||||
|
||||
app.use(pinia);
|
||||
app.use(router);
|
||||
app.use(ElementPlus, { locale: zhCn });
|
||||
registerElementPlus(app);
|
||||
|
||||
/**
|
||||
* 全局错误处理。
|
||||
|
||||
@@ -325,7 +325,7 @@ async function removeStudent(row: StudentDto): Promise<void> {
|
||||
const courseForm = reactive({ name: '' });
|
||||
|
||||
async function addCourse(): Promise<void> {
|
||||
if (!canManageDetailCourses.value) return;
|
||||
if (!auth.isAdmin || !canManageDetailCourses.value) return;
|
||||
if (!detail.value || !courseForm.name.trim()) {
|
||||
ElMessage.warning('请输入课程名称');
|
||||
return;
|
||||
@@ -771,7 +771,7 @@ async function saveSettings() {
|
||||
</el-table-column>
|
||||
</el-table>
|
||||
<el-input
|
||||
v-if="canManageDetailCourses"
|
||||
v-if="auth.isAdmin && canManageDetailCourses"
|
||||
v-model="courseForm.name"
|
||||
placeholder="输入课程名称后回车快速添加"
|
||||
class="mt-12"
|
||||
|
||||
@@ -187,6 +187,7 @@ async function onClassChange(): Promise<void> {
|
||||
const SUBJECT_PREFIX = 'subject:';
|
||||
|
||||
const subjectOptions = computed(() => {
|
||||
if (!auth.isAdmin) return [];
|
||||
const existing = new Set(courses.value.map((item) => item.name));
|
||||
return SUBJECT_CATALOG.filter((name) => !existing.has(name));
|
||||
});
|
||||
@@ -221,7 +222,7 @@ const ownCourses = computed(() =>
|
||||
);
|
||||
|
||||
/** 能不能在该班新建科目(与课表管理同权限:管理员或本班班主任) */
|
||||
const canCreateCourse = computed(() => auth.canManageClass('schedule:write', filter.classId));
|
||||
const canCreateCourse = computed(() => auth.isAdmin);
|
||||
|
||||
/** 录入弹窗的默认科目:优先沿用页面筛选,但筛的是别人的科目时退回"我的科目"第一条 */
|
||||
function defaultFormCourseId(): string {
|
||||
|
||||
@@ -222,6 +222,7 @@ const formCoursesLoading = ref(false);
|
||||
|
||||
/** 该班还没有的科目(来自 shared 的 SUBJECT_CATALOG) */
|
||||
const newSubjectOptions = computed(() => {
|
||||
if (!auth.isAdmin) return [];
|
||||
const existing = new Set(formCourses.value.map((item) => item.name));
|
||||
return SUBJECT_CATALOG.filter((name) => !existing.has(name));
|
||||
});
|
||||
@@ -237,8 +238,8 @@ const ownFormCourses = computed(() =>
|
||||
auth.isAdmin ? formCourses.value : formCourses.value.filter((item) => item.teacherId === auth.user?.id),
|
||||
);
|
||||
|
||||
/** 该班里能不能新建科目:与课表管理同权限(管理员或本班班主任) */
|
||||
const canCreateCourse = computed(() => auth.canManageClass('schedule:write', form.classId));
|
||||
/** 新建科目会建立任课关系,仅管理员可操作。 */
|
||||
const canCreateCourse = computed(() => auth.isAdmin);
|
||||
|
||||
async function loadFormCourses(): Promise<void> {
|
||||
const classId = form.classId;
|
||||
@@ -325,10 +326,10 @@ async function resolveCourseId(): Promise<string | null> {
|
||||
await loadFormCourses();
|
||||
return reusedId;
|
||||
}
|
||||
// 新建课程需要"管理员或本班班主任"权限(与课表管理一致),科任老师会被 403 拦截
|
||||
// 新建课程会建立任课关系,统一交给管理员配置。
|
||||
ElMessage.error(
|
||||
`新建科目「${name}」失败:${
|
||||
error instanceof Error ? error.message : '仅班主任/管理员可以在班级下新建课程'
|
||||
error instanceof Error ? error.message : '请联系管理员建立科目及任课关系'
|
||||
},可改用已有课程或直接留空发布`,
|
||||
);
|
||||
throw error;
|
||||
@@ -622,7 +623,7 @@ function canEditContent(row: HomeworkDto): boolean {
|
||||
? '正在加载该班课程…'
|
||||
: canCreateCourse
|
||||
? '只列你任教的科目;该班还没有的科目在「其他科目(新建)」里,选中后自动建课再发布'
|
||||
: '只列你任教的科目;需要别的科目请先由班主任/管理员在课表管理里建好并分配任课老师'
|
||||
: '只列你任教的科目;需要别的科目请联系管理员建立科目并分配任课老师'
|
||||
}}
|
||||
</div>
|
||||
</el-form-item>
|
||||
|
||||
@@ -504,10 +504,10 @@ watch(tab, () => {
|
||||
selectedLayout.value = plan.value.timeLayoutId;
|
||||
});
|
||||
const missingSubjects = computed(() =>
|
||||
SUBJECT_CATALOG.filter((name) => !courses.value.some((c) => c.name === name)),
|
||||
auth.isAdmin ? SUBJECT_CATALOG.filter((name) => !courses.value.some((c) => c.name === name)) : [],
|
||||
);
|
||||
async function addSubject(name: string) {
|
||||
if (!canWrite.value) return;
|
||||
if (!canWrite.value || !auth.isAdmin) return;
|
||||
try {
|
||||
const created = await courseApi.create({ classId: classId.value, name });
|
||||
courses.value.push(created);
|
||||
|
||||
@@ -107,6 +107,7 @@ async function loadCourses(): Promise<void> {
|
||||
const SUBJECT_PREFIX = 'subject:';
|
||||
|
||||
const subjectOptions = computed(() => {
|
||||
if (!auth.isAdmin) return [];
|
||||
const existing = new Set(courses.value.map((item) => item.name));
|
||||
return SUBJECT_CATALOG.filter((name) => !existing.has(name));
|
||||
});
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# 全仓审计检查清单
|
||||
|
||||
每条都要给出结论:`已修复` / `确认无问题(证据)` / `记为后续(原因)`。禁止只列"看起来可疑"而不核实。
|
||||
|
||||
### A. 服务端 · 正确性与安全(P0 优先)
|
||||
|
||||
- A1 路由与权限键一一对应:每个受控接口至少一个键;每个键至少一个真实入口;`scripts/check-authz.mjs` 的禁用符号与"必须显式传权限键"是否仍有遗漏。
|
||||
- A2 服务层断言:`lib/authz/assert.ts` 的 `assertContentWrite`、班主任/任课关系、范围校验不能被权限键替代,也不能重复计算。
|
||||
- A3 事务边界:多表写入(学生+历史、调班+广播、升级+归档、批量发布)是否单事务;事务外写导致半截数据的路径。
|
||||
- A4 错误处理:统一中间件是否把所有异常映射成正确状态码(400/401/403/404/409/413/429/500);错误文案是否可操作;是否有被 `catch` 吞掉的失败。
|
||||
- A5 输入校验:zod schema 是否覆盖全部写入口;上传大小/类型/scheme 校验;路径穿越。
|
||||
- A6 日期与周次:`dayKeyLocal` 使用;跨时区/UTC 切片;学期周次上限与班级逐周区间优先级。
|
||||
- A7 限流:两个登录接口共用登录限流;其余敏感接口的必要限流。
|
||||
- A8 敏感信息:日志与错误是否带密码、JWT、AI Key、设备令牌;AI Key 加密存储且不回传。
|
||||
- A9 AI 助手:只解析待确认动作,前端确认后调既有发布接口;参数重新校验;自动化用 mock 不访问外网。
|
||||
- A10 快照/备份/换库:`SNAPSHOT_TABLES` 是否覆盖全部表;导出/恢复/切库不丢数据。
|
||||
|
||||
### B. 服务端 · 性能
|
||||
|
||||
- B1 循环内 Prisma 调用(N+1):`for/of` 或 `map` 内 `await prisma.*`;逐账号/逐班级查权限、成员、计数。
|
||||
- B2 无界查询:`findMany` 无 `take`/游标、全表拉到内存过滤排序、`include` 过多关联。
|
||||
- B3 权限与身份重复计算:同一请求内多次 `loadAuthPrincipal` 或反复查 `Class`/`User`;以当前授权入口为准,核对请求缓存与失效条件。
|
||||
- B4 重复序列化:同一大对象多次 `JSON.stringify`;快照/备份全量拼接;日志打印大对象。
|
||||
- B5 实时:广播粒度与房间订阅;事件载荷是否携带整表;连接数与心跳开销。
|
||||
- B6 HTTP:`compression` 是否生效范围合理;大响应是否流式;静态资源缓存头。
|
||||
- B7 定时任务:心跳判在线(约 30s / 90s 窗口)、更新轮询、升级检查、到点自动升级;是否重复注册、是否阻塞请求线程。
|
||||
- B8 索引:高频 `where`/`orderBy` 字段(`classId`、`studentId`、`assignDate`、`examId`、`teacherId`、`createdAt` 及常用复合条件)是否有索引支撑;新增索引需要迁移且对 SQLite/MySQL 都成立。
|
||||
- B9 查询字段:是否 `select` 了整行但只用两三个字段;是否在前端可算的聚合被放到 `O(n)` 内存。
|
||||
- B10 大文件:课件上传/下载/校验是否流式;临时文件是否清理;范围请求是否需要。
|
||||
|
||||
### C. 数据层
|
||||
|
||||
- C1 schema 与代码一致(字段名/默认值/可空性);迁移可重放;旧库升级路径有默认值。
|
||||
- C2 `SNAPSHOT_TABLES` 完整;换库后业务可读。
|
||||
- C3 唯一约束与删除策略:`deleteTeacher` 必须保护班主任、课程任课、已发布作业/通知、所属课件。
|
||||
- C4 SQLite/MySQL 差异:大小写、事务隔离、并发写、`LIKE` 行为;不得引入只对一种库成立的语句。
|
||||
|
||||
### D. Web 管理端
|
||||
|
||||
- D1 包体积:全量 Element Plus + 全量 CSS 的代价;`chunkSizeWarningLimit: 2000` 是否在掩盖问题;是否引入 `manualChunks`/按需加载/路由懒加载;改造必须验证样式与交互不回归。
|
||||
- D2 守卫双检:路由 `meta.permission` 与服务端权限;`navigation.ts` 与路由一致;菜单项无权限漂移。
|
||||
- D3 请求层:重复请求、并发竞态、取消、错误提示统一;切换页面/退出登录后的迟到响应。
|
||||
- D4 渲染:大表格/长列表分页或虚拟滚动;`watch(..., { deep: true })` 与深层响应式大对象;`v-html`;`computed` 内做重活。
|
||||
- D5 生命周期:`setInterval`/`setTimeout`/Socket 订阅/事件监听是否在卸载时清理;页面切换是否重复订阅。
|
||||
- D6 PWA:`sw.js` 不缓存 `/api`、`/socket.io`;版本更新后的缓存失效策略。
|
||||
- D7 移动端与关怀模式:断点与字号放大后布局不破。
|
||||
- D8 可访问性与语义色:动效统一 shared 令牌,不新增硬编码时长/缓动。
|
||||
|
||||
### E. 桌面客户端与灵动岛
|
||||
|
||||
- E1 启动链路:主进程同步阻塞、窗口创建顺序、首屏依赖的等待项;冷启动可否更快。
|
||||
- E2 IPC 与桥接:白名单不暴露 `ipcRenderer`;跨桥只传纯数据(不传 Vue Proxy);大对象拷贝次数。
|
||||
- E3 离线缓存:IndexedDB 按服务端与班级隔离;缓存故障不阻断在线读取;整表读写与增量更新;退出/切服清理会话但保留 `deviceKey`。
|
||||
- E4 心跳/重连:切配置重置计时、隔离迟到响应、401/403 退避、未登录不报错。
|
||||
- E5 灵动岛:窗口几何护栏、逐像素透明、投影常驻、触摸输入、失焦宽限;消息按 id 去重;崩溃恢复限流;经典模式与自定义常驻模式规则不混写。
|
||||
- E6 课件传输:流式、临时文件、SHA256、每设备回执;状态显示优先级。
|
||||
- E7 更新:无哈希拒收;立即/放学后/空闲策略;关闭自动更新不得强装。
|
||||
- E8 资源泄漏:定时器、监听器、窗口引用;崩溃重启次数上限。
|
||||
- E9 包体与安全:asar 内容、未打包凭据(`check-bundle-secrets`)、`build/icon.*` 兜底。
|
||||
|
||||
### F. `packages/shared`
|
||||
|
||||
- F1 类型、权限键、事件名、房间名、动效令牌、岛方案契约的单一来源;三端引用一致。
|
||||
- F2 运行时常量与类型定义同步;导出面(`src/index.ts`)无死导出。
|
||||
- F3 新增/修改契约必须三端同步(服务端、Web、桌面),且离线兜底逻辑一致。
|
||||
|
||||
### G. 脚本与 CI
|
||||
|
||||
- G1 脚本重复:多个 `verify-*.mjs` 是否有可复用 setup(临时库、隔离服务、账号创建);重复逻辑是否值得收敛。
|
||||
- G2 门禁可读性:失败时是否给出"哪一步、文件、怎么修";退出码正确。
|
||||
- G3 跨平台:Windows 本地与 Linux CI 的路径/编码/依赖差异;改 Linux 交付脚本必须 bash 语法检查 + Linux/CI 验证。
|
||||
- G4 临时资源:脚本退出是否清理临时 SQLite、进程、端口、`.cache` 目录。
|
||||
- G5 版本/发布一致性:`version.mjs` 落点与 `docs/dev/release.md` 的产物映射是否仍一致。
|
||||
|
||||
### H. 文档、官网与文档站
|
||||
|
||||
- H0 交叉核对 README、AGENTS、源码索引、开发首页、测试与发布文档;历史漂移只作线索,以当前实现重新判断。
|
||||
- H1 README:每个命令、文件名、截图、链接都能在仓库或 Releases 里对上;不写会过期的总数。
|
||||
- H2 `AGENTS.md`:包表、脚本表、端口、路径、命令与仓库一致;已退役内容要么删除要么标注。
|
||||
- H3 `docs/`:`get-started/`、`app/`、`management/`、`dev/`、`reference.md`、`faq.md` 的入口索引与内容一致;无死链、无过期数字、无指向 docs 树外的相对链接(源码用 GitHub 绝对链接)。
|
||||
- H4 `docs/toc.yml` 覆盖全部页面(`docs:check` 警告即错误)。
|
||||
- H5 官网:`index.html` 能力描述、`download.html` 版本兜底与清单逻辑、`404.html` 的 `<base>` 注入;`.reveal-grad` 不拆逐字节点。
|
||||
- H6 图片:展示图进 `docs/images/`,回归截图进 `docs/screenshots/`,不被误删/误引用。
|
||||
|
||||
### I. 提示词
|
||||
|
||||
- I1 `prompts/*.prompt.md`:结构、时效性、可执行性、是否写死会过期的结论。
|
||||
- I2 `AGENTS.md` 作为"代理入口提示词"的清晰度:长度是否失控、约束是否互相矛盾、是否有能直接照抄的命令。
|
||||
- I3 本次交付用的提示词自检:换一个零上下文代理,能否只靠执行入口 §3 完成 Phase 0。
|
||||
|
||||
---
|
||||
@@ -0,0 +1,149 @@
|
||||
# ClassHelper 全仓审计、优化与本地交付
|
||||
|
||||
> 先读根 AGENTS.md,再完成本文件与[审计清单](full-repo-audit-checklist.md)。
|
||||
> 以现场源码和本次命令为证据;保留已有工作;每阶段汇报结果。历史报告只作线索。
|
||||
|
||||
## 0. 工作顺序
|
||||
|
||||
1. 确认 cwd、分支、HEAD 和未提交文件;读取 AGENTS.md 及适用的子目录规则。
|
||||
2. 读 docs/dev/architecture.md、testing.md、release.md、permissions.md,再用 docs/reference.md 定位实现。
|
||||
3. 完成 Phase 0,建立问题账本,再按域修复。自动执行模式逐阶段继续;用户要求先确认计划时先交基线、账本和计划。
|
||||
4. 每项按“复现/测量 → 最小修复 → 定向验证 → 按主题提交”闭环。
|
||||
|
||||
先用 rg 定位再分段读取。日志保存 .cache/audit/<本次运行>/,对话报告实际摘要。
|
||||
首次生成唯一 runId,并在账本记录 cwd、HEAD、工具版本、命令和进程标识;中断后沿用原目录,追加日志而不覆盖失败证据。
|
||||
只读可并行;同一文件单一写者,shared/schema/根配置串行处理,同时只运行一个大构建。
|
||||
每阶段建议 1–2 小时时间盒;到时报告卡点及下一步,不静默延长。
|
||||
|
||||
## 1. 工程边界
|
||||
|
||||
完整契约在 AGENTS.md,修改对应模块前核对:
|
||||
|
||||
- 验收使用临时 SQLite、独立账号与文件目录;真实库不 seed/reset,不改真实班级密码,不发测试消息。
|
||||
- 权限同时检查能力、该键范围和业务关系;CLASS_DEVICE 的既有本班能力保留;课表维护范围不能自授任课关系。
|
||||
- 单一 Prisma schema,SQLite/MySQL 通用;模型变动新增迁移并同步快照及旧库兼容,保留历史迁移。
|
||||
- 批量写入和整库恢复保留事务边界;事件在提交后发;日期/周次使用共享及服务端唯一入口。
|
||||
- Electron 保留桥接白名单、CSP、同源导航、缓存隔离、设备归属、去重和 SHA256 门禁。冒烟使用假系统执行器。
|
||||
- 岛的透明、几何、投影、触摸、崩溃限流和两种模式规则保持原约束;视觉与联网验收按 testing.md 的授权边界执行。
|
||||
- 保留运行数据、依赖缓存、dist、凭据及其他版本交付物;递归文件操作前验证绝对目标路径。
|
||||
- 中文文案、文档、注释与 Conventional Commits;LF,只格式化本次改动。
|
||||
- 版本只走 scripts/version.mjs;用户已给版本策略时沿用,否则打包前确认级别,建议 patch。
|
||||
- 未明确授权不 push、不建 tag/Release、不上传或替换远端资产;本地站点构建不等于发布。
|
||||
|
||||
## 2. 现场证据与账本
|
||||
|
||||
账本位于 .cache/audit/<本次运行>/ledger.md:
|
||||
|
||||
| ID | 域/检查项 | 文件:行号 | 复现命令与现象 | 级别 | 方案 | 验证日志 | 状态 |
|
||||
| ---- | --------- | --------- | -------------- | ---- | -------- | -------- | ---------------- |
|
||||
| 示例 | A3 | 具体源码 | 实际结果 | P0 | 单一主题 | 本次证据 | 修复/无问题/后续 |
|
||||
|
||||
清单 A–I 每项必须有结论;“无问题”要证据,“后续”要原因、影响和具体下一步。
|
||||
P0:越权、数据丢失/错乱、生产中断、迁移损坏;P1:已测量性能缺陷或错误行为;P2/P3:维护与文案。
|
||||
先复现 P0,再修 P1;候选不是结论,不为凑数改代码。
|
||||
|
||||
至少三项性能改进使用相同输入及工具链记录前后值和复现命令。
|
||||
指标可为查询/模型操作数、载荷、原始/gzip 体积、启动中位数或内存;模型操作数不能冒充底层 SQL 条数。
|
||||
保留 HTTP、事件和离线格式;必要的安全收紧明确说明触发条件,同步调用方、文档和断言。
|
||||
单文件超过 40% 或跨多个文件的大重构先报告方案、收益和回滚路径;不做无度量重写、全仓格式化、无关改名。
|
||||
新运行时依赖须说明现有依赖无法满足的原因、体积和回滚方式。
|
||||
|
||||
## 3. Phase 0:基线
|
||||
|
||||
依次记录命令、退出码、耗时和关键输出:
|
||||
|
||||
```text
|
||||
git status --short --branch
|
||||
git log --oneline -5
|
||||
node -v
|
||||
Get-Command pnpm
|
||||
pnpm --version
|
||||
pnpm version:check
|
||||
pnpm check:icons
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm docs:check
|
||||
pnpm build
|
||||
```
|
||||
|
||||
实际 pnpm 须匹配根 packageManager;DSH 配置见 AGENTS.md。需要前置时按 install → db:generate → 独立库 db:deploy → build:shared。
|
||||
基线构建不要求迁移业务库。确需准备独立夹具时,先显式设置本次审计目录内的绝对 SQLite `DATABASE_URL`,再执行 `pnpm --filter @classhelper/server db:deploy`,完成后恢复原环境变量;不能沿用 Prisma 从业务 `.env` 读取的地址。专项优先使用会自建临时库的 verify 包装器。
|
||||
大构建保存进程标识并轮询,不重复启动。出口:每条命令有本次结果;账本覆盖 A–I;P0 明确;汇报一次。
|
||||
|
||||
## 4. Phase 1–4:修复与优化
|
||||
|
||||
| 阶段 | 工作 | 出口 |
|
||||
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| 1 服务端/数据 | 清单 A–C;先鉴权、事务、竞态和错误码,再重复查询、序列化、索引 | 类型检查与相关隔离专项通过,快照/迁移完整,性能有测量 |
|
||||
| 2 Web | 清单 D;先构建量体积,再优化加载、守卫、请求、PWA、生命周期 | 构建与隐藏 UI 通过;样式、交互、组件注册不回归 |
|
||||
| 3 桌面 | 清单 E;检查真实启动、桥接、缓存、设备、传输、更新及资源调用链 | 桌面构建和默认 quick 冒烟通过;未改岛不额外占用桌面 |
|
||||
| 4 shared/脚本/CI | 清单 F–G;三端契约、退出码、临时资源、跨平台 | 静态与专项通过;Linux 交付改动有 bash 和 Linux/CI 证据 |
|
||||
|
||||
先保留失败信号再改实现;断言更新须对应明确行为修正,不删断言、不跳过、不放宽鉴权。
|
||||
缓存初始化或请求内重复计算时,权限变更仍实时生效,快照恢复/换库后初始化状态可重置。
|
||||
|
||||
## 5. Phase 5–6:文档和提示词
|
||||
|
||||
按源码同步 README、AGENTS、受影响帮助/开发文档、索引与官网;新增页登记 toc。
|
||||
核对改动页面全部链接和图片目标,docfx 严格构建不能代替普通链接检查。
|
||||
展示图保留 docs/images,回归留档 docs/screenshots;自动生成的新截图须人工核验后才交付。
|
||||
保持官网根站与 /docs/ 布局、脚本版本落点;下载页核对在线元数据及离线兜底路径。
|
||||
提示词保留目标、边界、现场入口、清单、出口、验证和失败处理,移除重复规则与固定模块/表/测试总数。
|
||||
用零上下文代理自检 Phase 0 可执行性;修正缺口,不重复昂贵或有副作用的验收。
|
||||
出口:格式、链接、docs:check、pages:build 通过;有提示词优化前后差异和自检结论。
|
||||
|
||||
## 6. 验证矩阵
|
||||
|
||||
以当前 package.json 为准;新改动只重跑受影响检查,最终汇总本批证据。
|
||||
|
||||
| 范围 | 检查 |
|
||||
| ------------- | --------------------------------------------------------------------- |
|
||||
| 静态 | lint、typecheck、check:icons、version:check |
|
||||
| 服务端 | verify:e2e、verify:v14;权限加 verify:authz |
|
||||
| 审计/事务/PWA | verify:audit;本次问题补夹具及指标 |
|
||||
| 生命周期/迁移 | verify:lifecycle、verify:client-migrations、临时旧库升级 |
|
||||
| 课件/设备 | verify:courseware、verify:clients-api |
|
||||
| 更新 | verify:update-download、verify:update-installer、verify:client-agent |
|
||||
| Web | Web 包 build、verify:web:isolated |
|
||||
| 桌面 | build:desktop、verify:desktop、相关逻辑专项 |
|
||||
| 打包 | verify:packaged --exe <portable 路径> --offline;服务端副本初始化复验 |
|
||||
| 文档/官网 | 本次文件格式和链接、docs:check、pages:build、关键输出页检查 |
|
||||
|
||||
默认不执行真实系统指令、安装器、桌面视觉或外网;需要时在已有授权内处理。
|
||||
记录真实通过/失败/阻塞,不引用历史数量。
|
||||
|
||||
## 7. Phase 7:版本与本地包
|
||||
|
||||
1. 沿用已确认版本策略;未指定时此时确认,建议 patch。确认后通过 version 脚本修改并 version:check。
|
||||
2. 检查磁盘和 releases 当前目录,保留其他版本及同号可恢复副本。
|
||||
3. 后台执行 dist:all,核对实际产物并完成打包冒烟,不只看退出码。
|
||||
4. 写 ReleaseNotes-<版本>.md,说明变化、兼容注意、实际验证和文件清单。
|
||||
5. 计算 SHA256SUMS-<版本>.txt,使用 release.md 的上传名,附本地名映射、大小、摘要。
|
||||
6. Linux 正式包由 Linux runner 构建;无远端授权时明确待 CI,不用 Windows 交叉包冒充。
|
||||
7. releases 无 win-unpacked、staging 或解包副本;只清理本次生成且已确认的临时对象。
|
||||
|
||||
出口:Windows 包齐全、哈希可复算、packaged=true 离线两次启动通过,说明与包一致。
|
||||
远端另按 release.md 在明确授权后执行,并等待 CI。
|
||||
|
||||
## 8. Phase 8:提交与交付
|
||||
|
||||
逐主题审阅 diff,排除凭据、业务数据、临时库、缓存和包;按中文 Conventional Commits 分组提交。
|
||||
保留任务输入外的原有未提交工作,不把历史 result 改写为当前事实。
|
||||
|
||||
最终交付:A–I 账本及级别汇总;三项以上性能前后表和命令;验证矩阵及重试原因;
|
||||
本地包路径/大小/SHA256、ReleaseNotes/清单;文档与提示词差异、自检;提交列表、未覆盖范围和后续。
|
||||
完成判据:P0 有修复回归,P1 修复或有量化延期理由;各项无“待看”;源码、版本、文档和包一致;
|
||||
受影响门禁通过或准确说明阻塞;有可审阅提交,没有把未执行检查写成通过。
|
||||
|
||||
## 9. 失败处理
|
||||
|
||||
| 情况 | 操作 |
|
||||
| --------------------- | ----------------------------------------------------------------- |
|
||||
| 工具版本不对 | 按 AGENTS 修正 DSH 路径并核验,不为转发壳修改依赖 |
|
||||
| Node 原生内存错误 | 留日志、限制并发或用满足 engines 的已安装 Node LTS 复验,记录版本 |
|
||||
| docfx 缺失/警告 | 按 build.mjs 提示处理、补 toc;装不上记阻塞,不关严格模式 |
|
||||
| electron-builder 受限 | 核对进程访问限制,用已授权环境;不据此重装依赖 |
|
||||
| 失败/超时 | 查本次日志及进程,只清理本次资源;先复现,不放宽断言 |
|
||||
| 写入受限 | 尝试授权范围内最小操作,拒绝时完成可行的只读工作并解释 |
|
||||
| 外网/CI 未授权 | 完成本地交付,远端步骤记后续 |
|
||||
| 中断恢复 | 先核对 git、日志、任务标识及进程,避免重复构建和覆盖结果 |
|
||||
@@ -0,0 +1,55 @@
|
||||
# 全仓审计与本地交付结果(2026-11-07)
|
||||
|
||||
本批从 master 的 71cc8eb 开始,用户确认补丁版本 1.4.3。记录仅代表本次执行,不是今后版本的能力保证。
|
||||
|
||||
## 结果
|
||||
|
||||
- 封堵通过建课取得任课并写成绩的越权链。
|
||||
- 批量成绩与快照恢复加入事务,并用无效末行、触发器故障及无效恢复字段验证回滚。
|
||||
- 通知并发已读通过唯一冲突重读保证幂等。
|
||||
- 三项重复数据库操作和 Web 入口体积有实测下降,指标明确区分模型操作与 SQL。
|
||||
- 本地 Windows 服务端、客户端安装包及便携包已生成,实际包验收通过;未发布远端。
|
||||
|
||||
## 性能
|
||||
|
||||
| 相同输入与指标 | 基线 | 修复后 |
|
||||
| ---------------------------------- | --------------: | --------------: |
|
||||
| 默认组已初始化后两次调用的模型操作 | 10 | 0 |
|
||||
| 同班同科50条等级修改的课程查找 | 50 | 1 |
|
||||
| 同班20设备放学更新的班级查找 | 20 | 1 |
|
||||
| Web入口JS原始/gzip | 918.75/292.26KB | 616.50/197.19KB |
|
||||
|
||||
前三项复现:`pnpm verify:audit`;Web:`pnpm --filter @classhelper/web-admin build`。
|
||||
主题 CSS 保留,未声称桌面启动或内存有性能提升。
|
||||
|
||||
## 兼容与验证
|
||||
|
||||
新建课程仅管理员可用,已有科目的排课及外观维护按原授权;旧请求被明确拒绝,不静默改写任课关系。
|
||||
schema、历史迁移、事件与离线格式未改。快照清单与迁移后实际表逐项校验,旧库升级通过。
|
||||
|
||||
本次输出:审计10/10、PWA5/5、授权23项、e2e251/251、verify:v14 37/37、生命周期31/31、
|
||||
课件61/61、设备API29/29、客户端代理17/17、客户端逻辑18/18、隐藏Web64/64。
|
||||
开发与实际便携包都连续两次70/70;便携包 `packaged=true` 且版本1.4.3。
|
||||
实际服务端包副本的密钥独立和配置保留检查通过。静态、格式、文档严格构建、Pages 与本地链接检查通过。
|
||||
|
||||
原生内存失败与早期失败断言保留在本地审计目录;通过限制堆、串行检查和独立复验完成验收,
|
||||
未删断言或跳过失败用例。桌面同步断言仅补诊断信息,保留原有延迟、几何和快照判据。
|
||||
|
||||
## 文档和提示词
|
||||
|
||||
修正权限源码路径、开发首页组成与房间名、README下载/索引/seed说明、测试包装器前置及发布目录口径。
|
||||
补 AI 助手帮助与 toc;同步科目、成绩、恢复的安全行为。官网兜底版本由脚本更新。
|
||||
任务入口拆为阶段执行文档和 A–I 清单;零上下文只读代理核对入口、命令、路径、版本和远端边界,
|
||||
反馈的失效节号、独立库绝对地址和唯一运行目录要求均已补齐。历史 result 文件保留。
|
||||
|
||||
## 后续与边界
|
||||
|
||||
- 大库快照全量序列化/压缩、完整数组分页、索引与虚拟滚动先补真实规模和查询计划。
|
||||
- 快捷导入保留12MB请求体硬边界,base64原始数据约9MB;流式大快照导入需另行设计契约。
|
||||
- Node24客户端代理测试的FileHandle GC告警需专门跟踪;未以通过用例宣称无资源泄漏。
|
||||
- MySQL实库、Linux runner、真实安装和完整视觉验收未执行。Linux正式包需授权远端CI,未用交叉包代替。
|
||||
- 远端未授权,未push、未建Tag/Release、未上传或替换资产。
|
||||
|
||||
完整A–I逐项账本、原始失败与通过日志、命令退出码、包大小/摘要及最终提交列表保存在
|
||||
`.cache/audit/2026-11-07/`;该目录和`releases/`按仓库规则不提交。
|
||||
本地交付说明为`releases/ReleaseNotes-1.4.3.md`,上传名摘要为`releases/SHA256SUMS-1.4.3.txt`。
|
||||
@@ -107,10 +107,15 @@ async function checkClassRelations(win, options, record) {
|
||||
return { studentWrite: Array.from(drawer.querySelectorAll('#pane-students button')).some(button => button.textContent.trim() === '添加学生'), courseCreate: Boolean(drawer.querySelector('#pane-courses input')), gradeQueryEnabled: !drawer.querySelector('#pane-settings .el-switch')?.classList.contains('is-disabled') };
|
||||
})()`);
|
||||
record(
|
||||
'班主任本人班级仍可维护名单、课程和成绩查询开关',
|
||||
owner.studentWrite && owner.courseCreate && owner.gradeQueryEnabled,
|
||||
'班主任可维护本班名单和成绩查询开关,但不能通过建课取得任课关系',
|
||||
owner.studentWrite && !owner.courseCreate && owner.gradeQueryEnabled,
|
||||
JSON.stringify(owner),
|
||||
);
|
||||
const created = await request('/courses', admin.token, 'POST', {
|
||||
classId: other.id,
|
||||
name: '管理员建课验证',
|
||||
});
|
||||
record('管理员仍可建立课程与任课关系', created.status === 201, `status=${created.status}`);
|
||||
const members = await data('/permissions/users', admin.token);
|
||||
const previous = members.find((member) => member.id === teacher.user.id).assignments;
|
||||
const groups = [];
|
||||
|
||||
@@ -442,6 +442,10 @@ async function main() {
|
||||
|
||||
win.on('show', () => record('后台验证禁止显示窗口', false, '出现 show 事件'));
|
||||
win.on('focus', () => record('后台验证禁止抢占焦点', false, '出现 focus 事件'));
|
||||
win.webContents.session.webRequest.onErrorOccurred((details) => {
|
||||
// 仅记录测试浏览器的失败请求;去除查询参数,便于区分换页取消和真实接口故障。
|
||||
console.log(`[ui-network] ${details.error} ${new URL(details.url).pathname}`);
|
||||
});
|
||||
// 把渲染进程的报错转发到控制台(兼容 Electron 新旧事件签名)
|
||||
win.webContents.on('console-message', (...args) => {
|
||||
const first = args[0];
|
||||
|
||||
@@ -35,5 +35,10 @@ await run([
|
||||
'--config',
|
||||
'packages/server/prisma.config.ts',
|
||||
]);
|
||||
await run(['packages/server/node_modules/tsx/dist/cli.mjs', 'packages/server/scripts/verify-authz.ts']);
|
||||
await run([
|
||||
'packages/server/node_modules/tsx/dist/cli.mjs',
|
||||
process.argv.includes('--audit')
|
||||
? 'packages/server/scripts/verify-audit.ts'
|
||||
: 'packages/server/scripts/verify-authz.ts',
|
||||
]);
|
||||
console.log(`授权隔离数据库:${dir}`);
|
||||
@@ -0,0 +1,111 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import fs from 'node:fs';
|
||||
import vm from 'node:vm';
|
||||
|
||||
const source = fs.readFileSync(new URL('../packages/web-admin/public/sw.js', import.meta.url), 'utf8');
|
||||
const registry = fs.readFileSync(
|
||||
new URL('../packages/web-admin/src/element-plus.ts', import.meta.url),
|
||||
'utf8',
|
||||
);
|
||||
function verifyComponentRegistry(dir) {
|
||||
for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
|
||||
const file = new URL(item.name + (item.isDirectory() ? '/' : ''), dir);
|
||||
if (item.isDirectory()) verifyComponentRegistry(file);
|
||||
else if (item.name.endsWith('.vue')) {
|
||||
for (const [, tag] of fs.readFileSync(file, 'utf8').matchAll(/<(el-[a-z0-9-]+)\b/g)) {
|
||||
const name = tag
|
||||
.split('-')
|
||||
.map((word) => word[0].toUpperCase() + word.slice(1))
|
||||
.join('');
|
||||
assert(registry.includes(name), `${file.pathname} 的 ${tag} 未注册`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
verifyComponentRegistry(new URL('../packages/web-admin/src/', import.meta.url));
|
||||
console.log('组件注册表覆盖全部模板标签');
|
||||
let passed = 0;
|
||||
let failed = 0;
|
||||
async function check(name, test) {
|
||||
const handlers = new Map();
|
||||
const writes = [];
|
||||
const deleted = [];
|
||||
const context = {
|
||||
URL,
|
||||
Response,
|
||||
self: {
|
||||
location: { origin: 'https://audit.invalid' },
|
||||
addEventListener: (name, fn) => handlers.set(name, fn),
|
||||
clients: { claim: async () => {} },
|
||||
skipWaiting: async () => {},
|
||||
},
|
||||
caches: {
|
||||
open: async () => ({
|
||||
addAll: async () => {},
|
||||
put: async (key) => {
|
||||
writes.push(key);
|
||||
},
|
||||
}),
|
||||
keys: async () => ['classhelper-admin-v1', 'unrelated-app-cache'],
|
||||
delete: async (key) => {
|
||||
deleted.push(key);
|
||||
},
|
||||
match: async () => undefined,
|
||||
},
|
||||
fetch: async () => new Response('应用外壳', { headers: { 'content-type': 'text/html' } }),
|
||||
};
|
||||
vm.runInNewContext(source, context);
|
||||
async function fire(name, request) {
|
||||
const tasks = [];
|
||||
let response;
|
||||
handlers.get(name)({
|
||||
request,
|
||||
waitUntil: (task) => tasks.push(task),
|
||||
respondWith: (task) => {
|
||||
response = task;
|
||||
},
|
||||
});
|
||||
const result = response ? await response : undefined;
|
||||
await Promise.all(tasks);
|
||||
await new Promise((resolve) => setImmediate(resolve));
|
||||
return result;
|
||||
}
|
||||
try {
|
||||
await test({ context, writes, deleted, fire });
|
||||
console.log(`通过 ${++passed}:${name}`);
|
||||
} catch (error) {
|
||||
failed++;
|
||||
console.error(`失败:${name}:${error.message}`);
|
||||
}
|
||||
}
|
||||
const navigate = (pathname) => ({ method: 'GET', mode: 'navigate', url: 'https://audit.invalid' + pathname });
|
||||
await check('错误导航响应不覆盖离线外壳', async ({ context, writes, fire }) => {
|
||||
context.fetch = async () =>
|
||||
new Response('失败页面', { status: 500, headers: { 'content-type': 'text/html' } });
|
||||
assert.equal((await fire('fetch', navigate('/dashboard'))).status, 500);
|
||||
assert.deepEqual(writes, []);
|
||||
});
|
||||
await check('非HTML导航不覆盖离线外壳', async ({ context, writes, fire }) => {
|
||||
context.fetch = async () => new Response('{}', { headers: { 'content-type': 'application/json' } });
|
||||
await fire('fetch', navigate('/download'));
|
||||
assert.deepEqual(writes, []);
|
||||
});
|
||||
await check('API与实时根路径及子路径全部透传', async ({ fire }) => {
|
||||
for (const pathname of ['/api', '/api/health', '/socket.io', '/socket.io/'])
|
||||
assert.equal(await fire('fetch', navigate(pathname)), undefined);
|
||||
});
|
||||
await check('只清理本应用的旧缓存', async ({ deleted, fire }) => {
|
||||
await fire('activate');
|
||||
assert.deepEqual(deleted, ['classhelper-admin-v1']);
|
||||
});
|
||||
await check('有效HTML仍更新外壳并支持离线回退', async ({ context, writes, fire }) => {
|
||||
assert.equal((await fire('fetch', navigate('/dashboard'))).status, 200);
|
||||
assert.deepEqual(writes, ['/index.html']);
|
||||
context.fetch = async () => {
|
||||
throw new Error('离线夹具');
|
||||
};
|
||||
context.caches.match = async () => new Response('已缓存外壳');
|
||||
assert.equal(await (await fire('fetch', navigate('/dashboard'))).text(), '已缓存外壳');
|
||||
});
|
||||
console.log(`Web Worker 专项:${passed} 通过,${failed} 失败`);
|
||||
if (failed) process.exitCode = 1;
|
||||
+1
-2
@@ -4,8 +4,7 @@
|
||||
*
|
||||
* ## 为什么要这个脚本
|
||||
*
|
||||
* 这个仓库里**同一个版本号写在 12 处(10 个文件)**:5 份 package.json、运行时常量、两个 compose 文件、
|
||||
* 官网页面上三处手写的版本号、下载页那一处兜底值。
|
||||
* 同一个版本号需要同步 workspace 包、部署清单与官网兜底值,具体落点以本脚本的目标清单为准。
|
||||
* 手工改必然漏一处,
|
||||
* 而漏掉的那处**不会报错**,只会在某个不常走的分支上表现为"版本号对不上":
|
||||
*
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
<!-- 页面上所有版本号与文件名都从这一行起步:脚本会去 GitHub Releases 取真实清单,
|
||||
取不到时(离线、被限流)就按这份版本号 + 发布命名约定拼直链。
|
||||
它和根 package.json 一起由 `pnpm version:bump` 维护 —— 别在这儿单独改。 -->
|
||||
<meta name="ch-version" content="1.4.2" />
|
||||
<meta name="ch-version" content="1.4.3" />
|
||||
<link rel="icon" href="assets/icon.png" />
|
||||
<link rel="apple-touch-icon" href="assets/icon.png" />
|
||||
|
||||
|
||||
+3
-3
@@ -44,7 +44,7 @@
|
||||
<a class="brand" href="#top" data-press="0.96">
|
||||
<img class="brand-mark" src="assets/icon.png" alt="" width="32" height="32" />
|
||||
<span class="brand-name">ClassHelper</span>
|
||||
<span class="brand-ver">1.4.2</span>
|
||||
<span class="brand-ver">1.4.3</span>
|
||||
</a>
|
||||
<nav class="topnav" aria-label="页内导航">
|
||||
<span class="nav-pill" aria-hidden="true"></span>
|
||||
@@ -93,7 +93,7 @@
|
||||
</div>
|
||||
|
||||
<ul class="hero-badges intro-seq" style="--intro-delay: 300ms">
|
||||
<li>v1.4.2</li>
|
||||
<li>v1.4.3</li>
|
||||
<li>Windows 10/11</li>
|
||||
<li>Linux · Docker</li>
|
||||
<li>触摸屏可用</li>
|
||||
@@ -733,7 +733,7 @@
|
||||
ClassHelper
|
||||
<span>Class Helper</span>
|
||||
</p>
|
||||
<p class="foot-ver">版本 1.4.2 · 源码公开 · 装在你自己的机器上</p>
|
||||
<p class="foot-ver">版本 1.4.3 · 源码公开 · 装在你自己的机器上</p>
|
||||
</div>
|
||||
</div>
|
||||
<nav class="foot-nav" aria-label="相关链接">
|
||||
|
||||
Reference in new issue
Block a user