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

+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。
---