355 lines
7.8 KiB
Markdown
355 lines
7.8 KiB
Markdown
# 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支持取消操作
|
||
|