# API SDK 使用指南

## 🚀 概述

本项目提供了两种API调用方式：

1. **原始SDK** (`sdk.gen.ts`) - 直接API调用，无认证
2. **认证SDK** (`authenticated-sdk.ts`) - 自动添加Token的API调用

## 📝 使用方法

### 1. 无认证的API调用（如登录、获取验证码）

```typescript
import { api } from '@/lib/api/authenticated-sdk';

// 获取验证码 - 不需要token
const captchaResponse = await api.getCaptcha();

// 用户登录 - 不需要token
const loginResponse = await api.login({
  body: {
    identifier: 'admin',
    password: 'password123',
    captcha_id: 'captcha-id',
    captcha_text: 'ABCD'
  }
});
```

### 2. 需要认证的API调用

```typescript
import { authenticatedSdk } from '@/lib/api/authenticated-sdk';

// 获取当前用户信息 - 自动添加token
const userResponse = await authenticatedSdk.getCurrentUser();

// 获取用户列表 - 自动添加token
const usersResponse = await authenticatedSdk.getUsers({
  query: { page: 1, size: 10 }
});

// 创建用户 - 自动添加token
const createResponse = await authenticatedSdk.createUser({
  body: {
    username: 'newuser',
    email: 'user@example.com'
  }
});
```

## 🔧 核心特性

### 自动Token管理
- 自动从localStorage获取token
- 自动添加到请求头 `Authorization: Bearer {token}`
- 请求日志记录

### 401错误处理
- 检测401响应自动清除本地认证信息
- 自动跳转到登录页面

### 类型安全
- 完整的TypeScript类型支持
- 智能代码提示

## 📋 API方法列表

### 认证相关
- `api.getCaptcha()` - 获取验证码
- `api.login(options)` - 用户登录
- `api.logout(options)` - 用户登出
- `authenticatedSdk.getCurrentUser()` - 获取当前用户
- `authenticatedSdk.refreshToken()` - 刷新token

### 用户管理
- `authenticatedSdk.getUsers()` - 获取用户列表
- `authenticatedSdk.getUser(options)` - 获取单个用户
- `authenticatedSdk.createUser(options)` - 创建用户
- `authenticatedSdk.updateUser(options)` - 更新用户
- `authenticatedSdk.deleteUser(options)` - 删除用户

### 部门管理
- `authenticatedSdk.getDepartments()` - 获取部门列表
- `authenticatedSdk.getDepartment(options)` - 获取单个部门
- `authenticatedSdk.createDepartment(options)` - 创建部门
- `authenticatedSdk.updateDepartment(options)` - 更新部门
- `authenticatedSdk.deleteDepartment(options)` - 删除部门

### 租户管理
- `authenticatedSdk.getTenants()` - 获取租户列表
- `authenticatedSdk.getTenant(options)` - 获取单个租户
- `authenticatedSdk.getCurrentTenant()` - 获取当前租户信息

## ⚠️ 重要说明

1. **API生成覆盖**: `sdk.gen.ts` 和 `client.gen.ts` 会被 `npm run api:generate` 覆盖
2. **安全文件**: `authenticated-sdk.ts` 不会被覆盖，可安全使用
3. **Token存储**: Token存储在localStorage的user对象中
4. **代理配置**: 所有请求通过Next.js代理到真实API地址

## 🔄 迁移指南

### 从原始SDK迁移到认证SDK

```typescript
// ❌ 旧方式 - 可能缺少认证
import { getUsersApiV1UsersGet } from '@/lib/api/sdk.gen';
const response = await getUsersApiV1UsersGet();

// ✅ 新方式 - 自动添加认证
import { authenticatedSdk } from '@/lib/api/authenticated-sdk';
const response = await authenticatedSdk.getUsers();
```

### 混合使用场景

```typescript
import { api, authenticatedSdk } from '@/lib/api/authenticated-sdk';

// 登录 - 不需要认证
const loginResponse = await api.login({ body: loginData });

// 登录成功后，获取用户信息 - 需要认证
const userInfo = await authenticatedSdk.getCurrentUser();
```