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

# 代码审查标准与质量评级规范 v3.0

**文档版本**: v3.0
**生成日期**: 2026-04-08
**适用范围**: User Management System (UMS) 项目
**审查专家**: 代码审查专家
**目标**: 生产级软件质量标准

---

## 修订说明

v3.0 版本针对"生产上线"要求进行全面升级：

| 维度 | v2.0 | v3.0 | 差距 |
|------|------|------|------|
| 代码质量 | 9.7/10 | **7.5/10** | 测试覆盖率仅32.1%，严重不足 |
| 安全强度 | 9.7/10 | **6.0/10** | 无gosec扫描、占位JWT密钥、缺渗透测试 |
| 部署简单性 | 8.0/10 | **5.0/10** | docker-compose简陋、无K8s、无健康检查 |
| 运维可靠性 | 7.0/10 | **4.0/10** | 无备份自动化、无灾备方案、监控薄弱 |
| 文档规范性 | 7.0/10 | **5.0/10** | 缺OpenAPI、缺Runbook、缺应急响应 |

**综合评分（v3.0真实评估）**: **5.9/10 ⚠️ 不合格**

---

## 一、生产级质量标准（v3.0）

### 1.1 五维评估体系

| 维度 | 权重 | 生产标准 | 当前差距 |
|------|------|----------|----------|
| **代码质量** | 25% | 覆盖率≥80%，无技术债 | 覆盖率32.1%，差距48% |
| **安全强度** | 30% | 渗透测试、gosec合格、合规 | 无扫描工具、占位密钥 |
| **部署简单性** | 15% | 一键部署、配置分离、不可变 | docker-compose简陋 |
| **运维可靠性** | 20% | 监控完善、告警到位、备份自动化 | 监控基础、告警未验证 |
| **文档规范性** | 10% | OpenAPI、Runbook、应急响应 | 文档残缺 |

### 1.2 生产合并门禁（必须全部通过）

```yaml
# 生产级 PR 合并门禁
pre_merge_checks:
  # 代码质量
  - name: 后端覆盖率
    command: go test -coverprofile coverage.out ./...
    threshold: 80%
    critical_paths: 90%
  - name: 前端覆盖率
    command: npm test -- --coverage
    threshold: 80%
    
  # 安全
  - name: Go安全扫描
    command: gosec ./...
    critical: high/critical must be 0
  - name: 前端安全扫描
    command: npm audit
    critical: 0 vulnerabilities
  - name: 依赖漏洞扫描
    command: govulncheck ./...
    critical: 0 findings
    
  # 构建
  - name: 后端编译
    command: go build ./cmd/server
  - name: 前端构建
    command: npm run build
    
  # 测试
  - name: 后端测试
    command: go test ./... -count=1 -race
  - name: 前端测试
    command: npm test -- --coverage
  - name: E2E测试
    command: npm run e2e:full:win
```

### 1.3 问题分级（生产级）

| 级别 | 标识 | 定义 | 合并影响 |
|------|------|------|----------|
| **P0 阻塞** | 🔴 | 安全漏洞、数据丢失风险、生产不可用 | **必须修复** |
| **P1 严重** | 🟠 | 功能错误、性能严重劣化、合规风险 | **必须修复** |
| **P2 高** | 🟡 | 测试覆盖率不足、技术债积累、文档缺失 | **72小时内修复** |
| **P3 中** | 🔵 | 代码风格、轻微优化、文档完善 | **本周修复** |
| **P4 低** | 💭 | 挑剔级改进、愿望清单 | 可延迟 |

---

## 二、代码质量审查清单

### 2.1 测试覆盖率要求

```yaml
coverage_requirements:
  backend:
    overall: 80%
    critical_paths:
      auth_handler: 90%
      jwt: 95%
      password: 95%
      repository: 70%
    excluded:
      - cmd/server/main.go  # 可豁免
      - docs/              # 文档包
      - testdb/           # 测试数据库
      - testutil/         # 测试工具
      
  frontend:
    overall: 80%
    critical_paths:
      auth: 90%
      http_client: 90%
      router: 100%
      guards: 100%
```

### 2.2 单元测试审查

```
□ 每个公开函数有单元测试
□ 边界条件被测试（空值、极大值、特殊字符）
□ 错误路径被测试
□ 并发安全被测试（go test -race）
□ 无 mock 滥用（真实依赖优先）
□ 测试命名规范：Test[函数名][场景]
□ 单元测试不依赖外部状态
```

### 2.3 集成测试审查

