user-system/docs/code-review/CODE_REVIEW_PROCESS.md

代码审查流程规范

文档版本: v1.0 生成日期: 2026-04-08 适用范围: User Management System (UMS) 项目

---

一、审查角色与职责

1.1 角色定义

角色	职责	要求
作者 (Author)	自审、修复问题、响应反馈	熟悉代码逻辑
审查者 (Reviewer)	全面审查、标注问题、给出建议	了解业务和安全要求
仲裁者 (Arbiter)	解决争议、最终决策	资深开发者/架构师

1.2 职责边界

作者职责：

1. 提交前完成自审检查清单
2. 确保代码可编译、可测试
3. 及时响应审查反馈
4. 修复问题时主动沟通

审查者职责：

1. 按时完成审查（常规 4h 内）
2. 提供具体、可操作的反馈
3. 公平、一致地执行标准
4. 记录审查结果

仲裁者职责：

1. 解决审查争议
2. 判定标准模糊地带
3. 优化审查流程

---

二、审查触发条件

2.1 必须审查

条件	说明
所有 PR 到 main	任何合入 main 的代码必须审查
安全相关变更	认证、授权、加密相关
基础设施变更	配置、部署、CI/CD
数据库 schema 变更	迁移文件

2.2 简化审查（可选）

条件	说明
文档更新	*.md 文件
测试用例补充	仅新增测试
依赖更新	无代码变更
配置调整	明确无风险

---

三、审查执行流程

3.1 阶段一：准备工作

审查者接收 PR 后：
1. 阅读 PR 描述，理解变更目的
2. 查看关联的 Issue/Ticket
3. 确认影响范围
4. 准备审查清单

3.2 阶段二：自动化检查

# 后端检查
go vet ./...
go build ./cmd/server
go test ./... -count=1
gosec ./...  # 安全扫描

# 前端检查
npm run lint
npm run build
npm test
npm audit

# 覆盖率检查
go test -coverprofile=coverage.out
go tool cover -func=coverage.out | tail -1

3.3 阶段三：代码审查

审查顺序（建议）

1. 接口/API 层 - 先看暴露的接口是否合理
2. 业务逻辑层 - 核心逻辑实现
3. 数据访问层 - 数据库操作
4. 基础设施 - 错误处理、日志
5. 测试 - 覆盖率、有效性

审查要点

文件维度：

• 新增文件是否必要
• 删除文件是否安全
• 修改文件是否最小化

安全维度：

• 输入验证
• 权限检查
• 敏感数据处理
• 加密实现

正确性维度：

• 逻辑正确
• 边界处理
• 错误处理
• 并发安全

性能维度：

• 数据库查询
• 缓存使用
• 资源释放

3.4 阶段四：反馈与修复

评论格式

🔴 **[级别] 问题标题**
位置: `file.go:42`

**问题描述**：
[清晰描述问题]

**为什么这是个问题**：
[解释风险或影响]

**建议修复**：
```code
// 建议的代码

---

🟠 [级别] 问题标题 ...

---

🟡 [级别] 问题标题 ...

---

💭 [挑剔] 可选优化 ...

---

✅ 做得好的地方 [具体表扬]

#### 修复确认

| 问题级别 | 修复要求 | 确认方式 |
|----------|----------|----------|
| 🔴 | 必须修复 | 重新审查 |
| 🟠 | 必须修复 | 截图确认或重新审查 |
| 🟡 | 建议修复 | 修复后标注或提供理由 |
| 💭 | 可选 | 可忽略，提供理由即可 |

### 3.5 阶段五：完成审查

#### Approve 条件

□ 所有 🔴🟠 问题已修复 □ 🟡 问题 ≤ 3 个或有明确修复计划 □ 覆盖率不下降 > 5% □ 审查者确认理解变更

#### 评论模板

```markdown
## 审查结论

✅ **可以合并**

**评分**: X.X/10

**亮点**:
- [1]
- [2]

**遗留问题**:
- [1] (P1, @负责人)
- [2] (P2, @负责人)

**后续关注**:
- [建议后续优化项]

---

四、审查时效管理

4.1 SLA 要求

PR 优先级	首次审查	修复后复核	最大周期
P0 (安全/紧急)	1 小时	30 分钟	4 小时
P1 (重要)	4 小时	1 小时	24 小时
P2 (常规)	8 小时	2 小时	48 小时
P3 (优化)	24 小时	4 小时	72 小时

4.2 超时处理

1. 超过 SLA 50% → 提醒（@审查者）
2. 超过 SLA 100% → 升级（@Tech Lead）
3. 超过 3 天无响应 → 仲裁者介入

---

五、争议解决

5.1 常见争议场景

场景	解决方式
问题级别判定分歧	参照分级标准，模糊取高
是否必须修复	审查者决定，仲裁者终裁
代码风格偏好	参考规范，无标准则接受
性能优化必要性	量化数据支持

5.2 仲裁流程

1. 作者提出仲裁请求
2. 审查者陈述理由
3. 仲裁者审查双方观点
4. 仲裁者做出最终决定
5. 记录仲裁结果（供后续参考）

---

六、审查质量保证

6.1 审查者自我检查

审查前：
□ 我理解这次变更的目的吗？
□ 我知道如何验证这些变更吗？

审查中：
□ 我是否检查了所有相关文件？
□ 我的反馈是否具体且可操作？
□ 我的反馈是否公平、一致？

审查后：
□ 我的评分是否合理？
□ 我的反馈是否有教育价值？

6.2 审查质量指标

指标	定义	目标
审查一致性	同类问题的判定一致率	> 90%
反馈质量	作者满意度评分	> 4.0/5
审查效率	平均审查时间	< 4h
缺陷逃逸率	合并后发现的问题数	< 2/版本

---

七、特殊场景处理

7.1 大型 PR

当 PR > 500 行变更时：
1. 请求作者拆分为多个 PR
2. 或分批审查（核心逻辑优先）
3. 明确标记哪些部分已审查
4. 剩余部分安排后续审查

7.2 紧急修复

当生产环境需要紧急修复时：
1. 允许先合并后审查（需要 Tech Lead 批准）
2. 24 小时内完成审查
3. 发现问题立即发版修复
4. 事后复盘，总结经验

7.3 外部贡献

当接收外部 PR 时：
1. 所有审查标准相同
2. 增加许可证检查
3. 增加贡献协议确认
4. 必要时要求补充签名

---

八、审查记录归档

8.1 归档内容

内容	位置	保存期限
PR 审查评论	GitHub PR	永久
审查报告	docs/code-review/	永久
争议解决记录	docs/team/disputes.md	永久
审查指标汇总	docs/team/metrics/	1 年

8.2 报告生成

每次全面审查后生成报告：

docs/code-review/CODE_REVIEW_REPORT_YYYY-MM-DD.md

报告模板见 CODE_REVIEW_STANDARD_V2.md 第 7 节。

---

九、持续改进

9.1 流程回顾

周期	内容	负责人
每月	审查效率分析	Tech Lead
每季度	流程优化讨论	Team
每半年	规范更新	代码审查专家

9.2 改进建议

团队成员可以通过以下方式提出改进建议：

1. 在 docs/team/improvements/ 创建提案
2. 在 Team Meeting 中讨论
3. PR 到本文档

---

本文档由代码审查专家 Agent 制定，版本: v1.0 最后更新: 2026-04-08