xtraderClient/.cursor/skills/xtrader-api-docs/SKILL.md

name, description

name	description
xtrader-api-docs	Interprets the XTrader API from the Swagger 2.0 spec at https://api.xtrader.vip/swagger/doc.json and helps implement endpoints, TypeScript types, and request helpers. Use when implementing or understanding XTrader API endpoints, adding new API calls, or when the user refers to the API docs or Swagger.

XTrader API 接口文档解读

规范来源：OpenAPI 规范（Swagger 2.0）。Swagger UI：https://api.xtrader.vip/swagger/index.html。

规范地址与格式

• 规范 URL：https://api.xtrader.vip/swagger/doc.json
• 格式：Swagger 2.0；接口在 paths 下，类型在 definitions 下，引用为 #/definitions/xxx（如 response.Response、system.SysUser）。
• 使用方式：用 mcp_web_fetch 或项目内请求获取 doc.json；解析 paths 与 definitions 编写 TS 类型与请求。鉴权：请求头 x-token（见 securityDefinitions.ApiKeyAuth）。

Swagger UI 与 doc.json 的对应关系（如何定位 Example Value / Model）

Swagger UI 页面（如 PmEvent findPmEvent）的数据来源就是 doc.json。页面上的「Parameters」「Responses」里的 Example Value 和 Model 都对应 doc.json 里的同一套 schema。

对应关系一览

Swagger UI 上看到的	在 doc.json 中的位置
某个接口（如「用id查询Event Management」）	paths["/PmEvent/findPmEvent"].get（或对应 path + method）
Parameters → Body / Query	paths["/PmEvent/findPmEvent"].get.parameters，或 body 的 schema（常为 $ref）
Responses → 200 → Model	paths["/PmEvent/findPmEvent"].get.responses["200"].schema，且需把其中的 $ref 解析到 definitions
Responses → 200 → Example Value	由同一 responses["200"].schema 生成（或 schema 里的 example）；结构同 Model
Model 里展开的 data、user 等对象	definitions 里对应的 schema，如 definitions["polymarket.PmEvent"]、definitions["system.SysUser"]

如何快速定位「响应」的 Model / 数据结构

1. 确定 path 和 method
   例如 findPmEvent：path = /PmEvent/findPmEvent，method = get。

2. 取 200 的 schema

   doc.json → paths["/PmEvent/findPmEvent"].get.responses["200"].schema
   

   这就是页面上 200 的 Model 的完整定义（可能含 allOf、$ref）。

3. 解析 allOf + $ref

   • 若 schema 为 allOf: [ { $ref: "#/definitions/response.Response" }, { type: "object", properties: { data: { $ref: "..." }, msg } } ]，则合并后得到根结构：code、data、msg。
   • 对 data 的 $ref（如 #/definitions/polymarket.PmEvent），到 definitions 里找：
     definitions["polymarket.PmEvent"]（或 definitions["response.LoginResponse"] 等）。
   • definitions 的 key 在 JSON 里是字符串，如 "polymarket.PmEvent"（带引号），对应 Swagger 里 #/definitions/polymarket.PmEvent。

4. Example Value
   与 Model 共用同一份 responses["200"].schema；Example Value 是 Swagger UI 按该 schema 生成的示例，或 schema 内 example 字段。所以看响应结构时以 Model 为准，在 doc.json 里就是上述 responses["200"].schema 及其引用的 definitions。

接口集成规范（必须按顺序执行）

接入任意 XTrader 接口时，必须按以下顺序执行，不得跳过或调换。

第一步：列出请求参数与响应参数

在写代码前，先从 doc.json 中整理并列出：

1. 请求参数

   • Query：paths["<path>"]["<method>"].parameters 中 in: "query" 的项（name、type、required、description）。
   • Body：若存在 in: "body"，写出其 schema 对应的 $ref 或内联结构（来自 definitions）。
   • 鉴权：该接口是否带 security: [ { ApiKeyAuth: [] } ]，若是则需在请求头加 x-token。

2. 响应参数

   • 取 paths["<path>"]["<method>"].responses["200"].schema。
   • 若有 allOf，合并得到根结构（通常为 code、data、msg）。
   • 对 data 及其他嵌套对象的 $ref，到 definitions 中查完整结构并列出字段（名称、类型、说明）。

输出形式可为表格或结构化列表，便于第二步写类型。

