# 项目介绍

<cite>
**本文档引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.py)
- [backend/requirements.txt](file://backend/requirements.txt)
- [docker-compose.yml](file://docker-compose.yml)
- [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/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/citations.py](file://backend/app/api/citations.py)
- [frontend/package.json](file://frontend/package.json)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/components/layout/header.tsx](file://frontend/components/layout/header.tsx)
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
</cite>

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

## 引言
GEO平台是一个面向智能学术查询与引用管理的现代化系统，旨在帮助研究人员、市场分析师与品牌监测团队高效地追踪特定品牌在多平台上的提及情况。平台通过“智能引用检测”“多AI平台集成”“定时查询调度”等核心能力，解决传统学术研究中品牌引用检测的痛点与多平台数据整合难题，提供统一的数据采集、分析与可视化入口。

- 核心使命：以自动化与智能化手段降低品牌监测与学术研究的人工成本，提升信息获取与洞察效率。
- 价值主张：统一平台、可扩展的AI适配、稳定的定时调度、清晰的统计与导出能力，满足不同规模用户的使用需求。

## 项目结构
项目采用前后端分离架构，后端基于FastAPI构建REST服务，数据库与缓存分别使用PostgreSQL与Redis；前端基于Next.js，提供用户认证、查询管理、引用数据展示与报告导出等功能。Docker Compose用于本地开发环境的一键编排。

```mermaid
graph TB
subgraph "前端(Frontend)"
FE_APP["Next.js 应用"]
FE_AUTH["认证模块<br/>登录/注册/会话"]
FE_UI["UI组件与布局<br/>头部/侧边栏/图表"]
FE_API["API封装<br/>统一请求与鉴权"]
end
subgraph "后端(Backend)"
BE_MAIN["FastAPI 应用<br/>路由与生命周期"]
BE_SCHED["定时调度器<br/>APScheduler"]
BE_ENGINE["引用检测引擎<br/>品牌匹配/竞争品牌检测"]
BE_MODELS["数据模型<br/>用户/查询/引用记录"]
BE_API["API接口<br/>认证/查询/引用/报告"]
end
subgraph "基础设施"
DB["PostgreSQL 数据库"]
REDIS["Redis 缓存/任务队列"]
end
FE_APP --> FE_API
FE_API --> BE_MAIN
BE_MAIN --> BE_API
BE_MAIN --> BE_SCHED
BE_SCHED --> BE_ENGINE
BE_ENGINE --> DB
BE_MAIN --> DB
BE_MAIN --> REDIS
```

**图示来源**
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
- [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)
- [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)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

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

## 核心组件
- 引用检测引擎：负责对指定关键词在多个AI平台进行检索，并执行品牌引用检测与竞争品牌识别，生成标准化的引用记录。
- 定时调度器：基于APScheduler周期性扫描数据库中到期的查询任务，自动触发引用检测流程。
- 数据模型：围绕用户、查询、引用记录与任务状态建立清晰的关系模型，支撑查询计划、历史记录与统计分析。
- API层：提供认证、查询管理、引用数据查询与统计、即时执行、报告导出等接口。
- 前端应用：提供用户认证、查询配置、引用数据浏览、趋势与平台分布图表以及CSV导出能力。

**章节来源**
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [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/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

## 架构总览
下图展示了从用户操作到数据落库的关键交互路径，包括认证、查询创建、定时调度、平台适配与结果存储。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端应用"
participant API as "后端API"
participant S as "调度器"
participant E as "引用检测引擎"
participant P as "AI平台适配器"
participant DB as "数据库"
U->>FE : 登录/创建查询
FE->>API : 发起请求(带鉴权)
API->>DB : 写入查询/更新状态
API-->>FE : 返回响应
S->>DB : 查询到期的查询任务
S->>E : 触发执行
E->>P : 平台查询(keyword)
P-->>E : 返回原始回复
E->>E : 品牌匹配/竞争品牌检测
E->>DB : 写入引用记录
E-->>S : 完成并更新下次执行时间
```

**图示来源**
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/models/query.py:25-31](file://backend/app/models/query.py#L25-L31)
- [backend/app/models/citation_record.py:19-33](file://backend/app/models/citation_record.py#L19-L33)

## 详细组件分析

### 引擎与平台适配
- 品牌匹配器：支持精确、别名与模糊匹配，返回是否引用、置信度、首次出现段落位置及上下文片段。
- 竞争品牌检测器：基于预定义行业品牌清单，识别文本中除目标品牌外的其他品牌。
- 引用检测引擎：封装平台适配器调用、品牌匹配与竞争品牌检测，生成标准化引用记录并更新查询的下次执行时间。
- 平台适配器：当前包含“文心”“Kimi”两个适配器，未来可扩展更多平台。

```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(freq) 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 QueryScheduler {
+start() void
+shutdown() void
+check_and_execute_queries() void
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
QueryScheduler --> CitationEngine : "驱动执行"
```

**图示来源**
- [backend/app/workers/citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)
- [backend/app/workers/citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

**章节来源**
- [backend/app/workers/citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)
- [backend/app/workers/citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)

### 定时调度流程
- 启动阶段：应用生命周期内启动调度器，设置每小时检查一次。
- 执行阶段：查询状态为“active”且下次执行时间已到达的任务，逐个触发引用检测。
- 错误处理：单个任务失败不影响整体调度，异常被记录并继续处理其他任务。

```mermaid
flowchart TD
Start(["启动调度器"]) --> AddJob["添加定时任务(每小时)"]
AddJob --> Wait["等待触发"]
Wait --> Trigger{"到达触发时间?"}
Trigger --> |否| Wait
Trigger --> |是| QueryDue["查询到期的查询任务"]
QueryDue --> HasTasks{"是否有待执行任务?"}
HasTasks --> |否| Wait
HasTasks --> |是| ExecOne["执行单个查询任务"]
ExecOne --> UpdateTime["更新下次执行时间"]
UpdateTime --> Wait
```

**图示来源**
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)
- [backend/app/models/query.py:25-31](file://backend/app/models/query.py#L25-L31)

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

### 数据模型与关系
- 用户(User)：用户基本信息、订阅计划与配额。
- 查询(Query)：关键词、目标品牌、别名、平台集合、频率、状态与时间戳。
- 引用记录(CitationRecord)：平台来源、是否引用、引用位置、上下文、竞争品牌列表与原始回复。
- 关系：用户与查询一对多；查询与引用记录、查询任务一对多。

```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string name
string plan
int max_queries
boolean is_active
}
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
}
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
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"
```

**图示来源**
- [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/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)

### API与前端交互
- 后端API：提供认证、查询管理、引用数据分页与统计、即时执行、报告导出等接口。
- 前端封装：统一的API模块负责鉴权头注入与错误处理，页面通过hooks与组件化UI实现交互。
- 认证流程：登录成功后保存会话，后续请求携带令牌访问受保护资源。

```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "认证API"
participant S as "会话状态"
participant D as "受保护API"
C->>A : POST /api/v1/auth/login
A-->>C : 返回令牌
C->>S : 保存令牌
C->>D : GET /api/v1/queries (携带Authorization)
D-->>C : 返回数据
```

**图示来源**
- [backend/app/api/citations.py:25-78](file://backend/app/api/citations.py#L25-L78)
- [frontend/lib/api.ts:23-57](file://frontend/lib/api.ts#L23-L57)
- [frontend/components/layout/header.tsx:7-28](file://frontend/components/layout/header.tsx#L7-L28)

**章节来源**
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/layout/header.tsx:1-30](file://frontend/components/layout/header.tsx#L1-L30)

## 依赖分析
- 运行时依赖：FastAPI、SQLAlchemy、Pydantic、Redis、APScheduler、Playwright、HTTPX、Python-Jose、Passlib等。
- 前端依赖：Next.js、Next-Auth、Recharts、Radix UI等。
- 基础设施：PostgreSQL与Redis容器通过Docker Compose编排，后端服务暴露8000端口，前端服务暴露3000端口。

```mermaid
graph LR
subgraph "后端"
F["FastAPI"]
S["SQLAlchemy"]
P["Pydantic"]
R["Redis"]
A["APScheduler"]
PW["Playwright"]
H["HTTPX"]
end
subgraph "前端"
N["Next.js"]
NA["Next-Auth"]
RC["Recharts"]
RU["Radix UI"]
end
F --> S
F --> P
F --> R
F --> A
F --> PW
F --> H
N --> NA
N --> RC
N --> RU
```

**图示来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-28](file://frontend/package.json#L11-L28)

**章节来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
- [docker-compose.yml:36-66](file://docker-compose.yml#L36-L66)

## 性能考虑
- 异步与并发：后端使用异步数据库会话与异步调度器，减少阻塞；平台适配器在执行查询时应避免同步阻塞操作。
- 缓存策略：利用Redis缓存短期高频数据与任务状态，降低数据库压力。
- 分页与索引：引用数据查询支持分页与多条件过滤；数据库表建立必要索引以优化查询性能。
- 调度粒度：默认每小时检查一次到期任务，可根据业务量调整间隔。
- 前端渲染：图表组件按需加载，避免一次性渲染大量数据导致卡顿。

## 故障排查指南
- 健康检查：后端提供健康检查端点，可用于容器编排下的存活探针。
- 日志定位：调度器与引擎均输出详细日志，便于定位任务失败原因。
- 数据一致性：若发现引用记录缺失，检查任务状态与错误信息，确认平台适配器可用性与网络连通性。
- 认证问题：确认前端令牌是否正确注入，后端CORS配置是否允许前端域名访问。

**章节来源**
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/workers/scheduler.py:76-84](file://backend/app/workers/scheduler.py#L76-L84)
- [backend/app/workers/citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)

## 结论
GEO平台通过“智能引用检测+多平台集成+定时调度”的组合拳，有效解决了品牌监测与学术研究中的重复劳动与数据割裂问题。其模块化设计与前后端分离架构便于扩展与维护，适合研究人员、市场分析师与品牌监测团队在不同场景下灵活使用。

## 附录
- 快速开始：使用Docker Compose一键启动数据库、缓存、后端与前端服务，访问 http://localhost:3000 进行体验。
- 开发建议：新增平台适配器时遵循现有适配器接口规范；为关键流程补充单元测试与集成测试；持续优化数据库索引与查询性能。