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

# 代码审查流程规范 v2.0

**文档版本**: v2.0  
**更新日期**: 2026-04-12  
**适用范围**: User Management System (UMS) 项目  
**配套标准**: `CODE_REVIEW_STANDARD_V4.md`  
**配套 Checklist**: `REVIEW_EXECUTION_CHECKLIST.md`

---

## 一、核心原则

### 1.1 零信任文档原则

> **任何"已完成"的声明，必须附带可重现的命令和输出，否则视为未完成。**

历史教训：
- v2.0 时期因依赖文档自述，评分虚高至 9.7/10
- 2026-04-11 发现前端构建实际失败，但文档标注 "PASS"
- v4.0 要求：工具证据先于文档断言

### 1.2 教学优先原则

审查的目的是让代码更好、让开发者成长，不是门卫把关：
- 每个问题说明"为什么是问题"，而非只说"改掉"
- 赞扬好的实践，具体表扬有教学价值

### 1.3 优先级纪律

| 级别 | 处理规则 | 不遵守的后果 |
|------|----------|-------------|
| 🔴 P0 | 禁止合并，4h 内修复 | 永久 Block |
| 🟠 P1 | 禁止合并，当天修复 | 永久 Block |
| 🟡 P2 | 附计划后可合并，本周修复 | 跟踪 Issue |
| 🔵 P3 | 可合并，本 Sprint 修复 | 技术债台账 |
| 💭 P4 | 可忽略 | - |

---

## 二、角色与职责

| 角色 | 职责 | SLA |
|------|------|-----|
| **作者** | 自审 → 提 PR → 修复问题 → 更新文档 | 当日响应 |
| **审查者** | 执行 Checklist → 标注问题 → 给出建议 → Approve | P0:1h / P1:4h / P2:8h |
| **Tech Lead** | SLA 超时升级，争议仲裁，流程优化 | 1个工作日 |

### 2.1 作者自审清单（提 PR 前必须执行）

```powershell
# 最小自审（2分钟）
cd d:\usersystem
go build ./cmd/server                    # 必须通过
go vet ./...                             # 必须通过
go test ./... -short -count=1            # 必须通过
cd frontend\admin
npm.cmd run lint                         # 必须通过
npm.cmd run build                        # 必须通过 ← 重点，历史有谎报
```

### 2.2 作者 PR 描述模板

```markdown
## 变更目的
[1-2句说明：解决什么问题，为什么这样解决]

## 影响范围
- [ ] 后端（Go）
- [ ] 前端（React/TypeScript）
- [ ] 数据库（schema变更）
- [ ] 部署配置
- [ ] 文档

## 验证命令与结果

```bash
$ go build ./cmd/server
# 输出: [粘贴实际输出]

$ go test ./... -short
# 输出: ok  ... [粘贴实际输出]

$ npm.cmd run build
# 输出: [粘贴实际输出]
```

## 是否需要 E2E 测试？
- [ ] 是 → 已执行 `npm.cmd run e2e:full:win`（粘贴结果）
- [ ] 否 → 理由：[说明为何不需要]

## 剩余已知问题（P2及以下）
- [问题1] #issue-link
```

---

## 三、审查执行流程（SOP）

