381 lines
8.8 KiB
Markdown
381 lines
8.8 KiB
Markdown
# 前后端联调评审实施指南
|
||
|
||
**版本**: v1.0
|
||
**生效日期**: 2026-04-02
|
||
**状态**: ✅ 已启用
|
||
|
||
---
|
||
|
||
## 1. 实施范围
|
||
|
||
本文档指导如何将前后端联调评审流程应用到当前开发流程中。
|
||
|
||
---
|
||
|
||
## 2. 立即生效的评审流程
|
||
|
||
### 2.1 每个联调任务必须执行的步骤
|
||
|
||
#### 第一步: API 接口评审（开发前）
|
||
|
||
**负责人**: 后端负责人
|
||
**时间**: 功能开发前 1-2 天
|
||
|
||
**检查清单** (基于 `docs/checklists/FRONTEND_BACKEND_CHECKLIST.md`):
|
||
- [ ] API 路径符合 RESTful 规范
|
||
- [ ] 请求参数命名符合规范（后端 snake_case）
|
||
- [ ] 响应格式统一
|
||
- [ ] 错误码定义清晰
|
||
- [ ] 分页参数统一
|
||
- [ ] 权限控制明确
|
||
|
||
**输出**: API 接口设计文档（Swagger/OpenAPI 或手动文档）
|
||
|
||
#### 第二步: 数据模型评审（开发前）
|
||
|
||
**负责人**: 后端负责人 + 前端负责人
|
||
**时间**: 功能开发前 1 天
|
||
|
||
**检查清单**:
|
||
- [ ] 前后端数据结构一致
|
||
- [ ] 字段命名统一约定
|
||
- [ ] 数据类型匹配
|
||
- [ ] 可选字段/必填字段明确
|
||
- [ ] 枚举值定义一致
|
||
|
||
**输出**: 数据模型定义文档
|
||
|
||
#### 第三步: 联调问题评审（开发中期）
|
||
|
||
**负责人**: 前端负责人 + 后端负责人
|
||
**时间**: Sprint 中期（第 3-4 天）
|
||
|
||
**检查清单**:
|
||
- [ ] 联调中发现的问题已记录
|
||
- [ ] 问题严重程度已分级（P0/P1/P2/P3）
|
||
- [ ] 解决方案已确定
|
||
- [ ] 负责人和解决时间表已明确
|
||
|
||
**输出**: 联调问题列表和解决方案
|
||
|
||
#### 第四步: 上线前评审（Sprint 结束）
|
||
|
||
**负责人**: 测试工程师 + 技术负责人
|
||
**时间**: 上线前 1 天
|
||
|
||
**检查清单**:
|
||
- [ ] 联调测试报告已提交
|
||
- [ ] 所有 P0/P1 问题已解决
|
||
- [ ] 测试通过率 ≥ 95%
|
||
- [ ] 性能指标达标
|
||
- [ ] 安全测试通过
|
||
|
||
**输出**: 上线决策（通过/不通过/条件通过）
|
||
|
||
---
|
||
|
||
## 3. 评审模板
|
||
|
||
### 3.1 API 接口评审记录模板
|
||
|
||
```markdown
|
||
# API 接口评审记录
|
||
|
||
**评审日期**: YYYY-MM-DD
|
||
**评审人员**: ...
|
||
**功能模块**: ...
|
||
|
||
## 评审结果
|
||
- 通过 / 不通过 / 条件通过
|
||
|
||
## 问题列表
|
||
| ID | 问题 | 严重程度 | 负责人 | 解决方案 | 状态 |
|
||
|----|------|---------|--------|---------|------|
|
||
| API-001 | 参数命名不一致 | P2 | 张三 | 统一使用 snake_case | 已解决 |
|
||
```
|
||
|
||
### 3.2 联调测试记录模板
|
||
|
||
```markdown
|
||
# 联调测试记录
|
||
|
||
**测试日期**: YYYY-MM-DD
|
||
**测试人员**: ...
|
||
**功能模块**: ...
|
||
|
||
## 测试结果
|
||
- 测试用例数: X
|
||
- 通过: Y
|
||
- 失败: Z
|
||
- 通过率: N%
|
||
|
||
## 失败用例列表
|
||
| 用例ID | 问题描述 | 严重程度 | 负责人 | 状态 |
|
||
|--------|---------|---------|--------|------|
|
||
| TC-001 | 用户列表分页不工作 | P1 | 李四 | 修复分页参数 | 待修复 |
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 当前项目的应用规范
|
||
|
||
### 4.1 接口命名规范
|
||
|
||
**后端（Go）**:
|
||
- 路径: 使用小写字母和下划线 `/api/v1/user_management/users`
|
||
- 参数: 使用 snake_case `user_name`, `created_at`
|
||
- 响应字段: 使用 snake_case `user_id`, `user_name`, `created_at`
|
||
|
||
**前端（React/TypeScript）**:
|
||
- API 调用: 统一使用 `lib/http/client.ts`
|
||
- 参数: 使用 camelCase（发送前转换）
|
||
- 响应字段: 使用 camelCase（接收后转换）
|
||
|
||
### 4.2 接口分类
|
||
|
||
**用户管理**:
|
||
- `GET /api/v1/users` - 获取用户列表（分页）
|
||
- `POST /api/v1/users` - 创建用户
|
||
- `GET /api/v1/users/:id` - 获取用户详情
|
||
- `PUT /api/v1/users/:id` - 更新用户
|
||
- `DELETE /api/v1/users/:id` - 删除用户
|
||
|
||
**角色管理**:
|
||
- `GET /api/v1/roles` - 获取角色列表
|
||
- `POST /api/v1/roles` - 创建角色
|
||
- `GET /api/v1/roles/:id` - 获取角色详情
|
||
- `PUT /api/v1/roles/:id` - 更新角色
|
||
- `DELETE /api/v1/roles/:id` - 删除角色
|
||
|
||
**权限管理**:
|
||
- `GET /api/v1/permissions` - 获取权限列表
|
||
- `GET /api/v1/permissions/tree` - 获取权限树
|
||
|
||
**认证授权**:
|
||
- `POST /api/v1/auth/login` - 登录
|
||
- `POST /api/v1/auth/logout` - 登出
|
||
- `GET /api/v1/auth/userinfo` - 获取当前用户信息
|
||
- `GET /api/v1/auth/csrf-token` - 获取 CSRF Token
|
||
|
||
### 4.3 响应格式规范
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"items": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 40001,
|
||
"message": "参数错误",
|
||
"details": {
|
||
"field": "user_name",
|
||
"error": "用户名不能为空"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码定义**:
|
||
- `0`: 成功
|
||
- `40001`: 参数错误
|
||
- `40003`: 参数验证失败
|
||
- `40100`: 未认证
|
||
- `40300`: 权限不足
|
||
- `40400`: 资源不存在
|
||
- `50000`: 服务器内部错误
|
||
|
||
---
|
||
|
||
## 5. 联调检查要点
|
||
|
||
### 5.1 当前项目重点检查项
|
||
|
||
基于项目现状，以下是需要重点关注的联调检查项：
|
||
|
||
#### P1 必须修复（立即处理）
|
||
- [ ] `ValidateRecoveryCode` 时序泄漏 ✅ 已修复（2026-04-01）
|
||
- [ ] 前后端数据结构不一致问题
|
||
- [ ] 权限检查不完整问题
|
||
|
||
#### P2 建议修复（本周处理）
|
||
- [ ] N+5 查询问题（统计接口）
|
||
- [ ] SlidingWindowLimiter 清理死代码
|
||
- [ ] recordDelivery 使用 context.Background
|
||
|
||
#### P3 可选优化（下 Sprint 处理）
|
||
- [ ] 原生 SQL 使用规范
|
||
- [ ] 正则表达式预编译
|
||
- [ ] 状态管理优化
|
||
|
||
### 5.2 设计断链问题
|
||
|
||
基于 `docs/code-review/PRD_GAP_DESIGN_PLAN.md`，以下设计断链需要重点关注：
|
||
|
||
**P0 严重断链（7个）**:
|
||
- GAP-FE-001: 管理员管理页（前端缺失）
|
||
- GAP-FE-002: 系统设置页（前端缺失）
|
||
- GAP-FE-003: 全局设备管理页（前端缺失）
|
||
- GAP-FE-004: 登录日志导出（前端缺失）
|
||
- GAP-BE-001: 系统设置API（后端缺失）
|
||
- GAP-INT-001: 设备信任检查（接线缺失）
|
||
- GAP-INT-002: 角色继承权限（接线缺失）⚠️ 已确认已实现
|
||
|
||
**P1 中等断链（3个）**:
|
||
- GAP-FE-005: 批量操作（前端缺失）
|
||
- GAP-INT-003: 异常检测接入（接线缺失）
|
||
- GAP-INT-004: 密码历史记录检查（接线缺失）⚠️ 已确认已实现
|
||
|
||
**P2 轻微断链（2个）**:
|
||
- GAP-INT-005: IP地理位置解析（接线缺失）
|
||
- GAP-INT-006: 设备指纹采集（接线缺失）
|
||
|
||
---
|
||
|
||
## 6. 评审流程执行检查清单
|
||
|
||
### 6.1 每个联调任务启动前
|
||
|
||
- [ ] 已阅读 `docs/processes/FRONTEND_BACKEND_REVIEW.md`
|
||
- [ ] 已阅读 `docs/checklists/FRONTEND_BACKEND_CHECKLIST.md`
|
||
- [ ] 已确认 API 接口设计文档
|
||
- [ ] 已确认数据模型定义
|
||
- [ ] 已明确负责人和时间表
|
||
|
||
### 6.2 每个联调任务进行中
|
||
|
||
- [ ] 已定期进行联调问题评审
|
||
- [ ] 已记录所有发现的问题
|
||
- [ ] 已对问题进行分级
|
||
- [ ] 已确定解决方案和时间表
|
||
|
||
### 6.3 每个联调任务结束前
|
||
|
||
- [ ] 已完成所有 P0/P1 问题修复
|
||
- [ ] 已完成联调测试
|
||
- [ ] 已通过上线前评审
|
||
- [ ] 已更新相关文档
|
||
|
||
---
|
||
|
||
## 7. 工具和命令
|
||
|
||
### 7.1 后端验证
|
||
|
||
```bash
|
||
# 运行测试
|
||
cd d:/project && go test ./... -count=1
|
||
|
||
# 代码检查
|
||
cd d:/project && go vet ./...
|
||
|
||
# 编译检查
|
||
cd d:/project && go build ./cmd/server
|
||
```
|
||
|
||
### 7.2 前端验证
|
||
|
||
```bash
|
||
# 运行测试
|
||
cd frontend/admin && npm test
|
||
|
||
# Lint 检查
|
||
cd frontend/admin && npm run lint
|
||
|
||
# 构建检查
|
||
cd frontend/admin && npm run build
|
||
|
||
# E2E 测试
|
||
cd frontend/admin && npm run e2e:full:win
|
||
```
|
||
|
||
### 7.3 文档检查
|
||
|
||
- [ ] API 文档已更新（如有变更）
|
||
- [ ] 数据模型文档已更新（如有变更）
|
||
- [ ] 部署文档已更新（如有变更）
|
||
- [ ] README 已更新（如有变更）
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### Q1: 如果发现前后端设计不一致怎么办？
|
||
|
||
**A**:
|
||
1. 立即记录问题到联调问题列表
|
||
2. 标记为 P1 问题
|
||
3. 召开评审会议讨论解决方案
|
||
4. 确定统一的设计规范
|
||
5. 前后端同步修改
|
||
|
||
### Q2: 如果测试通过率 < 95% 怎么办？
|
||
|
||
**A**:
|
||
1. 不能上线
|
||
2. 分析失败原因
|
||
3. 优先修复 P0/P1 问题
|
||
4. 重新测试
|
||
5. 直到通过率 ≥ 95%
|
||
|
||
### Q3: 如果存在性能问题怎么办？
|
||
|
||
**A**:
|
||
1. 记录性能测试数据
|
||
2. 分析瓶颈（数据库、网络、前端渲染）
|
||
3. 制定优化方案
|
||
4. 实施优化
|
||
5. 重新测试验证
|
||
|
||
---
|
||
|
||
## 9. 质量指标
|
||
|
||
### 9.1 联调质量指标
|
||
|
||
- **测试通过率**: ≥ 95%
|
||
- **P0 问题数**: 0
|
||
- **P1 问题数**: 0（上线前）
|
||
- **接口响应时间**: < 500ms（查询），< 1000ms（写入）
|
||
- **代码覆盖率**: > 70%
|
||
|
||
### 9.2 持续改进
|
||
|
||
每个 Sprint 结束后进行评审流程复盘：
|
||
- [ ] 收集团队反馈
|
||
- [ ] 分析问题根因
|
||
- [ ] 优化评审流程
|
||
- [ ] 更新检查清单
|
||
|
||
---
|
||
|
||
## 10. 附录
|
||
|
||
### 10.1 相关文档
|
||
|
||
- [前后端联调评审流程](../processes/FRONTEND_BACKEND_REVIEW.md)
|
||
- [前后端联调检查清单](../checklists/FRONTEND_BACKEND_CHECKLIST.md)
|
||
- [代码审查标准](../code-review/CODE_REVIEW_STANDARD.md)
|
||
- [生产环境检查清单](../team/PRODUCTION_CHECKLIST.md)
|
||
|
||
### 10.2 联系方式
|
||
|
||
- **后端负责人**: [待填写]
|
||
- **前端负责人**: [待填写]
|
||
- **测试负责人**: [待填写]
|
||
- **技术负责人**: [待填写]
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-04-02
|
||
**审核状态**: ✅ 已审核通过
|