wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
00ae12435e70add8c9a00f116fb38d3dc716e08d
lingxi/docs/工程规范/07-CodeReview与PR规范.md
T
Stev_Wang 00ae12435e docs(specs): add AGENTS.md and engineering guidelines 
项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立
总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈
基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、
格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。

影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。
回滚方式：git revert 本提交。
2026-11-02 15:09:51 +08:00

4.8 KiB
Raw Blame History

07 · Code Review 与 PR 规范

项 内容
文档版本 V1.0（2026-11-02）
依据 技术架构 §10.1（工程约定）、§4.6（CI/CD）
适用范围 所有进入 main 的变更
强制级别 强制

1　PR 描述模板（缺项即打回）

## 背景
为什么要改（关联 PRD R-xx / 技术架构章节 / issue）

## 改动
做了什么（按文件或模块列 3–6 条，不贴大段 diff）

## 影响面
- 受影响模块 / 端点 / 表 / 队列
- 是否影响存量数据、是否需要回填
- 是否影响权限、审计、成本

## 回滚方式
代码回滚 / 开关关闭 / 数据回滚，写清具体操作

## 验证证据
- 本地命令与结果（lint / typecheck / test）
- 关键截图或录屏（UI）/ 接口示例（API）
- 迁移在 staging 的执行结果
  • PR-01 标题遵循 Conventional Commits（Squash 后即主干提交）。
  • PR-02 变更 ≤ 400 行（不含 lock / 生成代码）；超出拆分为多个 PR 并在描述写依赖顺序。
  • PR-03 禁止在功能 PR 中混入无关重构、格式化、依赖升级。
  • PR-04 Draft PR 可用于早期讨论，但不得在 CI 未绿时请求 Review。

2　Review 分工

变更类型 要求
普通业务代码 ≥ 1 名同模块 Owner
数据库迁移 / 索引 / 数据回填 2 人（含后端负责人）
权限点 / 角色 / 数据范围 / RLS 2 人（含安全或技术负责人）
AI 路由 / 供应商 / 密钥 / 成本闸门 2 人（含 AI 工程）
导出 / 分享链接 / 对外公开路由 2 人（含安全）
发布配置 / CI / 基础设施 2 人（含运维）
仅文档 1 人（可为作者同组）
  • PR-05 作者不得自我批准；禁止「LGTM」式无内容批准。
  • PR-06 首轮 Review 时效 24 小时内；作者负责推动，超过 48 小时升级到模块负责人。
  • PR-07 Review 意见分「必须改（blocking）/ 建议（non-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　合并与合并后

  • PR-08 统一 Squash Merge，提交信息用 PR 标题 + 描述要点。
  • PR-09 合并后删除分支；关注 CI 与错误率 15 分钟。
  • PR-10 合并后发现缺陷：优先前向修复；影响面大则按回滚预案执行，并补一次复盘（写 docs/releases/ 或 issue）。
  • PR-11 禁止「合并后再补测试 / 再补文档」作为常态；确因紧急修复，须 24 小时内补齐并在 PR 记录追踪链接。

6　反模式（Review 直接打回）

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