# PDF报告系统

<cite>
**本文档引用的文件**
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

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

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

## 项目结构

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

```mermaid
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
```

**图表来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [frontend/lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)

**章节来源**
- [backend/README.md:148-199](file://backend/README.md#L148-L199)
- [frontend/README.md:68-101](file://frontend/README.md#L68-L101)

## 核心组件

### 1. 报告导出服务

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

```mermaid
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 : "创建"
```

**图表来源**
- [backend/app/services/citation.py:343-556](file://backend/app/services/citation.py#L343-L556)
- [backend/app/workers/citation_engine.py:161-330](file://backend/app/workers/citation_engine.py#L161-L330)
- [backend/app/workers/scheduler.py:27-183](file://backend/app/workers/scheduler.py#L27-L183)

### 2. 数据模型架构

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

```mermaid
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 : "拥有"
```

**图表来源**
- [backend/app/models/user.py:11-48](file://backend/app/models/user.py#L11-L48)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [backend/app/models/citation_record.py:11-44](file://backend/app/models/citation_record.py#L11-L44)

**章节来源**
- [backend/app/models/user.py:1-48](file://backend/app/models/user.py#L1-L48)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)

## 架构概览

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

```mermaid
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
```

**图表来源**
- [backend/app/main.py:39-84](file://backend/app/main.py#L39-L84)
- [backend/app/api/reports.py:1-75](file://backend/app/api/reports.py#L1-L75)
- [backend/app/services/citation.py:1-556](file://backend/app/services/citation.py#L1-L556)

## 详细组件分析

### 报告导出API流程

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

```mermaid
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文件
```

**图表来源**
- [backend/app/api/reports.py:51-75](file://backend/app/api/reports.py#L51-L75)
- [backend/app/services/citation.py:343-467](file://backend/app/services/citation.py#L343-L467)

### 引擎执行流程

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

```mermaid
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
```

**图表来源**
- [backend/app/workers/citation_engine.py:177-254](file://backend/app/workers/citation_engine.py#L177-L254)
- [backend/app/workers/citation_engine.py:256-287](file://backend/app/workers/citation_engine.py#L256-L287)

### 调度器工作流程

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

```mermaid
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
```

**图表来源**
- [backend/app/workers/scheduler.py:60-94](file://backend/app/workers/scheduler.py#L60-L94)
- [backend/app/workers/scheduler.py:102-173](file://backend/app/workers/scheduler.py#L102-L173)

**章节来源**
- [backend/app/api/reports.py:1-75](file://backend/app/api/reports.py#L1-L75)
- [backend/app/workers/citation_engine.py:1-330](file://backend/app/workers/citation_engine.py#L1-L330)
- [backend/app/workers/scheduler.py:1-183](file://backend/app/workers/scheduler.py#L1-L183)

## 依赖关系分析

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

```mermaid
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](file://backend/README.md#L236-L257)

**章节来源**
- [backend/README.md:201-208](file://backend/README.md#L201-L208)
- [backend/README.md:236-257](file://backend/README.md#L236-L257)

## 性能考虑

### 数据库优化

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

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

### 缓存策略

系统采用多层缓存策略：
- Redis缓存用于临时数据存储和会话管理
- 前端组件缓存减少重复渲染
- API响应缓存降低数据库压力

### 异步处理

系统广泛采用异步编程模式：
- 数据库操作使用异步连接池
- 文件生成采用异步I/O
- API请求处理支持并发处理

## 故障排除指南

### 常见问题及解决方案

1. **报告导出失败**
   - 检查查询ID是否有效且属于当前用户
   - 确认目标查询词仍处于激活状态
   - 验证系统中是否有可用的引用记录

2. **PDF生成异常**
   - 检查系统中是否存在可用的中文字体文件
   - 确认fpdf2库版本兼容性
   - 验证磁盘空间充足

3. **定时任务执行失败**
   - 检查数据库连接状态
   - 验证Redis服务可用性
   - 确认AI平台API密钥配置正确

4. **API认证问题**
   - 验证JWT令牌有效性
   - 检查用户账户状态
   - 确认权限配置正确

**章节来源**
- [backend/app/services/citation.py:343-467](file://backend/app/services/citation.py#L343-L467)
- [backend/app/workers/scheduler.py:174-178](file://backend/app/workers/scheduler.py#L174-L178)

## 结论

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

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

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