# 代码审查执行 Checklist v4.0

**用途**: 每次代码审查前执行，确保工具证据先于文档断言  
**原则**: 零信任文档 — 所有状态通过命令验证，不接受自述

---

## 🔧 阶段一：自动化验证（5分钟，PR 门禁）

### 后端验证序列

```powershell
# Windows PowerShell - 逐条执行，观察退出码

# [1] 构建验证
Set-Location d:\usersystem
go build ./cmd/server
Write-Host "BUILD Exit: $LASTEXITCODE"

# [2] 静态分析
go vet ./...
Write-Host "VET Exit: $LASTEXITCODE"

# [3] 全量测试（带竞态检测）
go test ./... -count=1 -race -timeout=5m
Write-Host "TEST Exit: $LASTEXITCODE"

# [4] 覆盖率检查
go test ./... -coverprofile=coverage.out -count=1
go tool cover -func=coverage.out | Select-String "total:"
# 期望: total: ... >= 60%

# [5] 安全扫描
govulncheck ./...
Write-Host "VULN Exit: $LASTEXITCODE"
# 期望: "No vulnerabilities found"

# [6] staticcheck（死代码/风格）
staticcheck ./...
# 观察 U1000 数量变化
```

### 前端验证序列

```powershell
Set-Location d:\usersystem\frontend\admin

# [7] Lint
npm.cmd run lint
Write-Host "LINT Exit: $LASTEXITCODE"

# [8] 构建（关键：必须无 TypeScript 错误）
npm.cmd run build
Write-Host "FE BUILD Exit: $LASTEXITCODE"
# 期望: vite build 成功，无 TS 编译错误

# [9] 单元测试
npm.cmd test -- --run
Write-Host "FE TEST Exit: $LASTEXITCODE"

# [10] 安全审计
npm.cmd audit --audit-level=high
# 期望: found 0 vulnerabilities（high及以上）
```

### 结果记录表

```
日期: ___________  PR: ___________  审查者: ___________

[1] go build         ✅/❌ _____________
[2] go vet           ✅/❌ _____________
[3] go test -race    ✅/❌ _____________
[4] 覆盖率           ___% (要求≥60%)
[5] govulncheck      ✅/❌ _____________
[6] staticcheck      ___ 个问题
[7] npm lint         ✅/❌ _____________
[8] npm build        ✅/❌ _____________
[9] npm test         ✅/❌ _____________
[10] npm audit       ✅/❌ _____________
```

---

## 🔒 阶段二：安全审查（10分钟）

### 2.1 新增 API 端点检查

```
对每个新增 API 端点，逐一确认：
□ 有 middleware 鉴权（RequireAuth / RequireAdmin）
□ 有权限校验（RBAC）
□ 输入有 struct binding + validate tag
□ 有响应格式统一处理
□ 错误响应不泄露内部堆栈
□ 有 swagger 注释（@Summary @Tags @Param @Success @Failure）
```

### 2.2 数据库操作检查

```powershell
# 搜索潜在 SQL 注入（fmt.Sprintf 拼接 SQL）
Select-String -Path "internal\**\*.go" -Pattern "fmt\.Sprintf.*SELECT|fmt\.Sprintf.*WHERE|fmt\.Sprintf.*INSERT" -Recurse
# 期望: 无结果

# 搜索裸 context.Background（请求链路中不应出现）
Select-String -Path "internal\api\**\*.go","internal\service\**\*.go" -Pattern "context\.Background\(\)" -Recurse
# 期望: 每处均有注释说明理由
```

### 2.3 密钥/凭证检查

```powershell
# 搜索硬编码密钥（非 oauth clientID 类）
Select-String -Path "internal\**\*.go" -Pattern "secret\s*=\s*[`"'][^`"']{8,}" -Recurse
Select-String -Path "configs\**\*.yaml" -Pattern "secret:\s*\S{8,}" -Recurse
# 期望: 无硬编码密钥（OAuth ClientID 是公开配置，可排除）
```

### 2.4 文件上传安全（如有相关改动）

```powershell
# 确认 magic bytes 校验存在
Select-String -Path "internal\api\handler\avatar_handler.go" -Pattern "DetectContentType"
# 期望: 有结果，表示已实现

# 确认扩展名校验 + MIME 双重校验
Select-String -Path "internal\api\handler\avatar_handler.go" -Pattern "allowedMIME|allowedExts"
```

---

## 🔗 阶段三：前后端集成验证（10分钟）

### 3.1 API 路径一致性

```powershell
# 提取后端所有路由
Select-String -Path "cmd\server\main.go","internal\api\**\*.go" -Pattern 'router\.(GET|POST|PUT|DELETE|PATCH)\s*\(' -Recurse

# 提取前端所有 API 调用
Select-String -Path "frontend\admin\src\**\*.ts","frontend\admin\src\**\*.tsx" -Pattern "fetch\(|client\." -Recurse
# 人工对比：路径是否一致
```

### 3.2 响应类型一致性检查

```powershell
# 检查前端类型定义
Get-ChildItem -Path "frontend\admin\src\types" -Filter "*.ts" | ForEach-Object { $_.Name }

