Stev_Wang
75cedbe97b
原 GIT-05 要求 subject 用英文祈使句，与团队实际书写习惯不符（已有提交均为 中文），且缺少中英混排与术语约定，容易写出 Chinglish、自造术语或中英标点混乱。 本次改动： - GIT-05 改为「提交信息一律使用中文」，type / scope 保留英文小写，规定祈使句、 字数（≤50 汉字 / 整行 ≤72 字符）与不加句末标点； - 新增 GIT-21~GIT-23：中英文间加空格、使用全角标点与反引号、术语沿用 PRD 术语表、 禁止 Chinglish 与无信息缩写； - 新增 §2.2 commitlint 配置要点：中文必须关闭 subject-case、拦截中文句号， 否则钩子校验实际无效； - 同步 03（commit-msg 钩子说明）、07（PR-01 标题用中文）与 AGENTS §7 / §9 / 附录。 影响面：仅文档，无代码影响。新规则对后续提交生效，已推送的历史提交不改写 （GIT-15 禁止改写 main 历史）。 回滚方式：git revert 本提交。
130 lines
4.9 KiB
Markdown
130 lines
4.9 KiB
Markdown
# 07 · Code Review 与 PR 规范
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | V1.0（2026-11-02） |
|
||
| 依据 | 技术架构 §10.1（工程约定）、§4.6（CI/CD） |
|
||
| 适用范围 | 所有进入 `main` 的变更 |
|
||
| 强制级别 | 强制 |
|
||
|
||
---
|
||
|
||
## 1 PR 描述模板（缺项即打回）
|
||
|
||
```markdown
|
||
## 背景
|
||
为什么要改（关联 PRD R-xx / 技术架构章节 / issue）
|
||
|
||
## 改动
|
||
做了什么（按文件或模块列 3–6 条，不贴大段 diff）
|
||
|
||
## 影响面
|
||
- 受影响模块 / 端点 / 表 / 队列
|
||
- 是否影响存量数据、是否需要回填
|
||
- 是否影响权限、审计、成本
|
||
|
||
## 回滚方式
|
||
代码回滚 / 开关关闭 / 数据回滚，写清具体操作
|
||
|
||
## 验证证据
|
||
- 本地命令与结果（lint / typecheck / test）
|
||
- 关键截图或录屏（UI）/ 接口示例（API）
|
||
- 迁移在 staging 的执行结果
|
||
```
|
||
|
||
- `PR-01` 标题遵循 Conventional Commits 且**用中文**（Squash 时以 PR 标题为准，`scope` 保留英文，写法见 [01](01-Git规范.md) §2）。
|
||
- `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](02-代码风格.md)
|
||
- [ ] 测试覆盖必测清单（[06](06-测试与CI规范.md) §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 与客户隔离 |
|
||
| 无回滚方案的迁移 | 生产事故无法收敛 |
|