docs(audit): 同步安全边界并整理全仓审计入口
This commit is contained in:
1 parent
3a7aed0800
commit
8bd5bcb9ff
17 files changed
+319
-30
No files matched your search
@@ -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、日志、任务标识及进程,避免重复构建和覆盖结果 |
|
||||
Reference in new issue
Block a user