# 功能扩展

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

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

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

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

```mermaid
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
```

**图表来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)

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

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

**章节来源**
- [backend/app/main.py:38-47](file://backend/app/main.py#L38-L47)
- [backend/app/workers/citation_engine.py:148-301](file://backend/app/workers/citation_engine.py#L148-L301)
- [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [backend/app/models/citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [backend/app/services/citation.py:24-201](file://backend/app/services/citation.py#L24-L201)
- [frontend/lib/api.ts:23-57](file://frontend/lib/api.ts#L23-L57)
- [frontend/components/ui/button.tsx:1-57](file://frontend/components/ui/button.tsx#L1-L57)

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

```mermaid
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 : "渲染图表与卡片"
```

**图表来源**
- [frontend/app/(dashboard)/dashboard/page.tsx:30-44](file://frontend/app/(dashboard)/dashboard/page.tsx#L30-L44)
- [frontend/lib/api.ts:46-50](file://frontend/lib/api.ts#L46-L50)
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [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)
- [backend/app/workers/citation_engine.py:148-301](file://backend/app/workers/citation_engine.py#L148-L301)

## 详细组件分析

### 新增API接口：后端路由、模型与业务逻辑
- 新增后端路由
  - 在API包中创建新的路由模块，定义路径、参数与响应模型。
  - 在应用入口注册路由并设置前缀与标签。
  - 示例参考：引用路由与统计接口的组织方式。
  
  **章节来源**
  - [backend/app/api/citations.py:21-78](file://backend/app/api/citations.py#L21-L78)
  - [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)

- 数据模型扩展
  - 在models目录新增或修改ORM模型，定义字段、索引与外键关系。
  - 使用PostgreSQL JSONB类型存储动态配置（如品牌别名、平台列表）。
  - 示例参考：查询与引用记录模型的字段与索引设计。
  
  **章节来源**
  - [backend/app/models/query.py:11-55](file://backend/app/models/query.py#L11-L55)
  - [backend/app/models/citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)

- 业务逻辑实现
  - 在services目录编写数据访问与聚合逻辑，确保权限校验与边界条件处理。
  - 对于复杂统计，使用SQL聚合函数与分组查询，保证性能与准确性。
  - 示例参考：引用统计与CSV导出的实现。
  
  **章节来源**
  - [backend/app/services/citation.py:76-201](file://backend/app/services/citation.py#L76-L201)
  - [backend/app/services/citation.py:237-269](file://backend/app/services/citation.py#L237-L269)

- Pydantic模型与响应格式
  - 在schemas目录定义请求/响应模型，确保类型安全与序列化一致性。
  - 示例参考：引用列表、统计与运行任务响应模型。
  
  **章节来源**
  - [backend/app/schemas/citation.py:7-50](file://backend/app/schemas/citation.py#L7-L50)

- 引擎扩展：品牌匹配与竞争品牌识别
  - 品牌匹配策略：精确匹配、别名匹配、模糊匹配（编辑距离），并返回置信度与上下文片段。
  - 竞争品牌识别：预定义行业品牌库，检测除目标品牌外的其他品牌。
  - 引擎执行流程：按平台顺序执行查询、匹配与记录生成，并更新查询任务状态与下次查询时间。
  
  **章节来源**
  - [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:159-234](file://backend/app/workers/citation_engine.py#L159-L234)

- 平台适配器扩展
  - 继承基类实现query方法，处理页面交互、稳定性检测与异常重试。
  - 支持多平台并行扩展，统一由引擎调度。
  
  **章节来源**
  - [backend/app/workers/platforms/base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)
  - [backend/app/workers/platforms/kimi.py:33-125](file://backend/app/workers/platforms/kimi.py#L33-L125)
  - [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py)

### 前端页面扩展：Next.js路由、组件与状态管理
- Next.js页面路由添加
  - 在App Router中新增页面目录与page组件，使用useSession获取会话信息。
  - 在根布局中注入Provider，确保全局状态可用。
  
  **章节来源**
  - [frontend/app/layout.tsx:22-36](file://frontend/app/layout.tsx#L22-L36)
  - [frontend/app/(dashboard)/dashboard/page.tsx:20-44](file://frontend/app/(dashboard)/dashboard/page.tsx#L20-L44)

- 组件开发与状态管理集成
  - 使用React Hook进行数据加载与错误处理，结合UI组件库构建卡片与图表。
  - 在图表组件中使用Recharts实现响应式可视化。
  
  **章节来源**
  - [frontend/components/layout/header.tsx:7-29](file://frontend/components/layout/header.tsx#L7-L29)
  - [frontend/components/charts/trend-chart.tsx:22-59](file://frontend/components/charts/trend-chart.tsx#L22-L59)

- API客户端集成
  - 统一封装fetchWithAuth，自动附加Authorization头并处理错误。
  - 在页面中调用api.citations.getStats加载统计数据。
  
  **章节来源**
  - [frontend/lib/api.ts:3-21](file://frontend/lib/api.ts#L3-L21)
  - [frontend/lib/api.ts:46-50](file://frontend/lib/api.ts#L46-L50)
  - [frontend/app/(dashboard)/dashboard/page.tsx:30-44](file://frontend/app/(dashboard)/dashboard/page.tsx#L30-L44)

### UI组件库扩展指南
- 新组件开发
  - 基于Radix UI与cva变体系统，定义默认样式与尺寸变体。
  - 使用Slot支持透传子节点，保持语义化与可组合性。
  
  **章节来源**
  - [frontend/components/ui/button.tsx:7-54](file://frontend/components/ui/button.tsx#L7-L54)

- 样式定制与响应式设计
  - 使用Tailwind CSS变量与暗色主题适配，确保组件在深色模式下的可读性。
  - 图表组件使用ResponsiveContainer实现自适应宽高。
  
  **章节来源**
  - [frontend/components/charts/trend-chart.tsx:24-58](file://frontend/components/charts/trend-chart.tsx#L24-L58)

## 依赖分析
- 后端模块耦合
  - API层仅依赖服务层；服务层依赖模型与引擎；引擎依赖平台适配器。
  - 数据库索引覆盖常用查询条件，提升统计与分页性能。
  
  ```mermaid
graph LR
API["API 层<br/>backend/app/api/*"] --> SVC["服务层<br/>backend/app/services/*"]
SVC --> MODELS["模型层<br/>backend/app/models/*"]
SVC --> ENGINE["引擎层<br/>backend/app/workers/citation_engine.py"]
ENGINE --> ADAPTERS["平台适配器<br/>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)