# 前后端联调检查清单

## 使用说明

本检查清单用于前后端联调过程，确保质量标准。每项必须逐条确认。

---

## 1. API 接口检查

### 1.1 接口定义
- [ ] API 路径符合 RESTful 规范
  - [ ] GET 用于查询
  - [ ] POST 用于创建
  - [ ] PUT/PATCH 用于更新
  - [ ] DELETE 用于删除
- [ ] 接口命名清晰、一致
- [ ] 接口版本控制正确（如 `/api/v1/`）
- [ ] 请求方法使用正确

### 1.2 请求参数
- [ ] 请求参数命名符合规范
  - [ ] 后端: snake_case
  - [ ] 前端: camelCase
- [ ] 参数类型定义准确
  - [ ] string, number, boolean, array, object
- [ ] 必填参数明确标注
- [ ] 可选参数有默认值
- [ ] 分页参数统一（page, pageSize/limit）
- [ ] 排序参数统一（sortField, sortOrder）

### 1.3 响应格式
- [ ] 响应体结构统一
```json
{
  "code": 0,
  "message": "success",
  "data": {...}
}
```
- [ ] 错误响应格式统一
```json
{
  "code": 40001,
  "message": "参数错误",
  "details": {...}
}
```
- [ ] 成功码统一为 0
- [ ] 错误码定义清晰、文档化
- [ ] 分页响应包含 total
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}
```

### 1.4 数据类型映射
- [ ] 前后端数据类型映射正确
  - [ ] 前端 string ↔ 后端 string
  - [ ] 前端 number ↔ 后端 int/float
  - [ ] 前端 boolean ↔ 后端 bool
  - [ ] 前端 array ↔ 后端 slice
  - [ ] 前端 object ↔ 后端 struct/map
- [ ] 日期时间格式统一（ISO 8601: `2026-04-01T12:00:00Z`）
- [ ] 枚举值定义一致
- [ ] 空值处理一致
  - [ ] null vs undefined vs ""

---

## 2. 认证与授权检查

### 2.1 认证机制
- [ ] 未登录接口返回 401
- [ ] 登录接口正确验证用户凭证
- [ ] Token 验证机制正常
  - [ ] Access token 验证
  - [ ] Refresh token 验证
- [ ] Token 过期自动刷新
- [ ] CSRF Token 机制正确

### 2.2 权限控制
- [ ] 需要权限的接口返回 403
- [ ] 权限检查粒度正确
  - [ ] 菜单级权限
  - [ ] 操作级权限
  - [ ] 数据级权限（如适用）
- [ ] 角色权限继承正确
- [ ] 权限缓存机制正常（如有）

---

## 3. 业务逻辑检查

### 3.1 核心流程
- [ ] 正常业务流程畅通
- [ ] 边界条件处理正确
  - [ ] 空列表
  - [ ] 超大数据量
  - [ ] 特殊字符
  - [ ] 极端值（最大值、最小值、0、负数）
- [ ] 异常场景覆盖
  - [ ] 网络错误
  - [ ] 服务器错误（500）
  - [ ] 超时
  - [ ] 并发请求

### 3.2 数据一致性
- [ ] 前端展示数据与后端存储一致
- [ ] 多端数据同步正确
- [ ] 乐观锁/悲观锁正确使用（如需要）
- [ ] 事务边界正确

### 3.3 用户体验
- [ ] 加载状态显示正确
- [ ] 错误提示友好、准确
- [ ] 成功操作反馈明确
- [ ] 避免重复提交
- [ ] 表单验证前端后端一致

---

## 4. 性能检查

### 4.1 接口性能
- [ ] 查询接口响应时间 < 500ms
- [ ] 写入接口响应时间 < 1000ms
- [ ] 分页接口支持大数据量
- [ ] 列表查询有分页
- [ ] 避免不必要的字段查询

### 4.2 前端性能
- [ ] 列表渲染支持虚拟滚动（大数据量）
- [ ] 图片懒加载
- [ ] 避免不必要的重新渲染
- [ ] 请求防抖/节流
- [ ] 本地缓存合理使用

### 4.3 数据库性能
- [ ] 避免全表扫描
- [ ] 索引使用正确
- [ ] 避免 N+1 查询
- [ ] 批量操作使用批量接口

---

## 5. 安全检查

### 5.1 输入验证
- [ ] 前端表单验证
- [ ] 后端参数验证
- [ ] SQL 注入防护
- [ ] XSS 防护
- [ ] 文件上传验证
  - [ ] 文件类型
  - [ ] 文件大小
  - [ ] 文件内容

### 5.2 数据保护
- [ ] 敏感数据加密存储（密码）
- [ ] 敏感数据传输加密（HTTPS）
- [ ] 不在日志中输出敏感信息
- [ ] 不在 URL 中传递敏感信息
- [ ] Token 安全存储
  - [ ] Access token 存内存
  - [ ] Refresh token 存 localStorage

### 5.3 安全漏洞
- [ ] 无 CSRF 漏洞
- [ ] 无 XSS 漏洞
- [ ] 无 SQL 注入漏洞
- [ ] 无时序攻击漏洞
  - [ ] 验证码比较使用恒定时间比较
  - [ ] 密码比较使用恒定时间比较
- [ ] 无信息泄露（错误消息不泄露敏感信息）

---

## 6. 错误处理检查

### 6.1 错误码
- [ ] 错误码定义清晰
- [ ] 错误信息准确、友好
- [ ] 前端正确处理各种错误码
- [ ] 错误日志记录完整

### 6.2 重试机制
- [ ] 临时错误有重试机制
- [ ] 重试次数限制合理
- [ ] 重试间隔合理

### 6.3 降级机制
- [ ] 依赖服务故障有降级方案
- [ ] 降级时用户体验可接受

---

## 7. 兼容性检查

### 7.1 浏览器兼容
- [ ] Chrome/Edge 最新版本
- [ ] Firefox 最新版本
- [ ] Safari 最新版本
- [ ] 移动端浏览器（如需要）

### 7.2 数据版本兼容
- [ ] API 版本兼容
- [ ] 数据结构变更有兼容方案

---

## 8. 测试覆盖

### 8.1 单元测试
- [ ] 后端核心逻辑有单元测试
- [ ] 前端工具有单元测试
- [ ] 测试覆盖率 > 70%

### 8.2 集成测试
- [ ] 关键接口有集成测试
- [ ] 联调场景有集成测试

### 8.3 E2E 测试
- [ ] 主流程有 E2E 测试
- [ ] E2E 测试通过

---

## 9. 文档检查

- [ ] API 文档完整（Swagger/OpenAPI）
- [ ] 接口变更文档更新
- [ ] README 更新（如需要）
- [ ] 数据库变更文档（如需要）
- [ ] 部署文档更新（如需要）

---

## 10. 部署检查

- [ ] 配置文件正确
- [ ] 环境变量正确
- [ ] 数据库迁移脚本正确
- [ ] 回滚方案准备
- [ ] 监控指标配置
- [ ] 告警规则配置

---

## 11. 上线前最终检查

- [ ] 所有 P0 问题已解决
- [ ] 所有 P1 问题已解决
- [ ] 测试通过率 ≥ 95%
- [ ] 性能指标达标
- [ ] 安全测试通过
- [ ] 代码审查通过
- [ ] 文档更新完整
- [ ] 回滚方案确认

---

## 附录

### 问题严重程度定义

| 级别 | 描述 | 示例 |
|------|------|------|
| P0 | 阻塞问题，无法联调 | 接口 500 错误，数据库连接失败 |
| P1 | 严重问题，影响核心功能 | 权限失效，数据丢失 |
| P2 | 一般问题，影响用户体验 | 错误提示不准确，性能较差 |
| P3 | 优化建议，不影响功能 | 命名不规范，代码可读性差 |

### 联调测试命令

```bash
# 后端测试
go test ./...

# 前端测试
cd frontend/admin && npm test

# 前端构建
cd frontend/admin && npm run build

# 前端 lint
cd frontend/admin && npm run lint

# E2E 测试
cd frontend/admin && npm run e2e:full:win
```