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
23 KiB
23 KiB
代码审查标准与质量评级规范 v4.0
文档版本: v4.0
生成日期: 2026-04-12
适用范围: User Management System (UMS) 项目
审查专家: 代码审查专家 Agent
迭代依据: v3.0 执行发现的系统性问题 + 2026-04-12 生产就绪验证结果
一、版本演进说明
v4.0 的核心升级是从"标准制定"转向"执行闭环"。历史教训：
| 版本 | 核心问题 | 教训 |
|---|---|---|
| v1.0 | 标准过于宽松 | 缺少量化门禁 |
| v2.0 | 评分虚高（9.7/10） | 未做工具验证，依赖文档自述 |
| v3.0 | 差距识别准确，但执行缺乏闭环机制 | 文档谎报问题未被预防 |
| v4.0 | 8维度评估 + 零信任验证原则 + 自动化闭环 | 工具证据先于文档断言 |
v4.0 关键原则
"零信任文档"原则：任何"已完成"的声明，必须附带可重现的命令和输出，否则视为未完成。
二、8 维度质量评估体系
| 维度 | 权重 | 生产合格线 | 当前基线（2026-04-12） |
|---|---|---|---|
| ① 代码质量 | 15% | 覆盖率≥60%，无严重技术债 | 36.3%（持续提升中） |
| ② API 契约 | 10% | OpenAPI 完整，响应格式统一 | ⚠️ 无 OpenAPI 规范 |
| ③ 安全强度 | 20% | gosec HIGH=0，无已知CVE | ✅ govulncheck 无漏洞 |
| ④ 前后端集成 | 10% | 接口对齐，错误处理一致 | ⚠️ 部分接口未完全对齐 |
| ⑤ 功能完整性 | 15% | PRD 功能100%实现 | ✅ 核心功能已完成 |
| ⑥ 业务专业性 | 10% | 符合IAM最佳实践 | ✅ Argon2id/RBAC/设备信任 |
| ⑦ 用户体验 | 10% | E2E测试通过，无原生弹窗 | ✅ 325个前端测试通过 |
| ⑧ 运维简洁性 | 10% | 一键部署，完整监控，Runbook存在 | ⚠️ Runbook不完整 |
评分计算公式
综合分 = Σ(维度分 × 权重)
生产上线标准：
- ≥ 8.5：卓越，立即发布
- 8.0 - 8.4：优秀，可发布
- 7.0 - 7.9：良好，修复 P1 后发布 ← 当前项目目标区间
- 6.0 - 6.9：需改进，修复 P0+P1 后再评
- < 6.0：不合格，停止合并主干
三、问题分级体系（v4.0）
| 级别 | 标识 | 定义 | 合并影响 | 修复 SLA |
|---|---|---|---|---|
| P0 阻塞 | 🔴 | 安全漏洞、数据丢失、构建/测试完全中断 | 禁止合并 | 4 小时 |
| P1 严重 | 🟠 | 功能错误、安全弱点、测试覆盖关键路径为 0% | 禁止合并 | 当天 |
| P2 高 | 🟡 | 技术债积累、覆盖率不足、文档缺失、设计隐患 | 附计划后可合并 | 本周 |
| P3 中 | 🔵 | 代码可读性、命名、日志完善 | 可合并 | 本 Sprint |
| P4 低 | 💭 | 挑剔级改进、Nice-to-have | 可忽略 | 无要求 |
四、维度一：代码质量审查清单
4.1 测试覆盖率门禁（分层要求）
backend_coverage:
overall_minimum: 60% # v4.0 降至可达标准，明确路线图至80%
critical_paths_minimum: 80% # 认证/权限/加密路径
specific_targets:
auth_handler: 85%
jwt: 95%
password: 95%
auth_middleware: 70% # 当前0%，必须修复
rbac_middleware: 70% # 当前0%，必须修复
repository: 70%
pagination: 60% # 当前0%，需添加
frontend_coverage:
overall_minimum: 70%
critical_paths:
auth_flow: 85%
http_client: 80%
route_guards: 90%
4.2 代码结构审查
□ SOLID 原则遵守（重点：依赖倒置原则 DIP）
□ 无具体类型直接依赖（使用接口，不用 *repository.XXXRepository）
□ 无 context.Background() 滥用（请求链路必须传播 ctx）
□ 无裸 goroutine（必须有 recover 或 errgroup）
□ 无 panic 作为业务流程的常规失败路径
□ 错误处理具体，不吞 error
□ 无死代码（staticcheck U1000 检查）
□ 函数复杂度可控（圈复杂度 ≤ 15）
4.3 并发安全
□ 共享状态有 mutex 或 channel 保护
□ go test -race 通过
□ 无 goroutine 泄漏（使用 context 取消）
□ 数据库事务不使用类型断言绕过接口
五、维度二：API 契约审查清单
5.1 响应格式统一性
□ 所有成功响应使用统一结构：
{ "code": 0, "message": "success", "data": {...} }
□ 所有错误响应使用统一结构：
{ "code": <错误码>, "message": "<说明>", "request_id": "<追踪ID>" }
□ 分页响应包含标准字段：
{ "items": [...], "total": N, "page": N, "page_size": N }
或游标模式：{ "items": [...], "next_cursor": "..." }
□ HTTP 状态码语义正确：
200/201/204/400/401/403/404/409/422/429/500
□ 不在 2xx 响应中返回 code != 0
5.2 OpenAPI 规范
□ 所有 endpoint 有 swagger 注释
□ 所有请求参数有类型和校验说明
□ 所有响应 schema 定义完整
□ 错误码有枚举文档
□ 认证方式（Bearer Token）标注清晰
□ swagger-ui 可访问（/swagger/index.html）
5.3 API 版本管理
□ 路由包含版本前缀（/api/v1/...）
□ 破坏性变更通过版本升级（/api/v2/...）
□ 废弃 endpoint 有 Deprecated 标注 + 迁移说明
5.4 关键 API 功能验证点
| API | 必须验证项 |
|---|---|
| POST /auth/login | 速率限制、设备信任、异常检测 |
| POST /auth/refresh | Token 轮换、并发刷新锁 |
| POST /auth/logout | Token 黑名单生效 |
| PUT /users/:id | 权限检查（自己或Admin）、密码历史 |
| POST /users/avatar | Magic Bytes 验证、文件大小限制 |
| GET /roles/:id | 角色继承链不循环 |
| * | CSRF Token 校验、请求 ID 追踪 |
六、维度三：安全强度审查清单
6.1 自动化安全工具（PR 必须通过）
# 后端安全扫描（HIGH/CRITICAL 必须为 0）
gosec -exclude=G404,G101 ./...
# 漏洞数据库检查（必须无已知 CVE）
govulncheck ./...
# 前端依赖安全（moderate+ 必须为 0）
npm audit --audit-level=moderate
# 依赖许可证检查（避免 GPL 污染）
go-licenses check ./...
6.2 认证安全（核心亮点 ✅）
✅ 密码：Argon2id（64MB/5次迭代/4并行）
✅ Token 随机性：crypto/rand（无 math/rand）
✅ JTI 防枚举：timestamp(8B) + random(16B)
✅ Refresh Token 滚动轮换（防无限续期）
✅ access_token 内存存储（非 localStorage）
✅ refresh_token HttpOnly Cookie
✅ 退出登录 Token 失效
✅ 登录速率限制 + 异常检测
✅ 常数时间密码比较（防时序攻击）
□ JWT_SECRET 生产环境必须通过环境变量注入（非 config.yaml）
□ JWT_SECRET 缺失时服务启动 fatal（非降级到弱密钥）
6.3 文件上传安全
✅ Magic Bytes 校验（http.DetectContentType）
□ 文件大小限制（最大 5MB）
□ 文件名清洗（path.Base + 随机前缀）
□ 存储目录在 webroot 之外，或使用 CDN
□ Content-Disposition: attachment（防 XSS）
6.4 输入校验
□ 所有 API 输入有 struct binding + validate tag
□ 字符串长度限制
□ 枚举值校验（role/status 等）
□ 数值范围校验（page_size 最大 100）
□ SQL 查询全部参数化（无 fmt.Sprintf 拼接 SQL）
6.5 传输与头部安全
□ HTTPS 强制（生产）
□ HSTS 配置
□ CORS 非 wildcard（指定白名单域名）
□ X-Content-Type-Options: nosniff
□ X-Frame-Options: DENY
□ Content-Security-Policy 配置
□ CSRF Token 校验（已实现 ✅）
□ no-store 缓存控制（敏感接口）
七、维度四：前后端集成审查清单
7.1 接口对齐验证
□ 前端所有 API 调用路径与后端路由一致
□ 请求 body 字段名与后端 struct json tag 一致
□ 响应字段名与前端类型定义一致
□ 分页参数名一致（page/page_size vs offset/limit）
□ 错误码枚举前后端同步
□ 时间格式统一（ISO 8601 UTC）
7.2 认证集成
□ 前端 access_token 内存存储（非 localStorage）✅
□ 前端 401 自动刷新机制（单次，有并发锁）✅
□ 前端刷新失败跳转登录页
□ 前端请求携带 CSRF Token
□ 前端设备信息上报（device_id/browser/os）✅
□ device_id 从 localStorage 持久化读取（非随机生成）✅
7.3 错误处理一致性
□ 前端 HTTP 客户端统一处理错误（lib/http/client.ts）
□ 后端错误响应格式前端能正确解析
□ 网络超时处理（显示友好提示，非崩溃）
□ 表单校验错误映射到字段级（非全局错误消息）
□ 全局错误边界（ErrorBoundary）捕获意外崩溃
7.4 前端组件质量
□ 无 window.alert/confirm/prompt（使用 Ant Design Modal）
□ 无 window.open（使用路由导航）
□ 列表页有加载态、空态、错误态
□ 表单提交有防重（loading 状态禁用按钮）
□ 敏感操作有二次确认
□ 权限不足显示友好提示（非空白页）
八、维度五：功能完整性审查清单
8.1 PRD 功能矩阵核查
| 模块 | 功能点 | 实现状态 | 测试状态 |
|---|---|---|---|
| 认证 | 密码登录 | ✅ | ✅ E2E |
| 认证 | 邮件验证码登录 | ✅ | ⚠️ 需测试 |
| 认证 | SMS 验证码登录 | ✅（需SMS配置） | ⚠️ 需测试 |
| 认证 | 社交登录（OAuth） | ✅ 框架完整 | ⚠️ 无 Live 测试 |
| 认证 | 多因素认证（TOTP） | ✅ | ⚠️ 需测试 |
| 认证 | 设备信任 | ✅ | ✅ |
| 用户管理 | CRUD | ✅ | ✅ |
| 用户管理 | 批量操作 | ❌ 未实现 | - |
| 角色权限 | RBAC + 继承 | ✅ | ✅ |
| 日志 | 登录日志 | ✅ | ✅ |
| 日志 | 操作日志 | ✅ | ⚠️ |
| 日志 | 导出 | ❌ 未实现 | - |
| 系统设置 | 全局设置 | ❌ 前端未实现 | - |
| 管理员管理 | 页面 | ❌ 前端未实现 | - |
| 监控 | 系统指标 | ✅ | ⚠️ |
| 通知 | 邮件 | ✅（需SMTP配置） | ⚠️ |
| 通知 | SMS | ✅（需配置） | ⚠️ |
8.2 边界场景测试要求
□ 并发登录（同账号多设备）
□ Token 过期刷新竞争
□ 密码错误连续次数限制
□ 大文件上传超限
□ SQL 特殊字符输入（XSS/SQLi 防御）
□ 角色循环继承防御
□ 超大分页请求（page_size=9999）
□ 并发写操作数据一致性
九、维度六：业务专业性审查清单（IAM 领域）
9.1 IAM 最佳实践符合性
✅ RBAC 权限模型（Role-Based Access Control）
✅ 角色继承（含循环检测 + 深度限制）
✅ 密码历史（防止重复使用近期密码）
✅ 账号异常检测（登录位置/时间/设备异常）
✅ 会话管理（access_token 短期 + refresh_token 长期）
✅ 审计日志（操作留痕）
□ 密码复杂度策略可配置（最小长度/特殊字符/数字要求）
□ 账号锁定策略（N次失败后锁定X分钟）
□ 密码过期强制更新策略
□ 最小权限原则验证（角色不超授权）
9.2 数据合规性
□ 敏感字段脱敏（手机号、邮箱在列表接口部分掩码）
□ 用户数据删除（软删除 + 可恢复，符合数据留存要求）
□ 个人数据导出（GDPR 右利用 - 如适用）
□ 操作日志不记录密码明文
□ 接口不返回密码哈希
9.3 系统健壮性
□ 外部依赖（邮件/SMS/OAuth）失败不影响核心登录功能
□ 缓存失效后降级到数据库（非崩溃）
□ 数据库连接池耗尽时返回 503（非 panic）
□ 配置文件缺失关键项时启动 fatal（非默认危险值）
十、维度七：用户体验审查清单
10.1 交互质量
□ 表单校验即时反馈（onChange，非仅 onSubmit）
□ 异步操作有 loading 状态指示
□ 操作成功/失败有清晰的 Toast 通知
□ 删除/危险操作有确认弹窗
□ 页面跳转有平滑过渡
□ 空数据状态有友好提示（非空白）
□ 错误页面（404/403/500）美观且有返回链接
10.2 响应式与多端适配
□ 桌面端布局（≥1440px）正常
□ 平板端布局（820px）正常
□ 移动端布局（390px）可用
□ 侧边栏折叠在小屏可用
□ 表格在小屏有横向滚动
10.3 E2E 测试覆盖（现有）
✅ 管理员引导（admin-bootstrap）
✅ 公开注册（public-registration）
✅ 邮箱激活（email-activation）
✅ 登录表面验证（login-surface）
✅ 认证工作流（auth-workflow）
✅ 响应式登录（responsive-login）
✅ 桌面/移动端导航（desktop-mobile-navigation）
❌ 用户 CRUD（缺失）
❌ 角色权限管理（缺失）
❌ 批量操作（未实现功能）
10.4 可访问性
□ 所有图片有 alt 文本
□ 表单字段有 label 关联
□ 键盘导航可用（Tab 顺序合理）
□ 颜色对比度符合 WCAG AA（4.5:1）
□ 错误提示不仅依赖颜色
十一、维度八：运维简洁性审查清单
11.1 部署简洁性
□ Docker 镜像多阶段构建（最小化镜像大小）
□ Docker healthcheck 配置（已修复 ✅）
□ docker-compose 资源限制（memory/cpu）
□ 环境变量完整文档（.env.example）
□ 一键启动命令（docker-compose up -d）
□ 一键停止和清理
□ 数据库迁移自动执行（启动时）
11.2 配置管理
□ 所有密钥从环境变量读取（非 config.yaml 硬编码）
□ 支持多环境（dev/staging/prod）
□ 配置有校验（启动时 fail-fast）
□ 默认值安全（不允许弱密钥启动）
11.3 可观测性
□ 结构化日志（JSON 格式）
□ 请求追踪 ID（Trace-ID header）✅
□ Prometheus 指标暴露（/metrics）✅
□ 健康检查端点（/health/ready + /health/live）
□ 关键业务指标（登录成功率/Token刷新率/错误率）
□ 慢查询日志
11.4 Runbook 完整性
必须存在的 Runbook（docs/runbooks/）：
□ 01-service-startup.md 服务启动
□ 02-service-shutdown.md 优雅停机
□ 03-config-update.md 配置热更新
□ 04-database-migration.md 数据库迁移
□ 05-backup-restore.md 备份与恢复
□ 06-log-analysis.md 日志分析
□ 07-incident-response.md 事件响应
□ 08-security-incident.md 安全事件响应
□ 09-scaling.md 扩缩容
□ 10-performance-troubleshoot.md 性能排查
11.5 监控告警门禁
critical_alerts: # 必须配置
- service_down # 服务不可用
- error_rate_5pct # 错误率 > 5%
- p99_latency_1s # P99 > 1秒
- db_connection_pool # 连接池 > 90%
warning_alerts: # 建议配置
- error_rate_1pct # 错误率 > 1%
- memory_85pct # 内存 > 85%
- disk_80pct # 磁盘 > 80%
十二、生产合并门禁矩阵（v4.0）
12.1 自动化门禁（CI 必须全部通过）
#!/bin/bash
# ============================================
# UMS 生产合并门禁检查脚本 v4.0
# 所有检查通过后，PR 才允许合并
# ============================================
set -e
FAIL=0
echo "━━━ [1/7] 后端编译 ━━━"
go build ./cmd/server && echo "✅ BUILD PASS" || { echo "🔴 BUILD FAIL"; FAIL=1; }
echo "━━━ [2/7] 静态分析 ━━━"
go vet ./... && echo "✅ VET PASS" || { echo "🔴 VET FAIL"; FAIL=1; }
echo "━━━ [3/7] 后端测试 ━━━"
go test ./... -count=1 -race -timeout=5m && echo "✅ TEST PASS" || { echo "🔴 TEST FAIL"; FAIL=1; }
echo "━━━ [4/7] 测试覆盖率 ━━━"
go test ./... -coverprofile=coverage.out -count=1
COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
echo "覆盖率: ${COVERAGE}%"
awk "BEGIN { exit (${COVERAGE} < 60) ? 1 : 0 }" && echo "✅ COVERAGE PASS (≥60%)" || { echo "🔴 COVERAGE FAIL (<60%)"; FAIL=1; }
echo "━━━ [5/7] 安全扫描 ━━━"
# gosec（排除已评估的误报）
gosec -exclude=G404 ./... && echo "✅ GOSEC PASS" || { echo "🟠 GOSEC: 请检查HIGH/CRITICAL问题"; }
govulncheck ./... && echo "✅ GOVULN PASS" || { echo "🔴 GOVULN FAIL: 存在已知漏洞"; FAIL=1; }
echo "━━━ [6/7] 前端构建与测试 ━━━"
cd frontend/admin
npm.cmd run lint && echo "✅ LINT PASS" || { echo "🔴 LINT FAIL"; FAIL=1; }
npm.cmd run build && echo "✅ BUILD PASS" || { echo "🔴 FE BUILD FAIL"; FAIL=1; }
npm.cmd test -- --run && echo "✅ TEST PASS" || { echo "🔴 FE TEST FAIL"; FAIL=1; }
npm.cmd audit --audit-level=high && echo "✅ NPM AUDIT PASS" || { echo "🟠 NPM AUDIT: 请检查high+漏洞"; }
cd ../..
echo "━━━ [7/7] 最终结果 ━━━"
if [ $FAIL -eq 0 ]; then
echo "✅ 所有门禁通过，PR 可以合并"
else
echo "🔴 门禁未通过，PR 禁止合并"
exit 1
fi
12.2 人工审查门禁（Reviewer 签字前必须确认）
安全维度（任一 NO → 拒绝合并）：
□ 无硬编码密钥或密码
□ 无 SQL 字符串拼接
□ 新 API 有权限校验
□ 文件上传有 Magic Bytes 验证
□ 敏感操作有审计日志
功能维度：
□ 新功能有对应测试（单元 + 集成）
□ 修复 Bug 有回归测试
□ 破坏性变更有兼容处理或版本升级
文档维度：
□ API 变更已更新 Swagger 注释
□ 配置变更已更新 .env.example
□ 破坏性变更已记录在 CHANGELOG
12.3 E2E 触发条件
以下变更必须运行 E2E 测试：
# 命令：cd frontend/admin && npm.cmd run e2e:full:win
触发条件（满足任一）：
├─ 认证相关变更（auth handler/middleware/service）
├─ 路由守卫变更（RequireAuth/RequireAdmin）
├─ 导航组件变更（Sidebar/Header）
├─ 登录/注册页面变更
├─ Token 管理变更（auth-session.ts/http client）
└─ 权限模型变更（RBAC）
十三、当前项目状态评估（2026-04-12）
13.1 各维度评分
| 维度 | 得分 | 权重 | 加权分 | 关键问题 |
|---|---|---|---|---|
| ① 代码质量 | 7.0 | 15% | 1.05 | 覆盖率36.3%，staticcheck 25个问题 |
| ② API 契约 | 6.5 | 10% | 0.65 | 无 OpenAPI 规范，部分响应格式不统一 |
| ③ 安全强度 | 8.5 | 20% | 1.70 | gosec误报已分析，govulncheck通过 |
| ④ 前后端集成 | 8.0 | 10% | 0.80 | P0/P1问题已修复，构建通过 |
| ⑤ 功能完整性 | 7.5 | 15% | 1.13 | 核心功能完整，批量操作/系统设置未实现 |
| ⑥ 业务专业性 | 8.5 | 10% | 0.85 | IAM最佳实践优秀，配置策略可扩展 |
| ⑦ 用户体验 | 8.0 | 10% | 0.80 | E2E通过，部分页面未实现 |
| ⑧ 运维简洁性 | 6.5 | 10% | 0.65 | 基础运维可用，Runbook不完整 |
| 综合 | 7.63 | 100% | 7.63 | 良好，修复 P1 后可上线 |
13.2 剩余 P1 问题（上线前必须修复）
| ID | 问题 | 影响维度 | 修复工作量 |
|---|---|---|---|
| P1-A | 测试覆盖率 auth_middleware = 0% | 代码质量 | 4h |
| P1-B | 测试覆盖率 rbac_middleware = 0% | 代码质量 | 4h |
| P1-C | JWT_SECRET 弱值时应 fatal（非随机临时密钥） | 安全 | 1h |
| P1-D | Runbook 核心 3 个必须存在（启停/数据库迁移/事件响应） | 运维 | 4h |
13.3 P2 问题（上线后第一个迭代修复）
| ID | 问题 | 影响维度 |
|---|---|---|
| P2-A | OpenAPI 规范（Swagger 注释完善） | API 契约 |
| P2-B | pagination 包单元测试覆盖 | 代码质量 |
| P2-C | context.Background() 滥用修复 | 代码质量 |
| P2-D | 批量操作功能实现 | 功能完整性 |
| P2-E | staticcheck U1000 死代码清理 | 代码质量 |
十四、审查执行 SOP
14.1 PR 审查流程（简化版）
开发者创建 PR
↓
自动化门禁（CI）
- 构建/测试/覆盖率/安全扫描
- 任一失败 → 自动 Block
↓（CI 全通过）
审查者人工审查（4h SLA）
- 安全维度 → 优先检查
- API 契约 → 对齐前后端
- 业务逻辑 → 正确性验证
- 测试有效性 → 非虚假测试
↓
问题标注（P0~P4）
- P0/P1 → 作者必须修复
- P2 → 附计划可合并
↓（P0/P1 均修复）
涉及认证/路由的 PR → 跑 E2E
↓
Approve + 合并
14.2 快速自审清单（作者提 PR 前）
# 5分钟自审命令序列（Windows PowerShell）
cd d:\usersystem
go build ./cmd/server; if($?) { "✅ Build OK" } else { "❌ Build FAIL" }
go vet ./...; if($?) { "✅ Vet OK" } else { "❌ Vet FAIL" }
go test ./... -short -count=1; if($?) { "✅ Tests OK" } else { "❌ Tests FAIL" }
cd frontend/admin
npm.cmd run lint; if($?) { "✅ Lint OK" } else { "❌ Lint FAIL" }
npm.cmd run build; if($?) { "✅ FE Build OK" } else { "❌ FE Build FAIL" }
14.3 审查评论模板
## 审查总结
**总体印象**：[1-2句概括，先说优点]
**综合评分**：X.X/10
---
### 🔴 P0 - 必须修复（阻塞合并）
**[问题标题]**
📍 位置：`file.go:行号`
**问题描述**：[清晰描述，包括为什么是问题]
**风险**：[如果不修复，会发生什么]
**建议修复**：
```go
// 修复后的代码
🟠 P1 - 必须修复
...
🟡 P2 - 建议修复（附计划后可合并）
...
✅ 做得好的地方
- [具体表扬，教学价值]
- [鼓励好的实践]
后续步骤
- 修复 P0/P1 后 @我复审
- P2 请在本周内提单跟踪
---
## 十五、版本演进路线图
| 阶段 | 目标分 | 关键任务 | 预计时间 |
|------|--------|----------|----------|
| **当前** | 7.63 | P1 修复（中间件测试 + JWT fatal + Runbook）| 本周 |
| **v1.0 上线** | ≥ 8.0 | P1 全清，E2E 覆盖核心业务流 | 2周内 |
| **v1.1 优化** | ≥ 8.5 | OpenAPI + 覆盖率 60% + 批量操作 | 1个月内 |
| **v2.0 完整** | ≥ 9.0 | 覆盖率 80% + K8s + 完整 Runbook + 渗透测试 | 季度内 |
---
## 附录 A：工具安装参考
```powershell
# Windows PowerShell
# gosec
go install github.com/securego/gosec/v2/cmd/gosec@latest
# govulncheck
go install golang.org/x/vuln/cmd/govulncheck@latest
# staticcheck
go install honnef.co/go/tools/cmd/staticcheck@latest
# 运行静态分析（完整）
staticcheck ./...
附录 B：gosec 误报白名单（已评估）
# 以下 gosec 规则在本项目属于误报或低风险，已评估记录
excluded_rules:
G404: # 弱随机数 - 用于验证码背景色/重试延迟，无安全要求
G101: # 硬编码凭证 - OAuth ClientID为公开配置，非秘密
G304: # 文件路径注入 - 路径来自配置/环境变量，非用户输入
G301: # 文件权限 0755 - 目录权限符合Linux惯例
G306: # 文件权限 0644 - 日志文件权限合理
# HIGH/CRITICAL 级别的非白名单规则必须 0 violations
文档版本: v4.0
制定日期: 2026-04-12
制定者: 代码审查专家 Agent
下次审查: 2026-04-19
适用分支: fix/status-review-sync-20260409