19 KiB
19 KiB
项目概述
**本文档引用的文件** - [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)目录
引言
GEO平台是一个面向智能学术查询与引用管理的系统，旨在帮助用户通过多AI平台进行关键词检索，并自动识别目标品牌在检索结果中的被引用情况，同时提供可视化报表与定时任务调度能力。平台采用前后端分离架构，后端基于FastAPI构建REST服务，前端基于Next.js提供交互界面；数据库采用PostgreSQL，缓存与任务调度由Redis与APScheduler支撑。
本项目的核心目标是：
- 提供统一的查询入口，整合多家AI平台能力
- 自动化定时查询与引用检测，降低人工成本
- 以图表形式直观展示各平台引用率趋势
- 保障可扩展性与可维护性，便于后续接入更多平台与功能
更新 新增完整的项目README文档，包含详细的安装说明、API端点清单、数据库迁移说明和测试说明，为开发者提供完整的快速开始指南。
项目结构
项目采用前后端分离与容器化部署策略：
- 后端：FastAPI应用，负责API路由、业务逻辑、定时任务调度与数据库交互
- 前端：Next.js应用，负责用户界面、图表展示与API调用
- 数据层：PostgreSQL存储查询与引用记录；Redis用于任务调度与缓存
- 容器编排：Docker Compose统一管理数据库、缓存、后端与前端服务
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
- backend/app/workers/scheduler.py:1-95
- backend/app/workers/citation_engine.py:1-309
- docker-compose.yml:1-71
章节来源
核心组件
- 后端主程序与生命周期管理：负责应用启动/关闭、CORS配置、路由注册与健康检查
- 定时任务调度器：基于APScheduler的异步调度器，周期性扫描待执行查询并触发引用检测
- 引用检测引擎：封装品牌匹配、竞争品牌检测与平台适配器调用流程
- 平台适配器基类：定义统一的AI平台查询接口，便于扩展新的平台
- API路由与服务：提供查询词的增删改查、运行一次查询等接口
- 数据模型：定义查询、引用记录、任务等核心实体及其索引
- 前端布局与图表：提供页面骨架、主题样式与平台引用率柱状图展示
章节来源
- backend/app/main.py:1-84
- backend/app/workers/scheduler.py:1-95
- backend/app/workers/citation_engine.py:1-309
- backend/app/workers/platforms/base.py:1-18
- backend/app/api/queries.py:1-86
- backend/app/models/query.py:1-55
- backend/app/models/citation_record.py:1-42
- frontend/app/layout.tsx:1-37
- frontend/components/charts/platform-chart.tsx:1-68
架构总览
GEO平台采用分层架构：
- 表现层：Next.js应用，负责UI渲染与用户交互
- 控制层：FastAPI路由与服务，处理请求、鉴权与业务编排
- 领域层：引用检测引擎与平台适配器，实现品牌匹配与跨平台查询
- 基础设施层：PostgreSQL与Redis，提供持久化与任务调度支撑
- 集成层：Docker Compose统一编排，确保服务间依赖与网络互通
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
- backend/app/workers/scheduler.py:1-95
- backend/app/workers/citation_engine.py:1-309
- backend/app/workers/platforms/base.py:1-18
详细组件分析
后端主程序与生命周期
- 负责注册认证、查询、引用、报告等路由
- 配置CORS允许前端本地开发环境访问
- 应用生命周期内启动调度器并在关闭时优雅退出
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 : "执行查询与检测"
图表来源
章节来源
定时任务调度器
- 使用AsyncIOScheduler按小时轮询查询表
- 过滤状态为active且到达下次查询时间的记录
- 逐条调用引用引擎执行查询，更新任务状态与下次查询时间
flowchart TD
Start(["定时任务触发"]) --> Fetch["查询数据库<br/>筛选待执行查询"]
Fetch --> HasMore{"是否有待执行查询？"}
HasMore --> |否| End(["结束"])
HasMore --> |是| Exec["调用引擎执行查询"]
Exec --> Update["更新查询任务状态与下次查询时间"]
Update --> Fetch
图表来源
章节来源
引用检测引擎
- 品牌匹配器：支持精确、别名、模糊匹配，输出引用位置与置信度
- 竞争品牌检测：在已知品牌库中识别其他相关品牌
- 平台适配器：封装不同AI平台的查询接口，统一返回原始文本
- 任务管理：为每次查询创建或获取任务记录，跟踪状态与错误信息
- 结果持久化：生成引用记录并写入数据库
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 : "调用"
图表来源
章节来源
API与数据模型
- 查询API：提供查询词的分页列表、创建、读取、更新、删除
- 查询模型：包含关键词、目标品牌、别名、平台集合、频率、状态与时间戳
- 引用记录模型：记录每次查询在特定平台上的引用结果、竞争品牌与原始响应
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/api/queries.py:1-86
- backend/app/models/query.py:1-55
- backend/app/models/citation_record.py:1-42
前端布局与可视化
- 页面布局：定义站点元数据与全局样式，提供Provider容器
- 图表组件：基于Recharts绘制平台引用率柱状图，支持响应式与自定义颜色
- 平台映射：提供平台键值到中文名称的映射，便于展示
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
- frontend/components/charts/platform-chart.tsx:1-68
- frontend/lib/platforms.ts:1-18
章节来源
- frontend/app/layout.tsx:1-37
- frontend/components/charts/platform-chart.tsx:1-68
- frontend/lib/platforms.ts:1-18
API客户端与认证
- API客户端：统一封装后端API调用，自动处理认证头与错误处理
- NextAuth认证：基于Credentials Provider实现JWT认证流程
- 环境变量配置：支持开发、测试、生产多环境配置
章节来源
依赖分析
- 技术栈选择理由
- 后端：FastAPI提供高性能异步API与自动生成文档；SQLAlchemy与异步驱动支持高并发；APScheduler与Redis满足任务调度与缓存需求
- 前端：Next.js提供SSR/CSR混合模式与良好开发体验；Radix UI与Tailwind提供一致的UI组件与样式；Recharts用于数据可视化
- 数据与基础设施：PostgreSQL适合结构化数据与复杂查询；Redis适合任务调度与会话缓存
- 外部依赖与集成点
- 平台适配器：通过抽象基类统一不同AI平台的查询接口
- CORS：允许前端本地开发端口访问后端
- 环境变量：数据库、缓存、密钥与浏览器自动化路径通过配置集中管理
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
图表来源
章节来源
性能考虑
- 异步化与并发
- 后端采用异步数据库会话与异步调度器，提升I/O密集型场景下的吞吐量
- 索引优化
- 查询与引用记录模型建立复合索引，加速定时任务扫描与报表查询
- 缓存与任务解耦
- Redis承担任务调度与会话缓存，避免阻塞主业务线程
- 可视化性能
- 图表组件使用响应式容器与轻量级渲染，减少重绘开销
故障排查指南
- 健康检查
- 后端提供健康检查端点，用于确认服务可用性
- 日志与错误处理
- 调度器与引擎在执行过程中记录错误日志，便于定位失败原因
- 常见问题
- 数据库连接失败：检查PostgreSQL容器健康状态与连接字符串
- 任务未执行：确认Redis可用与调度器已启动
- 平台适配器异常：检查对应平台的API密钥与网络连通性
章节来源
结论
GEO平台通过"多AI平台集成 + 定时查询任务调度 + 数据可视化"的组合，为用户提供从查询到洞察的一体化能力。其分层清晰、模块解耦的设计便于后续扩展更多平台与功能；容器化部署降低了运维复杂度。对于初学者，平台提供了直观的可视化与简洁的API；对于开发者，平台展示了异步架构、任务调度与领域建模的最佳实践。
更新 新增完整的项目文档体系，包括后端和前端的详细README文档，为开发者提供从环境搭建到API使用的完整指导。
附录
系统边界与核心组件关系图
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
- backend/app/workers/scheduler.py:1-95
- backend/app/workers/citation_engine.py:1-309
- docker-compose.yml:1-71
数据流向说明
- 用户在前端发起查询管理与报表查看请求
- 后端API接收请求并访问数据库与缓存
- 调度器周期性触发引用引擎执行跨平台查询
- 引擎对平台返回的原始文本进行品牌匹配与竞争品牌检测
- 结果写入数据库并供前端图表组件消费
章节来源
- backend/app/api/queries.py:1-86
- backend/app/workers/scheduler.py:1-95
- backend/app/workers/citation_engine.py:1-309
- frontend/components/charts/platform-chart.tsx:1-68
快速开始指南
更新 基于新增的README文档，提供完整的项目启动指南：
后端启动步骤
- 创建Python虚拟环境并激活
- 安装依赖：
pip install -r requirements.txt - 安装Playwright浏览器：
playwright install chromium - 复制并配置环境变量：
cp ../.env.example ../.env - 初始化数据库：
alembic upgrade head - 开发模式启动：
uvicorn app.main:app --reload --port 8000
前端启动步骤
- 安装依赖：
npm install - 开发模式启动：
npm run dev - 访问地址：
http://localhost:3000
API端点概览
- 认证模块：注册、登录、用户信息获取
- 查询管理：CRUD操作与立即执行
- 引用数据：列表查询与统计分析
- 报告导出：CSV格式数据导出
章节来源
测试与开发指南
更新 新增测试框架与开发流程说明：
- 测试环境配置：pytest + pytest-asyncio + aiosqlite
- 测试运行：
pytest或指定测试文件 - 覆盖率报告：
pytest --cov=backend/app --cov-report=html - 开发注意事项：统一API调用封装、认证状态管理、组件开发规范
章节来源