# API 接口文档

## 概述

本文档说明项目中API的使用方式和接口定义。

## API结构

项目中的API分为三个层次：
1. **API定义层** (`src/api/`): 业务API封装
2. **服务层** (`src/servers/`): 自动生成的API服务
3. **请求层** (`src/request/`): HTTP请求封装

## 请求封装

### HTTP请求 (`src/request/http.ts`)

#### 基础配置
- **BaseURL**: `/dada`
- **超时时间**: 60000ms (60秒)
- **认证方式**: Token + TenantId

#### 请求头自动添加
所有请求会自动添加以下请求头：
- `Token`: 用户认证Token
- `TenantId`: 租户ID
- `AuthId`: 客户端ID (固定值)
- `ApplicationId`: 应用ID (固定值: 3)

#### 请求方法

##### GET请求
```typescript
import { get } from '@/request/http'

// 基本用法
const data = await get('/api/endpoint', { param1: 'value1' })

// 带loading
const data = await get('/api/endpoint', params, loadingRef)

// 自定义请求头
const data = await get('/api/endpoint', params, loadingRef, customHeaders)

// 自定义超时
const data = await get('/api/endpoint', params, loadingRef, headers, 30000)
```

##### POST请求
```typescript
import { post } from '@/request/http'

// 基本用法
const result = await post('/api/endpoint', { key: 'value' })

// 带查询参数
const result = await post('/api/endpoint', bodyData, queryParams)

// 带loading
const result = await post('/api/endpoint', bodyData, queryParams, loadingRef)
```

##### PUT请求
```typescript
import { put } from '@/request/http'

const result = await put('/api/endpoint', updateData, queryParams, loadingRef)
```

##### DELETE请求
```typescript
import { del } from '@/request/http'

const result = await del('/api/endpoint', queryParams, bodyData, loadingRef)
```

##### 文件导出
```typescript
import { exportExcel, exportFile, exportExcelPost } from '@/request/http'

// 导出Excel (GET)
await exportExcel('文件名.xlsx', '/api/export', params, loadingRef)

// 导出文件 (GET)
await exportFile('文件名.zip', '/api/export', params, loadingRef)

// 导出Excel (POST)
await exportExcelPost('文件名.xlsx', '/api/export', queryParams, bodyData, loadingRef)
```

##### 流式请求
```typescript
import { postStream } from '@/request/http'

const response = await postStream('/api/stream', { data: 'value' })
```

### 其他请求封装

#### 审核请求 (`src/request/reviewHttp.ts`)
专门用于审核模块的HTTP请求封装，baseURL为 `/ai-review/api`

#### 写作请求 (`src/request/writingHttp.ts`)
专门用于写作模块的HTTP请求封装，baseURL为 `/ai-doc/api`

#### 可取消请求 (`src/request/fetchWithAbort.ts`)
支持取消的请求封装，用于SSE等场景

## 错误处理

### 认证错误码
以下错误码表示认证失效，会自动清除token并跳转登录：
- `11011`: 未能读取到有效Token
- `11012`: Token无效
- `11013`: Token已过期
- `11014`: Token已被顶下线
- `11015`: Token已被踢下线
- `11016`: 已被冻结

### 权限错误码
- `11051`: 无此权限

### 错误处理示例
```typescript
try {
  const data = await get('/api/endpoint')
  // 处理成功数据
} catch (error) {
  // 错误已在拦截器中处理，这里可以做一些额外处理
  console.error('请求失败:', error)
}
```

## API定义层 (`src/api/`)

### 用户认证API (`api/dada.ts`)
用户登录、登出、获取用户信息等

### Finyx Bot API (`api/finyxbot.ts`)
```typescript
import { aiChat } from '@/api/finyxbot'

// AI助手对话 (SSE)
const abortController = aiChat({
  message: '你好',
  chatId: 'xxx'
})
```

### 审核API (`api/review.ts`)
审核相关的API接口

### 写作API (`api/writing.ts`)
写作相关的API接口

## 服务层 (`src/servers/`)

### 基础服务 (`servers/base/api/`)

#### 组织管理 (`zuzhi.ts`)
- 组织CRUD操作
- 组织树查询

#### 员工管理 (`yuangong.ts`)
- 员工信息管理
- 员工查询

#### 角色管理 (`jiaose.ts`)
- 角色CRUD操作

#### 岗位管理 (`gangwei.ts`)
- 岗位管理

