Stev_Wang
c90a036f82
背景：远端自建 Gitea 未部署 Actions runner，推送后线上 CI 无法执行；原规范仍要求「推送后确认 CI」，容易误以为需等待远端流水线。 改动： - AGENTS §6/§7：CI 只本地执行，推送前必须 pnpm ci:local 或本地门禁全绿，禁止等待/依赖远端 CI。 - 06-测试与CI规范 V1.1：新增「本地 CI 流水线（远端不跑 CI）」强制规则；集成/契约运行时机改为推送前本地。 - 01-Git规范 / 07-CodeReview：删除「推送后确认 CI」，改为本地门禁后推送。 - README：明确远端无 runner，ci.yml 仅本地参考/手动触发。 - .gitea/workflows/ci.yml：去掉 push 触发，仅保留 workflow_dispatch，避免推送停留在 queued。 影响面：仅规范与工作流配置，不影响代码/数据。 验证：pnpm format:check / lint 通过；pnpm ci:local 全部门禁通过（237.2s，4 e2e 冒烟 passed，8 个门控用例按环境变量跳过）。
5.6 KiB
5.6 KiB
07 · Code Review 规范（main 直推）
| 项 | 内容 |
|---|---|
| 文档版本 | V1.1（2026-11-02） |
| 依据 | 技术架构 §10.1（工程约定）、§4.6（CI/CD） |
| 适用范围 | 所有直接推送到 main 的提交 |
| 强制级别 | 强制 |
1 提交说明模板（缺项不推送）
仓库仅保留
main，不再创建 PR。将下列模板写入提交说明正文（git commit -m "type(scope): 标题" -m "背景…"），Review 基于待推送的本地 diff 完成。
## 背景
为什么要改（关联 PRD R-xx / 技术架构章节 / issue）
## 改动
做了什么（按文件或模块列 3–6 条，不贴大段 diff）
## 影响面
- 受影响模块 / 端点 / 表 / 队列
- 是否影响存量数据、是否需要回填
- 是否影响权限、审计、成本
## 回滚方式
代码回滚 / 开关关闭 / 数据回滚，写清具体操作
## 验证证据
- 本地命令与结果（lint / typecheck / test）
- 关键截图或录屏（UI）/ 接口示例（API）
- 迁移在 staging 的执行结果
CR-01提交标题遵循 Conventional Commits 且用中文（scope保留英文，写法见 01 §2）。CR-02单次提交变更 ≤ 400 行（不含 lock / 生成代码）；超出拆为多个提交，并在说明写依赖顺序。CR-03禁止在功能提交中混入无关重构、格式化、依赖升级。CR-04本地门禁未全绿不得推送；高风险变更未完成走查不得推送。
2 Review 分工
无远程分支，Review 对象为待推送的本地提交（
git diff origin/main...HEAD）；高风险变更须在推送前完成双人走查。
| 变更类型 | 要求 |
|---|---|
| 普通业务代码 | ≥ 1 名同模块 Owner |
| 数据库迁移 / 索引 / 数据回填 | 2 人（含后端负责人） |
| 权限点 / 角色 / 数据范围 / RLS | 2 人（含安全或技术负责人） |
| AI 路由 / 供应商 / 密钥 / 成本闸门 | 2 人（含 AI 工程） |
| 导出 / 分享链接 / 对外公开路由 | 2 人（含安全） |
| 发布配置 / CI / 基础设施 | 2 人（含运维） |
| 仅文档 | 1 人（可为作者同组） |
CR-05作者不得自我批准；禁止「LGTM」式无内容批准。CR-06推送前 Review 时效 24 小时内；紧急变更允许推送后 24 小时内补走查，须在提交说明记录。CR-07Review 意见分「必须改（blocking）/ 建议（non-blocking）」，作者逐条回复；blocking 未解决不得推送。
3 Review 检查清单（按序检查）
正确性
- 逻辑与 PRD 规则一致，边界（空 / 超限 / 并发 / 重试）已处理
- 状态机迁移合法，非法路径返回明确错误
- 异步任务幂等，失败可重试且不重复计费
数据与隔离
- 所有查询带
customer_id，Repository 接收ScopeContext - 无跨模块直接
prisma.* - 迁移 expand/contract，索引与查询匹配，无
SELECT */ N+1
安全与合规
- 守卫链完整，特殊权限单独校验
- 无密钥 / Token / 签名 URL 进日志或响应
- 导出 / 分享 / 公开路由有签名、有效期、限流、留痕
- 审计埋点齐全（谁、何时、对什么、改前改后）
接口与前端
- 入参 Zod 校验，错误码取自常量
- UI 只用 Semi + 统一图标出口，无散落色值
- 权限守卫 + 403/404 页；URL 承载可分享状态
质量
4 DoD（推送即完成的定义）
同时满足才可推送：
- 本地门禁全绿（含契约与集成，必要时
pnpm ci:local）；远端 Gitea 无 runner，不等待线上 CI，无豁免。 - Review 通过，blocking 意见全部解决。
- 文档同步：PRD 规则编号、技术架构、OpenAPI、本目录细则（如涉及）。
- 迁移可回滚，或在描述说明为何不可回滚与前向修复方案。
- 可观测性就位：关键路径有日志、有指标、失败有告警（如适用）。
- 影响面与回滚方式已写清，release 记录已补。
5 推送与推送后
CR-08推送前完成本地门禁（format:check/lint/typecheck/test）；推送即进入主干，不再有 Squash 合并环节。CR-09直接git push origin main；禁止 force push、禁止 Merge commit；推送前确认pnpm ci:local全绿，推送后不等待远端 CI（远端无 runner）。CR-10推送后发现缺陷：优先以新提交前向修复；影响面大时按回滚预案执行（回滚也用新提交，不回写历史），并补一次复盘（写docs/releases/或 issue）。CR-11禁止「先推后补测试 / 补文档」作为常态；紧急修复须 24 小时内以新提交补齐，并在提交说明记录。
6 反模式（走查直接打回）
| 反模式 | 原因 |
|---|---|
| 巨型提交（> 800 行） | 无法有效 Review，缺陷率高 |
| 「顺手」重构无关模块 | 混淆影响面，增加回滚难度 |
用 any / @ts-ignore 绕过类型 |
把问题推到运行时 |
| 在 Controller 写业务规则 | 破坏分层，无法复用与测试 |
直接改 status 字段 |
绕过状态机，产生非法状态 |
| 同步接口里跑长任务 | 违反异步任务协议，超时不可控 |
| 硬编码阈值 / 客户 ID | 违反 PRD R-26 与客户隔离 |
| 无回滚方案的迁移 | 生产事故无法收敛 |