---
alwaysApply: false
---
# portal-ui API调用规范

## 1. 接口路径要求
- 所有调用 **portal-ui** 的接口必须使用 `/api` 开头（与后端 Java Controller 中的 `@RequestMapping("/api/...")` 对应）。
- 示例：
  ```ts
  // 正确
  const res = await api.get('/api/assets/list', { params })

  // 错误（不要省略 /api）
  const res = await api.get('/assets/list', { params })
  ```

## 2. API封装规范
- 统一使用项目中已封装的 `api` 实例（通常位于 `src/api/index.ts` 或 `src/utils/request.ts`）。
- 不要直接使用 `axios` 创建新实例。
- 请求方法统一使用：
  - `GET`、`POST`、`PUT`、`DELETE`
  - 复杂查询优先使用 `POST` + 请求体。

## 3. 类型定义要求
- 所有请求和响应必须定义 **TypeScript 接口**（放在 `src/types/` 或对应模块的 `types.ts` 中）。
- 命名规范：
  - 请求：`ListAssetsParams`、`CreateAssetRequest`
  - 响应：`ListAssetsResponse`、`ApiResponse<T>`
- 示例：
  ```ts
  export interface ListAssetsParams {
    isTop?: 'Y' | 'N'
    beginTime?: string
    endTime?: string
    pageNum?: number
    pageSize?: number
  }

  export interface ListAssetsResponse {
    code: number
    data: {
      list: AssetItem[]
      total: number
    }
    message: string
  }
  ```

## 4. 错误处理规范
- 使用统一的错误处理拦截器（项目已有全局拦截）。
- 业务错误统一抛出或使用 `ElMessage.error()` / `a-message`。
- 网络错误、超时、401/403 等状态码必须有清晰的用户提示。
- 重要操作（删除、收藏等）必须添加二次确认。

## 5. 其他最佳实践
- 使用 `async/await`，避免 `.then().catch()` 链式调用。
- Loading 状态统一使用 `loading` 变量 + Ant Design `a-spin`。
- 分页相关参数统一使用 `pageNum` / `pageSize`。
- 所有API调用必须添加中文注释说明用途。

**所有前端与后端交互的代码必须严格遵守以上规则。**