---
name: dev-integration
description: 前后端联调技能。API 契约验证、接口对接、联调报告生成。对应 req 流程 integration 阶段。纯后端需求自动跳过。
---

# 前后端联调 Skill (dev-integration)

## 概述

本技能用于前后端联调阶段，确保实际实现与 API 契约一致。

**核心价值**：发现契约偏差（字段名不一致、类型不匹配、缺少错误码处理）比测试阶段更早、修复成本更低。

---

## 技能间契约

| 上游 | 本技能输入 | 本技能输出 | 下游 |
|------|-----------|-----------|------|
| dev-coding | 已实现的前后端代码 + API 契约（来自 req-design） | 联调报告（通过/不通过 + 问题列表） | dev-test |

---

## 自动跳过条件

以下情况 integration 阶段**自动通过**，无需执行联调：

| 条件 | 原因 |
|------|------|
| 需求只有后端 implementation 任务（无前端任务） | 没有前端对接，无需联调 |
| 需求只有前端 implementation 任务（无后端任务） | 使用已有 API，无需联调 |
| 需求无 implementation 任务（纯 skill/ops/doc） | 非代码需求 |

**检测方法**：
```
get_requirement_tasks → 检查 linkRole=implementation 的任务标题
含【开发-后端】和【开发-前端】→ 需要联调
仅含一端 → 自动跳过
```

---

## 工作流程

```
1. 检查是否需要联调
   ├── 获取 implementation 任务列表
   ├── 判断是否有前后端双端任务
   └── 仅单端 → 自动跳过，生成跳过说明

2. 获取 API 契约
   ├── 从 req-design 文档中提取 API 契约
   └── 无契约 → 从代码反推接口定义

3. 契约验证
   ├── 后端实际接口 vs 契约定义
   │   ├── URL 路径是否一致
   │   ├── 请求/响应字段名是否一致
   │   ├── 字段类型是否匹配
   │   └── 错误码是否完整
   ├── 前端调用 vs 契约定义
   │   ├── API service 调用路径是否正确
   │   ├── 请求参数是否完整
   │   └── 响应处理是否覆盖所有错误码
   └── 前端 ↔ 后端一致性
       ├── 字段命名一致（camelCase vs snake_case 转换）
       └── 分页参数格式一致

4. 功能对接验证
   ├── 前端表单字段 vs 后端 binding 规则
   ├── 前端列表列 vs 后端响应字段
   └── 前端状态流转 vs 后端状态机

5. 生成联调报告
   ├── 契约一致性结果
   ├── 发现的偏差列表
   └── 结论：通过/不通过
```

---

## 联调报告模板

```markdown
## 联调报告 — {需求标题}

**日期**: YYYY-MM-DD
**API 契约来源**: {req-design 文档 / 代码反推}

### 契约验证结果

| # | 接口 | 契约 | 后端实际 | 前端调用 | 结果 |
|---|------|------|---------|---------|------|
| 1 | POST /api/v1/xxx | ✅ 已定义 | ✅ 一致 | ✅ 一致 | PASS |
| 2 | GET /api/v1/xxx | ✅ 已定义 | ⚠️ 字段名不一致 | ✅ 一致 | FAIL |

### 发现的偏差

| # | 类型 | 接口 | 描述 | 影响 | 建议 |
|---|------|------|------|------|------|
| 1 | 字段名不一致 | GET /api/v1/xxx | 契约定义 `created_at`，后端返回 `createTime` | 前端解析失败 | 统一为 `created_at` |

### 结论

**{通过 / 不通过}**

{如不通过，列出必须修复的偏差编号}
```

---

## 插件支持

| 插件 | 触发条件 | 说明 |
|------|---------|------|
| `api-contract-verify` | 有 API 变更 | 自动化契约验证（未来） |

---

## 与 ai-proj 集成

### req 流程内

```typescript
// 创建联调任务（如需要）
mcp__ai-proj__create_task({ title: "【联调】前后端对接: {需求标题}" })
mcp__ai-proj__link_tasks_to_requirement({
  requirementId, taskIds: [taskId], linkRole: "implementation"
})

// 附加联调报告
mcp__ai-proj__create-and-attach({
  taskId, title: "联调报告", content: "<报告内容>"
})
```

### 自动跳过时

```typescript
// 记录跳过原因
mcp__ai-proj__create-and-attach({
  taskId: <设计任务ID>,
  content: "## 联调阶段\n\n自动跳过：仅后端变更，无前端对接。"
})
```

---

## 最佳实践

1. **契约先行** — API 契约是联调的基准，没有契约就先补
2. **字段级验证** — 不只检查接口是否通，要检查每个字段名、类型、格式
3. **错误码覆盖** — 前端必须处理契约中定义的所有错误码
4. **snake_case 转换** — Go 后端用 snake_case，前端用 camelCase，确认自动转换正确