Files
ClassHelper/prompts/full-repo-audit-checklist.md
T

92 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 全仓审计检查清单
每条都要给出结论:`已修复` / `确认无问题(证据)` / `记为后续(原因)`。禁止只列"看起来可疑"而不核实。
### 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。
---