# 核心功能

<cite>
**本文档引用的文件**
- [backend/app/main.py](file://backend/app/main.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/reports.py](file://backend/app/api/reports.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/services/citation.py](file://backend/app/services/citation.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/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)
- [frontend/app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx)
- [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx)
</cite>

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

## 简介
本文件为 GEO 平台的核心功能概览，聚焦以下关键能力：
- 用户认证与权限管理：基于邮箱/密码注册登录、JWT 访问令牌签发与校验、会话保护接口。
- 智能查询任务管理：查询词创建、更新、删除、分页查询；按日/周/月频率自动调度；手动触发即时查询。
- 品牌引用检测引擎：多阶段匹配（精确/别名/模糊）、置信度评分、竞争品牌识别、上下文片段抽取。
- 多 AI 平台数据集成：抽象适配器模式对接不同大模型平台，统一查询与结果处理。
- 数据分析与可视化：统计指标（总查询/引用次数、引用率、平均位置）、平台对比、30 天趋势折线图。
- 报告导出：CSV 导出引用记录，便于离线分析与归档。

这些功能围绕“查询—检测—统计—可视—导出”的闭环展开，既满足管理员对系统运行与任务调度的掌控，也服务于研究人员对品牌监测与趋势分析的需求。

## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM，按领域划分 API、服务、模型与工作器；前端使用 Next.js + React，通过自定义 API 客户端与后端交互；数据库为 PostgreSQL。

```mermaid
graph TB
subgraph "后端"
A["FastAPI 应用<br/>app/main.py"]
B["API 层<br/>auth/queries/citations/reports"]
C["服务层<br/>auth/query/citation"]
D["模型层<br/>Query/CitationRecord"]
E["工作器<br/>Scheduler/CitationEngine/Platforms"]
end
subgraph "前端"
F["仪表盘页面<br/>dashboard/page.tsx"]
G["趋势图表组件<br/>trend-chart.tsx"]
end
A --> B
B --> C
C --> D
C --> E
F --> G
F --> B
```

**图表来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [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/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [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/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/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)

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

## 核心组件
- 认证与权限
  - 注册/登录：邮箱唯一性校验、密码哈希、JWT 签发；当前用户信息读取。
  - 权限边界：所有业务接口均通过当前用户上下文进行资源归属校验（查询、引用、统计、导出）。
- 查询任务管理
  - 查询 CRUD：分页列表、创建、读取、更新、删除；创建时校验用户配额上限；更新时可重算下次执行时间。
  - 自动调度：每小时扫描到期查询，自动触发引用检测；手动触发即时查询。
- 引用检测引擎
  - 多阶段匹配：精确命中 → 别名命中 → 模糊相似度阈值；返回是否引用、置信度、位置、上下文。
  - 竞争品牌：基于预设行业品牌库识别竞品。
  - 结果持久化：生成引用记录，包含平台、是否引用、位置、文本、竞品集合、原始响应。
- 多 AI 平台集成
  - 适配器基类定义统一接口；内置“文心”“Kimi”适配器；未来可扩展更多平台。
- 数据分析与可视化
  - 统计聚合：总查询/引用数、引用率、平均位置、按平台汇总、30 天趋势。
  - 前端展示：仪表盘卡片与趋势折线图组件。
- 报告导出
  - 支持 CSV 下载，包含日期、平台、是否引用、引用位置、引用文本、竞品品牌等字段。

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [frontend/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)

## 架构总览
下图展示从用户请求到数据落库与可视化的整体流程，以及定时调度与即时查询的协同机制。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant API as "后端API"
participant S as "服务层"
participant DB as "数据库"
participant W as "工作器"
participant CE as "引用检测引擎"
participant P as "AI平台适配器"
U->>FE : 登录/访问仪表盘
FE->>API : 获取统计/查询/引用/导出
API->>S : 参数校验与业务处理
S->>DB : 读写查询/引用/任务
Note over S,DB : 权限校验：仅允许访问本人资源
API->>W : 触发/查询任务
W->>CE : 执行查询
CE->>P : 平台查询
P-->>CE : 原始响应
CE->>S : 写入引用记录
S->>DB : 持久化
DB-->>S : 成功
S-->>API : 结果
API-->>FE : 响应数据/流式下载
```

**图表来源**
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
- [backend/app/api/citations.py:59-77](file://backend/app/api/citations.py#L59-L77)
- [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/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)

## 详细组件分析

### 用户认证与权限管理
- 功能要点
  - 注册：邮箱唯一性检查、密码加密存储、返回用户信息。
  - 登录：邮箱+密码验证、签发 JWT（含过期时间），返回用户与令牌。
  - 当前用户：受保护路由读取当前用户上下文。
- 关键价值
  - 保障数据隔离：所有业务接口均以当前用户为准进行资源归属校验。
  - 易于扩展：JWT 可用于跨域与第三方集成。
- 典型流程
  - 注册 → 登录 → 携带令牌访问受保护接口 → 获取/创建查询 → 触发查询 → 查看统计/导出报告。

```mermaid
sequenceDiagram
participant U as "用户"
participant API as "认证API"
participant S as "认证服务"
participant DB as "数据库"
U->>API : POST /api/v1/auth/register
API->>S : 注册逻辑
S->>DB : 检查邮箱/保存用户
DB-->>S : 成功
S-->>API : 用户对象
U->>API : POST /api/v1/auth/login
API->>S : 验证邮箱/密码
S->>DB : 查询用户
DB-->>S : 用户信息
S-->>API : JWT令牌
API-->>U : {access_token,user}
```

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

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)

### 智能查询任务管理
- 功能要点
  - 查询 CRUD：分页列表、创建（校验配额与频率）、读取、更新（频率变更时重算下次执行时间）、删除。
  - 自动调度：每小时扫描到期查询，调用引用检测引擎执行；更新查询最近与下次执行时间。
  - 即时查询：手动触发，为每个配置平台创建任务并入队。
- 核心价值
  - 减少人工干预：按计划自动抓取与检测，提升研究效率。
  - 灵活控制：支持日/周/月频率与手动触发，兼顾实时性与成本。
- 典型场景
  - 研究员创建查询（关键词、目标品牌、平台、频率），系统按时自动执行；也可随时“立即执行”。

```mermaid
flowchart TD
Start(["创建查询"]) --> CheckLimit["检查用户配额"]
CheckLimit --> |未超限| CalcNext["按频率计算下次执行时间"]
CheckLimit --> |超限| Deny["拒绝创建"]
CalcNext --> SaveQ["保存查询"]
SaveQ --> Schedule["等待调度器扫描"]
Schedule --> Due{"到期？"}
Due --> |否| Wait["继续等待"]
Due --> |是| Trigger["触发引用检测"]
Trigger --> UpdateTime["更新最近/下次执行时间"]
UpdateTime --> Done(["完成一轮周期"])
```

**图表来源**
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:291-300](file://backend/app/workers/citation_engine.py#L291-L300)

**章节来源**
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)

### 品牌引用检测引擎
- 功能要点
  - 品牌匹配器：精确命中（置信度1.0）→ 别名命中（置信度0.9）→ 模糊相似度（阈值0.4）；返回是否引用、置信度、位置、上下文。
  - 竞争品牌检测：基于预设行业品牌库识别其他品牌。
  - 结果持久化：记录平台、是否引用、位置、文本、竞品、原始响应。
- 核心价值
  - 置信度评分：帮助判断引用可靠性；模糊匹配提供兜底发现。
  - 上下文定位：快速定位品牌在原文中的首次出现段落，便于人工复核。
- 典型场景
  - 文本中提及“XX品牌”，匹配器判定为“别名命中”，置信度0.9，并返回首次出现段落片段。

```mermaid
classDiagram
class CitationEngine {
+execute_query(query, db) CitationRecord[]
+execute_single_platform(keyword, platform, target_brand, aliases) dict
}
class BrandMatcher {
+match(text) dict
}
class CompetitorDetector {
+detect(text, target_brand) str[]
}
class BasePlatformAdapter {
<<abstract>>
+query(keyword) str
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
CitationEngine --> BasePlatformAdapter : "委托查询"
```

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

**章节来源**
- [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)

### 多 AI 平台数据集成
- 功能要点
  - 适配器基类定义统一接口（平台名、URL、查询方法）。
  - 内置“文心”“Kimi”适配器；引擎按查询配置的平台列表逐一执行。
- 核心价值
  - 解耦平台差异：统一调用入口，便于扩展更多平台。
  - 可观测性：每个平台独立任务状态（pending/running/success/failed）。
- 典型场景
  - 查询配置包含“wenxin,kimi”，引擎为两者分别创建任务并行执行，最终汇总结果。

```mermaid
sequenceDiagram
participant CE as "CitationEngine"
participant Q as "Query"
participant T as "QueryTask"
participant A as "平台适配器"
CE->>Q : 读取平台列表
loop 遍历平台
CE->>T : 获取/创建任务
CE->>A : 调用 query(keyword)
A-->>CE : 返回原始响应
CE->>CE : 品牌匹配/竞品检测
CE->>T : 更新任务状态
end
```

**图表来源**
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/base.py:10-17](file://backend/app/workers/platforms/base.py#L10-L17)

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

### 数据分析与可视化
- 功能要点
  - 统计接口：总查询/引用数、引用率、平均位置、按平台汇总、30 天趋势（按自然周聚合）。
  - 前端仪表盘：卡片展示核心指标；趋势折线图展示过去 30 天每周引用次数。
- 核心价值
  - 快速洞察：总览指标帮助评估监测效果与变化趋势。
  - 易用性：图表直观呈现，降低阅读成本。
- 典型场景
  - 研究人员查看“过去30天引用趋势”，发现某周显著上升，结合上下文进一步分析。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "统计API"
participant S as "统计服务"
participant DB as "数据库"
FE->>API : GET /api/v1/citations/stats
API->>S : 统计聚合
S->>DB : 聚合查询/分组统计
DB-->>S : 结果集
S-->>API : {total,rate,avg,by_platform,trend}
API-->>FE : 返回JSON
FE->>FE : 渲染卡片与趋势图
```

**图表来源**
- [frontend/app/(dashboard)/dashboard/page.tsx:20-155](file://frontend/app/(dashboard)/dashboard/page.tsx#L20-L155)
- [frontend/components/charts/trend-chart.tsx:22-59](file://frontend/components/charts/trend-chart.tsx#L22-L59)
- [backend/app/api/citations.py:49-56](file://backend/app/api/citations.py#L49-L56)
- [backend/app/services/citation.py:76-201](file://backend/app/services/citation.py#L76-L201)

**章节来源**
- [frontend/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)

### 报告导出
- 功能要点
  - 支持 CSV 导出指定查询的所有引用记录，包含日期、平台、是否引用、引用位置、引用文本、竞品品牌。
  - 流式响应，避免大文件内存压力。
- 核心价值
  - 离线分析：便于导入 Excel/BI 工具做深度分析。
  - 合规归档：结构化导出满足审计与存档需求。
- 典型场景
  - 研究员导出某周的全部引用记录，用于撰写专题报告。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "导出API"
participant S as "导出服务"
participant DB as "数据库"
FE->>API : GET /api/v1/reports/export/csv?query_id=...
API->>S : 导出CSV
S->>DB : 查询引用记录
DB-->>S : 记录集
S-->>API : CSV字符串
API-->>FE : 流式响应(Attachment)
```

**图表来源**
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/services/citation.py:237-268](file://backend/app/services/citation.py#L237-L268)

**章节来源**
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/services/citation.py:237-268](file://backend/app/services/citation.py#L237-L268)

## 依赖分析
- 组件耦合
  - API 层仅负责参数解析与鉴权，业务逻辑集中在服务层，降低控制器复杂度。
  - 引擎与平台适配器通过抽象接口解耦，便于替换与扩展。
  - 调度器与引擎通过 ORM 与任务表协作，避免直接耦合业务数据。
- 外部依赖
  - FastAPI/SQLAlchemy：Web 框架与 ORM。
  - APScheduler：异步定时任务调度。
  - Recharts：前端图表渲染。
- 潜在风险
  - 平台适配器异常需隔离，避免影响其他平台任务。
  - 大量并发查询可能带来数据库与外部平台压力，建议限流与重试策略。

```mermaid
graph LR
API["API层"] --> SVC["服务层"]
SVC --> MODEL["模型层"]
SVC --> WORKER["工作器"]
WORKER --> ADAPTER["平台适配器"]
FE["前端"] --> API
```

**图表来源**
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [backend/app/workers/citation_engine.py:151-157](file://backend/app/workers/citation_engine.py#L151-L157)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)

## 性能考虑
- 数据库
  - 查询索引：查询与引用记录表均建立常用过滤字段索引，减少扫描开销。
  - 分页与聚合：统计接口使用分组与聚合，避免一次性拉取全量数据。
- 引擎与平台
  - 并行执行：同一查询的不同平台可并行处理，缩短总耗时。
  - 错误隔离：单平台失败不影响其他平台，保证整体可用性。
- 前端
  - 图表懒加载与响应式容器，提升大屏体验。
  - 导出采用流式响应，避免内存峰值。

[本节为通用指导，无需具体文件分析]

## 故障排查指南
- 认证问题
  - 注册失败：邮箱已被注册；检查重复提交或换用其他邮箱。
  - 登录失败：邮箱或密码错误；确认凭据正确与网络可达。
- 查询任务
  - 创建被拒：超出配额；联系管理员提升限额或清理历史查询。
  - 无法执行：查询状态非“active”或未配置平台；检查状态与平台列表。
  - 即时查询无响应：平台适配器异常或网络超时；查看任务状态与错误信息。
- 统计与导出
  - 统计为空：可能因筛选条件导致无数据；尝试放宽时间范围或移除查询筛选。
  - 导出失败：查询不存在或无权限；确认 query_id 与登录态。
- 调度器
  - 未触发：检查调度器是否启动、时区设置、下次执行时间是否已到达。

**章节来源**
- [backend/app/services/auth.py:37-69](file://backend/app/services/auth.py#L37-L69)
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)

## 结论
GEO 平台以“查询—检测—统计—可视—导出”为主线，构建了从自动化采集到深度分析的完整链路。通过严格的权限控制、可扩展的平台适配器、稳健的定时调度与清晰的可视化输出，既能满足管理员对系统运行的掌控，也能为研究人员提供高效、可靠的品牌监测工具。建议后续在平台适配器层面引入重试与熔断、在数据库侧增加慢查询监控与索引优化，持续提升稳定性与性能。

[本节为总结性内容，无需具体文件分析]

## 附录
- 典型使用流程（管理员）
  - 新建用户/分配配额 → 配置平台密钥 → 监控调度器运行 → 查看任务状态与错误日志 → 调整频率策略。
- 典型使用流程（研究人员）
  - 登录 → 创建查询（关键词/目标品牌/平台/频率） → 查看仪表盘趋势 → 导出报告 → 深度分析与汇报。
- 关键接口路径参考
  - 认证：POST /api/v1/auth/register, POST /api/v1/auth/login, GET /api/v1/auth/me
  - 查询：GET/POST/GET/PATCH/DELETE /api/v1/queries
  - 引用：GET /api/v1/citations, GET /api/v1/citations/stats, POST /api/v1/queries/{query_id}/run-now
  - 报告：GET /api/v1/reports/export/csv

[本节为概览性内容，无需具体文件分析]