#### 文件上传 (`wenjianshangchuan.ts`)
- 文件上传接口

#### 业务附件 (`yewufujian.ts`)
- 业务附件管理

### Finyx业务服务 (`servers/finyx/api/`)

#### 知识库 (`zhishiku.ts`)
- 知识库CRUD
- 知识库查询

#### 文档 (`wendang.ts`)
- 文档管理
- 文档查询

#### 智能体 (`zhinengti.ts`)
- 智能体创建
- 智能体配置
- 智能体查询

#### 智能写作 (`zhinengxiezuo.ts`)
- 写作任务创建
- 写作内容生成

#### 智能问答对话记录 (`zhinengtiduihuajilu.ts`)
- 对话记录查询
- 对话历史管理

#### 机器人服务 (`jiqirenfuwu.ts`)
- 机器人服务管理

### 认证服务 (`servers/oauth/api/`)

#### 登录登出 (`denglutuichuzhuce.ts`)
- 用户登录
- 用户登出
- 用户注册

#### 用户信息 (`yonghujibenxinxi.ts`)
- 获取用户基本信息

#### 验证码 (`yanzhengma.ts`)
- 获取验证码

## 使用示例

### 完整示例：获取知识库列表
```typescript
import { get } from '@/request/http'
import { ref } from 'vue'

const loading = ref(false)
const knowledgeList = ref([])

async function fetchKnowledgeList() {
  try {
    const data = await get('/finyx/knowledge/list', {
      page: 1,
      size: 10
    }, loading)
    knowledgeList.value = data
  } catch (error) {
    console.error('获取知识库列表失败:', error)
  }
}
```

### 完整示例：创建智能体
```typescript
import { post } from '@/request/http'
import { ref } from 'vue'

const loading = ref(false)

async function createAgent(agentData: any) {
  try {
    const result = await post('/finyx/agent/create', {
      name: agentData.name,
      description: agentData.description,
      modelId: agentData.modelId
    }, null, loading)
    return result
  } catch (error) {
    console.error('创建智能体失败:', error)
    throw error
  }
}
```

### 完整示例：文件上传
```typescript
import { post } from '@/request/http'
import { ref } from 'vue'

const loading = ref(false)

async function uploadFile(file: File) {
  const formData = new FormData()
  formData.append('file', file)
  
  try {
    const result = await post('/base/file/upload', formData, null, loading, {
      'Content-Type': 'multipart/form-data'
    })
    return result
  } catch (error) {
    console.error('文件上传失败:', error)
    throw error
  }
}
```

### 完整示例：SSE流式请求
```typescript
import { aiChat } from '@/api/finyxbot'

let abortController: AbortController | null = null

async function startChat(message: string) {
  // 取消之前的请求
  if (abortController) {
    abortController.abort()
  }
  
  abortController = aiChat({
    message,
    chatId: 'xxx'
  })
  
  // 处理流式响应
  // ... 处理逻辑
}

function stopChat() {
  if (abortController) {
    abortController.abort()
    abortController = null
  }
}
```

## 代理配置

开发环境的API代理配置在 `vite.config.ts` 中：

```typescript
proxyConf['/ai-review/api'] = {
  target: 'https://finyxdev.datacubeworld.com',
  changeOrigin: true,
  rewrite: (path) => path.replace(ENV.VITE_BASE_PATH, '/')
}

proxyConf['/ai-doc/api'] = {
  target: 'https://finyxdev.datacubeworld.com',
  changeOrigin: true,
  rewrite: (path) => path.replace(ENV.VITE_BASE_PATH, '/')
}

proxyConf['/finyx-bot/api'] = {
  target: 'https://finyxdev.datacubeworld.com',
  changeOrigin: true,
  rewrite: (path) => path.replace(ENV.VITE_BASE_PATH, '/')
}

proxyConf['/dada'] = {
  target: 'https://finyxdev.datacubeworld.com',
  changeOrigin: true,
  rewrite: (path) => path.replace(ENV.VITE_BASE_PATH, '/')
}
```

## 注意事项

1. **Token管理**: Token会自动从store中获取，无需手动添加
2. **错误处理**: 所有认证错误会自动处理，无需手动跳转
3. **Loading状态**: 可以传入ref来控制loading状态
4. **超时处理**: 默认超时60秒，可以自定义
5. **文件上传**: 需要设置正确的Content-Type
6. **流式请求**: 使用fetchWithAbort支持取消操作