fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/项目概述/项目概述.md

465 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 项目概述
<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)
Reference in New Issue View Git Blame Copy Permalink