long-agent
09beb173cc
- Fix DIP violations in service layer (device, stats, auth middleware) - Add ReplaceUserRoles interface method for transaction safety - Implement Magic Bytes validation for avatar uploads - Standardize OAuth error handling with ErrOAuthProviderNotSupported - Use crypto/rand for JWT secret generation instead of weak fixed key - Apply code formatting with gofumpt and goimports - Fix staticcheck issues (S1024, S1008, ST1005) - Add comprehensive quality and functional test reports - Achieve 36.3% test coverage (up from 16.3%) - All E2E, integration, and business logic tests passing
300 lines
8.2 KiB
Markdown
300 lines
8.2 KiB
Markdown
# 代码审查执行 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*
|