21 KiB

Raw Blame History

核心功能

**本文档引用的文件** - [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)

简介

本文件为 GEO 平台的核心功能概览，聚焦以下关键能力：

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

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

项目结构

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

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

核心组件

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

章节来源

架构总览

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

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 : 响应数据/流式下载

图表来源

详细组件分析

用户认证与权限管理

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

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}

图表来源

章节来源

智能查询任务管理

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

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

图表来源

章节来源

品牌引用检测引擎

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

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 : "委托查询"

图表来源

章节来源

多 AI 平台数据集成

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

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

图表来源

章节来源

数据分析与可视化

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

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 : 渲染卡片与趋势图

图表来源

章节来源

报告导出

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

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)

图表来源

章节来源

依赖分析

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

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

图表来源

章节来源

性能考虑

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

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

故障排查指南

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

章节来源

结论

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

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

21 KiB Raw Blame History Unescape Escape

核心功能

目录

简介

项目结构

核心组件

架构总览

详细组件分析

用户认证与权限管理

智能查询任务管理

品牌引用检测引擎

多 AI 平台数据集成

数据分析与可视化

报告导出

依赖分析

性能考虑

故障排查指南

结论

附录

21 KiB

Raw Blame History