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
+319 -30

No files matched your search

+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 之间恢复;格式与缺失表由快照校验器检查。
+19 -18
View File
@@ -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)。