feat: ✨ 更新接口

data/api/README.md

@@ -1,27 +1,32 @@
 # API 开发与类型定义流程
 
-为了保持代码健壮性，新增接口时请遵循以下步骤：
+当前接口与类型定义以 OpenAPI 文档为准：
 
-## 1. 记录请求与响应 (data/api/)
+- 源文件：`data/api/默认模块.openapi.json`
+- 来源：该文件由 **Apifox 导出**
+- 内容：包含接口定义、字段说明、请求/响应示例
 
-- **分文件夹管理**：每个接口在 `data/api/` 下拥有独立文件夹。
-- **请求逻辑 (`request.ts`)**：使用 Axios 编写接口调用逻辑，调用 `saveResponse(__dirname, data)` 自动保存响应。
-- **响应数据 (`response.json`)**：运行 `npx tsx data/api/run.ts` 后，会在该接口文件夹下生成或更新真实数据。
-- **自动化工具**：一键同步所有接口数据：
+## 1. 更新 OpenAPI 文档
 
-    ```bash
-    npx tsx data/api/run.ts
-    ```
+- 在 Apifox 中维护接口后，导出最新 OpenAPI 文件并覆盖 `data/api/默认模块.openapi.json`。
+- 新增/修改接口时，先以该文件为唯一事实来源（Single Source of Truth）。
 
-## 2. 定义类型 (src/types/api.ts)
+## 2. 生成/更新接口层 (src/api/)
 
-- 根据生成的 `response.json` 数据结构，在 `src/types/api.ts` 中创建接口。
-- **规则**：新增成员变量时务必添加 JSDoc 注释。
+- 根据 `paths` 中的接口定义，更新 `src/api/` 下的请求函数（路径、方法、请求参数）。
+- 保持现有业务兼容时，可新增标准方法并保留旧方法别名。
 
-## 3. 注册 URL (src/constants/api.ts)
+## 3. 生成/更新类型定义 (src/api/types/)
 
-- 在 `API_BASE` 基础上定义新的常量。
+- 根据 OpenAPI 中的 schema、字段说明和示例，维护 `src/api/types/` 下类型。
+- 在 `src/api/types/index.ts` 统一导出类型。
+- 新增字段时补充必要注释，命名与接口字段保持一致。
 
-## 4. 业务调用
+## 4. 使用与校验
 
-- 在对应的 Pinia Store 中使用 `ApiResponse<T>` 包装请求返回值。
+- 在业务层使用 `ApiResponse<T>` 包装响应类型。
+- 修改后执行类型检查：
+
+```bash
+npm run type-check
+```