```
□ 数据库操作有集成测试
□ API 端点有集成测试
□ 认证流程有集成测试
□ 测试使用隔离数据库（不污染开发数据）
```

---

## 三、安全强度审查清单

### 3.1 自动化安全扫描（必须集成CI）

```yaml
security_automation:
  gosec:
    schedule: daily
    fail_on: high/critical
    exclusions: documented
    
  npm_audit:
    schedule: daily
    fail_on: moderate/high
    audit_level: moderate
    
  govulncheck:
    schedule: weekly
    fail_on: any
    
  owasp_dependency_check:
    schedule: weekly
    report: required
```

### 3.2 安全审查清单

#### 认证安全
```
□ 密码使用 Argon2id（已验证 ✅）
□ Token 使用 crypto/rand（已验证 ✅）
□ JTI 防枚举（已验证 ✅）
□ Token 滚动轮换（已验证 ✅）
□ 登录速率限制（已验证 ✅）
□ 异常登录检测（已验证 ✅）
□ 退出登录清理状态（已验证 ✅）
```

#### 数据安全
```
□ 敏感数据不写入日志
□ 敏感数据不返回 API
□ 数据库使用参数化查询
□ 密码不硬编码
□ 密钥从环境变量/密钥管理器读取
```

#### 传输安全
```
□ HTTPS 强制
□ HSTS 配置
□ CSRF 保护
□ CORS 非 wildcard
```

#### 依赖安全
```
□ 无已知 CVE 漏洞
□ 无弃用依赖
□ 最小权限依赖原则
```

### 3.3 渗透测试要求

```yaml
penetration_testing:
  schedule: quarterly
  scope:
    - SQL注入测试
    - XSS测试
    - CSRF测试
    - 认证绕过测试
    - 会话管理测试
    - 敏感数据泄露测试
  report: required
  responsible: external_security_team
```

---

## 四、部署简单性审查清单

### 4.1 Docker 部署标准

```yaml
docker_requirements:
  # 镜像构建
  multi_stage: true          # 使用多阶段构建减小镜像
  non_root_user: true       # 非 root 用户运行
  scratch_base: preferred    # 最小基础镜像
  
  # 健康检查
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"]
    interval: 30s
    timeout: 10s
    retries: 3
    
  # 资源限制
  resources:
    memory: 512Mi
    cpu: "500m"
    
  # 重启策略
  restart: unless-stopped
  restart_max_attempts: 5
```

### 4.2 Kubernetes 部署要求

```
□ 有 Helm Chart 或 Kustomize 配置
□ 有 Deployment/StatefulSet
□ 有 Service 配置
□ 有 Ingress 配置
□ 有 ConfigMap/Secret 管理配置
□ 有 HPA（水平自动扩缩容）
□ 有 PodDisruptionBudget
□ 有资源请求/限制
□ 有健康检查（liveness/readiness）
□ 有安全上下文
□ 有网络策略
```

### 4.3 部署配置管理

```
□ 环境变量与配置分离
□ 敏感配置使用 Secret
□ 配置有版本控制
□ 支持多环境部署（dev/staging/prod）
□ 部署脚本幂等
□ 回滚方案可用
```

---

## 五、运维可靠性审查清单

### 5.1 监控要求

```yaml
monitoring_requirements:
  # 基础设施监控
  infrastructure:
    - CPU使用率
    - 内存使用率
    - 磁盘使用率
    - 网络IO
    
  # 应用监控
  application:
    - 请求延迟（P50/P95/P99）
    - 错误率
    - QPS
    - 活跃连接数
    
  # 业务监控
  business:
    - 登录成功率
    - 注册成功率
    - API 调用成功率
    - Token 刷新成功率
    
  # 数据库监控
  database:
    - 连接池使用率
    - 查询延迟
    - 慢查询数量
    - 复制延迟（如果有）
```

### 5.2 告警要求

```yaml
alerting_requirements:
  # 关键告警
  critical:
    - 服务不可用
    - 错误率 > 5%
    - P99延迟 > 1s
    - 数据库连接池耗尽
    
  # 警告告警
  warning:
    - 错误率 > 1%
    - P95延迟 > 500ms
    - 磁盘使用率 > 80%
    - 内存使用率 > 85%
    
  # 通知渠道
  channels:
    - email: on_call_team
    - slack: ops-alerts
    - sms: critical_only
    
  # 告警升级
  escalation:
    - 5分钟未响应 → 升级
    - 15分钟未响应 → 升级到 manager
```

### 5.3 日志要求

