codex-helper/docs/reference/code-review-rules.md

Codex Helper 代码审查规则

目标是发现可复现的正确性、安全性、兼容性和可靠性问题，而不是增加评论数量。审查必须结合完整 diff、调用链、测试和部署边界，不能孤立阅读修改行。

输出格式

findings 优先，按 P0 至 P3 排序。每条必须包含严重级别和简短标题、精确文件与起始行号、触发输入或执行顺序、实际影响和最小修复方向。同一根因只报告一次。

• P0：可利用的安全突破、不可恢复数据丢失或全系统中断。
• P1：高概率生产故障、认证绕过、账号凭据删除或核心同步失效。
• P2：条件性但真实的错误、兼容性破坏、状态漂移、重复通知或资源风险。
• P3：影响有限且不阻塞合并的真实维护问题。

不要报告纯格式偏好、没有现实失败路径的猜测、仓库已有且未被当前改动暴露的问题，或仅以“缺少测试”为问题本身。没有 finding 时明确说明，并列出未执行验证或剩余风险。

审查流程

1. 阅读完整 diff，识别 API、认证、SQLite、Codex runtime、通知、前端、部署和持久数据影响。
2. 搜索修改符号的调用方、被调用方、相似路径和测试，走完实际成功与失败路径。
3. 对照 engineering-invariants.md 和 backend/CONTRACT.md。
4. 在容器内运行与风险成比例的验证；复核 finding，删除重复根因和不影响用户的推测。

后端专项

• 匿名端点是否意外扩大；session、过期检查和非只读来源头是否在所有路径生效；cookie 改动是否适配 HTTPS 反代。
• setup 是否事务化且不能覆盖管理员；登录限流是否存在竞态、无限内存或错误信任代理头。
• SQLite migration 是否可从旧 schema 启动且保留数据；查询是否带正确 account_id；rows、transaction 和临时文件是否关闭。
• 删除账号是否只删除精确的本地 runtime 和级联历史，且不会调用 CPA 删除凭据或误导用户。
• CPA authIndex 是否在创建/修改前验证唯一、provider、状态和本地重复；失败是否可能留下半绑定账号。
• CPA Management API 是否有 timeout、响应体大小限制、包装状态与上游状态双重校验；错误或日志是否泄露 management key、OAuth token 或原始正文。
• /wham/* optional/null、多 bucket、未知套餐和部分接口失败是否按契约降级，而非生成错误数据或清除有效绑定。
• 提醒是否稳定去重、限定六小时重试、正确区分 before/after/detected reset；多渠道部分失败是否按既定语义重试。
• SMTP、Telegram 错误是否有 timeout、TLS 和 HTML 转义；设置接口、日志和错误是否泄露秘密。
• 备份是否包含 committed WAL 且不阻塞写入；文案是否误称数据库快照为完整恢复包。

前端专项

• 初始化、未登录、登录态路由是否无闪烁或循环；401 后是否进入可恢复状态。
• 切换或删除账号时，旧 Dashboard 和 localStorage 是否清理；异步旧响应是否覆盖新账号。
• API 类型是否准确表达 null、optional、unknown 和空列表；错误响应是否可能被当作成功。
• 邮箱是否在所有可见位置掩码；服务端文本和外部 URL 是否以安全方式渲染。
• effect、30 秒 polling、timer 和 event handler 是否在卸载时清理。
• 设置 tab 是否保持键盘操作、inert 隔离、表单状态、滚动位置和窄屏无溢出。

部署与验证专项

• 固定 Go、Node 和 Playwright 版本是否同步 Dockerfile、lockfile 与文档；架构和静态构建是否匹配运行层。
• 静态前端是否在 Go build 前正确复制；.dockerignore 是否会丢失必须资源或带入运行数据。
• 最终镜像是否继续非 root，/data 权限是否兼容 UID 10001；Compose 升级是否复用原卷。
• 新环境变量是否同步代码、Compose、README 和部署文档；秘密是否可能进入 build arg、镜像层或日志。
• 最低验证遵循 development-and-validation.md 的矩阵。纯文档至少检查链接、术语、事实来源和 git diff --check。