ai-proj-helper/skills-dev/dev-integration-plugin/skills/SKILL.md

name, description

name	description
dev-integration	前后端联调技能。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. 生成联调报告
   ├── 契约一致性结果
   ├── 发现的偏差列表
   └── 结论：通过/不通过

---

联调报告模板

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

**日期**: 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 流程内

// 创建联调任务（如需要）
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: "<报告内容>"
})

自动跳过时

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

---

最佳实践

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