16 KiB

Raw Permalink Blame History

报告导出接口

**本文档引用的文件** - [backend/app/api/reports.py](file://backend/app/api/reports.py) - [backend/app/services/citation.py](file://backend/app/services/citation.py) - [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/models/query_task.py](file://backend/app/models/query_task.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py) - [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py) - [backend/app/main.py](file://backend/app/main.py) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/app/(dashboard)/dashboard/reports/page.tsx](file://frontend/app/(dashboard)/dashboard/reports/page.tsx)

简介

本文件面向“报告导出系统”的使用者与维护者，提供完整的CSV格式数据导出API文档。内容涵盖：

导出流程与参数配置
报告生成触发机制（手动触发、定时触发）
数据筛选条件与输出格式选项
导出进度监控、错误处理与文件下载
报告模板定制、数据格式转换与性能优化建议

项目结构

后端采用FastAPI + SQLAlchemy异步ORM，前端基于Next.js。导出能力通过独立的报告路由暴露，并由服务层负责数据聚合与CSV生成。

graph TB
subgraph "前端"
FE_API["前端API封装<br/>frontend/lib/api.ts"]
FE_PAGE["报告页面<br/>frontend/app/(dashboard)/dashboard/reports/page.tsx"]
end
subgraph "后端"
MAIN["应用入口<br/>backend/app/main.py"]
ROUTER["报告路由<br/>backend/app/api/reports.py"]
SERVICE["导出服务<br/>backend/app/services/citation.py"]
MODELS["模型定义<br/>models/*.py"]
WORKERS["工作流与调度<br/>workers/*.py"]
end
FE_PAGE --> FE_API
FE_API --> ROUTER
ROUTER --> SERVICE
SERVICE --> MODELS
WORKERS --> MODELS
MAIN --> ROUTER
MAIN --> WORKERS

图表来源

章节来源

核心组件

报告导出路由：提供CSV导出接口，接收查询词ID并返回流式CSV响应。
导出服务：验证用户与查询所有权，查询引用记录并生成CSV字符串。
数据模型：查询、引用记录、查询任务等，支撑筛选与统计。
引擎与调度：定时检查到期查询并执行，支持手动触发。
前端集成：提供查询词选择、导出按钮与下载逻辑。

章节来源

架构总览

下图展示从前端发起导出请求到后端生成CSV并返回下载的完整链路。

sequenceDiagram
participant FE as "前端页面<br/>page.tsx"
participant API as "前端API封装<br/>lib/api.ts"
participant FAST as "报告路由<br/>reports.py"
participant SVC as "导出服务<br/>services/citation.py"
participant DB as "数据库<br/>SQLAlchemy"
FE->>API : "调用导出接口"
API->>FAST : "GET /api/v1/reports/export/csv?query_id=..."
FAST->>SVC : "export_citations_csv(db, user_id, query_id)"
SVC->>DB : "查询引用记录"
DB-->>SVC : "返回记录集合"
SVC-->>FAST : "返回CSV字符串"
FAST-->>API : "StreamingResponse(csv)"
API-->>FE : "下载CSV文件"

图表来源

详细组件分析