第二步：根据响应数据创建 Model 类

• 在 src/api/ 下相应模块（如 event.ts、market.ts）中，根据第一步整理出的响应结构定义 TypeScript 类型/接口：
  • 根响应：如 XxxResponse { code: number; data: XxxData; msg: string }。
  • data 及嵌套对象：对应 doc.json 的 definitions，写出完整 Model（如 PmEvent、PmMarket），避免只写 any 或过度使用 [key: string]: unknown（仅在确有扩展字段时使用）。
• 命名与项目一致：PageResult<T>、XxxResponse、XxxParams 等；与 event.ts 风格保持一致。

第三步：将接口集成到页面

• 在对应 API 模块中实现请求函数：使用 get/post（src/api/request.ts），路径、query/body 与第一步一致，返回类型使用第二步定义的 Response 类型。
• 在页面（Vue 组件）中：调用该请求函数，将返回的 data 绑定到组件的状态或 UI；处理 loading、错误与空数据；若为鉴权接口，确保调用时传入带 x-token 的 config（或使用已注入 token 的 request 封装）。

---

解读规范并落地的步骤

1. Base URL：规范中 host + basePath（可为空）；本项目已用 src/api/request.ts 的 BASE_URL（默认 https://api.xtrader.vip），实现时用相对 path 即可。

2. 路径与方法：遍历 paths，每个 path + method 对应一个接口；path 以 / 开头。需鉴权接口在请求中加 config.headers['x-token']。

3. 请求参数：Query 对应 parameters 中 in: 'query'；Body 对应 in: 'body' 的 schema（常为 $ref 到 definitions）。Swagger 2.0 中 body 参数名为 data 时，实际请求体即该 schema 的 JSON。

4. 响应类型：看 responses['200'].schema；若为 allOf，合并 response.Response 与扩展中的 data、msg 等。$ref 到 #/definitions/XXX 时，在 definitions 中查对应结构并转为 TS 接口。统一响应包装为 { code, data, msg }。

5. 与项目风格一致：新接口放在 src/api/ 下；导出请求/响应类型及调用 get/post 的函数；类型命名与 event.ts 一致（如 PageResult<T>、XxxResponse）。

已知接口（来自 doc.json）

钱包登录 POST /base/walletLogin

• 请求体（definitions.request.WalletLogin）：{ message: string, nonce: string, signature: string, walletAddress: string }。
• 响应 200：{ code, data, msg }；data 为 response.LoginResponse。
• response.LoginResponse：{ expiresAt: number, token: string, user: system.SysUser }。
• system.SysUser（data.user）：含 ID（integer，主键）、userName、nickName、headerImg、uuid、authorityId、authority、createdAt、updatedAt、email、phone、enable、walletAddress 等。返回结果中包含用户 id，对应字段为 user.ID（JSON 中可能为 ID 或 id，与后端序列化一致即可）。
• 项目映射：src/views/Login.vue 调该接口；src/stores/user.ts 的 UserInfo 建议包含 id?: number | string 并与 data.user.ID 对应。

公开事件列表 GET /PmEvent/getPmEventPublic

• Query：page、pageSize、keyword、createdAtRange（array）。
• 响应 200：data 为 response.PageResult（list、page、pageSize、total）；list 项为 polymarket.PmEvent，内含 markets、series、tags 等，markets[].outcomePrices 为价格数组，首项对应 Yes 概率。

通用响应与鉴权

• response.Response：{ code: number, data: any, msg: string }。
• response.PageResult：{ list, page, pageSize, total }。
• 需鉴权接口在文档中带 security: [ { ApiKeyAuth: [] } ]，请求时加 header x-token。

简要检查清单

• 按规范顺序：已先列出请求参数与响应参数，再建 Model，最后集成到页面
• 规范 URL 使用 https://api.xtrader.vip/swagger/doc.json，或本地缓存与之一致
• 请求 path、method、query/body 与 paths 一致
• 响应类型（Model）覆盖 code/data/msg 及 definitions 中业务字段
• 鉴权接口使用 x-token header
• 新代码风格与 src/api/request.ts、src/api/event.ts 一致

参考

• 规范：https://api.xtrader.vip/swagger/doc.json
• Swagger UI：https://api.xtrader.vip/swagger/index.html
• 项目请求封装：src/api/request.ts
• 现有接口与类型：src/api/event.ts