From 8bd5bcb9ff56d281becf3e5a76e1d06124b9695f Mon Sep 17 00:00:00 2001 From: LoveChengke Date: Sat, 7 Nov 2026 02:02:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(audit):=20=E5=90=8C=E6=AD=A5=E5=AE=89?= =?UTF-8?q?=E5=85=A8=E8=BE=B9=E7=95=8C=E5=B9=B6=E6=95=B4=E7=90=86=E5=85=A8?= =?UTF-8?q?=E4=BB=93=E5=AE=A1=E8=AE=A1=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 9 +- README.md | 8 +- docs/app/assistant.md | 26 +++ docs/app/classes.md | 2 + docs/app/grades.md | 4 +- docs/app/index.md | 1 + docs/app/schedules.md | 2 + docs/app/toc.yml | 2 + docs/dev/architecture.md | 2 + docs/dev/index.md | 6 +- docs/dev/permissions.md | 2 + docs/dev/release.md | 2 +- docs/dev/testing.md | 5 +- docs/management/database.md | 1 + docs/reference.md | 37 ++--- prompts/full-repo-audit-checklist.md | 91 +++++++++++ ...full-repo-audit-optimize-release.prompt.md | 149 ++++++++++++++++++ 17 files changed, 319 insertions(+), 30 deletions(-) create mode 100644 docs/app/assistant.md create mode 100644 prompts/full-repo-audit-checklist.md create mode 100644 prompts/full-repo-audit-optimize-release.prompt.md diff --git a/AGENTS.md b/AGENTS.md index 6d72f4b..987e20b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 描述。只有用户要求发布/同步时才执行远端发布链。 diff --git a/README.md b/README.md index 01cbabc..c3bf61c 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ ClassHelper是给中小学班级用的一套信息管理系统。
| 教室机器 / 学生电脑 | **学生客户端** | `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` 会清空并写入演示账号、班级、学生、课表与教学内容,仅用于独立演示库: | 角色 | 账号 | 密码 | | -------------------------- | ------------- | ------------ | diff --git a/docs/app/assistant.md b/docs/app/assistant.md new file mode 100644 index 0000000..b98f7e9 --- /dev/null +++ b/docs/app/assistant.md @@ -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)。 diff --git a/docs/app/classes.md b/docs/app/classes.md index 951539e..90f0a47 100644 --- a/docs/app/classes.md +++ b/docs/app/classes.md @@ -32,6 +32,8 @@ Student 存学号、姓名、班级、性别、家长电话和状态,没有密 科任关系唯一存于 Course(classId, name, teacherId),分配任课关系由班级管理权限及服务端断言限制。 班主任不任教某科就不能修改该科作业/成绩;科任老师有相应权限时可以管理自己任教科目。 +新建科目同时建立任课关系,只对管理员开放。教师需要增加科目或改变任课老师时,请联系管理员;年级、部或全校课表维护范围不能用来给自己任课。 + 删除教师前,服务端检查其负责的班级、任课课程、发布过的作业/通知与所属课件;仍有业务内容则返回冲突,避免级联丢失。 教师本人改密码、管理员修改教师密码、班级账号密码是不同入口;学生没有密码接口。 diff --git a/docs/app/grades.md b/docs/app/grades.md index b166e58..02c8bd2 100644 --- a/docs/app/grades.md +++ b/docs/app/grades.md @@ -6,11 +6,13 @@ description: 录入、按学号查询、排名与关闭个人查询后的集体 # 成绩 Web 管理端支持单条、批量和表格导入成绩;记录通过 Grade.studentId 关联学生名单。 -科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。 +科目来自班级课程与共享科目目录,分数、总分和等级按录入规则校验。新增科目及任课关系由管理员配置。 成绩写入需 grade:write 或相应导入权限,并通过班级和科目检查: 管理员可管理,教师只能编辑自己任课科目,无科目内容按班主任规则;班级端不能写成绩。 表格导入另有管理员/本班班主任门槛,班主任也只能导入符合科目权限的行;它与单条/批量录入的准入不同。 +整班批量录入在同一事务中校验学生、授权并写入成绩;任意一行无效或写入失败时整批回滚,不留下部分成绩。等级批量修改按每个班级与科目组合独立检查授权。 + ## 查看、排名与隐私 班级客户端可显示本班考试、成绩总览、等级分布,以及按学号查询明细。 diff --git a/docs/app/index.md b/docs/app/index.md index 24fb099..5f7b3cc 100644 --- a/docs/app/index.md +++ b/docs/app/index.md @@ -10,6 +10,7 @@ description: ClassHelper每一项功能怎么用:课表、作业、通知、 | 页面 | 讲什么 | | --------------------------------- | ---------------------------------------------------------- | +| [AI 助手](assistant.md) | 自然语言解析、核对确认、业务权限与离线示例 | | [课表](schedules.md) | 周视图与「今天」时间轴、单双周、学期周数、课表来源 | | [课件](courseware.md) | 上传、班级可见范围、推送与逐设备接收 | | [作业](homeworks.md) | 按所属日期归类、看板与全屏看板、教室机器录入、未交名单 | diff --git a/docs/app/schedules.md b/docs/app/schedules.md index 6ed9711..fa1266f 100644 --- a/docs/app/schedules.md +++ b/docs/app/schedules.md @@ -22,6 +22,8 @@ Web 管理端统一从「教学事务 → 课表档案」查看周课表并编 时间表保存时间点:上课、课间、分割线、行动;日课表引用时间表,每节课程通过外键关联时间点。 可以维护多套班级作息或共享作息、复制日课表、调整课程、配置启用规则和群组。 + +新增科目会建立任课关系,仅管理员可执行;课表维护者可以使用已配置的科目排课,需要新增或更换任课老师时联系管理员。 时间点排序不会改变课程关联。行动配置当前保存数据,不执行外部动作。 日课表按星期、周次范围和轮换规则启用,支持 1–9 周轮换;单双周是 2 周轮换的特例,第 1 教学周为单周。 diff --git a/docs/app/toc.yml b/docs/app/toc.yml index 5d76649..7427216 100644 --- a/docs/app/toc.yml +++ b/docs/app/toc.yml @@ -1,5 +1,7 @@ - name: 应用帮助 href: index.md +- name: AI 助手 + href: assistant.md - name: 课表 href: schedules.md - name: 作业 diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 3780785..b21da6b 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -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 构建时拼接 | ## 模块与数据流 diff --git a/docs/dev/index.md b/docs/dev/index.md index abe320b..ce62826 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -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(含灵动岛) ▲ │ └──── 老师下发的提醒 ◄──────┘ diff --git a/docs/dev/permissions.md b/docs/dev/permissions.md index 8086ae4..03468fe 100644 --- a/docs/dev/permissions.md +++ b/docs/dev/permissions.md @@ -55,6 +55,8 @@ description: 能力目录、岗位模板、分配范围与业务关系的授权 ALL 也不能替代班主任、任课、发布者关系,只有 ADMIN 无条件绕过关系。班级端可代录作业,不能写成绩。跨班调班检查源班与目标班。事务中的断言使用同一事务连接,不能因事务路径省略授权。 +`POST /courses` 会建立任课关系,仅管理员可新建。教师的日课表维护范围不授予建课或自分配任课资格;已有课程仍可按课表权限排课及维护外观。离线档案导入复用既有科目,新增占位科目按班主任归属,不采信导入文件中的教师姓名作为授权。 + 成绩列表、考试、排名和集体分析都要求 grade:read 与对应班级范围。学生明细另要求 student:grade-query。关闭班级自助查询后,本班设备仍可获得集体聚合,个人明细、原始成绩、考试列表和排名拒绝。实时载荷同样受隐私开关保护,服务端执行稀疏样本和补集抑制。 ## 实时与设备 diff --git a/docs/dev/release.md b/docs/dev/release.md index f61eb5c..f0b35be 100644 --- a/docs/dev/release.md +++ b/docs/dev/release.md @@ -30,7 +30,7 @@ pnpm verify:packaged --exe "releases/client/<版本>/安装包/ClassHelper-<版 以上按发布改动范围执行;显式 --visual 才是桌面视觉验收。测试数量和结果必须来自本次输出。 完整边界见[验收](testing.md)。同号本地重构建先保留可恢复副本,最新包核验完成后按用户要求清理旧归档。 -2026-10-18 工作区清理后,1.4.0 仅保留当前 client/server 目录和当前更新日志/校验清单。 +版本目录与清单以本次实际构建结果为准;历史清理记录不代表当前保留的版本。 ## 产物与文件名 diff --git a/docs/dev/testing.md b/docs/dev/testing.md index 9c1d86b..c1726b5 100644 --- a/docs/dev/testing.md +++ b/docs/dev/testing.md @@ -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 复验,记录实际版本。 ## 截图 diff --git a/docs/management/database.md b/docs/management/database.md index 4ab10f6..7e9ce4c 100644 --- a/docs/management/database.md +++ b/docs/management/database.md @@ -25,6 +25,7 @@ Web 管理端有一个「数据库管理」页(`/database`,**仅管理员可 - 按 `lib/snapshot.ts` 的 `SNAPSHOT_TABLES` 依赖顺序导出; - 恢复时临时**关闭外键检查** —— 用于处理跨表外键关联,表清单与恢复顺序由 `lib/snapshot.ts` 统一维护; +- 清空与重新写入属于同一事务;中途写入失败时回滚并保留原库。MySQL 的外键开关在该事务的同一连接上恢复,SQLite 在事务前后切换; - 分批 `createMany` 写入。 相容版本的快照可以在受支持的 SQLite/MySQL 之间恢复;格式与缺失表由快照校验器检查。 diff --git a/docs/reference.md b/docs/reference.md index 5c67737..739fe77 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -8,24 +8,25 @@ 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` | -| 作业 | [作业](app/homeworks.md) | `server/src/modules/homeworks/` | -| 通知与叫人 | [通知](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/` | -| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` | -| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` | -| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` | -| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` | -| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` | -| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` | -| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` | -| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 | +| 主题 | 文档 | 工作区源码入口 | +| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| 架构与模块 | [架构总览](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/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/` | +| 经典与自定义常驻岛 | [灵动岛](app/island.md) | `desktop-client/src/island/LayoutIslandApp.vue`、`CustomIslandRuntime.vue` | +| 导入 | [表格与课表导入](app/imports.md) | `server/src/modules/imports/`、`class-plans/profile-import.service.ts` | +| API 与实时 | [REST API](dev/api.md)、[实时事件](dev/realtime.md) | `server/src/modules/`、`realtime/`、`shared/src/constants.ts` | +| 数据模型与迁移 | [数据模型](dev/data-model.md) | `server/prisma/schema.prisma`、`migrations/` | +| 数据库管理 | [数据库管理](management/database.md)、[MySQL](management/mysql.md) | `server/src/lib/snapshot.ts`、`modules/database/` | +| 安装与升级 | [生产部署](management/production.md)、[Linux](management/linux-deploy.md)、[更新](management/upgrade.md) | `deploy/`、`scripts/dist-server.mjs` | +| 验证与发布 | [验收](dev/testing.md)、[发布](dev/release.md) | 根 `package.json`、`scripts/`、`.github/workflows/` | +| 当前实现约定 | [实现约定](dev/implementation.md) | 课表、升级、岛、课件与设备维护的关键边界 | 表中的包路径均相对仓库 `packages/`;脚本和部署目录相对仓库根。 源码总入口:[GitHub 仓库](https://github.com/LoveChengke/ClassHelper)。 diff --git a/prompts/full-repo-audit-checklist.md b/prompts/full-repo-audit-checklist.md new file mode 100644 index 0000000..3ab2afd --- /dev/null +++ b/prompts/full-repo-audit-checklist.md @@ -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` 的 `` 注入;`.reveal-grad` 不拆逐字节点。 +- H6 图片:展示图进 `docs/images/`,回归截图进 `docs/screenshots/`,不被误删/误引用。 + +### I. 提示词 + +- I1 `prompts/*.prompt.md`:结构、时效性、可执行性、是否写死会过期的结论。 +- I2 `AGENTS.md` 作为"代理入口提示词"的清晰度:长度是否失控、约束是否互相矛盾、是否有能直接照抄的命令。 +- I3 本次交付用的提示词自检:换一个零上下文代理,能否只靠执行入口 §3 完成 Phase 0。 + +--- diff --git a/prompts/full-repo-audit-optimize-release.prompt.md b/prompts/full-repo-audit-optimize-release.prompt.md new file mode 100644 index 0000000..5a230e3 --- /dev/null +++ b/prompts/full-repo-audit-optimize-release.prompt.md @@ -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 --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、日志、任务标识及进程,避免重复构建和覆盖结果 |