fix: 统一API响应格式并修复前端测试

- 所有Handler方法使用标准{code:0,message:"success",data:...}响应格式 - 修复Cursor分页响应包装(GetAllDevices,GetLoginLogs,ListUsers等) - 修复AuthHandler和SMSHandler认证方法响应格式 - 修复operation_log.go admin用户operation_type前缀问题 - 修复DashboardPage嵌套stats结构 - 修复LoginLogsPage reset功能stale closure问题 - 修复UsersPage批量操作API调用 - 修复多个前端测试(mock格式、按钮选择、断言逻辑) - 添加OAuth测试域名白名单 - 新增代码审查流程文档
2026-04-08 20:06:54 +08:00
parent 26c5def4d7
commit a85d822419
33 changed files with 2108 additions and 206 deletions
--- a/docs/code-review/CODE_REVIEW_STANDARD_V2.md
+++ b/docs/code-review/CODE_REVIEW_STANDARD_V2.md
@@ -0,0 +1,488 @@
+# 代码审查标准与质量评级规范 v2.0
+
+**文档版本**: v2.0
+**生成日期**: 2026-04-08
+**适用范围**: User Management System (UMS) 项目
+**审查专家**: 代码审查专家
+
+---
+
+## 一、审查目标与原则
+
+### 1.1 核心目标
+
+建立**可量化、可执行、可追踪**的代码审查机制，确保：
+- 代码质量持续达标
+- 安全漏洞零容忍
+- 技术债可控增长
+- 团队能力持续提升
+
+### 1.2 审查原则
+
+| 原则 | 说明 |
+|------|------|
+| **事实优先** | 审查结论必须有代码证据，不基于猜测 |
+| **分级治理** | 不同严重程度的问题差异化处理 |
+| **教育导向** | 每条审查意见都应教会开发者一些东西 |
+| **持续改进** | 每次审查沉淀经验，完善规范 |
+
+---
+
+## 二、质量评级体系
+
+### 2.1 代码评分维度
+
+| 维度 | 权重 | 评分标准 | 工具支持 |
+|------|------|----------|----------|
+| **安全性** | 30% | 0-10 | 人工审查 + gosec |
+| **正确性** | 25% | 0-10 | go vet + 单元测试 |
+| **可维护性** | 20% | 0-10 | 人工审查 |
+| **性能** | 15% | 0-10 | 人工审查 + 基准测试 |
+| **测试覆盖** | 10% | 0-10 | go test coverage |
+
+### 2.2 综合评分公式
+
+```
+综合评分 = 安全性×0.30 + 正确性×0.25 + 可维护性×0.20 + 性能×0.15 + 测试覆盖×0.10
+```
+
+### 2.3 评级标准
+
+| 评分区间 | 评级 | 行动 |
+|----------|------|------|
+| **9.0-10.0** | 🏆 卓越 | 可合并，记录亮点 |
+| **8.0-8.9** | ✅ 优秀 | 可合并，有改进空间 |
+| **7.0-7.9** | ⚠️ 良好 | 建议修复后合并 |
+| **6.0-6.9** | 🔶 需要改进 | 必须修复🟡问题后合并 |
+| **< 6.0** | 🔴 不合格 | 必须修复所有🟡问题，审查员确认后合并 |
+
+---
+
+## 三、问题分级标准
+
+### 3.1 分级定义
+
+| 级别 | 标识 | 定义 | 合并影响 |
+|------|------|------|----------|
+| **阻塞** | 🔴 | 安全漏洞、数据丢失风险、编译失败 | **必须修复**，否则禁止合并 |
+| **严重** | 🟠 | 功能错误、严重性能问题、错误处理缺失 | **必须修复**，否则禁止合并 |
+| **建议** | 🟡 | 代码重复、轻微性能问题、可维护性改进 | 建议修复，🟡≤3可合并 |
+| **挑剔** | 💭 | 代码风格、命名优化、注释改进 | 鼓励修复，不阻塞合并 |
+
+### 3.2 阻塞级问题清单（必须修复）
+
+#### 安全类 🔴
+
+| ID | 规则 | 检查方法 |
+|----|------|----------|
+| SEC-B01 | SQL 注入 | 参数化查询验证 |
+| SEC-B02 | XSS 漏洞 | 输出编码验证 |
+| SEC-B03 | 认证绕过 | 权限中间件验证 |
+| SEC-B04 | 敏感数据泄露 | 日志/响应审查 |
+| SEC-B05 | 不安全随机数 | crypto/rand 使用验证 |
+| SEC-B06 | 硬编码密钥 | 密钥扫描 |
+| SEC-B07 | 密码明文存储 | 哈希算法验证 |
+
+#### 正确性类 🔴
+
+| ID | 规则 | 检查方法 |
+|----|------|----------|
+| CORR-B01 | 编译失败 | `go build` 验证 |
+| CORR-B02 | 单元测试失败 | `go test` 验证 |
+| CORR-B03 | 竞态条件 | 并发代码审查 |
+| CORR-B04 | 资源泄漏 | defer/cleanup 审查 |
+| CORR-B05 | 错误被忽略 | `_ = err` 扫描 |
+
+### 3.3 严重级问题清单（必须修复）
+
+| ID | 规则 | 检查方法 |
+|----|------|----------|
+| SEV-01 | N+1 查询 | Repository 调用链审查 |
+| SEV-02 | Goroutine 泄漏 | context 使用审查 |
+| SEV-03 | 无超时控制 | HTTP/DB 超时审查 |
+| SEV-04 | 错误处理不当 | 错误传播审查 |
+| SEV-05 | 事务边界错误 | 事务代码审查 |
+
+---
+
+## 四、模块化审查清单
+
+### 4.1 认证模块审查
+
+```
+□ 密码哈希使用 Argon2id 或 bcrypt
+□ 密码哈希使用 crypto/rand 生成盐
+□ Token 使用 crypto/rand 生成
+□ JTI 支持黑名单/轮换
+□ 刷新令牌有滚动机制
+□ 登录尝试有速率限制
+□ 错误信息不泄露用户存在性
+□ 会话超时配置合理
+□ 退出登录正确清理状态
+□ 敏感操作需要二次验证
+```
+
+### 4.2 API 路由审查
+
+```
+□ 所有受保护路由有权限中间件
+□ 输入验证使用 binding:"required"
+□ 参数化查询防 SQL 注入
+□ 响应不包含敏感字段
+□ 错误响应不泄露内部信息
+□ CSRF 保护配置正确
+□ CORS 配置非 wildcard
+□ 限流中间件覆盖
+```
+
+### 4.3 数据库操作审查
+
+```
+□ 使用 GORM 参数化查询
+□ 索引覆盖常用查询条件
+□ 无 N+1 查询模式
+□ 事务边界正确
+□ 连接池配置合理
+□ 批量操作有分页限制
+□ LIKE 查询有转义处理
+□ 软删除/硬删除策略明确
+```
+
+### 4.4 并发安全审查
+
+```
+□ 共享 map 使用 RWMutex
+□ goroutine 有 context 控制
+□ 无 context.Background() 滥用
+□ 资源在 defer 释放
+□ 无数据竞争（go test -race）
+□ 原子操作使用 sync/atomic
+```
+
+### 4.5 前端安全审查
+
+```
+□ access_token 仅存内存
+□ refresh_token 用 HttpOnly Cookie
+□ XSS 防护：用户输入转义
+□ CSRF：状态变更请求带 token
+□ 敏感数据不存 localStorage
+□ API 错误不直接展示给用户
+□ 路由守卫正确配置
+□ 退出清理完整（内存+Cookie）
+```
+
+---
+
+## 五、自动化检查配置
+
+### 5.1 Go 后端配置
+
+```yaml
+# .golangci.yml
+linters:
+  enable:
+    - gosec       # 安全扫描
+    - govet       # 代码诊断
+    - gocyclo     # 圈复杂度（>15 报警）
+    - revive      # 代码风格
+    - unused      # 未使用代码
+    - staticcheck # 静态分析
+    - structcheck # 结构体检查
+    - errcheck    # 错误检查
+
+linters-settings:
+  gosec:
+    excludes:
+      - G104  # Audit errors not checked
+  gocyclo:
+    min-complexity: 15
+  revive:
+    rules:
+      - name: blank-imports
+      - name: context-as-argument
+      - name: context-keys-type
+      - name: dot-imports
+      - name: error-return
+      - name: error-strings
+      - name: error-naming
+      - name: exported
+      - name: increment-decrement
+      - name: var-naming
+      - name: var-declaration
+      - name: package-comments
+      - name: range
+      - name: receiver-naming
+      - name: time-naming
+```
+
+### 5.2 前端配置
+
+```javascript
+// .eslintrc.js (关键规则)
+rules: {
+  // 安全
+  'no-eval': 'error',
+  'no-implied-eval': 'error',
+  'no-new-func': 'error',
+  
+  // 最佳实践
+  'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
+  'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
+  
+  // TypeScript
+  '@typescript-eslint/no-explicit-any': 'warn',
+  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  
+  // React
+  'react-hooks/exhaustive-deps': 'warn',
+  'react/no-direct-mutation-state': 'error',
+}
+```
+
+---
+
+## 六、审查流程
+
+### 6.1 提交前自审（开发者）
+
+```bash
+# 后端
+go vet ./...
+go build ./cmd/server
+go test ./... -count=1
+go test -race ./...  # 竞态检测
+
+# 前端
+npm run lint
+npm run build
+npm test -- --coverage
+```
+
+### 6.2 PR 审查流程
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        PR 创建                                     │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  1. CI 检查                                                         │
+│     □ go build / npm run build                                     │
+│     □ go test / npm test                                           │
+│     □ go vet / npm run lint                                        │
+│     □ 覆盖率不下降                                                  │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  2. 人工审查（审查者）                                               │
+│     □ 逐文件审查关键代码                                             │
+│     □ 执行模块化审查清单                                             │
+│     □ 标注问题并分级                                                 │
+│     □ 给出修复建议                                                   │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  3. 问题修复（作者）                                                 │
+│     🔴 → 必须修复后重新审查                                          │
+│     🟠 → 必须修复后重新审查                                          │
+│     🟡 → 修复后标注或忽略（有理由）                                   │
+│     💭 → 可忽略，有理由即可                                          │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  4. 审查确认（审查者）                                               │
+│     □ 所有 🔴🟠 已修复                                               │
+│     □ 🟡 ≤ 3 个且有修复计划                                          │
+│     □ 综合评分 ≥ 7.0                                                 │
+│     □ Approve                                                         │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  5. 合并                                                              │
+│     □ Squash merge 到 main                                          │
+│     □ 删除源分支                                                      │
+│     □ 更新相关文档                                                    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 6.3 审查时效要求
+
+| PR 类型 | 首次审查 | 问题修复后复核 | 总时限 |
+|---------|----------|----------------|--------|
+| 紧急修复 | 1 小时 | 30 分钟 | 4 小时 |
+| 常规功能 | 4 小时 | 1 小时 | 24 小时 |
+| 重构/优化 | 8 小时 | 2 小时 | 48 小时 |
+
+---
+
+## 七、审查报告规范
+
+### 7.1 报告模板
+
+```markdown
+# 代码审查报告
+
+**PR**: #[编号] [标题]
+**作者**: [姓名]
+**审查者**: [姓名]
+**日期**: YYYY-MM-DD
+**综合评分**: X.X/10 ([评级])
+
+---
+
+## 执行摘要
+
+[2-3 句话总结代码质量]
+
+## 检查清单执行
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| go vet | ✅/❌ |  |
+| go build | ✅/❌ |  |
+| go test | ✅/❌ |  |
+| 覆盖率 | X% |  |
+| 安全审查 | ✅/❌ |  |
+| ... | ... |  |
+
+## 问题清单
+
+### 🔴 阻塞 (X 个)
+
+| # | 问题 | 位置 | 修复状态 |
+|---|------|------|----------|
+| 1 |  |  | 已修复/未修复 |
+
+### 🟠 严重 (X 个)
+
+...
+
+### 🟡 建议 (X 个)
+
+...
+
+### 💭 挑剔 (X 个)
+
+...
+
+## 做得好的地方
+
+- [亮点1]
+- [亮点2]
+
+## 修复建议优先级
+
+| 优先级 | 问题数 | 行动 |
+|--------|--------|------|
+| P0 (立即) | X |  |
+| P1 (今天) | X |  |
+| P2 (本周) | X |  |
+
+## 审查结论
+
+✅ **可以合并** / ❌ **需要修改后重新审查**
+
+---
+
+签名: __________ 日期: __________
+```
+
+### 7.2 问题追踪
+
+```yaml
+# .github/ISSUE_TEMPLATE/code_review.yml
+name: Code Review Issue
+description: 追踪代码审查中发现的问题
+labels: [code-review, security, bug, improvement]
+```
+
+---
+
+## 八、质量门禁
+
+### 8.1 合并门禁（必须全部通过）
+
+| 检查项 | 标准 | 命令 |
+|--------|------|------|
+| 编译 | 成功 | `go build ./...` / `npm run build` |
+| 单元测试 | 100% 通过 | `go test ./... -count=1` |
+| Lint | 无 error | `go vet` / `npm run lint` |
+| 覆盖率 | 不下降 | `go test -coverprofile` |
+| 安全扫描 | 无高危漏洞 | `gosec ./...` |
+
+### 8.2 代码扫描工具
+
+```bash
+# Go 安全扫描
+gosec ./...
+
+# 前端安全扫描
+npm audit --audit-level=moderate
+
+# 依赖漏洞检查
+go mod verify
+npm outdated
+```
+
+---
+
+## 九、持续改进机制
+
+### 9.1 审查指标
+
+| 指标 | 目标 | 当前值 | 趋势 |
+|------|------|--------|------|
+| 平均审查时间 | < 8h | - | - |
+| 首次通过率 | > 60% | - | - |
+| 阻塞问题数/版本 | < 2 | - | - |
+| 代码覆盖率 | > 80% | - | - |
+
+### 9.2 审查知识库
+
+每次审查后：
+1. 记录新的反模式 → `docs/security/anti-patterns.md`
+2. 记录性能优化案例 → `docs/performance/case-studies.md`
+3. 更新检查清单 → `docs/checklists/`
+
+### 9.3 定期回顾
+
+| 周期 | 内容 | 负责人 |
+|------|------|--------|
+| 每 PR | 审查报告归档 | 审查者 |
+| 每周 | 审查指标汇总 | Tech Lead |
+| 每月 | 规范更新、工具升级 | 代码审查专家 |
+| 每季度 | 全面审查、流程优化 | Team |
+
+---
+
+## 十、附录
+
+### 10.1 快速检查命令
+
+```bash
+# 后端完整检查
+go vet ./... && go build ./cmd/server && go test ./... -count=1 -race
+
+# 前端完整检查
+cd frontend/admin && npm run lint && npm run build && npm test -- --coverage
+
+# E2E 测试
+cd frontend/admin && npm run e2e:full:win
+
+# 安全扫描
+gosec ./...
+npm audit
+```
+
+### 10.2 参考资料
+
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+- [Google Engineering Practices](https://google.github.io/eng-practices/)
+- [Security Code Review Checklist (OWASP)](https://owasp.org/www-pdf-archive/OWASP_Code_Review_Guide_v2.pdf)
+
+---
+
+*本文档由代码审查专家 Agent 制定并维护，版本: v2.0*
+*最后更新: 2026-04-08*