前端 API 适配指南

后端 API 路径变更说明

2026-02-12 更新

由于后端 graph-service 控制器重命名以避免 Bean 冲突，API 路径已更新：

Graph Service 路径变更

所有 graph-service 的接口路径已从 /api/v1/ 改为 /api/v1/graph/：

旧路径 → 新路径

/api/v1/templates → /api/v1/graph/templates
/api/v1/projects → /api/v1/graph/projects
/api/v1/reports → /api/v1/graph/reports
/api/v1/attachments → /api/v1/graph/attachments

前端 API 模块说明

1. Extract Service API（数据提取服务）

路径前缀: /api/v1/extract/

templateApi - 提取模板管理
variableApi - 变量配置管理
generationApi - 生成任务管理
projectApi - 提取项目管理
sourceFileApi - 来源文件管理
sourceDocumentApi - 来源文档管理

2. Graph Service API（图谱服务）

路径前缀: /api/v1/graph/

knowledgeGraphApi - 知识图谱查询
graphTemplateApi - 图谱模板管理（新增）
graphProjectApi - 图谱项目管理（新增）
graphReportApi - 图谱报告管理（新增）

3. Document Service API（文档服务）

路径前缀: /api/v1/documents/

documentApi - 文档管理
parseApi - 文档解析

4. Auth Service API（认证服务）

路径前缀: /auth/

authApi - 用户认证和授权

5. Task Center API（任务中心）

路径前缀: /api/v1/tasks/

taskCenterApi - 任务管理

使用示例

Extract Service 示例

import { templateApi, generationApi } from '@/api'

// 获取模板列表
const templates = await templateApi.list(1, 20)

// 创建生成任务
const generation = await generationApi.create({
  templateId: 'xxx',
  documentIds: ['doc1', 'doc2']
})

// 执行提取
await generationApi.execute(generation.id)

Graph Service 示例

import { knowledgeGraphApi, graphReportApi } from '@/api'

// 获取文档图谱
const graph = await knowledgeGraphApi.getDocumentGraph('doc-id')

// 创建图谱报告
const report = await graphReportApi.create({
  title: '项目报告',
  projectId: 'project-id'
})

// 上传报告附件
await graphReportApi.uploadAttachment(report.id, file, '附件名称')

Document Service 示例

import { documentApi, parseApi } from '@/api'

// 上传并解析文档
const result = await parseApi.upload(file, templateId)

// 获取文档结构化内容
const structured = await documentApi.getStructured(documentId)

// 标记实体
await documentApi.markEntity(documentId, blockId, {
  elementIndex: 0,
  startOffset: 10,
  endOffset: 20,
  entityType: 'person'
})

开发环境配置

本地开发

编辑 vite.config.js：

const API_SERVER = 'http://localhost:18520'

远程服务器

const API_SERVER = 'http://服务器IP:18520'

或使用环境变量：

API_SERVER=http://服务器IP:18520 npm run dev

API 响应格式

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    // 实际数据
  }
}

错误响应

{
  "code": 500,
  "msg": "错误信息",
  "data": null
}

认证说明

Token 管理

登录后将 token 存储到 localStorage：

const { accessToken, refreshToken } = await authApi.login({
  username: 'user',
  password: 'pass'
})

localStorage.setItem('accessToken', accessToken)
localStorage.setItem('refreshToken', refreshToken)

请求拦截器

在 src/api/index.js 中已配置请求拦截器，可以自动添加 token：

api.interceptors.request.use(config => {
  const token = localStorage.getItem('accessToken')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

注意事项

路径区分：Extract Service 和 Graph Service 的模板、项目接口路径不同
- Extract 模板：/api/v1/templates
- Graph 模板：/api/v1/graph/templates
文件上传：使用 FormData，设置正确的 Content-Type
错误处理：响应拦截器已处理基本错误，业务层需要 try-catch
Token 刷新：accessToken 过期时使用 refreshToken 刷新

后端服务端口

主服务: 18520 (lingyue-starter)
前端开发服务: 5173 (vite)

更新日志

2026-02-12

✅ 更新 graph-service API 路径为 /api/v1/graph/*
✅ 新增 graphTemplateApi、graphProjectApi、graphReportApi
✅ 更新 vite.config.js 默认使用本地后端
✅ 添加图谱报告附件上传接口

API_GUIDE.md 4.5 KB История Исходник