docs: add maintainer guidance and API contract
This commit is contained in:
zhoujun0601
@@ -0,0 +1,50 @@
|
||||
# Codex Helper 代码审查规则
|
||||
|
||||
目标是发现可复现的正确性、安全性、兼容性和可靠性问题，而不是增加评论数量。审查必须结合完整 diff、调用链、测试和部署边界，不能孤立阅读修改行。
|
||||
|
||||
## 输出格式
|
||||
|
||||
findings 优先，按 `P0` 至 `P3` 排序。每条必须包含严重级别和简短标题、精确文件与起始行号、触发输入或执行顺序、实际影响和最小修复方向。同一根因只报告一次。
|
||||
|
||||
- `P0`：可利用的安全突破、不可恢复数据丢失或全系统中断。
|
||||
- `P1`：高概率生产故障、认证绕过、账号凭据删除或核心同步失效。
|
||||
- `P2`：条件性但真实的错误、兼容性破坏、状态漂移、重复通知或资源风险。
|
||||
- `P3`：影响有限且不阻塞合并的真实维护问题。
|
||||
|
||||
不要报告纯格式偏好、没有现实失败路径的猜测、仓库已有且未被当前改动暴露的问题，或仅以“缺少测试”为问题本身。没有 finding 时明确说明，并列出未执行验证或剩余风险。
|
||||
|
||||
## 审查流程
|
||||
|
||||
1. 阅读完整 diff，识别 API、认证、SQLite、Codex runtime、通知、前端、部署和持久数据影响。
|
||||
2. 搜索修改符号的调用方、被调用方、相似路径和测试，走完实际成功与失败路径。
|
||||
3. 对照 [`engineering-invariants.md`](engineering-invariants.md) 和 [`backend/CONTRACT.md`](../../backend/CONTRACT.md)。
|
||||
4. 在容器内运行与风险成比例的验证；复核 finding，删除重复根因和不影响用户的推测。
|
||||
|
||||
## 后端专项
|
||||
|
||||
- 匿名端点是否意外扩大；session、过期检查和非只读来源头是否在所有路径生效；cookie 改动是否适配 HTTPS 反代。
|
||||
- setup 是否事务化且不能覆盖管理员；登录限流是否存在竞态、无限内存或错误信任代理头。
|
||||
- SQLite migration 是否可从旧 schema 启动且保留数据；查询是否带正确 `account_id`；rows、transaction 和临时文件是否关闭。
|
||||
- 删除账号是否精确停止 runtime、级联历史并删除正确目录，尤其是账号 1 的旧路径。
|
||||
- app-server 生命周期是否可能双启动、停止后重启、死锁或由旧进程回调污染新进程；pending 请求在所有结束路径是否释放。
|
||||
- app-server 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、设备码 polling、timer 和 event handler 是否在卸载时清理。
|
||||
- 设置 tab 是否保持键盘操作、`inert` 隔离、表单状态、滚动位置和窄屏无溢出。
|
||||
|
||||
## 部署与验证专项
|
||||
|
||||
- 固定 Go、Node、Codex CLI 和 Playwright 版本是否同步 Dockerfile、lockfile 与文档；架构和静态构建是否匹配运行层。
|
||||
- 静态前端是否在 Go build 前正确复制；`.dockerignore` 是否会丢失必须资源或带入运行数据。
|
||||
- 最终镜像是否继续非 root，`/data` 权限是否兼容 UID `10001`；Compose 升级是否复用原卷。
|
||||
- 新环境变量是否同步代码、Compose、README 和部署文档；秘密是否可能进入 build arg、镜像层或日志。
|
||||
- 最低验证遵循 [`development-and-validation.md`](../guides/development-and-validation.md) 的矩阵。纯文档至少检查链接、术语、事实来源和 `git diff --check`。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 工程不变量
|
||||
|
||||
修改鉴权、SQLite、账号删除、Codex 进程、秘密、通知、备份或部署边界前核对本页。
|
||||
|
||||
## API 与认证
|
||||
|
||||
- [`backend/CONTRACT.md`](../../backend/CONTRACT.md) 是路径、状态码、响应字段和兼容文案的契约。匿名入口只能是当前 status、setup 和 login。
|
||||
- 所有受保护端点必须回查 session；非只读请求还必须验证 `X-Requested-With`。前端路由与按钮不能代替后端门禁。
|
||||
- session 原 token 只进入 cookie，SQLite 只保存摘要；密码保持 argon2id。错误和日志不得包含密码、cookie、Bot Token、SMTP 密码或 Codex token。
|
||||
- 初始化是事务性单管理员创建。新增自动初始化能力前必须保留并发与首次公网暴露的安全边界。
|
||||
|
||||
## 数据与账号
|
||||
|
||||
- `internal/store/store.go` 是 SQLite schema 和兼容迁移的事实来源。启动迁移必须幂等、保留旧数据并启用 foreign keys。
|
||||
- 旧单账号数据迁到账号 1；账号 1 的凭据路径永久为 `/data/codex`，不能统一搬到 `accounts/1`。
|
||||
- 删除账号必须先停止并移除精确 runtime，再删除该账号数据库行和精确凭据目录；不得使用未校验路径、glob 或宽泛递归删除。
|
||||
- `daily_usage` 与 `limit_snapshots` 以 `account_id` 隔离。任何查询、更新、提醒 key 或清理不得串账号。
|
||||
- `expectedKind` 只是校验期望；未知套餐保持 unknown。相同邮箱提示重复不能成为自动合并依据。
|
||||
|
||||
## Codex 运行时
|
||||
|
||||
- 每账号一套 app-server 和 `CODEX_HOME`。进程存活与协议 ready 是不同状态，初始化失败必须关闭旧进程。
|
||||
- lifecycle mutex 串行启动/停止，syncing mutex 串行同步和 Dashboard 访问，state mutex 保护 ready/stopped；不得以无锁读写替换。
|
||||
- 旧子进程晚退出不能断开新子进程或失败新请求。请求取消和 20 秒 timeout 必须清除 pending channel。
|
||||
- `account/read` 是同步的硬依赖；rate limits 与 usage 是可缺失数据。optional、`null`、多 bucket 和未知字段必须安全降级。
|
||||
|
||||
## 通知、外部输入与秘密
|
||||
|
||||
- SMTP 密码和 Telegram Token 使用 `/data/secret.key` 的 AES-GCM 密文保存；设置响应继续掩去秘密。密钥丢失不能通过返回密文或明文“修复”。
|
||||
- 提醒 dedupe key 必须包含账号、limit、window、reset 或旧 snapshot 身份及 kind；重试窗口保持计划时间后六小时。
|
||||
- Telegram/SMTP 用户文本进入 HTML 前必须转义。Telegram HTTP client 和 SMTP 连接/读写必须保留 timeout；SMTP TLS 最低 1.2 并验证 server name。
|
||||
- Telegram 绑定码十分钟且成功即消费；其他 chat 在绑定后不得查询实例数据。
|
||||
|
||||
## 前端与部署
|
||||
|
||||
- 所有可见邮箱继续掩码。账号切换清空旧 Dashboard；删除账号清除设备码和 localStorage 选择。
|
||||
- 非活动设置 panel 保持 `inert`，tab 键盘和布局稳定性是现有可访问性契约。
|
||||
- 前端生产资源嵌入 Go 二进制；Docker build stage 的复制顺序变化必须验证实际嵌入的是新产物。
|
||||
- `/data` 是唯一完整恢复单元。数据库快照不含 `secret.key` 和 Codex 凭据；任何文档不得暗示其可完整灾难恢复。
|
||||
- 运行数据、数据库、密钥、凭据、`.env`、`node_modules` 和构建缓存不得进入 Git 或 Docker 构建上下文。
|
||||
Reference in New Issue
Block a user