```
□ 结构化日志（JSON）
□ 日志级别配置
□ 日志轮转配置
□ 敏感信息脱敏
□ 日志保留期配置（默认30天）
□ 集中式日志收集
□ 日志查询支持
```

### 5.4 备份与恢复

```yaml
backup_requirements:
  # 数据库备份
  database:
    frequency: daily
    retention: 30days
    verification: weekly
    encrypted: true
    offsite: true
    
  # 配置备份
  config:
    frequency: on_change
    storage: git
    
  # 文件备份
  files:
    frequency: weekly
    scope: uploads/
    
  # 恢复测试
  recovery_test:
    frequency: quarterly
    documented: true
```

---

## 六、文档规范性审查清单

### 6.1 API 文档

```yaml
api_documentation:
  # OpenAPI 规范
  openapi:
    version: "3.0.0"
    required: true
    generation: automated
    
  # 文档内容
  content:
    - 所有端点有描述
    - 所有参数有说明
    - 所有响应有示例
    - 错误码有说明
    - 认证方式有说明
    
  # 文档位置
  location:
    - swagger_ui: /swagger/index.html
    - openapi_json: /swagger/doc.json
    - redoc: /docs
```

### 6.2 部署文档

```
□ 部署前置条件清单
□ 部署步骤（分环境）
□ 环境变量说明
□ 依赖服务说明
□ 验证步骤
□ 回滚步骤
□ 常见问题与解决方案
```

### 6.3 运维文档

```
□ 系统架构图
□ 组件说明
□ 监控指标说明
□ 告警处理手册
□ 日志说明
□ 备份恢复手册
□ 扩容指南
□ 故障排查手册
□ 应急响应流程
```

### 6.4 Runbook 要求

```yaml
runbook_requirements:
  # 必需 Runbook
  required:
    - service_startup: 服务启动
    - service_shutdown: 服务停止
    - config_update: 配置更新
    - log_analysis: 日志分析
    - backup_restore: 备份恢复
    - incident_response: 事件响应
    - security_incident: 安全事件响应
    - scaling: 扩缩容
    - database_migration: 数据库迁移
    
  # Runbook 格式
  format:
    - 触发条件明确
    - 步骤清晰可执行
    - 验证步骤明确
    - 回滚步骤存在
    - 联系人明确
```

---

## 七、差距分析与行动计划

### 7.1 当前差距评估

| 维度 | 当前状态 | 目标状态 | 差距 | 优先级 |
|------|----------|----------|------|--------|
| 后端测试覆盖率 | 32.1% | 80% | -47.9% | 🔴 P0 |
| 前端测试覆盖率 | ~70% | 80% | -10% | 🟠 P1 |
| gosec 集成 | 未安装 | 集成CI | N/A | 🔴 P0 |
| JWT密钥占位符 | config.yaml | 环境变量 | N/A | 🔴 P0 |
| Docker健康检查 | 无 | 必须 | N/A | 🟠 P1 |
| K8s配置 | 无 | 必需 | N/A | 🟡 P2 |
| 备份自动化 | 手动 | 自动 | N/A | 🟠 P1 |
| 监控完善 | 基础 | 完整 | N/A | 🟡 P2 |
| Runbook | 缺失 | 必需 | N/A | 🟡 P2 |
| 渗透测试 | 无 | 季度 | N/A | 🟠 P1 |

### 7.2 修复行动计划

#### 🔴 P0 - 必须立即修复（本周）

| # | 任务 | 影响 | 工作量 |
|---|------|------|--------|
| 1 | 安装 gosec 并集成 CI | 安全扫描 | 2h |
| 2 | 移除 config.yaml 占位密钥，改为环境变量 | 生产安全 | 1h |
| 3 | 提升后端测试覆盖率至 60% | 代码质量 | 8h |
| 4 | Docker 添加 healthcheck | 部署可靠性 | 1h |

#### 🟠 P1 - 本周内完成

| # | 任务 | 影响 | 工作量 |
|---|------|------|--------|
| 5 | 后端覆盖率提升至 80% | 代码质量 | 16h |
| 6 | 前端覆盖率提升至 80% | 代码质量 | 8h |
| 7 | Docker 添加资源限制 | 运维可靠性 | 1h |
| 8 | 备份脚本自动化 | 运维可靠性 | 4h |
| 9 | 季度渗透测试计划 | 安全合规 | 2h |

#### 🟡 P2 - 本月完成

