moon-web: Skill for Cursor

更新 API（Update API）

根据后端服务的 OpenAPI 文档，同步更新前端 src/api/ 下的请求与类型。代码风格遵循 React 与 TypeScript 规范。

项目约定

• API 目录：src/api/ 下每个一级目录对应一个后端服务：
  • account — 认证与用户
  • marksman — 策略与数据源
  • rabbit — 消息与发送
• 文档地址：每个后端服务在根路径下提供 /doc/swagger/openapi.yaml，需从对应服务的 base URL 获取（如 https://api.example.com/account/doc/swagger/openapi.yaml）。
• 请求封装：统一使用 src/api/common/request.ts 的 http（get/post/put/delete/patch），baseURL 为 /v1；路径写相对路径如 /datasources、/user/${uid}。
• 模块结构：每个子模块（如 marksman/datasource）包含：
  • index.ts — 导出请求函数与 re-export 类型
  • types.ts — 请求/响应/枚举的 TypeScript 类型定义

工作流程

1. 确认目标服务与文档 URL

   • 若用户未指定服务，询问要更新哪个服务（account / marksman / rabbit）或“全部”。
   • 确认该服务对应的 OpenAPI 文档完整 URL（例如 {服务 base URL}/doc/swagger/openapi.yaml）。若项目中有配置（如 .env、文档），优先使用；否则向用户确认。

2. 获取并解析 OpenAPI

   • 使用 GET 请求或读取本地/网络文件获取 openapi.yaml（或 openapi.json）。
   • 解析 paths 与 components.schemas，得到接口路径、方法、请求体/查询参数、响应 schema。

3. 映射到前端路径

   • 前端 baseURL 为 /v1，若 OpenAPI 中 path 已含 /v1 或前缀，生成请求路径时去掉重复前缀，只保留与 /v1 后一致的部分（如 /v1/datasources → 请求路径 /datasources）。
   • 按现有习惯：一个 OpenAPI tag 或资源名对应 src/api/<服务>/<子模块>/ 一个目录；若已有对应目录则更新，没有则新建并补全 index.ts、types.ts。

4. 更新 types.ts

   • 根据 components.schemas 生成 TypeScript 接口/类型；枚举与后端一致时使用 export enum，否则用 string 联合类型或 string。
   • 命名与现有风格一致：列表项 XxxItem、列表参数 XxxListParams 或 ListXxxParams、列表响应 XxxListResponse 或 ListXxxResponse、创建/更新参数 CreateXxxParams、UpdateXxxParams 等。
   • 所有字段可选用 ?，除非业务上明确必填；与后端一致的注释可保留简短说明。

5. 更新 index.ts

   • 从 ../../index 或 ../../common/request 引入 http（与现有模块一致，见 src/api/marksman/datasource/index.ts、src/api/account/user/index.ts）。
   • 每个 path + method 对应一个导出函数：使用 http.get<T>()、http.post<T>()、http.put<T>()、http.delete<T>()、http.patch<T>()，泛型 T 为响应类型。
   • 路径参数（如 uid）用模板字符串 `/path/${uid}`；query 作为第二参数传入；body 作为 post/put/patch 的第二参数。
   • 函数上方用 JSDoc 注释说明接口用途及路径，例如：/** 获取数据源列表 GET /v1/datasources */。
   • 文件末尾统一 export type { ... } from './types' 以及需要的 export { EnumName } from './types'，与现有模块一致。