# 代码审查流程规范

**文档版本**: 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 阶段二：自动化检查

```bash
# 后端检查
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 阶段四：反馈与修复

#### 评论格式

```markdown
🔴 **[级别] 问题标题**
位置: `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*