# 后端已实现的接口汇总

**统计时间**: 2026-02-12  
**接口总数**: 约 185+ 个  
**微服务数量**: 7 个

---

## 目录

1. [auth-service (认证服务)](#1-auth-service-认证服务)
2. [~~document-service (文档服务)~~ ⚠️ 已废弃](#2-document-service-文档服务--已废弃)
3. [ai-service (AI服务)](#3-ai-service-ai服务)
4. [parse-service (解析服务)](#4-parse-service-解析服务)
5. [extract-service (数据提取服务)](#5-extract-service-数据提取服务)
6. [graph-service (图谱服务) ✅ 推荐使用](#6-graph-service-图谱服务)

---

## 1. auth-service (认证服务)

### AuthController
**路径**: `backend/auth-service/src/main/java/com/lingyue/auth/controller/AuthController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录 |
| POST | `/auth/logout` | 用户登出 |
| POST | `/auth/refresh` | 刷新Token |
| GET | `/auth/me` | 获取当前用户信息 |
| PUT | `/auth/profile` | 更新用户资料 |
| PUT | `/auth/password` | 修改密码 |

---

## 2. document-service (文档服务) ⚠️ 已废弃

> **⚠️ 重要提示**: 
> - **document-service 是老逻辑，已被 graph-service 替代**
> - **与 graph-service 存在功能冲突，建议使用 graph-service**
> - 以下接口仅供参考，新功能开发请使用 graph-service

### DocumentController
**路径**: `backend/document-service/src/main/java/com/lingyue/document/controller/DocumentController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/documents` | 获取文档列表（分页） |
| GET | `/api/v1/documents/{documentId}` | 获取文档详情 |
| GET | `/api/v1/documents/{documentId}/text` | 获取文档文本内容 |
| GET | `/api/v1/documents/{documentId}/parse-status` | 获取解析状态 |
| PUT | `/api/v1/documents/{documentId}` | 更新文档信息 |
| DELETE | `/api/v1/documents/{documentId}` | 删除文档（级联删除） |
| POST | `/api/v1/documents/batch-delete` | 批量删除文档 |
| GET | `/api/v1/documents/{documentId}/elements` | 获取文档结构化内容 |
| GET | `/api/v1/documents/{documentId}/images` | 获取文档图片列表 |
| GET | `/api/v1/documents/{documentId}/tables` | 获取文档表格列表 |
| GET | `/api/v1/documents/{documentId}/toc` | 获取文档目录 |

### StructuredDocumentController
**路径**: `backend/document-service/src/main/java/com/lingyue/document/controller/StructuredDocumentController.java`  
**设计**: 参考飞书文档设计，文档由Block树组成，实体作为TextElement嵌入

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/documents/{documentId}/structured` | 获取结构化文档 |
| PUT | `/api/v1/documents/{documentId}/blocks/{blockId}/elements` | 更新块元素 |
| POST | `/api/v1/documents/{documentId}/blocks` | 创建块 |
| DELETE | `/api/v1/documents/{documentId}/blocks/{blockId}` | 删除块 |
| POST | `/api/v1/documents/{documentId}/blocks/{blockId}/mark-entity` | 标记实体 |
| DELETE | `/api/v1/documents/{documentId}/blocks/{blockId}/entities/{entityId}` | 取消实体标记 |
| PUT | `/api/v1/documents/{documentId}/blocks/{blockId}/entities/{entityId}` | 更新实体类型 |
| POST | `/api/v1/documents/{documentId}/blocks/{blockId}/entities/{entityId}/confirm` | 确认实体 |
| POST | `/api/v1/documents/{documentId}/blocks/batch` | 批量保存块 |

### ReportController
**路径**: `backend/document-service/src/main/java/com/lingyue/document/controller/ReportController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/reports/{reportId}` | 获取报告详情 |
| POST | `/api/v1/reports` | 新建报告 |
| GET | `/api/v1/reports` | 我的文档列表（分页） |
| PUT | `/api/v1/reports/{reportId}` | 更新报告 |
| DELETE | `/api/v1/reports/{reportId}` | 删除报告 |

### ReportAttachmentController
**路径**: `backend/document-service/src/main/java/com/lingyue/document/controller/ReportAttachmentController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/reports/{reportId}/attachments` | 获取报告附件列表 |
| POST | `/api/v1/reports/{reportId}/attachments` | 添加材料（上传文件） |
| DELETE | `/api/v1/reports/{reportId}/attachments/{attachmentId}` | 删除附件 |
| PUT | `/api/v1/reports/{reportId}/attachments/{attachmentId}` | 更新附件信息 |
| GET | `/api/v1/reports/{reportId}/attachments/{attachmentId}/download` | 下载附件 |

---

## 3. ai-service (AI服务)

### AIController
**路径**: `backend/ai-service/src/main/java/com/lingyue/ai/controller/AIController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/ai/extract-elements` | 提取要素（待实现） |
| POST | `/ai/polish-text` | 文本润色（待实现） |
| POST | `/ai/generate-prompt` | 生成Prompt（待实现） |

### NerController
**路径**: `backend/ai-service/src/main/java/com/lingyue/ai/controller/NerController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/ner/extract` | 提取实体（同步） |
| POST | `/api/ner/extract/async` | 异步提取实体 |
| POST | `/api/ner/relations` | 提取关系 |
| POST | `/api/ner/document/{documentId}` | 对文档执行NER并保存 |
| POST | `/api/ner/document/{documentId}/async` | 异步对文档执行NER |

---

## 4. parse-service (解析服务)

### ParseController
**路径**: `backend/parse-service/src/main/java/com/lingyue/parse/controller/ParseController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/parse/start` | 启动解析任务（传入文件路径） |
| POST | `/api/v1/parse/start/{documentId}` | 启动解析任务（自动获取路径） |
| GET | `/api/v1/parse/status/{documentId}` | 查询解析任务状态 |
| GET | `/api/v1/parse/structured/{documentId}` | 获取Word文档结构化内容 |
| GET | `/api/v1/parse/elements/{documentId}` | 获取已保存的文档结构化元素 |
| GET | `/api/v1/parse/elements/{documentId}/images` | 获取文档图片元素 |
| GET | `/api/v1/parse/elements/{documentId}/tables` | 获取文档表格元素 |

### ParseTaskCenterController
**路径**: `backend/parse-service/src/main/java/com/lingyue/parse/controller/ParseTaskCenterController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tasks/list` | 查询解析任务列表 |
| GET | `/api/v1/tasks/{taskId}/detail` | 查询解析任务详情 |
| GET | `/api/v1/tasks/by-document/{documentId}` | 根据文档ID查询解析任务详情 |
| GET | `/api/v1/tasks/statistics` | 查询解析任务统计信息 |
| DELETE | `/api/v1/tasks/{taskId}` | 删除解析任务 |

### TaskProgressController (内部接口)
**路径**: `backend/parse-service/src/main/java/com/lingyue/parse/controller/TaskProgressController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/internal/task-progress/structured/{documentId}` | 更新结构化解析进度 |
| POST | `/api/internal/task-progress/ner/{documentId}` | 更新NER进度 |
| POST | `/api/internal/task-progress/graph/{documentId}` | 更新图构建进度 |
| POST | `/api/internal/task-progress/fail/{documentId}` | 标记任务失败 |
| POST | `/api/internal/task-progress/complete/{documentId}` | 标记任务完成 |

### FileUploadController
**路径**: `backend/parse-service/src/main/java/com/lingyue/parse/controller/FileUploadController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/parse/upload` | 上传文件（PDF、Word、Excel、图片） |
| GET | `/api/v1/parse/file/exists` | 检查文件是否存在 |
| DELETE | `/api/v1/parse/file` | 删除文件 |

### ImageController
**路径**: `backend/parse-service/src/main/java/com/lingyue/parse/controller/ImageController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/files/images/{documentId}/{imageName}` | 获取文档图片 |

---

## 5. extract-service (数据提取服务)

### TemplateController
**路径**: `backend/extract-service/src/main/java/com/lingyue/extract/controller/TemplateController.java`

#### 模板管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/templates` | 创建模板 |
| GET | `/api/v1/templates/{id}` | 获取模板详情 |
| GET | `/api/v1/templates` | 获取模板列表（分页） |
| GET | `/api/v1/templates/accessible` | 获取可访问的模板 |
| GET | `/api/v1/templates/search` | 搜索模板 |
| GET | `/api/v1/templates/stats` | 获取统计数据 |
| PUT | `/api/v1/templates/{id}` | 更新模板 |
| DELETE | `/api/v1/templates/{id}` | 删除模板 |
| POST | `/api/v1/templates/{id}/publish` | 发布模板 |
| POST | `/api/v1/templates/{id}/archive` | 归档模板 |
| POST | `/api/v1/templates/{id}/duplicate` | 复制模板 |

#### 来源文件管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/templates/{templateId}/source-files` | 添加来源文件定义 |
| GET | `/api/v1/templates/{templateId}/source-files` | 获取来源文件定义列表 |
| PUT | `/api/v1/templates/source-files/{id}` | 更新来源文件定义 |
| DELETE | `/api/v1/templates/source-files/{id}` | 删除来源文件定义 |
| POST | `/api/v1/templates/{templateId}/source-files/reorder` | 重排序来源文件 |

#### 变量管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/templates/{templateId}/variables` | 添加变量 |
| GET | `/api/v1/templates/{templateId}/variables` | 获取变量列表 |
| GET | `/api/v1/templates/{templateId}/variables/grouped` | 获取变量按类别分组 |
| GET | `/api/v1/templates/variables/{id}` | 获取变量详情 |
| PUT | `/api/v1/templates/variables/{id}` | 更新变量 |
| DELETE | `/api/v1/templates/variables/{id}` | 删除变量 |
| POST | `/api/v1/templates/variables/{id}/preview` | 预览变量提取结果 |
| POST | `/api/v1/templates/{templateId}/variables/reorder` | 重排序变量 |

### GenerationController
**路径**: `backend/extract-service/src/main/java/com/lingyue/extract/controller/GenerationController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/generations` | 创建生成任务 |
| GET | `/api/v1/generations/{id}` | 获取生成任务详情 |
| GET | `/api/v1/generations` | 获取生成任务列表（分页） |
| GET | `/api/v1/generations/recent` | 获取最近的生成任务 |
| GET | `/api/v1/generations/template/{templateId}` | 按模板获取生成任务 |
| DELETE | `/api/v1/generations/{id}` | 删除生成任务 |
| POST | `/api/v1/generations/{id}/execute` | 执行提取 |
| GET | `/api/v1/generations/{id}/progress` | 获取执行进度 |
| PUT | `/api/v1/generations/{id}/variables/{variableName}` | 更新变量值 |
| POST | `/api/v1/generations/{id}/confirm` | 确认并生成文档 |
| GET | `/api/v1/generations/{id}/download` | 下载生成的文档 |
| GET | `/api/v1/generations/{id}/download-info` | 获取下载信息 |

### ProjectController
**路径**: `backend/extract-service/src/main/java/com/lingyue/extract/controller/ProjectController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/extract/projects` | 创建项目 |
| GET | `/api/v1/extract/projects/{id}` | 获取项目详情 |
| GET | `/api/v1/extract/projects` | 分页查询项目列表 |
| GET | `/api/v1/extract/projects/by-status/{status}` | 按状态查询项目列表 |
| PUT | `/api/v1/extract/projects/{id}` | 更新项目 |
| DELETE | `/api/v1/extract/projects/{id}` | 删除项目 |
| POST | `/api/v1/extract/projects/{id}/archive` | 归档项目 |
| GET | `/api/v1/extract/projects/statistics` | 获取用户项目统计 |

### SourceDocumentController
**路径**: `backend/extract-service/src/main/java/com/lingyue/extract/controller/SourceDocumentController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/extract/projects/{projectId}/documents` | 添加来源文档 |
| POST | `/api/v1/extract/projects/{projectId}/documents/batch` | 批量添加来源文档 |
| GET | `/api/v1/extract/projects/{projectId}/documents` | 获取项目的来源文档列表 |
| GET | `/api/v1/extract/projects/{projectId}/documents/{id}` | 获取来源文档详情 |
| PUT | `/api/v1/extract/projects/{projectId}/documents/{id}` | 更新来源文档 |
| DELETE | `/api/v1/extract/projects/{projectId}/documents/{id}` | 移除来源文档 |
| POST | `/api/v1/extract/projects/{projectId}/documents/reorder` | 调整来源文档顺序 |

### HealthController
**路径**: `backend/extract-service/src/main/java/com/lingyue/extract/controller/HealthController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/extract/health` | 健康检查 |
| GET | `/api/v1/extract/info` | 服务信息 |

---

## 6. graph-service (图谱服务) ✅ 推荐使用

> **✅ 推荐**: graph-service 是当前主要使用的服务，替代了 document-service 的功能

### GraphReportController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/GraphReportController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/graph/reports` | 获取报告列表（分页） |
| GET | `/api/v1/graph/reports/{id}` | 获取报告详情 |
| POST | `/api/v1/graph/reports` | 创建报告 |
| PUT | `/api/v1/graph/reports/{id}` | 更新报告 |
| DELETE | `/api/v1/graph/reports/{id}` | 删除报告 |
| GET | `/api/v1/graph/reports/{id}/values` | 获取报告要素值列表 |
| PUT | `/api/v1/graph/reports/{reportId}/values/{elementKey}` | 更新报告要素值 |
| PUT | `/api/v1/graph/reports/{id}/values/batch` | 批量更新报告要素值 |
| POST | `/api/v1/graph/reports/{id}/copy` | 复制报告 |
| POST | `/api/v1/graph/reports/{id}/export` | 导出报告 |
| GET | `/api/v1/graph/reports/{id}/preview` | 生成报告预览 |

### GraphTemplateController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/GraphTemplateController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/graph/templates` | 获取模板列表（分页） |
| GET | `/api/v1/graph/templates/{id}` | 获取模板详情 |
| POST | `/api/v1/graph/templates` | 创建模板 |
| PUT | `/api/v1/graph/templates/{id}` | 更新模板 |
| DELETE | `/api/v1/graph/templates/{id}` | 删除模板 |
| GET | `/api/v1/graph/templates/{templateId}/elements` | 获取模板要素列表 |
| POST | `/api/v1/graph/templates/{templateId}/elements` | 添加要素到模板 |
| PUT | `/api/v1/graph/templates/{templateId}/elements/reorder` | 调整要素顺序 |
| POST | `/api/v1/graph/templates/{id}/create-report` | 基于模板创建报告 |

### GraphProjectController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/GraphProjectController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/graph/projects` | 获取项目列表（分页） |
| GET | `/api/v1/graph/projects/{id}` | 获取项目详情 |
| POST | `/api/v1/graph/projects` | 创建项目 |
| PUT | `/api/v1/graph/projects/{id}` | 更新项目 |
| DELETE | `/api/v1/graph/projects/{id}` | 删除项目 |
| POST | `/api/v1/graph/projects/{id}/archive` | 归档项目 |
| POST | `/api/v1/graph/projects/{id}/copy` | 复制项目 |

### GraphAttachmentController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/GraphAttachmentController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/graph/reports/{reportId}/attachments/upload` | 上传附件 |
| GET | `/api/v1/graph/reports/{reportId}/attachments` | 获取报告附件列表 |
| GET | `/api/v1/graph/attachments/{id}` | 获取附件详情 |
| POST | `/api/v1/graph/attachments/{id}/parse` | 触发附件解析 |
| PUT | `/api/v1/graph/attachments/{id}` | 更新附件 |
| DELETE | `/api/v1/graph/attachments/{id}` | 删除附件 |
| PUT | `/api/v1/graph/reports/{reportId}/attachments/reorder` | 调整附件顺序 |

### RuleController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/RuleController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/reports/{reportId}/rules` | 获取报告规则列表 |
| GET | `/api/v1/rules/{id}` | 获取规则详情 |
| POST | `/api/v1/reports/{reportId}/rules` | 创建规则 |
| PUT | `/api/v1/rules/{id}` | 更新规则 |
| DELETE | `/api/v1/rules/{id}` | 删除规则 |
| POST | `/api/v1/rules/{id}/execute` | 执行规则 |
| POST | `/api/v1/reports/{reportId}/rules/execute-all` | 批量执行规则 |

### EntityController
**路径**: `backend/graph-service/src/main/java/com/lingyue/graph/controller/EntityController.java`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/attachments/{attachmentId}/entities` | 获取附件实体列表 |
| GET | `/api/v1/reports/{reportId}/entities` | 获取报告所有实体 |
| GET | `/api/v1/entities/{id}` | 获取实体详情 |
| PUT | `/api/v1/entities/{id}` | 更新实体 |
| POST | `/api/v1/entities/merge` | 合并实体 |

---

## 功能模块总结

### ✅ 已实现的核心功能

1. **用户认证与授权**
   - 注册、登录、登出
   - Token刷新
   - 用户信息管理

2. **文档管理**
   - 文档上传、解析、删除
   - 结构化内容提取
   - 图片、表格、目录提取

3. **结构化文档编辑**
   - 飞书风格的Block树结构
   - 实体标注与管理
   - 块级编辑操作

4. **NER与知识图谱**
   - 命名实体识别（同步/异步）
   - 关系抽取
   - 实体合并与管理

5. **报告模板系统**
   - 模板创建、编辑、发布
   - 来源文件定义
   - 变量配置与预览

6. **数据提取规则**
   - 项目管理
   - 来源文档管理
   - 生成任务执行

7. **图谱服务**
   - 项目、报告、模板管理
   - 附件上传与解析
   - 规则引擎
   - 实体图谱

### 📊 服务架构

```
lingyue-zhibao/
├── auth-service      (认证服务)
├── document-service  (文档服务)
├── ai-service        (AI服务)
├── parse-service     (解析服务)
├── extract-service   (数据提取服务)
├── graph-service     (图谱服务)
└── common           (公共模块)
```

### 🔗 服务间调用关系

- **parse-service** → **document-service**: 解析完成后更新文档状态
- **ai-service** → **graph-service**: NER结果保存到图数据库
- **extract-service** → **document-service**: 获取文档内容进行提取
- **graph-service** → **parse-service**: 触发附件解析

---

## 注意事项

1. **⚠️ 服务冲突**: 
   - **document-service 是老逻辑，已被 graph-service 替代**
   - document-service 中的 ReportController 和 ReportAttachmentController 与 graph-service 功能重复
   - **新功能开发请使用 graph-service**，document-service 仅保留用于兼容性

2. **服务迁移建议**:
   - 报告管理: `document-service` → `graph-service` (GraphReportController)
   - 附件管理: `document-service` → `graph-service` (GraphAttachmentController)
   - 项目管理: `extract-service` → `graph-service` (GraphProjectController)
   - 模板管理: `extract-service` → `graph-service` (GraphTemplateController)

3. **内部接口**: `TaskProgressController` 中的接口为内部服务间调用接口

4. **待实现功能**: `AIController` 中的部分接口标记为待实现

5. **权限控制**: 大部分接口需要通过 `Authorization` header 或 `X-User-Id` header 传递用户信息

6. **文件上传**: 支持 PDF、Word、Excel、图片等多种格式

---

**最后更新**: 2026-02-12