```
┌─────────────────────────────────────────────────────────────────┐
│  作者自审 + 提 PR                                                │
│  □ go build / go vet / go test -short 全通过                    │
│  □ npm lint / npm build 全通过（无 TS 错误！）                   │
│  □ PR 描述包含验证命令输出                                        │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 1：自动化门禁（CI，约5分钟）                                │
│  □ go build + go vet + go test -race                            │
│  □ 覆盖率 ≥ 60%                                                  │
│  □ govulncheck（无已知CVE）                                      │
│  □ npm lint + npm build + npm test                              │
│  □ npm audit（high漏洞=0）                                       │
│                                                                  │
│  ⚠️ 任一失败 → PR 自动 Block，作者修复后重新触发                  │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼（CI 全通过）
┌─────────────────────────────────────────────────────────────────┐
│  阶段 2：审查者人工审查（10-20分钟）                              │
│                                                                  │
│  按优先级审查顺序：                                               │
│  1. 安全维度（P0 优先）—— 新 API 权限？文件上传？SQL 注入？        │
│  2. API 契约 —— 响应格式统一？HTTP状态码正确？                    │
│  3. 前后端集成 —— 路径/字段名/类型一致？                          │
│  4. 业务逻辑 —— 功能正确？边界处理？                              │
│  5. 测试质量 —— 测试是真实的？非虚假断言？                        │
│  6. 运维影响 —— 配置变更？Runbook 需要更新？                      │
│                                                                  │
│  使用 REVIEW_EXECUTION_CHECKLIST.md 逐项执行                     │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 3：问题标注                                                 │
│  使用标准格式（见第四节）                                          │
│  P0/P1 → 逐项说明问题+原因+建议修复                               │
│  P2/P3 → 可集中列表                                              │
│  亮点 → 至少指出 1 个好的做法                                     │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 4：作者修复                                                 │
│  P0/P1 → 修复后回复每条评论，附命令输出证明                        │
│  P2 → 修复或创建 Issue 跟踪，评论 Issue 链接                      │
│  P3 → 修复或在 PR 评论说明原因                                    │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 5：E2E 检查（条件触发）                                     │
│  触发条件（满足任一）：                                           │
│  - 认证相关变更                                                   │
│  - 路由守卫变更                                                   │
│  - 导航组件变更                                                   │
│  - Token 管理变更                                                 │
│  命令：cd frontend/admin && npm.cmd run e2e:full:win              │
└─────────────────────────┬───────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 6：Approve + 合并                                          │
│  □ 所有 🔴🟠 问题已修复（有验证命令证明）                          │
│  □ P2 有 Issue 跟踪计划                                           │
│  □ 覆盖率未下降 > 5%                                              │
│  □ 文档已同步（API 变更 → Swagger，配置变更 → .env.example）      │
│  □ Approve                                                       │
└─────────────────────────────────────────────────────────────────┘
```

---

## 四、审查评论格式规范

### 问题标注格式

```markdown
🔴 **[P0 - 安全] 文件上传缺少 Magic Bytes 校验**
📍 位置：`internal/api/handler/avatar_handler.go:95`

**问题描述**：
当前仅校验文件扩展名，攻击者可将 PHP Shell 命名为 `.jpg` 绕过检查。

**风险**：
恶意文件可能被服务端执行，导致 RCE（远程代码执行）。

**建议修复**：
```go
src, _ := file.Open()
buf := make([]byte, 512)
n, _ := src.Read(buf)
contentType := http.DetectContentType(buf[:n])
allowedMIME := map[string]bool{
    "image/jpeg": true, "image/png": true,
}
if !allowedMIME[contentType] {
    c.JSON(400, gin.H{"message": "invalid file content"})
    return
}
src.Seek(0, io.SeekStart)
```

---

🟡 **[P2 - 可维护性] context.Background() 在请求链路中截断追踪**
📍 位置：`internal/api/middleware/auth.go:131`

**问题描述**：缓存查询使用 `context.Background()` 而非请求 context，导致 Trace ID 无法传播。

**建议**：将函数签名改为接收 `ctx context.Context`，传递调用者的 context。

---

✅ **做得好：Argon2id 密码哈希配置优秀**
`internal/auth/password.go` 中 64MB 内存、5次迭代的 Argon2id 配置超越行业基准，
有效防御 GPU 暴力破解。
```

### Approve 评论格式

```markdown
## 审查结论

✅ **批准合并**

**综合评分**：X.X/10

**亮点**：
- Argon2id 配置超越行业基准
- 游标分页 P99=53ms，性能优秀

**遗留 P2（已有 Issue 跟踪）**：
- #123 OpenAPI 注释完善
- #124 pagination 包测试

**合并后 24h 内请确认**：
- 生产监控无异常告警
- 关键业务指标（登录成功率）正常

LGTM 🚀
```

