Home Verkennen Help
Inloggen
hewensong
/
lingyue-zhibao
1
0
Vork 0
Bestanden Issues 0 Pull-aanvragen 0 Wiki
Boom: 271ad9af74
Aftakkingen Labels
lingyue-zhibao
/
docs
/
backend-api-summary.md

backend-api-summary.md 19 KB
Geschiedenis Ruwe

后端已实现的接口汇总

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

目录

  1. auth-service (认证服务)
  2. document-service (文档服务) ⚠️ 已废弃
  3. ai-service (AI服务)
  4. parse-service (解析服务)
  5. extract-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