# API 接口实现规范

## 概述

本系统采用基于 axios 的 HTTP 客户端来与后端进行通信，所有 API 请求都经过统一的封装和管理。该文档旨在说明如何在系统中添加和使用新的 API 接口。

## 核心架构

### 1. 请求客户端 (request.ts)

系统在 `packages/app-client/src/services/request.ts` 文件中创建了一个全局的 axios 实例，用于处理所有 HTTP 请求。

```typescript
import axios from "axios";
import Taro from "@tarojs/taro";

const request = axios.create({
  baseURL: process.env.TARO_API_DOMAIN,
});
```

该实例具有以下特性：
- 设置了基础 URL，从环境变量 `TARO_API_DOMAIN` 获取
- 包含请求拦截器，自动添加认证信息（如 saToken 和角色信息）
- 包含响应拦截器，处理通用的响应逻辑（如权限验证、错误提示等）

### 2. 请求拦截器

在发送请求前，系统会自动添加以下头部信息：
- `saToken`: 用户的身份认证令牌，从本地存储中获取
- `Xh-Role-Slug`: 用户当前角色标识，从本地存储中获取

### 3. 响应拦截器

响应拦截器负责处理通用的业务逻辑：
- 成功响应时检查是否需要更新本地存储的认证信息
- 错误响应时根据错误码显示相应提示或执行特定操作（如 401 时跳转登录页）

## API 接口组织

### 1. 模块划分

API 接口按照业务模块进行组织，每个模块对应一个文件：
- 所有业务 API 存放在 `packages/app-client/src/services/business/` 目录下
- 每个文件代表一个业务模块（如 [platform.ts](file:///D:/xinfaleisheng/ERPTurbo_Client/packages/app-client/src/services/business/platform.ts)、[user.ts](file:///D:/xinfaleisheng/ERPTurbo_Client/packages/app-client/src/services/business/user.ts) 等）
- 每个模块导出一组相关的 API 函数

### 2. 接口定义格式

每个 API 函数遵循统一的格式：

```typescript
/** 接口说明 GET|POST|PUT|DELETE /api/path */
export async function apiFunctionName(
  // 参数类型定义
  params: BusinessAPI.paramsType,
  options?: { [key: string]: any },
) {
  return request<BusinessAPI.ResponseType>("/api/path", {
    method: "GET|POST|PUT|DELETE",
    // 根据请求方法设置 headers、params 或 data
    ...(options || {}),
  });
}
```

### 3. 模块导出

所有业务模块在 `packages/app-client/src/services/business/index.ts` 中统一导出：

```typescript
import * as moduleName from "./moduleName";
export default {
  moduleName,
  // ...
};
```

## 添加新接口步骤

### 1. 确定业务模块

首先确定新接口属于哪个业务模块，如果现有模块都不合适，则需要创建新的模块文件。

### 2. 定义数据类型

在 `typings.d.ts` 文件中定义接口所需的请求参数类型和响应数据类型。

### 3. 编写接口函数

在对应的模块文件中添加新的接口函数，参考以下模板：

```typescript
/** 接口说明 动作 /api/path */
export async function functionName(
  // 根据实际参数类型修改
  body: BusinessAPI.RequestType,
  options?: { [key: string]: any },
) {
  // 根据实际响应类型修改
  return request<BusinessAPI.ResponseType>("/api/path", {
    method: "POST", // 根据实际情况修改为 POST/GET/PUT/DELETE
    headers: {
      "Content-Type": "application/json",
    },
    data: body, // GET 请求使用 params，其他请求使用 data
    ...(options || {}),
  });
}
```

### 4. 导出模块

确保在 `packages/app-client/src/services/business/index.ts` 中导出了包含新接口的模块。

## 使用示例

在组件或其他服务中使用 API 接口：

```typescript
import businessServices from "@/services/business";

// 调用平台列表接口
const {data: {data: platformList}} = await businessServices.platform.listPlatform({
	// 参数
});

// 调用创建平台接口
const {data: {data: platform}} = await businessServices.platform.createPlatform({
	// 数据体
});
```

## 最佳实践

1. **类型安全**: 始终使用 TypeScript 类型定义请求参数和响应数据
2. **错误处理**: 在调用 API 的地方适当处理可能发生的错误
3. **命名规范**: 接口函数名应该清晰表达其功能，通常采用动词+名词的形式
4. **注释说明**: 每个接口函数都需要添加注释说明接口用途和路径
5. **统一管理**: 所有 API 接口都应该按业务模块分类管理
6. **避免重复**: 相似的接口可以复用已有模式，保持一致性