# 检查后端响应结构
Select-String -Path "internal\api\handler\**\*.go" -Pattern "c\.JSON\(" -Recurse | Select-Object -First 20
```

### 3.3 前端关键防线验证

```powershell
# 检查是否有 window.alert/confirm（违禁）
Select-String -Path "frontend\admin\src\**\*.tsx","frontend\admin\src\**\*.ts" -Pattern "window\.alert|window\.confirm|window\.prompt" -Recurse
# 期望: 无结果

# 检查 access_token 存储方式（应在内存，非 localStorage）
Select-String -Path "frontend\admin\src\lib\auth-session.ts" -Pattern "localStorage.*token|sessionStorage.*token"
# 期望: access_token 不在 localStorage（refresh_token 可以在）
```

---

## ⚙️ 阶段四：业务逻辑验证（15分钟）

### 4.1 认证流程完整性

```powershell
# CSRF 保护
Select-String -Path "internal\api\middleware\**\*.go" -Pattern "csrf" -Recurse

# 速率限制（登录端点）
Select-String -Path "internal\api\middleware\**\*.go","cmd\server\main.go" -Pattern "ratelimit|RateLimit" -Recurse

# Token 黑名单（退出登录有效性）
Select-String -Path "internal\service\**\*.go" -Pattern "Blacklist|blacklist|RevokeToken" -Recurse
```

### 4.2 权限模型验证

```powershell
# 角色继承循环检测
Select-String -Path "internal\service\**\*.go","internal\repository\**\*.go" -Pattern "circular|cycle|loop" -Recurse

# 权限汇总逻辑
Select-String -Path "internal\api\middleware\**\*.go" -Pattern "GetEffectivePermissions|HasPermission" -Recurse
```

### 4.3 错误处理完整性

```powershell
# 检查 handleError 或统一错误处理
Select-String -Path "internal\api\handler\**\*.go" -Pattern "handleError\|respondError\|handleErr" -Recurse | Measure-Object | Select-Object Count
# 观察是否有统一处理

# 检查 goroutine 中是否有 gin context 使用（已知缺陷）
Select-String -Path "internal\**\*.go" -Pattern "go func" -Recurse | Select-Object -First 10
```

---

## 📊 阶段五：覆盖率深度分析（5分钟）

```powershell
# 生成详细覆盖率报告
go test ./... -coverprofile=coverage.out -count=1
go tool cover -func=coverage.out | Sort-Object { [double]($_.Split()[-1].TrimEnd('%')) }

# 关键路径覆盖率检查
go tool cover -func=coverage.out | Select-String "auth|middleware|service|repository"

# HTML 可视化（可选，用浏览器打开）
go tool cover -html=coverage.out -o coverage.html
```

### 覆盖率评估标准

| 包 | 目标 | 不合格条件 |
|----|------|-----------|
| api/middleware/auth | ≥ 70% | < 30% 为 P1 |
| api/middleware/rbac | ≥ 70% | < 30% 为 P1 |
| service/* | ≥ 65% | < 40% 为 P2 |
| repository/* | ≥ 60% | < 40% 为 P2 |
| auth/* | ≥ 75% | < 50% 为 P1 |
| pkg/pagination | ≥ 60% | 0% 为 P2 |

---

## 📋 阶段六：运维检查（5分钟）

```powershell
# Docker 健康检查
Select-String -Path "Dockerfile","docker-compose.yml" -Pattern "healthcheck" -Recurse

# 资源限制
Select-String -Path "docker-compose.yml" -Pattern "mem_limit|cpus|memory|cpu_shares"

# .env.example 完整性
Get-Content ".env.example" | Where-Object { $_ -notmatch "^#" -and $_ -ne "" }

# Runbook 存在性
Get-ChildItem -Path "docs\runbooks" -Filter "*.md" | ForEach-Object { $_.Name }
```

---

## ✅ 最终审查结论模板

```markdown
## PR 审查结论

**审查日期**: 2026-XX-XX
**PR 标题**: [标题]
**审查者**: [名字]

### 自动化门禁
| 检查项 | 结果 |
|--------|------|
| go build | ✅/❌ |
| go vet | ✅/❌ |
| go test -race | ✅/❌ |
| 覆盖率 | __% |
| govulncheck | ✅/❌ |
| npm build | ✅/❌ |
| npm test | ✅/❌ |

### 人工审查结果

**安全维度**: X.X/10
**API 契约**: X.X/10
**前后端集成**: X.X/10
**业务逻辑**: X.X/10
**测试质量**: X.X/10

### 发现的问题

🔴 P0（共 X 个）：[列表]
🟠 P1（共 X 个）：[列表]
🟡 P2（共 X 个）：[列表]

### 结论

[ ] ✅ 批准合并（所有 P0/P1 已修复）
[ ] 🔴 拒绝合并（存在未修复的 P0/P1）
[ ] 🟡 条件合并（P2 已有修复计划）

**修复后请 @我 复审**
```

---

*Checklist 版本: v4.0*  
*生效日期: 2026-04-12*