cozsweet-frontend-nextjs/.agents/skills/sync-backend-api/SKILL.md

name, description

name	description
sync-backend-api	Sync frontend code with backend OpenAPI specification

sync-backend-api

根据用户指定的模块或接口，根据后端文档更新前端代码（服务层、仓库层、UI层）。

使用场景

当后端 API 发生变更时（如新增接口、修改参数），使用此 skill 同步更新前端代码。

可用模块

模块	说明	API 路径
auth	认证模块	/api/auth/*
chat	聊天模块	/api/chat/*
user	用户模块	/api/user/*
verify	验证码模块	/api/verify/*

使用方式

按模块更新（可多选，用逗号分隔）

根据后端文档更新 auth,chat 模块

按接口更新（可多选，用逗号分隔）

根据后端文档更新接口 /api/auth/sendCode
根据后端文档更新接口 /api/chat/send
根据后端文档更新接口 /api/auth/register,/api/user/profile

混合同步

根据后端文档更新 auth 模块和接口 /api/chat/send

OpenAPI 文档路径

• 测试环境: docs/backend/openapi.json

更新流程

1. 读取 OpenAPI 文档

读取 docs/backend/openapi.json，根据用户指定的模块筛选接口。

2. 分析接口变更

• 新增接口：创建对应的模型、API 方法
• 修改接口：更新现有模型字段
• 删除接口：移除不再使用的代码

3. 更新数据模型 (lib/data/models/)

• 根据 schema 创建/更新 freezed 模型

4. 更新 API 客户端 (lib/data/services/)

• 更新 *_api_client.dart 中的接口定义
• 更新 api_path.dart 中的路径常量（如有新增）
• 运行 build_runner 生成 *_api_client.g.dart

5. 更新仓储层 (lib/data/repositories/)

• 更新 *_repository.dart 接口定义
• 更新 *_repository_impl.dart 实现

6. 更新 UI 层

• 根据功能模块更新对应 BLoC/ViewModel
• 更新 UI 调用逻辑

7. 生成代码

运行 dart run build_runner build --delete-conflicting-outputs

示例

按模块更新：

根据后端文档更新 auth 模块
根据后端文档更新 auth,user,verify 模块

按接口更新：

根据后端文档更新接口 /api/auth/sendCode
根据后端文档更新接口 /api/chat/send
根据后端文档更新接口 /api/auth/register,/api/user/profile

混合同步：

根据后端文档更新 auth 模块和接口 /api/chat/send

注意事项

1. 测试覆盖: 更新后运行相关测试确保正常