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

# 代码审查标准与质量评级规范 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 测试覆盖率门禁（分层要求）

```yaml
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 必须通过）

```bash
# 后端安全扫描（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 监控告警门禁

```yaml
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 必须全部通过）

```bash
#!/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 测试**：

```bash
# 命令：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 前）

```bash
# 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 审查评论模板

```markdown
## 审查总结

**总体印象**：[1-2句概括，先说优点]

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

---

### 🔴 P0 - 必须修复（阻塞合并）

**[问题标题]**  
📍 位置：`file.go:行号`

**问题描述**：[清晰描述，包括为什么是问题]

**风险**：[如果不修复，会发生什么]

**建议修复**：
```go
// 修复后的代码
```

---

### 🟠 P1 - 必须修复

...

---

### 🟡 P2 - 建议修复（附计划后可合并）

...

---

### ✅ 做得好的地方

- [具体表扬，教学价值]
- [鼓励好的实践]

---

### 后续步骤

1. 修复 P0/P1 后 @我复审
2. 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 误报白名单（已评估）

```yaml
# 以下 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*