# 后端系统架构

<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/auth.py](file://backend/app/api/auth.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
- [backend/app/api/admin.py](file://backend/app/api/admin.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
- [backend/app/api/subscriptions.py](file://backend/app/api/subscriptions.py)
- [backend/app/middleware/logging_middleware.py](file://backend/app/middleware/logging_middleware.py)
- [backend/app/middleware/rate_limit.py](file://backend/app/middleware/rate_limit.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/schemas/subscription.py](file://backend/app/schemas/subscription.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py)
- [backend/app/models/subscription.py](file://backend/app/models/subscription.py)
- [backend/app/models/query_task.py](file://backend/app/models/query_task.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/services/admin.py](file://backend/app/services/admin.py)
- [backend/app/services/subscription.py](file://backend/app/services/subscription.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)
</cite>

## 更新摘要
**所做更改**
- 新增中间件系统章节，包含限流中间件和日志中间件
- 新增管理员服务和API路由，支持系统管理和用户管理
- 新增订阅服务和API路由，支持套餐管理和订阅管理
- 新增PDF报告服务，支持CSV和PDF格式导出
- 更新项目结构图，反映新增模块和文件
- 更新数据模型关系图，包含订阅和查询任务模型
- 更新架构总览图，展示新增中间件和服务层

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [中间件系统](#中间件系统)
7. [管理员服务](#管理员服务)
8. [订阅服务](#订阅服务)
9. [报告服务](#报告服务)
10. [依赖关系分析](#依赖关系分析)
11. [性能考量](#性能考量)
12. [故障排查指南](#故障排查指南)
13. [结论](#结论)
14. [附录](#附录)

## 引言
本文件为 GEO 平台后端系统的架构文档，基于 FastAPI 构建，采用异步 SQLAlchemy ORM、APScheduler 定时任务与多平台适配器模式，实现查询词管理、引用检测与报告统计等功能。文档覆盖应用配置、中间件、路由组织、生命周期管理、数据库连接与 ORM、异步处理、认证与权限控制、API 设计与错误处理、系统监控与日志、性能优化策略，并给出架构决策的技术背景与权衡。

**更新** 本次更新反映了应用的重大功能扩展，包括中间件系统的引入、管理员管理功能、订阅管理系统和报告导出功能。

## 项目结构
后端采用分层与功能域结合的组织方式：
- 应用入口与生命周期：app/main.py
- 配置中心：app/config.py
- 数据库与依赖注入：app/database.py
- API 层：app/api/ 下按功能模块划分（auth、queries、citations、admin、reports、subscriptions、deps）
- 中间件层：app/middleware/（logging_middleware、rate_limit）
- 模型层：app/models/（SQLAlchemy ORM 映射）
- 服务层：app/services/（business logic encapsulation）
- 工作器与调度：app/workers/（APScheduler 调度器、引用检测引擎、平台适配器）
- 测试：tests/（pytest）

```mermaid
graph TB
subgraph "应用入口"
MAIN["app/main.py"]
end
subgraph "配置与数据库"
CFG["app/config.py"]
DB["app/database.py"]
end
subgraph "中间件层"
LOGMW["middleware/logging_middleware.py"]
RATEMW["middleware/rate_limit.py"]
end
subgraph "API 层"
AUTH["api/auth.py"]
QUERIES["api/queries.py"]
CITATIONS["api/citations.py"]
ADMIN["api/admin.py"]
REPORTS["api/reports.py"]
SUBSCRIPTIONS["api/subscriptions.py"]
DEPS["api/deps.py"]
end
subgraph "模型与服务"
MODEL_USER["models/user.py"]
MODEL_QUERY["models/query.py"]
MODEL_CIT["models/citation_record.py"]
MODEL_SUB["models/subscription.py"]
MODEL_TASK["models/query_task.py"]
SVC_AUTH["services/auth.py"]
SVC_ADMIN["services/admin.py"]
SVC_SUB["services/subscription.py"]
end
subgraph "工作器与调度"
SCHED["workers/scheduler.py"]
ENGINE["workers/citation_engine.py"]
end
MAIN --> LOGMW
MAIN --> RATEMW
MAIN --> AUTH
MAIN --> QUERIES
MAIN --> CITATIONS
MAIN --> ADMIN
MAIN --> REPORTS
MAIN --> SUBSCRIPTIONS
AUTH --> SVC_AUTH
ADMIN --> SVC_ADMIN
SUBSCRIPTIONS --> SVC_SUB
AUTH --> DB
QUERIES --> DB
CITATIONS --> DB
ADMIN --> DB
REPORTS --> DB
SUBSCRIPTIONS --> DB
DEPS --> DB
SVC_AUTH --> CFG
SVC_ADMIN --> CFG
SVC_SUB --> CFG
SCHED --> DB
SCHED --> ENGINE
ENGINE --> MODEL_QUERY
ENGINE --> MODEL_CIT
DB --> CFG
```

**图表来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/middleware/logging_middleware.py:1-24](file://backend/app/middleware/logging_middleware.py#L1-L24)
- [backend/app/middleware/rate_limit.py:1-83](file://backend/app/middleware/rate_limit.py#L1-L83)
- [backend/app/api/admin.py:1-108](file://backend/app/api/admin.py#L1-L108)
- [backend/app/api/reports.py:1-75](file://backend/app/api/reports.py#L1-L75)
- [backend/app/api/subscriptions.py:1-77](file://backend/app/api/subscriptions.py#L1-L77)
- [backend/app/services/admin.py:1-188](file://backend/app/services/admin.py#L1-L188)
- [backend/app/services/subscription.py:1-155](file://backend/app/services/subscription.py#L1-L155)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)

## 核心组件
- 应用入口与生命周期：通过 lifespan 钩子在启动时初始化模型与调度器，在关闭时优雅停止。
- 中间件：启用 CORS、限流中间件和日志中间件，提供安全防护和性能监控。
- 路由组织：按模块拆分，统一前缀与标签，便于 API 文档生成与维护。
- 数据库：异步 SQLAlchemy 引擎与会话工厂，依赖注入式获取会话。
- 认证与权限：OAuth2 密码流 + JWT，依赖注入解析当前用户，未授权时抛出 401。
- 引擎与调度：APScheduler 定时扫描到期查询，调用 CitationEngine 执行并持久化结果。

**更新** 新增中间件系统提供限流和日志功能，增强系统的安全性和可观测性。

**章节来源**
- [backend/app/main.py:13-48](file://backend/app/main.py#L13-L48)
- [backend/app/database.py:6-29](file://backend/app/database.py#L6-L29)
- [backend/app/api/deps.py:13-43](file://backend/app/api/deps.py#L13-L43)

## 架构总览
系统采用"API 层-中间件层-服务层-模型层-基础设施"的分层架构，配合异步 I/O 与定时任务，实现高并发与可扩展的查询与检测能力。

```mermaid
graph TB
CLIENT["客户端/前端"]
FASTAPI["FastAPI 应用<br/>lifespan/CORS"]
MIDDLEWARE["中间件层<br/>限流/日志"]
ROUTER_AUTH["认证路由"]
ROUTER_QUERIES["查询路由"]
ROUTER_CIT["引用路由"]
ROUTER_ADMIN["管理员路由"]
ROUTER_REPORTS["报告路由"]
ROUTER_SUB["订阅路由"]
DEPS["依赖注入<br/>OAuth2/JWT 解析"]
SVC_AUTH["认证服务<br/>密码哈希/JWT"]
SVC_ADMIN["管理员服务<br/>用户管理/统计"]
SVC_SUB["订阅服务<br/>套餐管理/订阅流程"]
DB["异步数据库<br/>Session 工厂"]
SCHED["查询调度器<br/>APScheduler"]
ENGINE["引用检测引擎<br/>平台适配器"]
CLIENT --> FASTAPI
FASTAPI --> MIDDLEWARE
MIDDLEWARE --> ROUTER_AUTH
MIDDLEWARE --> ROUTER_QUERIES
MIDDLEWARE --> ROUTER_CIT
MIDDLEWARE --> ROUTER_ADMIN
MIDDLEWARE --> ROUTER_REPORTS
MIDDLEWARE --> ROUTER_SUB
ROUTER_AUTH --> DEPS
ROUTER_QUERIES --> DEPS
ROUTER_CIT --> DEPS
ROUTER_ADMIN --> DEPS
ROUTER_REPORTS --> DEPS
ROUTER_SUB --> DEPS
ROUTER_AUTH --> SVC_AUTH
ROUTER_ADMIN --> SVC_ADMIN
ROUTER_SUB --> SVC_SUB
ROUTER_QUERIES --> DB
ROUTER_CIT --> DB
ROUTER_REPORTS --> DB
DEPS --> DB
SVC_AUTH --> DB
SVC_ADMIN --> DB
SVC_SUB --> DB
SCHED --> DB
SCHED --> ENGINE
ENGINE --> DB
```

**图表来源**
- [backend/app/main.py:24-48](file://backend/app/main.py#L24-L48)
- [backend/app/middleware/rate_limit.py:10-83](file://backend/app/middleware/rate_limit.py#L10-L83)
- [backend/app/middleware/logging_middleware.py:8-24](file://backend/app/middleware/logging_middleware.py#L8-L24)
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)
- [backend/app/services/auth.py:16-69](file://backend/app/services/auth.py#L16-L69)
- [backend/app/services/admin.py:14-188](file://backend/app/services/admin.py#L14-L188)
- [backend/app/services/subscription.py:69-155](file://backend/app/services/subscription.py#L69-L155)
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)

## 详细组件分析

### 应用入口与生命周期
- 使用 lifespan 钩子在启动时导入模型并启动查询调度器；在关闭时优雅停止调度器与引擎资源。
- 注册 CORS 中间件，允许前端跨域访问。
- 统一注册认证、查询、引用、报告、订阅、管理员路由，并为"立即执行"路由复用同一前缀。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant App as "FastAPI 应用"
participant Life as "lifespan"
participant Sched as "查询调度器"
Client->>App : 启动请求
App->>Life : 进入 lifespan
Life->>Sched : start()
App-->>Client : 200 OK
Note over App,Sched : 应用运行中
Client->>App : 关闭请求
App->>Life : 退出 lifespan
Life->>Sched : shutdown()
App-->>Client : 200 OK
```

**图表来源**
- [backend/app/main.py:13-22](file://backend/app/main.py#L13-L22)
- [backend/app/workers/scheduler.py:86-90](file://backend/app/workers/scheduler.py#L86-L90)

**章节来源**
- [backend/app/main.py:13-48](file://backend/app/main.py#L13-L48)

### 配置与数据库
- 配置项：数据库连接、Redis、JWT 秘钥与过期时间、浏览器路径、平台 API Key 等。
- 数据库：异步引擎、会话工厂、基础模型类；提供依赖注入函数以获取会话。
- 会话行为：非自动提交/刷新/回滚，显式管理事务边界。

```mermaid
flowchart TD
Start(["应用启动"]) --> LoadCfg["加载配置"]
LoadCfg --> InitEngine["创建异步引擎"]
InitEngine --> InitSession["创建会话工厂"]
InitSession --> RegisterDep["注册 get_db 依赖"]
RegisterDep --> Ready(["就绪"])
```

**图表来源**
- [backend/app/config.py:4-17](file://backend/app/config.py#L4-L17)
- [backend/app/database.py:6-29](file://backend/app/database.py#L6-L29)

**章节来源**
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)

### 认证系统
- 登录：校验邮箱与密码，成功则签发 JWT。
- 注册：检查邮箱唯一性，哈希密码后创建用户。
- 当前用户：通过 OAuth2 密码流获取令牌，解码 JWT 提取用户 ID，查询数据库返回当前用户。
- 错误处理：未通过凭据验证时返回 401。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Auth as "认证路由"
participant Svc as "认证服务"
participant DB as "数据库"
Client->>Auth : POST /api/v1/auth/login
Auth->>Svc : authenticate_user(email, password)
Svc->>DB : 查询用户
DB-->>Svc : 用户对象
Svc-->>Auth : 用户或空
Auth-->>Client : {access_token, user} 或 401
Client->>Auth : GET /api/v1/auth/me (携带 Bearer Token)
Auth->>Svc : verify_token(token)
Svc-->>Auth : 载荷
Auth->>DB : 查询用户 by id
DB-->>Auth : 用户对象
Auth-->>Client : 用户信息
```

**图表来源**
- [backend/app/api/auth.py:13-43](file://backend/app/api/auth.py#L13-L43)
- [backend/app/services/auth.py:37-69](file://backend/app/services/auth.py#L37-L69)
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/schemas/auth.py:1-34](file://backend/app/schemas/auth.py#L1-L34)
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/api/deps.py:1-43](file://backend/app/api/deps.py#L1-L43)

### 查询与引用 API
- 查询 API：支持分页、创建、读取、更新、删除，均需当前用户权限。
- 引用 API：支持分页查询、统计、立即执行查询任务（返回任务状态）。
- 权限控制：所有路由依赖 get_current_user，未通过验证返回 401。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Q as "查询路由"
participant D as "依赖注入"
participant S as "服务层"
participant DB as "数据库"
Client->>Q : POST /api/v1/queries/
Q->>D : get_current_user()
D-->>Q : 当前用户
Q->>S : create_query(...)
S->>DB : 写入
DB-->>S : 成功
S-->>Q : 查询对象
Q-->>Client : 201 + 查询对象
```

**图表来源**
- [backend/app/api/queries.py:26-39](file://backend/app/api/queries.py#L26-L39)
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)

**章节来源**
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)

### 引擎与调度
- 调度器：每小时扫描 queries 表中 status='active' 且 next_query_at <= now() 的记录，逐条执行。
- 引擎：对每个平台执行查询，进行品牌匹配与竞争品牌检测，写入 citation_records，并更新查询时间字段。
- 平台适配器：抽象不同平台的查询接口，统一返回原始响应供匹配器处理。

```mermaid
flowchart TD
Tick["定时触发(每小时)"] --> Scan["扫描到期查询"]
Scan --> Found{"找到待执行查询?"}
Found -- 否 --> Wait["等待下一轮"]
Found -- 是 --> Exec["遍历查询平台执行"]
Exec --> Record["写入引用记录"]
Record --> Update["更新查询时间字段"]
Update --> Done["完成"]
Wait --> Tick
```

**图表来源**
- [backend/app/workers/scheduler.py:51-85](file://backend/app/workers/scheduler.py#L51-L85)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)

**章节来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)

### 数据模型与关系
- 用户：主键 UUID、邮箱唯一、密码哈希、计划与配额、活跃状态、活跃状态、时间戳。
- 查询：外键用户、关键词、目标品牌、别名、平台集合、频率、状态与时间字段。
- 引用记录：外键查询、平台、是否引用、位置、文本、竞争品牌、原始响应、时间戳。
- 订阅：外键用户、套餐类型、状态、开始结束日期、金额、支付方式、时间戳。
- 查询任务：外键查询、平台、状态、错误信息、调度时间、开始完成时间。

```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
int max_queries
bool is_active
bool is_admin
timestamp created_at
timestamp updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb 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
bool cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
timestamp queried_at
}
SUBSCRIPTIONS {
uuid id PK
uuid user_id FK
string plan
string status
date start_date
date end_date
numeric amount
string payment_method
timestamp created_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
timestamp scheduled_at
timestamp started_at
timestamp completed_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"
USERS ||--o{ SUBSCRIPTIONS : "订阅"
QUERIES ||--o{ QUERY_TASKS : "包含"
```

**图表来源**
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [backend/app/models/citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [backend/app/models/subscription.py:11-37](file://backend/app/models/subscription.py#L11-L37)
- [backend/app/models/query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)

**章节来源**
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)

## 中间件系统

### 限流中间件
限流中间件提供基于内存的请求限制功能，支持多种限流规则：

- **认证接口限流**：针对登录、注册、忘记密码接口，每分钟最多5次请求
- **查询执行限流**：针对/run-now接口，每小时最多10次请求  
- **全局限流**：全局请求频率限制，每分钟最多100次请求
- **健康检查豁免**：/health、/docs、/openapi 路径不受限流限制

```mermaid
flowchart TD
Req["请求到达"] --> Health{"健康检查?"}
Health -- 是 --> Pass["直接通过"]
Health -- 否 --> AuthCheck{"认证接口?"}
AuthCheck -- 是 --> AuthKey["auth:{client_ip}"]
AuthCheck -- 否 --> RunCheck{"查询执行?"}
RunCheck -- 是 --> RunKey["query_run:{client_ip}"]
RunCheck -- 否 --> GlobalKey["global:{client_ip}"]
AuthKey --> CheckAuth["检查认证限流"]
RunKey --> CheckRun["检查查询限流"]
GlobalKey --> CheckGlobal["检查全局限流"]
CheckAuth --> AuthLimited{"超过限制?"}
CheckRun --> RunLimited{"超过限制?"}
CheckGlobal --> GlobalLimited{"超过限制?"}
AuthLimited -- 是 --> Block["返回429"]
RunLimited -- 是 --> Block
GlobalLimited -- 是 --> Block
AuthLimited -- 否 --> Pass
RunLimited -- 否 --> Pass
GlobalLimited -- 否 --> Pass
Pass --> Next["继续处理"]
Block --> End["结束"]
Next --> End
```

**图表来源**
- [backend/app/middleware/rate_limit.py:34-83](file://backend/app/middleware/rate_limit.py#L34-L83)

### 日志中间件
日志中间件提供统一的请求日志记录功能：

- **访问日志**：记录请求方法、URL、状态码、耗时、客户端IP
- **性能监控**：精确到毫秒的响应时间统计
- **结构化日志**：使用 geo.access 日志器，便于日志聚合和分析

**章节来源**
- [backend/app/middleware/rate_limit.py:1-83](file://backend/app/middleware/rate_limit.py#L1-L83)
- [backend/app/middleware/logging_middleware.py:1-24](file://backend/app/middleware/logging_middleware.py#L1-L24)

## 管理员服务

### 系统管理功能
管理员服务提供完整的系统管理能力：

- **系统统计**：统计总用户数、查询数、引用数、引用率、当日活跃用户
- **用户管理**：用户列表查询、详情查看、启用/禁用切换、套餐更新
- **权限控制**：管理员专用路由，非管理员访问返回403

```mermaid
sequenceDiagram
participant Admin as "管理员客户端"
participant AdminAPI as "管理员API"
participant AdminSvc as "管理员服务"
participant DB as "数据库"
Admin->>AdminAPI : GET /api/v1/admin/stats
AdminAPI->>AdminSvc : get_system_stats()
AdminSvc->>DB : 统计查询
DB-->>AdminSvc : 统计数据
AdminSvc-->>AdminAPI : {total_users, total_queries, ...}
AdminAPI-->>Admin : 系统统计信息
Admin->>AdminAPI : POST /api/v1/admin/users/{user_id}/toggle-active
AdminAPI->>AdminSvc : toggle_user_active(user_id)
AdminSvc->>DB : 更新用户状态
DB-->>AdminSvc : 更新结果
AdminSvc-->>AdminAPI : {id, is_active, message}
AdminAPI-->>Admin : 操作结果
```

**图表来源**
- [backend/app/api/admin.py:29-108](file://backend/app/api/admin.py#L29-L108)
- [backend/app/services/admin.py:14-188](file://backend/app/services/admin.py#L14-L188)

**章节来源**
- [backend/app/api/admin.py:1-108](file://backend/app/api/admin.py#L1-L108)
- [backend/app/services/admin.py:1-188](file://backend/app/services/admin.py#L1-L188)

## 订阅服务

### 套餐管理功能
订阅服务提供完整的套餐管理能力：

- **套餐定义**：免费版、入门版、专业版、企业版四个套餐
- **功能特性**：基于套餐的差异化功能支持（CSV导出、PDF报告、定时查询等）
- **订阅流程**：创建订阅、取消订阅、历史记录查询
- **用户配额**：根据套餐更新用户最大查询次数

```mermaid
flowchart TD
Plan["套餐定义"] --> Features["功能特性映射"]
Features --> Free["免费版<br/>max_queries=5"]
Features --> Starter["入门版<br/>max_queries=20"]
Features --> Pro["专业版<br/>max_queries=100"]
Features --> Enterprise["企业版<br/>max_queries=500"]
User["用户"] --> Subscribe["订阅流程"]
Subscribe --> Create["创建订阅"]
Create --> UpdateUser["更新用户套餐"]
UpdateUser --> Active["激活状态"]
Active --> Cancel["取消订阅"]
Cancel --> Downgrade["降级到免费版"]
```

**图表来源**
- [backend/app/services/subscription.py:25-155](file://backend/app/services/subscription.py#L25-L155)

**章节来源**
- [backend/app/api/subscriptions.py:1-77](file://backend/app/api/subscriptions.py#L1-L77)
- [backend/app/schemas/subscription.py:1-41](file://backend/app/schemas/subscription.py#L1-L41)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
- [backend/app/services/subscription.py:1-155](file://backend/app/services/subscription.py#L1-L155)

## 报告服务

### 导出功能
报告服务提供多种格式的数据导出能力：

- **CSV导出**：支持查询结果的CSV格式导出，Stream响应
- **PDF报告**：支持生成PDF格式的详细报告
- **权限控制**：仅限当前用户访问自己的数据
- **错误处理**：数据不存在时返回404错误

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Reports as "报告API"
participant Service as "导出服务"
participant DB as "数据库"
Client->>Reports : GET /export/csv?query_id=...
Reports->>Service : export_citations_csv(query_id)
Service->>DB : 查询引用数据
DB-->>Service : 引用数据
Service-->>Reports : CSV内容
Reports-->>Client : StreamResponse CSV
Client->>Reports : GET /export/pdf?query_id=...
Reports->>Service : export_citations_pdf(query_id)
Service-->>Reports : PDF字节流
Reports-->>Client : Response PDF
```

**图表来源**
- [backend/app/api/reports.py:18-75](file://backend/app/api/reports.py#L18-L75)

**章节来源**
- [backend/app/api/reports.py:1-75](file://backend/app/api/reports.py#L1-L75)

## 依赖关系分析
- 组件内聚：API 路由与服务层职责清晰，模型仅负责映射。
- 组件耦合：API 依赖服务，服务依赖数据库与配置；调度器依赖引擎与数据库；引擎依赖平台适配器。
- 依赖注入：通过 FastAPI 依赖系统注入数据库会话与当前用户。
- 循环依赖：未见明显循环依赖。

```mermaid
graph LR
MIDDLEWARE["middleware/*"] --> API_AUTH["api/auth.py"]
MIDDLEWARE --> API_ADMIN["api/admin.py"]
MIDDLEWARE --> API_SUB["api/subscriptions.py"]
MIDDLEWARE --> API_REPORTS["api/reports.py"]
API_AUTH --> SVC_AUTH["services/auth.py"]
API_ADMIN --> SVC_ADMIN["services/admin.py"]
API_SUB --> SVC_SUB["services/subscription.py"]
API_AUTH --> DEPS["api/deps.py"]
API_ADMIN --> DEPS
API_SUB --> DEPS
API_REPORTS --> DEPS
SVC_AUTH --> DB["database.py"]
SVC_ADMIN --> DB
SVC_SUB --> DB
DEPS --> DB
SCHED["workers/scheduler.py"] --> DB
SCHED --> ENGINE["workers/citation_engine.py"]
ENGINE --> MODELS["models/*.py"]
```

**图表来源**
- [backend/app/middleware/rate_limit.py:1-83](file://backend/app/middleware/rate_limit.py#L1-L83)
- [backend/app/middleware/logging_middleware.py:1-24](file://backend/app/middleware/logging_middleware.py#L1-L24)
- [backend/app/api/admin.py:1-108](file://backend/app/api/admin.py#L1-L108)
- [backend/app/api/reports.py:1-75](file://backend/app/api/reports.py#L1-L75)
- [backend/app/api/subscriptions.py:1-77](file://backend/app/api/subscriptions.py#L1-L77)
- [backend/app/services/admin.py:1-188](file://backend/app/services/admin.py#L1-L188)
- [backend/app/services/subscription.py:1-155](file://backend/app/services/subscription.py#L1-L155)

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/deps.py:1-43](file://backend/app/api/deps.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)

## 性能考量
- 异步 I/O：数据库与平台查询均采用异步，提升并发吞吐。
- 会话管理：显式事务边界，避免长事务占用连接池。
- 定时任务：APScheduler 异步调度，事件循环兼容处理，降低阻塞风险。
- 索引优化：查询与引用表建立复合索引，加速过滤与排序。
- 缓存建议：可引入 Redis 缓存热点查询结果与用户会话信息（当前配置已准备）。
- 日志采样：生产环境建议开启采样与结构化日志，避免高频日志影响性能。
- **中间件性能**：限流中间件使用内存存储，性能开销低；日志中间件仅记录必要信息。

**更新** 新增中间件系统的性能考量，包括内存存储的限流机制和结构化日志的性能影响。

## 故障排查指南
- 认证失败：检查 JWT 秘钥、过期时间与前端令牌传递；确认 OAuth2 tokenUrl 与 Bearer 头正确。
- 数据库连接：核对 DATABASE_URL；确认容器网络可达；查看连接池与超时配置。
- 定时任务异常：关注调度器日志，检查查询状态与平台适配器可用性；确认 next_query_at 计算逻辑。
- 引擎执行失败：查看平台适配器错误与原始响应；检查品牌匹配器与竞争品牌检测逻辑。
- CORS 问题：确认前端域名与请求头是否在允许范围内。
- **中间件问题**：检查限流规则配置，确认健康检查路径是否被正确豁免；验证日志中间件的logger配置。
- **管理员权限**：确认用户 is_admin 字段，检查管理员路由的权限验证逻辑。
- **订阅状态**：检查用户套餐与订阅状态的一致性，验证订阅历史记录的查询逻辑。

**更新** 新增中间件、管理员服务、订阅服务相关的故障排查指导。

**章节来源**
- [backend/app/api/deps.py:16-43](file://backend/app/api/deps.py#L16-L43)
- [backend/app/config.py:7-13](file://backend/app/config.py#L7-L13)
- [backend/app/workers/scheduler.py:42-90](file://backend/app/workers/scheduler.py#L42-L90)
- [backend/app/workers/citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)
- [backend/app/middleware/rate_limit.py:34-83](file://backend/app/middleware/rate_limit.py#L34-L83)
- [backend/app/middleware/logging_middleware.py:8-24](file://backend/app/middleware/logging_middleware.py#L8-L24)

## 结论
该架构以 FastAPI 为核心，结合异步数据库、定时任务与多平台适配器，形成高可用、可扩展的查询与引用检测系统。通过明确的分层与依赖注入，系统具备良好的可测试性与可维护性。新增的中间件系统提供了安全防护和性能监控能力，管理员服务增强了系统管理功能，订阅服务完善了商业化运营能力，报告服务提升了用户体验。建议在生产环境中完善日志与监控、接入缓存与告警，并持续优化索引与查询计划。

**更新** 本次更新显著增强了系统的功能完整性，包括安全防护、管理能力、商业运营和用户体验等方面。

## 附录
- API 设计原则：统一前缀与标签、明确响应模型、一致的状态码与错误消息。
- 错误处理：在路由层捕获业务异常并转换为标准 HTTP 状态码；在依赖层统一 401 未授权。
- 响应格式：遵循 Pydantic 模型序列化，确保前后端契约一致。
- 架构决策背景：选择异步栈以提升 I/O 密集场景性能；APScheduler 简化定时任务编排；JWT 适合无状态认证场景；中间件系统提供安全防护和性能监控。
- **新增功能背景**：中间件系统满足安全需求；管理员服务满足系统管理需求；订阅服务满足商业化需求；报告服务满足用户体验需求。