# 前端 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 示例

```javascript
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 示例

```javascript
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 示例

```javascript
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`：

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

### 远程服务器

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

或使用环境变量：

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

## API 响应格式

### 成功响应

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

### 错误响应

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

## 认证说明

### Token 管理

登录后将 token 存储到 localStorage：

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

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

### 请求拦截器

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

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

## 注意事项

1. **路径区分**：Extract Service 和 Graph Service 的模板、项目接口路径不同
   - Extract 模板：`/api/v1/templates`
   - Graph 模板：`/api/v1/graph/templates`

2. **文件上传**：使用 FormData，设置正确的 Content-Type

3. **错误处理**：响应拦截器已处理基本错误，业务层需要 try-catch

4. **Token 刷新**：accessToken 过期时使用 refreshToken 刷新

## 后端服务端口

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

## 更新日志

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