# 项目概述

<cite>
**本文档引用的文件**
- [backend/README.md](file://backend/README.md)
- [frontend/README.md](file://frontend/README.md)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.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)
- [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.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)
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
- [frontend/package.json](file://frontend/package.json)
- [frontend/components/charts/platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx)
- [frontend/lib/platforms.ts](file://frontend/lib/platforms.ts)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/lib/auth.ts](file://frontend/lib/auth.ts)
- [tests/conftest.py](file://tests/conftest.py)
- [tests/test_auth.py](file://tests/test_auth.py)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
GEO平台是一个面向智能学术查询与引用管理的系统，旨在帮助用户通过多AI平台进行关键词检索，并自动识别目标品牌在检索结果中的被引用情况，同时提供可视化报表与定时任务调度能力。平台采用前后端分离架构，后端基于FastAPI构建REST服务，前端基于Next.js提供交互界面；数据库采用PostgreSQL，缓存与任务调度由Redis与APScheduler支撑。

本项目的核心目标是：
- 提供统一的查询入口，整合多家AI平台能力
- 自动化定时查询与引用检测，降低人工成本
- 以图表形式直观展示各平台引用率趋势
- 保障可扩展性与可维护性，便于后续接入更多平台与功能

**更新** 新增完整的项目README文档，包含详细的安装说明、API端点清单、数据库迁移说明和测试说明，为开发者提供完整的快速开始指南。

## 项目结构
项目采用前后端分离与容器化部署策略：
- 后端：FastAPI应用，负责API路由、业务逻辑、定时任务调度与数据库交互
- 前端：Next.js应用，负责用户界面、图表展示与API调用
- 数据层：PostgreSQL存储查询与引用记录；Redis用于任务调度与缓存
- 容器编排：Docker Compose统一管理数据库、缓存、后端与前端服务

```mermaid
graph TB
subgraph "前端"
FE_APP["Next.js 应用<br/>页面与图表组件"]
end
subgraph "后端"
BE_API["FastAPI 应用<br/>路由与服务"]
BE_SCHED["APScheduler 调度器<br/>定时任务"]
BE_ENGINE["引用检测引擎<br/>品牌匹配与竞争品牌检测"]
end
subgraph "数据与基础设施"
DB[("PostgreSQL")]
CACHE[("Redis 缓存/队列")]
end
FE_APP --> |"HTTP 请求"| BE_API
BE_API --> |"数据库访问"| DB
BE_API --> |"任务调度"| BE_SCHED
BE_SCHED --> |"调用引擎"| BE_ENGINE
BE_ENGINE --> |"写入记录"| DB
BE_API --> CACHE
BE_SCHED --> CACHE
```

**图表来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [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)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

**章节来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

## 核心组件
- 后端主程序与生命周期管理：负责应用启动/关闭、CORS配置、路由注册与健康检查
- 定时任务调度器：基于APScheduler的异步调度器，周期性扫描待执行查询并触发引用检测
- 引用检测引擎：封装品牌匹配、竞争品牌检测与平台适配器调用流程
- 平台适配器基类：定义统一的AI平台查询接口，便于扩展新的平台
- API路由与服务：提供查询词的增删改查、运行一次查询等接口
- 数据模型：定义查询、引用记录、任务等核心实体及其索引
- 前端布局与图表：提供页面骨架、主题样式与平台引用率柱状图展示

**章节来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [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/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [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)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)

## 架构总览
GEO平台采用分层架构：
- 表现层：Next.js应用，负责UI渲染与用户交互
- 控制层：FastAPI路由与服务，处理请求、鉴权与业务编排
- 领域层：引用检测引擎与平台适配器，实现品牌匹配与跨平台查询
- 基础设施层：PostgreSQL与Redis，提供持久化与任务调度支撑
- 集成层：Docker Compose统一编排，确保服务间依赖与网络互通

```mermaid
graph TB
UI["前端页面<br/>Next.js"] --> API["后端API<br/>FastAPI"]
API --> SCHED["调度器<br/>APScheduler"]
API --> DBM["数据库<br/>SQLAlchemy ORM"]
API --> CACHE["缓存<br/>Redis"]
SCHED --> ENGINE["引擎<br/>CitationEngine"]
ENGINE --> ADAPTERS["平台适配器<br/>BasePlatformAdapter"]
ENGINE --> DBM
ADAPTERS --> |"调用外部平台"| EXTERNAL["外部AI平台"]
```

**图表来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [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/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)

## 详细组件分析

### 后端主程序与生命周期
- 负责注册认证、查询、引用、报告等路由
- 配置CORS允许前端本地开发环境访问
- 应用生命周期内启动调度器并在关闭时优雅退出

```mermaid
sequenceDiagram
participant Client as "浏览器"
participant API as "FastAPI 应用"
participant Sched as "调度器"
participant Engine as "引用引擎"
Client->>API : "GET /health"
API-->>Client : "{status : ok}"
Note over API,Sched : "应用启动时"
API->>Sched : "start()"
Sched->>Sched : "注册每小时检查任务"
Note over Sched,Engine : "定时触发"
Sched->>Engine : "执行查询与检测"
```

**图表来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

**章节来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)

### 定时任务调度器
- 使用AsyncIOScheduler按小时轮询查询表
- 过滤状态为active且到达下次查询时间的记录
- 逐条调用引用引擎执行查询，更新任务状态与下次查询时间

```mermaid
flowchart TD
Start(["定时任务触发"]) --> Fetch["查询数据库<br/>筛选待执行查询"]
Fetch --> HasMore{"是否有待执行查询？"}
HasMore --> |否| End(["结束"])
HasMore --> |是| Exec["调用引擎执行查询"]
Exec --> Update["更新查询任务状态与下次查询时间"]
Update --> Fetch
```

**图表来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

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

### 引用检测引擎
- 品牌匹配器：支持精确、别名、模糊匹配，输出引用位置与置信度
- 竞争品牌检测：在已知品牌库中识别其他相关品牌
- 平台适配器：封装不同AI平台的查询接口，统一返回原始文本
- 任务管理：为每次查询创建或获取任务记录，跟踪状态与错误信息
- 结果持久化：生成引用记录并写入数据库

```mermaid
classDiagram
class CitationEngine {
+execute_query(query, db) list
+execute_single_platform(keyword, platform, target_brand, aliases) dict
-_get_or_create_task(db, query_id, platform) QueryTask
-_calculate_next_query_at(frequency) datetime
+close() void
}
class BrandMatcher {
+match(text) dict
-_extract_candidates(text) list
-_extract_position_and_context(text, keyword) tuple
}
class CompetitorDetector {
+detect(text, target_brand) list
}
class BasePlatformAdapter {
<<abstract>>
+platform_name str
+platform_url str
+query(keyword) str
+close() void
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
CitationEngine --> BasePlatformAdapter : "调用"
```

**图表来源**
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)

**章节来源**
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)

### API与数据模型
- 查询API：提供查询词的分页列表、创建、读取、更新、删除
- 查询模型：包含关键词、目标品牌、别名、平台集合、频率、状态与时间戳
- 引用记录模型：记录每次查询在特定平台上的引用结果、竞争品牌与原始响应

```mermaid
erDiagram
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
boolean cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
timestamp queried_at
}
QUERIES ||--o{ CITATION_RECORDS : "包含"
```

**图表来源**
- [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/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [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)

### 前端布局与可视化
- 页面布局：定义站点元数据与全局样式，提供Provider容器
- 图表组件：基于Recharts绘制平台引用率柱状图，支持响应式与自定义颜色
- 平台映射：提供平台键值到中文名称的映射，便于展示

```mermaid
graph LR
Layout["页面布局<br/>layout.tsx"] --> Providers["全局Provider"]
Providers --> Charts["图表组件<br/>PlatformChart"]
Charts --> Data["引用统计数据"]
Charts --> Map["平台映射<br/>platforms.ts"]
```

**图表来源**
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)

**章节来源**
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)

### API客户端与认证
- API客户端：统一封装后端API调用，自动处理认证头与错误处理
- NextAuth认证：基于Credentials Provider实现JWT认证流程
- 环境变量配置：支持开发、测试、生产多环境配置

**章节来源**
- [frontend/lib/api.ts:1-154](file://frontend/lib/api.ts#L1-L154)
- [frontend/lib/auth.ts:1-73](file://frontend/lib/auth.ts#L1-L73)
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)

## 依赖分析
- 技术栈选择理由
  - 后端：FastAPI提供高性能异步API与自动生成文档；SQLAlchemy与异步驱动支持高并发；APScheduler与Redis满足任务调度与缓存需求
  - 前端：Next.js提供SSR/CSR混合模式与良好开发体验；Radix UI与Tailwind提供一致的UI组件与样式；Recharts用于数据可视化
  - 数据与基础设施：PostgreSQL适合结构化数据与复杂查询；Redis适合任务调度与会话缓存
- 外部依赖与集成点
  - 平台适配器：通过抽象基类统一不同AI平台的查询接口
  - CORS：允许前端本地开发端口访问后端
  - 环境变量：数据库、缓存、密钥与浏览器自动化路径通过配置集中管理

```mermaid
graph TB
subgraph "后端依赖"
FAST["FastAPI"]
SQL["SQLAlchemy + asyncpg"]
REDIS["Redis"]
APS["APScheduler"]
PW["Playwright"]
end
subgraph "前端依赖"
NEXT["Next.js"]
RADIX["Radix UI"]
RECHARTS["Recharts"]
TAILWIND["TailwindCSS"]
end
FAST --> SQL
FAST --> REDIS
FAST --> APS
FAST --> PW
NEXT --> RADIX
NEXT --> RECHARTS
NEXT --> TAILWIND
```

**图表来源**
- [backend/requirements.txt:1-39](file://backend/requirements.txt#L1-L39)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

**章节来源**
- [backend/requirements.txt:1-39](file://backend/requirements.txt#L1-L39)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)

## 性能考虑
- 异步化与并发
  - 后端采用异步数据库会话与异步调度器，提升I/O密集型场景下的吞吐量
- 索引优化
  - 查询与引用记录模型建立复合索引，加速定时任务扫描与报表查询
- 缓存与任务解耦
  - Redis承担任务调度与会话缓存，避免阻塞主业务线程
- 可视化性能
  - 图表组件使用响应式容器与轻量级渲染，减少重绘开销

## 故障排查指南
- 健康检查
  - 后端提供健康检查端点，用于确认服务可用性
- 日志与错误处理
  - 调度器与引擎在执行过程中记录错误日志，便于定位失败原因
- 常见问题
  - 数据库连接失败：检查PostgreSQL容器健康状态与连接字符串
  - 任务未执行：确认Redis可用与调度器已启动
  - 平台适配器异常：检查对应平台的API密钥与网络连通性

**章节来源**
- [backend/app/main.py:81-84](file://backend/app/main.py#L81-L84)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/config.py:1-23](file://backend/app/config.py#L1-L23)

## 结论
GEO平台通过"多AI平台集成 + 定时查询任务调度 + 数据可视化"的组合，为用户提供从查询到洞察的一体化能力。其分层清晰、模块解耦的设计便于后续扩展更多平台与功能；容器化部署降低了运维复杂度。对于初学者，平台提供了直观的可视化与简洁的API；对于开发者，平台展示了异步架构、任务调度与领域建模的最佳实践。

**更新** 新增完整的项目文档体系，包括后端和前端的详细README文档，为开发者提供从环境搭建到API使用的完整指导。

## 附录

### 系统边界与核心组件关系图
```mermaid
graph TB
subgraph "外部系统"
Users["用户"]
AIs["多家AI平台"]
end
subgraph "GEO平台"
Frontend["前端应用"]
Backend["后端API"]
Scheduler["调度器"]
Engine["引用引擎"]
DB[("PostgreSQL")]
Cache[("Redis")]
end
Users --> Frontend
Frontend --> Backend
Backend --> DB
Backend --> Cache
Scheduler --> Engine
Engine --> AIs
Engine --> DB
Scheduler --> DB
Scheduler --> Cache
```

**图表来源**
- [backend/app/main.py:1-84](file://backend/app/main.py#L1-L84)
- [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)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)

### 数据流向说明
- 用户在前端发起查询管理与报表查看请求
- 后端API接收请求并访问数据库与缓存
- 调度器周期性触发引用引擎执行跨平台查询
- 引擎对平台返回的原始文本进行品牌匹配与竞争品牌检测
- 结果写入数据库并供前端图表组件消费

**章节来源**
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [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)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)

### 快速开始指南
**更新** 基于新增的README文档，提供完整的项目启动指南：

#### 后端启动步骤
1. 创建Python虚拟环境并激活
2. 安装依赖：`pip install -r requirements.txt`
3. 安装Playwright浏览器：`playwright install chromium`
4. 复制并配置环境变量：`cp ../.env.example ../.env`
5. 初始化数据库：`alembic upgrade head`
6. 开发模式启动：`uvicorn app.main:app --reload --port 8000`

#### 前端启动步骤
1. 安装依赖：`npm install`
2. 开发模式启动：`npm run dev`
3. 访问地址：`http://localhost:3000`

#### API端点概览
- 认证模块：注册、登录、用户信息获取
- 查询管理：CRUD操作与立即执行
- 引用数据：列表查询与统计分析
- 报告导出：CSV格式数据导出

**章节来源**
- [backend/README.md:12-67](file://backend/README.md#L12-L67)
- [frontend/README.md:11-34](file://frontend/README.md#L11-L34)
- [backend/README.md:69-126](file://backend/README.md#L69-L126)

### 测试与开发指南
**更新** 新增测试框架与开发流程说明：

- 测试环境配置：pytest + pytest-asyncio + aiosqlite
- 测试运行：`pytest` 或指定测试文件
- 覆盖率报告：`pytest --cov=backend/app --cov-report=html`
- 开发注意事项：统一API调用封装、认证状态管理、组件开发规范

**章节来源**
- [backend/README.md:209-234](file://backend/README.md#L209-L234)
- [tests/conftest.py:1-123](file://tests/conftest.py#L1-L123)
- [tests/test_auth.py:1-104](file://tests/test_auth.py#L1-L104)
- [frontend/README.md:161-170](file://frontend/README.md#L161-L170)