| # | 任务 | 影响 | 工作量 |
|---|------|------|--------|
| 10 | K8s Helm Chart | 部署简单性 | 16h |
| 11 | 完善监控指标 | 运维可靠性 | 8h |
| 12 | 告警配置验证 | 运维可靠性 | 4h |
| 13 | 核心 Runbook | 运维可靠性 | 8h |
| 14 | OpenAPI 规范完善 | 文档规范性 | 4h |

---

## 八、审查流程（v3.0）

### 8.1 PR 审查流程

```
┌─────────────────────────────────────────────────────────────────────┐
│                        PR 创建                                      │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  1. CI 门禁（自动）                                                  │
│     □ go vet / npm run lint                                          │
│     □ go build / npm run build                                       │
│     □ go test / npm test                                             │
│     □ 覆盖率检查（≥80%）                                              │
│     □ gosec / npm audit（安全扫描）                                   │
│     ⚠️ 任一失败 → PR Blocked                                        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  2. 人工审查（审查者）                                                │
│     □ 业务逻辑审查                                                    │
│     □ 安全审查                                                        │
│     □ 性能审查                                                        │
│     □ 可维护性审查                                                    │
│     □ 文档审查                                                        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  3. 问题修复（作者）                                                  │
│     🔴 P0 → 必须修复后重新审查                                        │
│     🟠 P1 → 必须修复后重新审查                                        │
│     🟡 P2 → 72小时内修复                                             │
│     🔵 P3 → 本周修复                                                 │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  4. 审查确认（审查者）                                                │
│     □ 所有 🔴🟠 已修复                                               │
│     □ 覆盖率达标                                                      │
│     □ 安全扫描通过                                                    │
│     □ Approve                                                          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│  5. 生产合并前检查                                                    │
│     □ E2E 测试通过                                                    │
│     □ 部署文档更新                                                    │
│     □ 变更日志记录                                                    │
│     □ 监控指标验证                                                    │
└─────────────────────────────────┴───────────────────────────────────┘
```

### 8.2 审查时效

| PR 类型 | 首次审查 | 问题修复复核 | 总时限 |
|---------|----------|------------|--------|
| 紧急修复 | 1小时 | 30分钟 | 4小时 |
| 常规功能 | 4小时 | 2小时 | 24小时 |
| 重构/优化 | 8小时 | 4小时 | 48小时 |
| P0修复 | 30分钟 | 15分钟 | 2小时 |

---

## 九、合规要求

### 9.1 安全合规

```yaml
security_compliance:
  # 数据保护
  data_protection:
    - GDPR合规（如果适用）
    - 数据加密存储
    - 数据传输加密
    - 数据访问审计
    
  # 访问控制
  access_control:
    - 最小权限原则
    - 密钥轮换
    - 多因素认证
    - 访问审计日志
    
  # 漏洞管理
  vulnerability_management:
    - 依赖扫描（每日）
    - 渗透测试（季度）
    - 漏洞修复 SLA（严重24h，高危7天）
```

### 9.2 运营合规

```yaml
operational_compliance:
  # 可用性
  availability:
    - SLO定义（99.9%）
    - SLA承诺（99.5%）
    - 错误预算监控
    
  # 备份
  backup:
    - 备份策略文档
    - 恢复测试记录
    - 备份保留策略
    
  # 事件管理
  incident_management:
    - 事件分级标准
    - 升级流程
    - 事后复盘要求
```

---

## 十、附录

### 10.1 快速检查命令

```bash
# 完整门禁检查（生产合并前必须）
#!/bin/bash
set -e

echo "=== 代码质量检查 ==="
go test ./... -count=1 -race
go tool cover -func coverage.out | grep total | awk '{print "Coverage:", $3}'

echo "=== 安全扫描 ==="
gosec ./...
npm audit
govulncheck ./...

echo "=== 构建检查 ==="
go build ./cmd/server
npm run build

echo "=== E2E 测试 ==="
npm run e2e:full:win

echo "=== 所有检查通过 ==="
```

### 10.2 评分计算器

```
综合评分 = 代码质量×0.25 + 安全强度×0.30 + 部署简单性×0.15 + 运维可靠性×0.20 + 文档规范性×0.10

生产标准：
- ≥9.0：卓越，可随时发布
- 8.0-8.9：优秀，可发布
- 7.0-7.9：良好，修复P2后发布
- 6.0-6.9：需要改进，修复P1后发布
- <6.0：不合格，修复P0后重新评估
```

---

*本文档由代码审查专家 Agent 生成*
*版本: v3.0*
*最后更新: 2026-04-08*
*下次审查: 2026-04-15*