13 KiB

Raw Blame History

PDF报告系统

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/database.py](file://backend/app/database.py) - [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/user.py](file://backend/app/models/user.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/api/deps.py](file://backend/app/api/deps.py) - [backend/README.md](file://backend/README.md) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx) - [frontend/README.md](file://frontend/README.md)

简介

PDF报告系统是一个基于FastAPI和Next.js构建的品牌曝光度分析平台。该系统能够监控特定品牌的在线提及情况，通过集成多个AI平台进行智能分析，并提供CSV和PDF格式的详细报告。

系统的核心功能包括：

多平台AI查询集成（文心一言、通义千问、讯飞星火等）
实时品牌曝光监测
自动化报告生成
数据可视化分析
用户权限管理和订阅系统

项目结构

该项目采用前后端分离的架构设计，主要分为以下层次：

graph TB
subgraph "前端层 (Frontend)"
FE_Next[Next.js 应用]
FE_Components[React 组件]
FE_API[API 客户端]
end
subgraph "后端层 (Backend)"
BE_FastAPI[FastAPI 应用]
BE_API[API 路由层]
BE_Services[业务逻辑层]
BE_Workers[后台任务]
BE_Models[数据模型层]
end
subgraph "基础设施"
DB[(PostgreSQL 数据库)]
Redis[(Redis 缓存)]
Storage[(文件存储)]
end
FE_Next --> BE_FastAPI
BE_FastAPI --> BE_API
BE_API --> BE_Services
BE_Services --> BE_Workers
BE_Services --> BE_Models
BE_Models --> DB
BE_Workers --> Redis
BE_API --> Storage

图表来源

章节来源

核心组件

1. 报告导出服务

报告导出服务是系统的核心功能模块，负责生成CSV和PDF格式的分析报告。

classDiagram
class ReportService {
+export_citations_csv(db, user_id, query_id) str
+export_citations_pdf(db, user_id, query_id) bytes
-verify_query_ownership(db, query_id, user_id) Query
}
class CitationEngine {
+execute_single_platform(keyword, platform, target_brand, brand_aliases) dict
+execute_query(query, db) CitationRecord[]
-BrandMatcher matcher
-CompetitorDetector detector
}
class QueryScheduler {
+start() void
+check_and_execute_queries() void
+check_and_execute_pending_tasks() void
-engine CitationEngine
}
ReportService --> CitationEngine : "使用"
QueryScheduler --> CitationEngine : "调度执行"
CitationEngine --> BrandMatcher : "创建"
CitationEngine --> CompetitorDetector : "创建"

图表来源

2. 数据模型架构

系统采用ORM模型设计，主要包含用户、查询词、引用记录等核心实体。

erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
int max_queries
boolean is_active
boolean is_admin
timestamp created_at
timestamp updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
json brand_aliases
json platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
boolean cited
int citation_position
text citation_text
json competitor_brands
text raw_response
float confidence
string match_type
timestamp queried_at
}
QUERIES ||--o{ CITATION_RECORDS : "包含"
USERS ||--o{ QUERIES : "拥有"

图表来源

章节来源

架构概览

系统采用分层架构设计，确保各层职责清晰、耦合度低。

graph TB
subgraph "表现层"
UI[前端界面]
Charts[数据图表]
end
subgraph "API网关"
Auth[认证中间件]
RateLimit[限流中间件]
Logging[日志中间件]
end
subgraph "业务逻辑层"
Reports[报告服务]
Queries[查询服务]
Citations[引用服务]
end
subgraph "数据访问层"
ORM[SQLAlchemy ORM]
Cache[Redis缓存]
end
subgraph "外部服务"
Platforms[AI平台适配器]
Storage[文件存储]
end
UI --> Auth
Auth --> Reports
Auth --> Queries
Auth --> Citations
Reports --> ORM
Queries --> ORM
Citations --> ORM
ORM --> Cache
Reports --> Platforms
Reports --> Storage

图表来源

详细组件分析

报告导出API流程

报告导出功能通过RESTful API提供，支持CSV和PDF两种格式的导出。

sequenceDiagram
participant Client as 客户端
participant API as 报告API
participant Service as 报告服务
participant Engine as 引擎
participant DB as 数据库
participant File as 文件系统
Client->>API : GET /api/v1/reports/export/pdf?query_id=xxx
API->>Service : export_citations_pdf(db, user_id, query_id)
Service->>Service : 验证查询所有权
Service->>DB : 查询引用记录
DB-->>Service : 返回记录数据
Service->>Engine : 生成PDF报告
Engine->>Engine : 处理数据格式化
Engine->>File : 生成PDF文件
File-->>Engine : 返回PDF字节流
Engine-->>Service : 返回PDF内容
Service-->>API : 返回PDF响应
API-->>Client : 下载PDF文件

图表来源

引擎执行流程

引用检测引擎负责协调多个AI平台进行品牌曝光监测。

flowchart TD
Start([开始执行查询]) --> LoadQuery[加载查询配置]
LoadQuery --> InitMatcher[初始化品牌匹配器]
InitMatcher --> CheckPlatforms{检查平台列表}
CheckPlatforms --> |有平台| CreateTask[创建查询任务]
CheckPlatforms --> |无平台| Error[抛出异常]
CreateTask --> SetRunning[设置任务状态为运行中]
SetRunning --> ExecutePlatform[执行单平台查询]
ExecutePlatform --> PlatformSuccess{平台执行成功?}
PlatformSuccess --> |是| ProcessResult[处理查询结果]
PlatformSuccess --> |否| HandleError[处理执行错误]
ProcessResult --> SaveRecord[保存引用记录]
HandleError --> SaveErrorRecord[保存错误记录]
SaveRecord --> NextPlatform{还有平台?}
SaveErrorRecord --> NextPlatform
NextPlatform --> |是| ExecutePlatform
NextPlatform --> |否| UpdateQuery[更新查询状态]
UpdateQuery --> Complete([执行完成])
Error --> Complete

图表来源

调度器工作流程

系统使用APScheduler实现定时任务调度，确保查询任务按时执行。

sequenceDiagram
participant Scheduler as 调度器
participant DB as 数据库
participant Engine as 引擎
participant Task as 查询任务
loop 每小时检查
Scheduler->>DB : 查询到期的查询任务
DB-->>Scheduler : 返回待执行任务
alt 有待执行任务
Scheduler->>Engine : 执行查询任务
Engine->>Task : 处理单个平台
Task-->>Engine : 返回执行结果
Engine-->>Scheduler : 返回处理结果
else 无待执行任务
Scheduler->>Scheduler : 等待下个小时
end
end
loop 每分钟检查
Scheduler->>DB : 查询遗留的pending任务
DB-->>Scheduler : 返回遗留任务
alt 有遗留任务
Scheduler->>Engine : 执行遗留任务
Engine-->>Scheduler : 返回执行结果
else 无遗留任务
Scheduler->>Scheduler : 继续等待
end
end

图表来源

章节来源

依赖关系分析

系统采用模块化设计，各组件间依赖关系清晰：

graph TB
subgraph "核心依赖"
FastAPI[FastAPI 0.109+]
SQLAlchmey[SQLAlchemy 2.0+]
AsyncPG[asyncpg]
APScheduler[APScheduler 3.10+]
end
subgraph "数据处理"
FPDF[fpdf2 2.7+]
CSV[Python CSV模块]
JSON[Python JSON模块]
end
subgraph "前端集成"
NextJS[Next.js 14]
Recharts[Recharts]
TailwindCSS[TailwindCSS 3.4]
end
subgraph "工具库"
Pydantic[Pydantic 2.0+]
Bcrypt[Bcrypt]
JWT[jose/cryptography]
end
Backend --> FastAPI
Backend --> SQLAlchmey
Backend --> AsyncPG
Backend --> APScheduler
Backend --> FPDF
Backend --> CSV
Backend --> JSON
Frontend --> NextJS
Frontend --> Recharts
Frontend --> TailwindCSS
Backend --> Pydantic
Backend --> Bcrypt
Backend --> JWT

图表来源

backend/README.md:236-257

章节来源

性能考虑

数据库优化

系统在关键查询字段上建立了适当的索引以提升查询性能：

citation_records.query_id: 支持按查询词快速检索引用记录
citation_records.queried_at: 支持按时间范围查询
citation_records.platform: 支持按平台过滤
queries.user_id: 支持按用户快速定位查询词
queries.status: 支持按状态过滤活跃查询

缓存策略

系统采用多层缓存策略：

Redis缓存用于临时数据存储和会话管理
前端组件缓存减少重复渲染
API响应缓存降低数据库压力

异步处理

系统广泛采用异步编程模式：

数据库操作使用异步连接池
文件生成采用异步I/O
API请求处理支持并发处理

故障排除指南

常见问题及解决方案

报告导出失败
- 检查查询ID是否有效且属于当前用户
- 确认目标查询词仍处于激活状态
- 验证系统中是否有可用的引用记录
PDF生成异常
- 检查系统中是否存在可用的中文字体文件
- 确认fpdf2库版本兼容性
- 验证磁盘空间充足
定时任务执行失败
- 检查数据库连接状态
- 验证Redis服务可用性
- 确认AI平台API密钥配置正确
API认证问题
- 验证JWT令牌有效性
- 检查用户账户状态
- 确认权限配置正确

章节来源

结论

PDF报告系统是一个功能完整、架构清晰的品牌曝光度分析平台。系统通过集成多个AI平台，实现了智能化的品牌监测和分析功能。其模块化设计确保了良好的可维护性和扩展性，异步架构保证了系统的高性能和高可用性。

主要优势包括：

完整的前后端分离架构
多平台AI集成能力
灵活的报告生成功能
完善的权限管理和安全机制
可扩展的调度系统

未来可以考虑的功能增强：

支持更多AI平台集成
增强数据分析算法
优化移动端用户体验
添加实时通知功能
扩展报告格式支持

13 KiB Raw Blame History Unescape Escape

PDF报告系统

目录

简介

项目结构

核心组件

1. 报告导出服务

2. 数据模型架构

架构概览

详细组件分析

报告导出API流程

引擎执行流程

调度器工作流程

依赖关系分析

性能考虑

数据库优化

缓存策略

异步处理

故障排除指南

常见问题及解决方案

结论

13 KiB

Raw Blame History