wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
340a8ed176753c25176012e341dd47cc7a096e0d
lingxi/docs/工程规范/07-CodeReview与PR规范.md
T
Stev_Wang dd01b89214
ci / 质量门禁 (push) Canceled after 0s
Details
docs(docs): 调整分支策略为仅 main 直推 
背景：用户确认仓库只保留 main，不再创建任何远程分支或走 PR 合并。

改动：
- 01-Git规范 V1.1：仅 main 直推，禁止非 main 分支推送、force push 与 Merge commit；
- AGENTS V1.1：变更流程改为直接提交并推送 main；
- 07-CodeReview：PR 模板改为提交说明，合并流程改为推送与推送后观察；
- 03/06/工程规范 README 同步去除 PR 措辞；
- CI 仅保留 push main 与 workflow_dispatch 触发。

影响面：仅流程与文档，无代码/数据/接口变更。
回滚方式：git revert 本提交即可恢复旧流程。
验证：format:check、lint、typecheck 全绿（10/10）。
2026-11-02 17:40:01 +08:00

5.5 KiB
Raw Blame History

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-07 Review 意见分「必须改（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 承载可分享状态

质量

  • 命名、类型、错误处理符合 02
  • 测试覆盖必测清单（06 §2）
  • 无 eslint-disable 新增；无 TODO 无主
  • 文档 / OpenAPI / 变更记录同步更新

4　DoD（推送即完成的定义）

同时满足才可推送：

  1. 本地门禁全绿；推送后 CI 全绿（含契约与集成），无豁免。
  2. Review 通过，blocking 意见全部解决。
  3. 文档同步：PRD 规则编号、技术架构、OpenAPI、本目录细则（如涉及）。
  4. 迁移可回滚，或在描述说明为何不可回滚与前向修复方案。
  5. 可观测性就位：关键路径有日志、有指标、失败有告警（如适用）。
  6. 影响面与回滚方式已写清，release 记录已补。

5　推送与推送后

  • CR-08 推送前完成本地门禁（format:check / lint / typecheck / test）；推送即进入主干，不再有 Squash 合并环节。
  • CR-09 直接 git push origin main；禁止 force push、禁止 Merge commit；推送后 15 分钟内确认 CI 与错误率。
  • CR-10 推送后发现缺陷：优先以新提交前向修复；影响面大时按回滚预案执行（回滚也用新提交，不回写历史），并补一次复盘（写 docs/releases/ 或 issue）。
  • CR-11 禁止「先推后补测试 / 补文档」作为常态；紧急修复须 24 小时内以新提交补齐，并在提交说明记录。

6　反模式（走查直接打回）

反模式 原因
巨型提交（> 800 行） 无法有效 Review，缺陷率高
「顺手」重构无关模块 混淆影响面，增加回滚难度
用 any / @ts-ignore 绕过类型 把问题推到运行时
在 Controller 写业务规则 破坏分层，无法复用与测试
直接改 status 字段 绕过状态机，产生非法状态
同步接口里跑长任务 违反异步任务协议，超时不可控
硬编码阈值 / 客户 ID 违反 PRD R-26 与客户隔离
无回滚方案的迁移 生产事故无法收敛
Reference in new issue View Git Blame Copy Permalink