user-system/docs/processes/FRONTEND_BACKEND_REVIEW_IMPLEMENTATION_GUIDE.md

前后端联调评审实施指南

版本: 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 接口评审记录模板

# API 接口评审记录

**评审日期**: YYYY-MM-DD
**评审人员**: ...
**功能模块**: ...

## 评审结果
- 通过 / 不通过 / 条件通过

## 问题列表
| ID | 问题 | 严重程度 | 负责人 | 解决方案 | 状态 |
|----|------|---------|--------|---------|------|
| API-001 | 参数命名不一致 | P2 | 张三 | 统一使用 snake_case | 已解决 |

3.2 联调测试记录模板

# 联调测试记录

**测试日期**: 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 响应格式规范

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

错误响应:

{
  "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 后端验证

# 运行测试
cd d:/project && go test ./... -count=1

# 代码检查
cd d:/project && go vet ./...

# 编译检查
cd d:/project && go build ./cmd/server

7.2 前端验证

# 运行测试
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 相关文档

• 前后端联调评审流程
• 前后端联调检查清单
• 代码审查标准
• 生产环境检查清单

10.2 联系方式

• 后端负责人: [待填写]
• 前端负责人: [待填写]
• 测试负责人: [待填写]
• 技术负责人: [待填写]

---

最后更新: 2026-04-02
审核状态: ✅ 已审核通过