---

## 五、审查时效 SLA

| PR 优先级 | 首次审查 | 修复后复核 | 最大总周期 |
|-----------|----------|------------|-----------|
| P0 安全紧急 | **30 分钟** | 15 分钟 | 2 小时 |
| P1 重要修复 | **1 小时** | 30 分钟 | 4 小时 |
| P2 常规功能 | **4 小时** | 2 小时 | 24 小时 |
| P3 重构/文档 | **8 小时** | 4 小时 | 48 小时 |

### 超时处理

```
超 SLA 50% → 作者 @审查者 催促
超 SLA 100% → 作者 @Tech Lead 升级
超 3 个工作日无响应 → Tech Lead 仲裁
```

---

## 六、特殊场景处理

### 6.1 大型 PR（>500 行）

```
优先请求作者拆分，按以下维度拆：
- 后端/前端 分开
- 功能/测试 分开
- 重构/新功能 分开

如必须整体审查：
1. 分批审查（核心安全逻辑优先）
2. 明确标记哪些部分已审查
3. 剩余部分安排跟进审查
```

### 6.2 生产紧急修复（Hotfix）

```
流程：
1. Tech Lead 批准先合并（P0 安全问题）
2. 24 小时内完成完整审查
3. 发现问题立即 Hotfix v2
4. 72 小时内完成事后复盘

条件：
- 只允许 P0 安全/稳定性问题
- 必须在 Hotfix 分支（hotfix/XXX）
- 合并后必须同步更新所有文档
```

### 6.3 安全相关变更（额外严格）

```
触发条件（满足任一）：
- 认证/授权逻辑
- 密码/Token 处理
- 文件上传
- 外部服务调用（OAuth/SMS/Email）
- 数据库 schema（含敏感字段）

额外要求：
- Tech Lead 必须参与审查
- 发布前必须运行完整安全扫描（gosec + govulncheck）
- 需要额外的攻击场景测试
```

---

## 七、争议解决

| 争议类型 | 解决方式 |
|----------|----------|
| 问题级别分歧 | 参照标准，模糊取高；Tech Lead 终裁 |
| 是否必须修复 | 审查者决定，作者提仲裁请求 |
| 技术方案选择 | 量化数据支持（性能/复杂度），Tech Lead 仲裁 |
| 代码风格偏好 | 参考项目规范，无标准则接受 |

---

## 八、审查记录归档

| 内容 | 位置 | 保存期限 |
|------|------|----------|
| 全面审查报告 | `docs/code-review/COMPREHENSIVE_REVIEW_YYYY-MM-DD.md` | 永久 |
| 专项审查报告 | `docs/code-review/[主题]_REVIEW_YYYY-MM-DD.md` | 永久 |
| 问题跟踪 | Gitea Issues | 永久 |
| 工具扫描结果 | `docs/evidence/` | 90天 |

---

## 九、持续改进

### 9.1 回顾周期

| 周期 | 内容 | 负责人 |
|------|------|--------|
| 每次 Sprint 结束 | 审查效率/质量小结 | Tech Lead |
| 每月 | 流程优化讨论（缺陷逃逸率、审查一致性）| Team |
| 每季度 | 标准文档更新（CODE_REVIEW_STANDARD_VX.md）| 代码审查专家 |

### 9.2 关键质量指标（目标）

| 指标 | 当前 | 目标 |
|------|------|------|
| 缺陷逃逸率 | 未量化 | < 2个/Sprint |
| P0/P1 修复时效 | 未量化 | 100% 在 SLA 内 |
| 审查覆盖率 | 100% | 保持 |
| 虚假完成率 | 历史有案例 | 0 |

---

*文档版本: v2.0*  
*更新时间: 2026-04-12*  
*主要变更: 新增零信任文档原则 + SOP 流程图 + E2E 触发条件 + 各维度专项检查要求*