finyx_frontend/docs/API.md

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请求

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请求

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请求

import { put } from '@/request/http'

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

DELETE请求

import { del } from '@/request/http'

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

文件导出

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)

流式请求

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: 无此权限

错误处理示例

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)

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)

• 获取验证码

使用示例

完整示例：获取知识库列表

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)
  }
}

完整示例：创建智能体

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
  }
}

完整示例：文件上传

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流式请求

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 中：

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支持取消操作