# 前端接口对接文档

## 通用说明

### 1. 接口响应格式

所有接口统一返回以下格式：
```typescript
interface Response<T> {
    success: boolean;      // 请求是否成功
    code: number;         // 状态码，200表示成功，其他表示失败
    message: string;      // 提示信息
    data?: T;            // 响应数据，可选
}
```

### 2. 分页请求参数
```typescript
interface PageQuery {
    pageNum: number;      // 页码，从1开始
    pageSize: number;     // 每页大小
    sortField?: string;   // 排序字段，可选
    sortOrder?: 'asc' | 'desc';  // 排序方式，可选
}
```

### 3. 分页响应格式
```typescript
interface PageResponse<T> {
    content: T[];         // 数据列表
    totalElements: number;// 总记录数
    totalPages: number;   // 总页数
    size: number;        // 每页大小
    number: number;      // 当前页码（从0开始）
    first: boolean;      // 是否第一页
    last: boolean;       // 是否最后一页
    empty: boolean;      // 是否为空
}
```

## 通用接口

### 1. 基础CRUD接口
所有实体都支持以下基础操作接口：

#### 1.1 分页查询
```typescript
GET /api/v1/{module}/page

请求参数：PageQuery & {
    // 其他查询条件，根据具体模块定义
}

响应结果：Response<PageResponse<T>>
```

#### 1.2 列表查询
```typescript
GET /api/v1/{module}/list

请求参数：{
    // 查询条件，根据具体模块定义
}

响应结果：Response<T[]>
```

#### 1.3 获取详情
```typescript
GET /api/v1/{module}/{id}

响应结果：Response<T>
```

#### 1.4 创建
```typescript
POST /api/v1/{module}

请求参数：{
    // 创建参数，根据具体模块定义
}

响应结果：Response<T>
```

#### 1.5 更新
```typescript
PUT /api/v1/{module}/{id}

请求参数：{
    // 更新参数，根据具体模块定义
}

响应结果：Response<T>
```

#### 1.6 删除
```typescript
DELETE /api/v1/{module}/{id}

响应结果：Response<void>
```

#### 1.7 批量删除
```typescript
DELETE /api/v1/{module}/batch

请求参数：{
    ids: number[];       // ID列表
}

响应结果：Response<void>
```

#### 1.8 导出数据
```typescript
GET /api/v1/{module}/export

请求参数：{
    // 查询条件，根据具体模块定义
}

响应结果：二进制文件流
```

### 2. 树形结构接口
对于树形结构的数据（如部门、菜单等），还支持以下接口：

#### 2.1 获取树形数据
```typescript
GET /api/v1/{module}/tree

响应结果：Response<TreeNode[]>

interface TreeNode {
    id: number;
    parentId: number | null;
    children: TreeNode[];
    // 其他字段根据具体模块定义
}
```

### 3. 状态管理接口
对于需要状态管理的数据（如租户、用户等），还支持以下接口：

#### 3.1 获取状态
```typescript
GET /api/v1/{module}/{id}/enabled

响应结果：Response<boolean>
```

#### 3.2 更新状态
```typescript
PUT /api/v1/{module}/{id}/enabled

请求参数：
enabled=true    // 是否启用

响应结果：Response<void>
```

## 错误处理

### 1. 错误码说明
- 200：成功
- 400：请求参数错误
- 401：未认证
- 403：无权限
- 404：资源不存在
- 500：服务器内部错误

### 2. 错误响应示例
```json
{
    "success": false,
    "code": 400,
    "message": "请求参数错误",
    "data": {
        "field": "name",
        "message": "名称不能为空"
    }
}
```

## 接口调用示例

### TypeScript 示例
```typescript
// 定义接口返回类型
interface User {
    id: number;
    username: string;
    enabled: boolean;
}

// 分页查询
async function getUserList(query: PageQuery & { username?: string }) {
    const response = await axios.get<Response<PageResponse<User>>>('/api/v1/user/page', {
        params: query
    });
    return response.data;
}

// 创建用户
async function createUser(user: Omit<User, 'id'>) {
    const response = await axios.post<Response<User>>('/api/v1/user', user);
    return response.data;
}

// 更新状态
async function updateUserStatus(id: number, enabled: boolean) {
    const response = await axios.put<Response<void>>(`/api/v1/user/${id}/enabled`, null, {
        params: { enabled }
    });
    return response.data;
}
```

### Vue3 + TypeScript 示例
```typescript
// 在组件中使用
import { ref, onMounted } from 'vue';

export default defineComponent({
    setup() {
        const userList = ref<User[]>([]);
        const total = ref(0);
        const loading = ref(false);

        const queryList = async (query: PageQuery) => {
            try {
                loading.value = true;
                const response = await getUserList(query);
                if (response.success) {
                    userList.value = response.data.content;
                    total.value = response.data.totalElements;
                }
            } finally {
                loading.value = false;
            }
        };

        onMounted(() => {
            queryList({
                pageNum: 1,
                pageSize: 10
            });
        });

        return {
            userList,
            total,
            loading,
            queryList
        };
    }
});
```

## 注意事项

1. 请求头要求
```typescript
{
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ${token}'  // JWT认证token
}
```

2. 日期时间格式
- 请求参数：使用ISO 8601格式（YYYY-MM-DDTHH:mm:ss.sssZ）
- 响应数据：统一返回ISO 8601格式

3. 文件上传
- 使用multipart/form-data格式
- 文件大小限制：10MB

4. 接口版本
- 所有接口统一使用v1版本
- URL格式：/api/v1/{module}/{resource}

5. 安全性
- 所有接口都需要JWT认证
- Token过期时间：2小时
- 需要定期刷新Token

6. 错误处理
- 统一使用axios拦截器处理错误
- 401错误跳转到登录页
- 其他错误统一提示