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测试域名白名单
- 新增代码审查流程文档
This commit is contained in:
360
docs/code-review/CODE_REVIEW_PROCESS.md
Normal file
360
docs/code-review/CODE_REVIEW_PROCESS.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# 代码审查流程规范
|
||||
|
||||
**文档版本**: v1.0
|
||||
**生成日期**: 2026-04-08
|
||||
**适用范围**: User Management System (UMS) 项目
|
||||
|
||||
---
|
||||
|
||||
## 一、审查角色与职责
|
||||
|
||||
### 1.1 角色定义
|
||||
|
||||
| 角色 | 职责 | 要求 |
|
||||
|------|------|------|
|
||||
| **作者 (Author)** | 自审、修复问题、响应反馈 | 熟悉代码逻辑 |
|
||||
| **审查者 (Reviewer)** | 全面审查、标注问题、给出建议 | 了解业务和安全要求 |
|
||||
| **仲裁者 (Arbiter)** | 解决争议、最终决策 | 资深开发者/架构师 |
|
||||
|
||||
### 1.2 职责边界
|
||||
|
||||
**作者职责**：
|
||||
1. 提交前完成自审检查清单
|
||||
2. 确保代码可编译、可测试
|
||||
3. 及时响应审查反馈
|
||||
4. 修复问题时主动沟通
|
||||
|
||||
**审查者职责**：
|
||||
1. 按时完成审查（常规 4h 内）
|
||||
2. 提供具体、可操作的反馈
|
||||
3. 公平、一致地执行标准
|
||||
4. 记录审查结果
|
||||
|
||||
**仲裁者职责**：
|
||||
1. 解决审查争议
|
||||
2. 判定标准模糊地带
|
||||
3. 优化审查流程
|
||||
|
||||
---
|
||||
|
||||
## 二、审查触发条件
|
||||
|
||||
### 2.1 必须审查
|
||||
|
||||
| 条件 | 说明 |
|
||||
|------|------|
|
||||
| 所有 PR 到 main | 任何合入 main 的代码必须审查 |
|
||||
| 安全相关变更 | 认证、授权、加密相关 |
|
||||
| 基础设施变更 | 配置、部署、CI/CD |
|
||||
| 数据库 schema 变更 | 迁移文件 |
|
||||
|
||||
### 2.2 简化审查（可选）
|
||||
|
||||
| 条件 | 说明 |
|
||||
|------|------|
|
||||
| 文档更新 | *.md 文件 |
|
||||
| 测试用例补充 | 仅新增测试 |
|
||||
| 依赖更新 | 无代码变更 |
|
||||
| 配置调整 | 明确无风险 |
|
||||
|
||||
---
|
||||
|
||||
## 三、审查执行流程
|
||||
|
||||
### 3.1 阶段一：准备工作
|
||||
|
||||
```
|
||||
审查者接收 PR 后：
|
||||
1. 阅读 PR 描述，理解变更目的
|
||||
2. 查看关联的 Issue/Ticket
|
||||
3. 确认影响范围
|
||||
4. 准备审查清单
|
||||
```
|
||||
|
||||
### 3.2 阶段二：自动化检查
|
||||
|
||||
```bash
|
||||
# 后端检查
|
||||
go vet ./...
|
||||
go build ./cmd/server
|
||||
go test ./... -count=1
|
||||
gosec ./... # 安全扫描
|
||||
|
||||
# 前端检查
|
||||
npm run lint
|
||||
npm run build
|
||||
npm test
|
||||
npm audit
|
||||
|
||||
# 覆盖率检查
|
||||
go test -coverprofile=coverage.out
|
||||
go tool cover -func=coverage.out | tail -1
|
||||
```
|
||||
|
||||
### 3.3 阶段三：代码审查
|
||||
|
||||
#### 审查顺序（建议）
|
||||
|
||||
1. **接口/API 层** - 先看暴露的接口是否合理
|
||||
2. **业务逻辑层** - 核心逻辑实现
|
||||
3. **数据访问层** - 数据库操作
|
||||
4. **基础设施** - 错误处理、日志
|
||||
5. **测试** - 覆盖率、有效性
|
||||
|
||||
#### 审查要点
|
||||
|
||||
**文件维度**：
|
||||
- [ ] 新增文件是否必要
|
||||
- [ ] 删除文件是否安全
|
||||
- [ ] 修改文件是否最小化
|
||||
|
||||
**安全维度**：
|
||||
- [ ] 输入验证
|
||||
- [ ] 权限检查
|
||||
- [ ] 敏感数据处理
|
||||
- [ ] 加密实现
|
||||
|
||||
**正确性维度**：
|
||||
- [ ] 逻辑正确
|
||||
- [ ] 边界处理
|
||||
- [ ] 错误处理
|
||||
- [ ] 并发安全
|
||||
|
||||
**性能维度**：
|
||||
- [ ] 数据库查询
|
||||
- [ ] 缓存使用
|
||||
- [ ] 资源释放
|
||||
|
||||
### 3.4 阶段四：反馈与修复
|
||||
|
||||
#### 评论格式
|
||||
|
||||
```markdown
|
||||
🔴 **[级别] 问题标题**
|
||||
位置: `file.go:42`
|
||||
|
||||
**问题描述**：
|
||||
[清晰描述问题]
|
||||
|
||||
**为什么这是个问题**：
|
||||
[解释风险或影响]
|
||||
|
||||
**建议修复**：
|
||||
```code
|
||||
// 建议的代码
|
||||
```
|
||||
---
|
||||
|
||||
🟠 **[级别] 问题标题**
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
🟡 **[级别] 问题标题**
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
💭 **[挑剔] 可选优化**
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
✅ **做得好的地方**
|
||||
[具体表扬]
|
||||
```
|
||||
|
||||
#### 修复确认
|
||||
|
||||
| 问题级别 | 修复要求 | 确认方式 |
|
||||
|----------|----------|----------|
|
||||
| 🔴 | 必须修复 | 重新审查 |
|
||||
| 🟠 | 必须修复 | 截图确认或重新审查 |
|
||||
| 🟡 | 建议修复 | 修复后标注或提供理由 |
|
||||
| 💭 | 可选 | 可忽略，提供理由即可 |
|
||||
|
||||
### 3.5 阶段五：完成审查
|
||||
|
||||
#### Approve 条件
|
||||
|
||||
```
|
||||
□ 所有 🔴🟠 问题已修复
|
||||
□ 🟡 问题 ≤ 3 个或有明确修复计划
|
||||
□ 覆盖率不下降 > 5%
|
||||
□ 审查者确认理解变更
|
||||
```
|
||||
|
||||
#### 评论模板
|
||||
|
||||
```markdown
|
||||
## 审查结论
|
||||
|
||||
✅ **可以合并**
|
||||
|
||||
**评分**: X.X/10
|
||||
|
||||
**亮点**:
|
||||
- [1]
|
||||
- [2]
|
||||
|
||||
**遗留问题**:
|
||||
- [1] (P1, @负责人)
|
||||
- [2] (P2, @负责人)
|
||||
|
||||
**后续关注**:
|
||||
- [建议后续优化项]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、审查时效管理
|
||||
|
||||
### 4.1 SLA 要求
|
||||
|
||||
| PR 优先级 | 首次审查 | 修复后复核 | 最大周期 |
|
||||
|-----------|----------|------------|----------|
|
||||
| P0 (安全/紧急) | 1 小时 | 30 分钟 | 4 小时 |
|
||||
| P1 (重要) | 4 小时 | 1 小时 | 24 小时 |
|
||||
| P2 (常规) | 8 小时 | 2 小时 | 48 小时 |
|
||||
| P3 (优化) | 24 小时 | 4 小时 | 72 小时 |
|
||||
|
||||
### 4.2 超时处理
|
||||
|
||||
```
|
||||
1. 超过 SLA 50% → 提醒（@审查者）
|
||||
2. 超过 SLA 100% → 升级（@Tech Lead）
|
||||
3. 超过 3 天无响应 → 仲裁者介入
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、争议解决
|
||||
|
||||
### 5.1 常见争议场景
|
||||
|
||||
| 场景 | 解决方式 |
|
||||
|------|----------|
|
||||
| 问题级别判定分歧 | 参照分级标准，模糊取高 |
|
||||
| 是否必须修复 | 审查者决定，仲裁者终裁 |
|
||||
| 代码风格偏好 | 参考规范，无标准则接受 |
|
||||
| 性能优化必要性 | 量化数据支持 |
|
||||
|
||||
### 5.2 仲裁流程
|
||||
|
||||
```
|
||||
1. 作者提出仲裁请求
|
||||
2. 审查者陈述理由
|
||||
3. 仲裁者审查双方观点
|
||||
4. 仲裁者做出最终决定
|
||||
5. 记录仲裁结果（供后续参考）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、审查质量保证
|
||||
|
||||
### 6.1 审查者自我检查
|
||||
|
||||
```
|
||||
审查前：
|
||||
□ 我理解这次变更的目的吗？
|
||||
□ 我知道如何验证这些变更吗？
|
||||
|
||||
审查中：
|
||||
□ 我是否检查了所有相关文件？
|
||||
□ 我的反馈是否具体且可操作？
|
||||
□ 我的反馈是否公平、一致？
|
||||
|
||||
审查后：
|
||||
□ 我的评分是否合理？
|
||||
□ 我的反馈是否有教育价值？
|
||||
```
|
||||
|
||||
### 6.2 审查质量指标
|
||||
|
||||
| 指标 | 定义 | 目标 |
|
||||
|------|------|------|
|
||||
| 审查一致性 | 同类问题的判定一致率 | > 90% |
|
||||
| 反馈质量 | 作者满意度评分 | > 4.0/5 |
|
||||
| 审查效率 | 平均审查时间 | < 4h |
|
||||
| 缺陷逃逸率 | 合并后发现的问题数 | < 2/版本 |
|
||||
|
||||
---
|
||||
|
||||
## 七、特殊场景处理
|
||||
|
||||
### 7.1 大型 PR
|
||||
|
||||
```
|
||||
当 PR > 500 行变更时：
|
||||
1. 请求作者拆分为多个 PR
|
||||
2. 或分批审查（核心逻辑优先）
|
||||
3. 明确标记哪些部分已审查
|
||||
4. 剩余部分安排后续审查
|
||||
```
|
||||
|
||||
### 7.2 紧急修复
|
||||
|
||||
```
|
||||
当生产环境需要紧急修复时：
|
||||
1. 允许先合并后审查（需要 Tech Lead 批准）
|
||||
2. 24 小时内完成审查
|
||||
3. 发现问题立即发版修复
|
||||
4. 事后复盘，总结经验
|
||||
```
|
||||
|
||||
### 7.3 外部贡献
|
||||
|
||||
```
|
||||
当接收外部 PR 时：
|
||||
1. 所有审查标准相同
|
||||
2. 增加许可证检查
|
||||
3. 增加贡献协议确认
|
||||
4. 必要时要求补充签名
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、审查记录归档
|
||||
|
||||
### 8.1 归档内容
|
||||
|
||||
| 内容 | 位置 | 保存期限 |
|
||||
|------|------|----------|
|
||||
| PR 审查评论 | GitHub PR | 永久 |
|
||||
| 审查报告 | `docs/code-review/` | 永久 |
|
||||
| 争议解决记录 | `docs/team/disputes.md` | 永久 |
|
||||
| 审查指标汇总 | `docs/team/metrics/` | 1 年 |
|
||||
|
||||
### 8.2 报告生成
|
||||
|
||||
每次全面审查后生成报告：
|
||||
```
|
||||
docs/code-review/CODE_REVIEW_REPORT_YYYY-MM-DD.md
|
||||
```
|
||||
|
||||
报告模板见 `CODE_REVIEW_STANDARD_V2.md` 第 7 节。
|
||||
|
||||
---
|
||||
|
||||
## 九、持续改进
|
||||
|
||||
### 9.1 流程回顾
|
||||
|
||||
| 周期 | 内容 | 负责人 |
|
||||
|------|------|--------|
|
||||
| 每月 | 审查效率分析 | Tech Lead |
|
||||
| 每季度 | 流程优化讨论 | Team |
|
||||
| 每半年 | 规范更新 | 代码审查专家 |
|
||||
|
||||
### 9.2 改进建议
|
||||
|
||||
团队成员可以通过以下方式提出改进建议：
|
||||
1. 在 `docs/team/improvements/` 创建提案
|
||||
2. 在 Team Meeting 中讨论
|
||||
3. PR 到本文档
|
||||
|
||||
---
|
||||
|
||||
*本文档由代码审查专家 Agent 制定，版本: v1.0*
|
||||
*最后更新: 2026-04-08*
|
||||
Reference in New Issue
Block a user