docs(audit): 同步安全边界并整理全仓审计入口

This commit is contained in:
LoveChengke committed 2026-11-07 02:02:22 +08:00
1 parent 3a7aed0800
commit 8bd5bcb9ff
17 files changed
+303 -14

No files matched your search

+7 -2
View File
@@ -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 描述。只有用户要求发布/同步时才执行远端发布链。
+4 -4
View File
@@ -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` 会清空并写入演示账号、班级、学生、课表与教学内容,仅用于独立演示库:
| 角色 | 账号 | 密码 |
| -------------------------- | ------------- | ------------ |
+26
View File
@@ -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)。
+2
View File
@@ -32,6 +32,8 @@ Student 存学号、姓名、班级、性别、家长电话和状态,没有密
科任关系唯一存于 Course(classId, name, teacherId),分配任课关系由班级管理权限及服务端断言限制。
班主任不任教某科就不能修改该科作业/成绩;科任老师有相应权限时可以管理自己任教科目。
新建科目同时建立任课关系,只对管理员开放。教师需要增加科目或改变任课老师时,请联系管理员;年级、部或全校课表维护范围不能用来给自己任课。
删除教师前,服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件;仍有业务内容则返回冲突,避免级联丢失。
教师本人改密码、管理员修改教师密码、班级账号密码是不同入口;学生没有密码接口。
+3 -1
View File
@@ -6,11 +6,13 @@ description: 录入、按学号查询、排名与关闭个人查询后的集体
# 成绩
Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。
科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。新增科目及任课关系由管理员配置。
成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查:
管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。
表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。
整班批量录入在同一事务中校验学生、授权并写入成绩;任意一行无效或写入失败时整批回滚,不留下部分成绩。等级批量修改按每个班级与科目组合独立检查授权。
## 查看、排名与隐私
班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。
+1
View File
@@ -10,6 +10,7 @@ description: ClassHelper每一项功能怎么用:课表、作业、通知、
| 页面 | 讲什么 |
| --------------------------------- | ---------------------------------------------------------- |
| [AI 助手](assistant.md) | 自然语言解析、核对确认、业务权限与离线示例 |
| [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 |
| [课件](courseware.md) | 上传、班级可见范围、推送与逐设备接收 |
| [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 |
+2
View File
@@ -22,6 +22,8 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编
时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。
可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。
新增科目会建立任课关系,仅管理员可执行;课表维护者可以使用已配置的科目排课,需要新增或更换任课老师时联系管理员。
时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。
日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。
+2
View File
@@ -1,5 +1,7 @@
- name: 应用帮助
href: index.md
- name: AI 助手
href: assistant.md
- name: 课表
href: schedules.md
- name: 作业
+2
View File
@@ -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
View File
@@ -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(含灵动岛)
▲ │
└──── 老师下发的提醒 ◄──────┘
+2
View File
@@ -55,6 +55,8 @@ description: 能力目录、岗位模板、分配范围与业务关系的授权
ALL 也不能替代班主任、任课、发布者关系,只有 ADMIN 无条件绕过关系。班级端可代录作业,不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接,不能因事务路径省略授权。
`POST /courses` 会建立任课关系,仅管理员可新建。教师的日课表维护范围不授予建课或自分配任课资格;已有课程仍可按课表权限排课及维护外观。离线档案导入复用既有科目,新增占位科目按班主任归属,不采信导入文件中的教师姓名作为授权。
成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后,本班设备仍可获得集体聚合,个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护,服务端执行稀疏样本和补集抑制。
## 实时与设备
+1 -1
View File
@@ -30,7 +30,7 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版
以上按发布改动范围执行;显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。
完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本,最新包核验完成后按用户要求清理旧归档。
2026-10-18 工作区清理后,1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。
版本目录与清单以本次实际构建结果为准;历史清理记录不代表当前保留的版本。
## 产物与文件名
+4 -1
View File
@@ -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 复验,记录实际版本。
## 截图
+1
View File
@@ -25,6 +25,7 @@ Web 管理端有一个「数据库管理」页(`/database`,**仅管理员可
- 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出;
- 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联,表清单与恢复顺序由 `lib/snapshot.ts` 统一维护;
- 清空与重新写入属于同一事务;中途写入失败时回滚并保留原库。MySQL 的外键开关在该事务的同一连接上恢复,SQLite 在事务前后切换;
- 分批 `createMany` 写入。
相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复;格式与缺失表由快照校验器检查。
+3 -2
View File
@@ -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/` |
+91
View File
@@ -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、日志、任务标识及进程,避免重复构建和覆盖结果 |