16 KiB

Raw Permalink Blame History

功能扩展

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/api/citations.py](file://backend/app/api/citations.py) - [backend/app/schemas/citation.py](file://backend/app/schemas/citation.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/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/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py) - [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py) - [frontend/app/layout.tsx](file://frontend/app/layout.tsx) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [frontend/app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx) - [frontend/components/ui/button.tsx](file://frontend/components/ui/button.tsx) - [frontend/components/layout/header.tsx](file://frontend/components/layout/header.tsx) - [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx)

简介

本文件面向GEO平台的功能扩展，系统性地说明如何新增API接口（后端路由、数据模型、业务逻辑）、前端页面扩展（Next.js路由、组件与状态管理）、引用检测引擎扩展（新品牌匹配策略、竞争品牌识别算法）、以及UI组件库扩展（新组件开发、样式定制与响应式设计）。文档同时提供流程图、序列图与类图，帮助开发者快速理解并落地实施。

项目结构

后端采用FastAPI，模块化组织API、模型、服务与工作流；数据库使用SQLAlchemy ORM，迁移通过Alembic管理。
前端采用Next.js App Router，以功能域分层组织页面、组件与工具函数；UI基于Radix UI与Tailwind CSS。

graph TB
subgraph "后端"
A["FastAPI 应用<br/>backend/app/main.py"]
B["API 路由<br/>backend/app/api/*"]
C["模型与表结构<br/>backend/app/models/*"]
D["服务层<br/>backend/app/services/*"]
E["工作流与引擎<br/>backend/app/workers/*"]
end
subgraph "前端"
F["应用布局<br/>frontend/app/layout.tsx"]
G["API 客户端<br/>frontend/lib/api.ts"]
H["页面与组件<br/>frontend/app/(dashboard)/*"]
I["UI 组件库<br/>frontend/components/ui/*"]
J["图表组件<br/>frontend/components/charts/*"]
end
A --> B
B --> D
D --> C
D --> E
F --> H
H --> G
H --> I
H --> J

图表来源

章节来源

核心组件

后端API入口与路由挂载：在应用生命周期内注册认证、查询、引用、报告等路由，并开放健康检查端点。
引用检测引擎：负责品牌匹配、竞争品牌识别、跨平台适配与任务调度。
数据模型：查询、引用记录、任务等核心实体及索引。
服务层：封装数据访问、统计聚合、导出与即时触发逻辑。
前端API客户端：统一处理鉴权头、错误与响应解析。
UI组件库：基于Radix UI的可变样式组件，支持主题与尺寸变体。

章节来源

架构总览

下图展示从前端到后端的关键交互路径，包括API调用、服务层处理与引擎执行。

sequenceDiagram
participant FE as "前端页面<br/>frontend/app/(dashboard)/dashboard/page.tsx"
participant API as "API 客户端<br/>frontend/lib/api.ts"
participant APP as "FastAPI 应用<br/>backend/app/main.py"
participant ROUTER as "引用路由<br/>backend/app/api/citations.py"
participant SVC as "服务层<br/>backend/app/services/citation.py"
participant ENG as "引擎<br/>backend/app/workers/citation_engine.py"
FE->>API : "调用统计数据接口"
API->>APP : "GET /api/v1/citations/stats"
APP->>ROUTER : "转发到引用统计路由"
ROUTER->>SVC : "get_citation_stats(user_id, query_id?)"
SVC->>ENG : "聚合统计含趋势、平台分布"
ENG-->>SVC : "返回统计结果"
SVC-->>ROUTER : "返回统计结果"
ROUTER-->>API : "JSON 响应"
API-->>FE : "渲染图表与卡片"

图表来源

详细组件分析

新增API接口：后端路由、模型与业务逻辑

新增后端路由
- 在API包中创建新的路由模块，定义路径、参数与响应模型。
- 在应用入口注册路由并设置前缀与标签。
- 示例参考：引用路由与统计接口的组织方式。
章节来源
- backend/app/api/citations.py:21-78
- backend/app/main.py:38-42
数据模型扩展
- 在models目录新增或修改ORM模型，定义字段、索引与外键关系。
- 使用PostgreSQL JSONB类型存储动态配置（如品牌别名、平台列表）。
- 示例参考：查询与引用记录模型的字段与索引设计。
章节来源
- backend/app/models/query.py:11-55
- backend/app/models/citation_record.py:11-42
业务逻辑实现
- 在services目录编写数据访问与聚合逻辑，确保权限校验与边界条件处理。
- 对于复杂统计，使用SQL聚合函数与分组查询，保证性能与准确性。
- 示例参考：引用统计与CSV导出的实现。
章节来源
- backend/app/services/citation.py:76-201
- backend/app/services/citation.py:237-269
Pydantic模型与响应格式
- 在schemas目录定义请求/响应模型，确保类型安全与序列化一致性。
- 示例参考：引用列表、统计与运行任务响应模型。
章节来源
- backend/app/schemas/citation.py:7-50
引擎扩展：品牌匹配与竞争品牌识别
- 品牌匹配策略：精确匹配、别名匹配、模糊匹配（编辑距离），并返回置信度与上下文片段。
- 竞争品牌识别：预定义行业品牌库，检测除目标品牌外的其他品牌。
- 引擎执行流程：按平台顺序执行查询、匹配与记录生成，并更新查询任务状态与下次查询时间。
章节来源
平台适配器扩展
- 继承基类实现query方法，处理页面交互、稳定性检测与异常重试。
- 支持多平台并行扩展，统一由引擎调度。
章节来源

前端页面扩展：Next.js路由、组件与状态管理

Next.js页面路由添加
- 在App Router中新增页面目录与page组件，使用useSession获取会话信息。
- 在根布局中注入Provider，确保全局状态可用。
章节来源
- frontend/app/layout.tsx:22-36
- frontend/app/(dashboard)/dashboard/page.tsx:20-44
组件开发与状态管理集成
- 使用React Hook进行数据加载与错误处理，结合UI组件库构建卡片与图表。
- 在图表组件中使用Recharts实现响应式可视化。
章节来源
- frontend/components/layout/header.tsx:7-29
- frontend/components/charts/trend-chart.tsx:22-59
API客户端集成
- 统一封装fetchWithAuth，自动附加Authorization头并处理错误。
- 在页面中调用api.citations.getStats加载统计数据。
章节来源

UI组件库扩展指南

新组件开发
- 基于Radix UI与cva变体系统，定义默认样式与尺寸变体。
- 使用Slot支持透传子节点，保持语义化与可组合性。
章节来源
- frontend/components/ui/button.tsx:7-54
样式定制与响应式设计
- 使用Tailwind CSS变量与暗色主题适配，确保组件在深色模式下的可读性。
- 图表组件使用ResponsiveContainer实现自适应宽高。
章节来源
- frontend/components/charts/trend-chart.tsx:24-58

依赖分析

后端模块耦合
- API层仅依赖服务层；服务层依赖模型与引擎；引擎依赖平台适配器。
- 数据库索引覆盖常用查询条件，提升统计与分页性能。

graph LR API["API 层
backend/app/api/"] --> SVC["服务层
backend/app/services/"] SVC --> MODELS["模型层
backend/app/models/"] SVC --> ENGINE["引擎层
backend/app/workers/citation_engine.py"] ENGINE --> ADAPTERS["平台适配器
backend/app/workers/platforms/"]


**图表来源**
- [backend/app/api/citations.py:15-19](file://backend/app/api/citations.py#L15-L19)
- [backend/app/services/citation.py:9-12](file://backend/app/services/citation.py#L9-L12)
- [backend/app/workers/citation_engine.py:148-157](file://backend/app/workers/citation_engine.py#L148-L157)
- [backend/app/workers/platforms/base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)

**章节来源**
- [backend/app/models/query.py:50-54](file://backend/app/models/query.py#L50-L54)
- [backend/app/models/citation_record.py:37-41](file://backend/app/models/citation_record.py#L37-L41)

## 性能考虑
- 数据库查询优化
  - 为高频过滤字段建立索引（如用户ID、状态、下次查询时间、查询ID、查询时间等）。
  - 使用SQL聚合与分组减少Python侧计算开销。
- 引擎执行策略
  - 平台查询采用指数退避与稳定性检测，避免频繁失败与重复请求。
  - 将统计聚合与导出逻辑异步化，避免阻塞主流程。
- 前端渲染优化
  - 图表组件使用ResponsiveContainer与轻量级数据结构，降低重排成本。
  - 页面按需加载与错误兜底，提升用户体验。

**章节来源**
- [backend/app/models/query.py:50-54](file://backend/app/models/query.py#L50-L54)
- [backend/app/models/citation_record.py:37-41](file://backend/app/models/citation_record.py#L37-L41)
- [backend/app/workers/platforms/kimi.py:126-197](file://backend/app/workers/platforms/kimi.py#L126-L197)
- [frontend/components/charts/trend-chart.tsx:24-58](file://frontend/components/charts/trend-chart.tsx#L24-L58)

## 故障排查指南
- 引擎执行失败
  - 平台适配器抛出异常时，记录错误信息并创建一条cited=False的占位记录，便于追踪。
  - 关闭适配器资源，避免句柄泄漏。
  
  **章节来源**
  - [backend/app/workers/citation_engine.py:211-228](file://backend/app/workers/citation_engine.py#L211-L228)
  - [backend/app/workers/citation_engine.py:302-309](file://backend/app/workers/citation_engine.py#L302-L309)

- API调用失败
  - 前端API客户端统一处理HTTP错误与JSON解析，抛出可读错误信息。
  - 页面中捕获错误并提供重试入口。
  
  **章节来源**
  - [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)
  - [frontend/app/(dashboard)/dashboard/page.tsx:54-66](file://frontend/app/(dashboard)/dashboard/page.tsx#L54-L66)

- 权限与数据隔离
  - 服务层在查询与导出前验证查询归属，防止越权访问。
  
  **章节来源**
  - [backend/app/services/citation.py:14-22](file://backend/app/services/citation.py#L14-L22)
  - [backend/app/services/citation.py:242-244](file://backend/app/services/citation.py#L242-L244)

## 结论
通过模块化的后端架构与清晰的前后端职责划分，GEO平台具备良好的扩展性。新增API接口与页面只需遵循现有路由、模型与服务层规范；引擎与适配器的抽象设计使得品牌匹配策略与平台能力可插拔扩展；UI组件库提供了统一的样式与交互体验。建议在扩展过程中严格遵循数据权限、错误处理与性能优化的最佳实践。

## 附录
- 新增品牌匹配策略的实现要点
  - 在BrandMatcher中扩展候选词提取与相似度阈值，支持领域特定规则（如正则匹配、停用词过滤）。
  - 为不同行业维护品牌别名库，提高别名匹配准确率。
  
  **章节来源**
  - [backend/app/workers/citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)

- 竞争品牌识别算法的实现要点
  - 基于预定义品牌分类（保险、金融、科技等）进行集合比对，排除目标品牌。
  - 可引入NLP分词与实体识别进一步提升召回质量。
  
  **章节来源**
  - [backend/app/workers/citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)

- 平台适配器扩展流程
  - 继承BasePlatformAdapter，实现query方法与可选的close方法。
  - 在引擎中注册平台映射，确保execute_query能够调度新平台。
  
  **章节来源**
  - [backend/app/workers/platforms/base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)
  - [backend/app/workers/citation_engine.py:152-157](file://backend/app/workers/citation_engine.py#L152-L157)

16 KiB Raw Permalink Blame History Unescape Escape