John Qiu
3706d7f32d
批次1: req-prd 瘦身 + req-design 重定位 + dev-coding 聚焦 批次2: dev-review 新建 + review-checklist 插件 批次3: dev-integration 新建 + req-compare 拆出 批次4: 插件完善 (req-research/db-migration/dev-scaffold/deploy-rollback) 批次5: 平台拆分 (dev-ios/dev-android/dev-mcp/dev-pda) + dev 分组更新 批次6: marketplace.json 32→44 plugins Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
---
|
||
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，确认自动转换正确
|