# 前后端联调评审实施指南

**版本**: 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  
**审核状态**: ✅ 已审核通过