Menu
当需要将前端与后端API对接时使用。API集成自动生成，基于API契约自动生成前端请求层代码，包含类型安全的API客户端、请求/响应拦截器、错误处理和Mock数据。关键词：API对接、接口联调、请求层、API客户端、前后端联调、接API、调接口。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
当需要评估获客渠道或优化获客漏斗时使用。用户获取指挥官，调度 acquisition-analysis（获客分析一体化），实现从渠道评估到漏斗优化的闭环。关键词：用户获取、获客渠道、漏斗优化、渠道评估、获客策略、acquisition-analysis、拉新、获客。
当需要识别和工程化Aha Moment时使用。Aha Moment自动工程化Pipeline，分析留存数据和行为数据，自动识别Aha Moment候选，测量到达率，识别最短路径，输出Onboarding优化建议。关键词：Aha Moment、激活时刻、用户激活、到达率、Onboarding优化、什么时候觉得好用、体验核心价值、爽点在哪。
当需要优化用户Onboarding流程时使用。Onboarding自动优化Pipeline，分析Onboarding数据和用户分群，自动生成个性化引导策略，设计A/B测试方案。关键词：Onboarding、新用户引导、引导优化、个性化引导、用户激活、新手引导、上手快、引导太长。
当需要识别Aha Moment或设计Onboarding流程时使用。用户激活指挥官，调度activation-aha/onboarding。关键词：用户激活、Aha Moment、Onboarding、新用户引导、新手引导、激活率。
当需要管理Sprint周期或追踪敏捷执行时使用。敏捷执行指挥官，调度 agile-sprint-planning、agile-daily-sync、agile-review 子Skill执行。agile-review 已合并 retrospective-auto 的自动回顾能力。关键词：敏捷执行、Sprint规划、每日站会、Sprint评审、敏捷管理、Sprint复盘、迭代复盘、敏捷开发、复盘报告、自动回顾。
当需要自动化Sprint评审和复盘报告时使用。Sprint评审与复盘报告一体化，Step 1完成Sprint评审（产出清单整理、Demo准备清单、反馈收集分类、数据收集、问题识别、改进建议生成），Step 2生成完整复盘报告（Sprint目标达成分析、交付质量评估、团队速率趋势、改进行动项、下一Sprint建议），Step 3完成上线复盘（效果复盘、工程质量复盘、过程复盘、改进行动项生成）。关键词：Sprint Review、Sprint Retro、迭代评审、迭代回顾、敏捷复盘、评审会、复盘报告、Sprint复盘、改进行动项、做得怎么样、上线复盘、发布复盘、效果评估、持续改进。
| name | api-integration |
| description | 当需要将前端与后端API对接时使用。API集成自动生成，基于API契约自动生成前端请求层代码，包含类型安全的API客户端、请求/响应拦截器、错误处理和Mock数据。关键词：API对接、接口联调、请求层、API客户端、前后端联调、接API、调接口。 |
| metadata | {"module":"UI设计与前端开发","sub-module":"前端集成","type":"pipeline","version":"2.0","domain_tags":["互联网","通用"],"trigger_examples":["对接后端API","生成请求层代码","调接口"],"interaction_mode":"ai_suggest_human_approve"} |
🤖 AI建议，人类确认
| 输入项 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
| API契约 | YAML/JSON | ○ | output/backend-api-design/api-design-spec/openapi.yaml | OpenAPI 3.0规范（缺失时基于页面数据流推断） |
| 认证鉴权方案 | JSON | ○ | output/backend-api-design/api-design-spec/auth-scheme.json | 后端API认证鉴权设计（JWT/OAuth2/SSO方案、权限模型、会话管理），优先于PRD非功能需求 |
| 安全策略 | JSON | ○ | output/backend-api-design/api-design-spec/security-policy.json | 后端API安全策略（限流规则、CORS策略、数据脱敏规则），用于前端错误处理和安全策略对齐 |
| 页面数据流 | JSON | 是 | output/ui-frontend/page-builder/pages.json | 页面数据获取需求 |
| 目标框架 | string | 是 | 上游编排器传递 | React/Vue/Svelte |
| 目标语言 | string | ○ | 上游编排器传递（默认zh-CN） | 目标界面语言，影响Mock数据和错误提示语言 |
| project_dir | string | 是 | 上游编排器传递 | 项目根目录绝对路径 |
| 认证方案 | string | ○ | PRD非功能需求 / 用户提供 | JWT/OAuth2/Cookie/ApiKey（默认JWT），当auth-scheme.json不可用时使用 |
1a. 契约解析
若有API契约输入：
若API契约缺失：
inferred: true1b. 端点分类与目录规划
| 分类规则 | 目录结构 | 示例 |
|---|---|---|
| 按领域模块 | src/api/{module}/ | src/api/auth/、src/api/user/、src/api/product/ |
| 公共端点 | src/api/shared/ | 健康检查、配置接口 |
| 端点≤5个 | 单文件 src/api/index.ts | 小型项目不分模块 |
1c. 认证方案规划
| 认证类型 | 实现策略 | Token存储 |
|---|---|---|
| JWT | axios拦截器自动注入Authorization头 | localStorage + 内存缓存 |
| OAuth2 | 授权码流程 + PKCE | localStorage + 内存缓存 |
| Cookie | withCredentials配置 | 浏览器自动管理 |
| ApiKey | 请求头/查询参数注入 | 环境变量 |
Token刷新策略：
2a. 类型定义生成
从契约schema推导TypeScript类型：
type {Endpoint}Request = { /* 从requestBody推导 */ }
type {Endpoint}Response = { /* 从200响应schema推导 */ }
type {Endpoint}Error = { /* 从4xx/5xx响应schema推导 */ }
type ApiResponse<T> = { code: number; data: T; message: string }
type PaginatedResponse<T> = { items: T[]; total: number; page: number; page_size: number }
2b. 请求函数生成
每个端点生成一个请求函数：
export async function {endpointName}(params: {Endpoint}Request, config?: RequestConfig): Promise<{Endpoint}Response> {
return request.{method}<{Endpoint}Response>('{path}', params, config)
}
生成规则：
2c. 请求层基础设施
| 基础设施 | 实现内容 |
|---|---|
| HTTP客户端 | axios实例（React/Vue）或fetch封装（Svelte） |
| 请求拦截器 | token注入 + 请求ID + 时间戳 + 请求体序列化 |
| 响应拦截器 | 统一错误处理 + token过期自动刷新 + 响应解包 |
| 错误处理 | 网络错误/超时(10s)/业务错误/认证过期 分级处理 |
| 重试策略 | 网络错误和5xx重试2次，指数退避(1s/2s) |
| 取消机制 | AbortController封装，页面卸载自动取消 |
| 请求去重 | 相同URL+参数的并发请求合并 |
2d. 错误处理策略
| 错误类型 | 处理方式 | 用户反馈 |
|---|---|---|
| 网络错误 | 重试2次→提示网络异常 | "网络连接异常，请检查网络后重试" |
| 超时(>10s) | 重试1次→提示响应超时 | "请求超时，请稍后重试" |
| 401未授权 | 尝试刷新token→跳转登录 | 自动跳转登录页 |
| 403禁止 | 提示无权限 | "您没有权限执行此操作" |
| 404不存在 | 提示资源不存在 | "请求的资源不存在" |
| 422验证失败 | 提取字段错误 | 显示具体字段错误信息 |
| 429限流 | 等待后重试 | "操作过于频繁，请稍后重试" |
| 5xx服务错误 | 重试2次→提示服务异常 | "服务异常，请稍后重试" |
3a. Mock数据生成
从契约的response schema生成Mock数据：
3b. Mock切换机制
export const useMock = import.meta.env.VITE_API_MOCK === 'true'
export async function getUser(id: string) {
if (useMock) return mockData.user
return request.get(`/users/${id}`)
}
3c. MSW集成（推荐）
生成MSW（Mock Service Worker）handler：
4a. 数据预加载配置
| 框架 | 方案 | 配置 |
|---|---|---|
| React | React Query (TanStack Query) | staleTime/cacheTime/refetchOnWindowFocus |
| Vue | Vue Query (TanStack Query) | staleTime/cacheTime/refetchOnWindowFocus |
| Svelte | svelte-query | staleTime/cacheTime/refetchOnWindowFocus |
4b. 缓存策略
| 数据类型 | staleTime | cacheTime | refetch策略 |
|---|---|---|---|
| 用户信息 | 5min | 30min | 窗口聚焦 |
| 列表数据 | 2min | 10min | 窗口聚焦 |
| 详情数据 | 10min | 30min | 不自动刷新 |
| 配置数据 | 30min | 60min | 不自动刷新 |
| 实时数据 | 0 | 5min | 轮询(5s) |
4c. 乐观更新配置
对写操作（POST/PUT/PATCH）生成乐观更新配置：
4d. 与page-builder fallback数据层替换
当api-integration执行时，替换page-builder生成的fallback数据层：
@api-integration 的文件代码文件输出：{project_dir}/src/api/（API客户端、类型定义、Mock数据直接写入项目目录）
元数据输出：output/ui-frontend-integration/api-integration/
输出文件：api-integration.json
输出Schema：
{
"type": "object",
"required": ["endpoints", "types", "mock_data", "auth_config", "cache_config", "error_handling", "project_dir"],
"properties": {
"endpoints": {
"type": "array",
"description": "API端点列表",
"items": {
"type": "object",
"properties": {
"name": {"type": "string", "description": "函数名"},
"method": {"type": "string", "enum": ["GET","POST","PUT","PATCH","DELETE"]},
"path": {"type": "string", "description": "API路径"},
"request_type": {"type": "string", "description": "请求类型名"},
"response_type": {"type": "string", "description": "响应类型名"},
"module": {"type": "string", "description": "所属模块"},
"inferred": {"type": "boolean", "description": "是否为推断端点"},
"deprecated": {"type": "boolean", "description": "是否已废弃"}
}
}
},
"types": {
"type": "array",
"description": "TypeScript类型定义文件列表",
"items": {
"type": "object",
"properties": {
"file_path": {"type": "string", "description": "类型文件路径"},
"type_count": {"type": "number", "description": "定义的类型数量"},
"endpoints_covered": {"type": "array", "description": "覆盖的端点列表"}
}
}
},
"mock_data": {
"type": "array",
"description": "Mock数据文件列表",
"items": {
"type": "object",
"properties": {
"file_path": {"type": "string", "description": "Mock数据文件路径"},
"endpoint": {"type": "string", "description": "对应端点"},
"record_count": {"type": "number", "description": "Mock数据条数"}
}
}
},
"auth_config": {
"type": "object",
"description": "认证配置",
"properties": {
"type": {"type": "string", "enum": ["JWT","OAuth2","Cookie","ApiKey","None"]},
"token_storage": {"type": "string", "description": "Token存储方式"},
"refresh_enabled": {"type": "boolean", "description": "是否启用自动刷新"},
"login_redirect": {"type": "string", "description": "未授权跳转路径"}
}
},
"cache_config": {
"type": "object",
"description": "缓存策略配置",
"properties": {
"library": {"type": "string", "description": "数据请求库"},
"strategies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data_type": {"type": "string", "description": "数据类型（user_info/list_data/detail_data/config_data/realtime_data）"},
"stale_time": {"type": "string", "description": "数据新鲜时间"},
"cache_time": {"type": "string", "description": "缓存保留时间"},
"refetch_strategy": {"type": "string", "description": "重新获取策略（window_focus/polling/none）"}
}
}
}
}
},
"error_handling": {
"type": "object",
"description": "错误处理配置",
"properties": {
"timeout_ms": {"type": "number", "description": "请求超时时间(ms)"},
"retry_count": {"type": "number", "description": "重试次数"},
"retry_delay_ms": {"type": "number", "description": "重试延迟(ms)"},
"error_codes_mapped": {"type": "number", "description": "已映射的错误码数量"},
"error_strategies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"error_type": {"type": "string", "description": "错误类型（network/timeout/401/403/404/422/429/5xx）"},
"handling": {"type": "string", "description": "处理方式"},
"user_feedback": {"type": "string", "description": "用户反馈文案"}
}
}
}
}
},
"project_dir": {"type": "string", "description": "项目根目录路径"}
}
}
| 条件 | 决策 |
|---|---|
| 目标框架=React | 使用React Query + axios |
| 目标框架=Vue | 使用Vue Query + axios |
| 目标框架=Svelte | 使用svelte-query + fetch封装 |
| API端点>20个 | 按领域模块分文件 |
| 有分页接口 | 生成通用分页Hook |
| 有文件上传接口 | 生成进度回调封装 |
| 目标语言≠en-US | Mock数据使用目标语言内容 |
| 认证方案=JWT | 自动生成token刷新拦截器 |
| 认证方案缺失 | 默认JWT，标注"待确认认证方案" |
| 推断端点>50% | 标注"高推断比例，建议补充API契约" |
P0（必须通过，不通过则阻断输出）：
P1（建议通过，不通过则标注"待修复"）：
| 缺失的上游输入 | 降级方案 | 输出影响 |
|---|---|---|
| API契约缺失 | 基于页面数据流推断API需求，推断端点标注inferred:true | API函数为骨架，需人类确认后补充契约细节 |
| 页面数据流缺失 | 为所有API端点生成独立函数，无页面级预加载 | 缺少页面级数据预加载和缓存配置 |
| 认证方案缺失 | 默认JWT方案，标注"待确认认证方案" | token刷新逻辑可能需调整 |
| 安全策略缺失 | 跳过安全策略对齐，标注"待安全策略补充" | CORS/限流等前端安全策略未对齐 |
| project_dir缺失 | 仅输出到output/目录 | 代码需手动复制 |
| 上游变更 | 影响范围 | 响应策略 |
|---|---|---|
| API契约变更（端点增删/参数变更/响应结构变更/认证方案变更） | 请求函数、类型定义、Mock数据、认证配置 | 标注受影响的端点和类型，建议重新生成对应请求函数、Mock数据和认证拦截器 |
| 页面数据流变更（数据获取方式/缓存策略变更） | 数据预加载配置、缓存策略、请求去重 | 标注受影响的页面数据流，建议更新React Query/Vue Query/svelte-query配置 |
| 目标框架变更 | 请求层技术选型（React Query/Vue Query/svelte-query） | 标注需替换的数据请求层方案，建议重新生成 |
| 认证方案变更 | token注入/刷新/过期处理逻辑 | 标注需替换的认证拦截器，建议重新生成认证基础设施 |
| 本Skill输出变更 | 通知下游Skill | 通知内容 | 触发条件 |
|---|---|---|---|
| API端点增删 | production-ready | 受影响的测试和构建配置 | endpoints列表变更 |
| 类型定义变更 | production-ready | 受影响的类型相关测试 | types结构变更 |
| Mock数据变更 | production-ready | 受影响的测试Mock | mock_data文件变更 |
| 请求层技术选型变更 | production-ready | 依赖和构建配置变更 | 目标框架或请求库变更 |
| 认证配置变更 | production-ready | 认证相关测试和依赖变更 | auth_config变更 |
| 缓存策略变更 | production-ready | 数据层相关测试变更 | cache_config变更 |
| 错误处理变更 | production-ready | 错误处理相关测试变更 | error_handling变更 |