# 适配器架构设计

<cite>
**本文档引用的文件**
- [base.py](file://backend/app/workers/platforms/base.py)
- [kimi.py](file://backend/app/workers/platforms/kimi.py)
- [wenxin.py](file://backend/app/workers/platforms/wenxin.py)
- [citation_engine.py](file://backend/app/workers/citation_engine.py)
- [scheduler.py](file://backend/app/workers/scheduler.py)
- [queries.py](file://backend/app/api/queries.py)
- [query.py](file://backend/app/models/query.py)
- [main.py](file://backend/app/main.py)
- [platforms.ts](file://frontend/lib/platforms.ts)
- [platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx)
</cite>

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

## 简介

本项目采用适配器模式设计了一个可扩展的AI平台查询系统。该架构通过统一的接口抽象，实现了对不同AI平台（如Kimi、文心一言等）的无缝集成和切换。适配器模式在此场景中的应用价值体现在：

- **统一接口**：为不同的AI平台提供一致的查询接口
- **可扩展性**：轻松添加新的AI平台适配器
- **资源管理**：统一的资源清理和生命周期管理
- **错误处理**：标准化的异常处理和重试机制

## 项目结构

该项目采用前后端分离的架构设计，后端使用Python FastAPI框架，前端使用Next.js React框架。适配器架构主要集中在后端的workers目录中。

```mermaid
graph TB
subgraph "前端层"
FE[前端应用<br/>Next.js React]
PC[平台图表组件<br/>platform-chart.tsx]
PL[平台映射<br/>platforms.ts]
end
subgraph "后端层"
API[FastAPI API]
CE[CitationEngine<br/>引用检测引擎]
SCH[Scheduler<br/>调度器]
subgraph "适配器层"
BA[BasePlatformAdapter<br/>抽象基类]
KA[KimiAdapter<br/>Kimi适配器]
WA[WenxinAdapter<br/>文心一言适配器]
end
end
subgraph "数据层"
DB[(PostgreSQL数据库)]
QM[Query模型]
CRM[CitationRecord模型]
end
FE --> API
API --> CE
CE --> SCH
CE --> BA
BA --> KA
BA --> WA
CE --> DB
QM --> DB
CRM --> DB
```

**图表来源**
- [main.py:13-22](file://backend/app/main.py#L13-L22)
- [citation_engine.py:148-157](file://backend/app/workers/citation_engine.py#L148-L157)
- [base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)

**章节来源**
- [main.py:1-48](file://backend/app/main.py#L1-L48)
- [platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)

## 核心组件

### BasePlatformAdapter 抽象基类

BasePlatformAdapter是整个适配器架构的核心抽象类，定义了所有AI平台适配器必须实现的标准接口。

#### 设计理念

该类采用了Python的ABC（Abstract Base Classes）机制，确保子类必须实现指定的抽象方法。设计理念包括：

- **最小接口原则**：只定义必要的抽象方法，避免过度设计
- **职责单一原则**：专注于平台适配功能，不包含业务逻辑
- **扩展性优先**：为未来添加新平台预留空间

#### 核心属性

| 属性名称 | 类型 | 描述 | 示例值 |
|---------|------|------|--------|
| platform_name | str | 平台标识符，用于内部识别 | "kimi", "wenxin" |
| platform_url | str | 平台官方网站地址 | "https://kimi.moonshot.cn" |

#### 抽象方法

**query(keyword: str) -> str**
- **设计目的**：在AI平台上查询关键词并返回原始响应文本
- **参数规范**：
  - keyword: str - 要查询的关键词
  - 返回值: str - AI平台的原始响应文本
- **实现要求**：必须异步实现，支持重试机制

**close()**
- **设计目的**：清理适配器使用的系统资源
- **实现要求**：异步方法，确保资源正确释放

**章节来源**
- [base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)

### 具体适配器实现

#### KimiAdapter

KimiAdapter是针对Moonshot AI平台的适配器实现，具有以下特点：

- **浏览器自动化**：使用Playwright进行页面交互
- **智能重试**：指数退避重试机制
- **稳定性保障**：超时处理和异常恢复

#### WenxinAdapter

WenxinAdapter是针对百度文心一言平台的适配器实现：

- **相似架构**：与KimiAdapter类似的实现模式
- **平台特定**：针对文心一言的界面结构优化
- **一致性保证**：保持与BasePlatformAdapter的接口兼容

**章节来源**
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)

## 架构概览

整个系统采用分层架构设计，适配器模式位于中间层，向上提供统一接口，向下封装具体实现细节。

```mermaid
sequenceDiagram
participant Client as 客户端
participant API as FastAPI API
participant Engine as CitationEngine
participant Adapter as BasePlatformAdapter
participant Platform as AI平台
Client->>API : 发起查询请求
API->>Engine : execute_query()
Engine->>Engine : 创建BrandMatcher
Engine->>Adapter : execute_single_platform()
Adapter->>Adapter : query(keyword)
Adapter->>Platform : 执行平台查询
Platform-->>Adapter : 返回响应文本
Adapter-->>Engine : 返回原始响应
Engine->>Engine : 品牌匹配和竞争检测
Engine-->>API : 返回检测结果
API-->>Client : 返回查询结果
```

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

## 详细组件分析

### CitationEngine 引用检测引擎

CitationEngine是系统的中央协调器，负责管理多个平台适配器并执行完整的查询流程。

#### 核心功能

1. **平台管理**：维护平台适配器字典
2. **查询执行**：协调单个平台的查询过程
3. **结果处理**：整合品牌匹配和竞争检测结果
4. **任务跟踪**：管理查询任务的状态和历史

#### 关键流程

```mermaid
flowchart TD
Start([开始查询]) --> InitMatcher["初始化BrandMatcher"]
InitMatcher --> GetPlatforms["获取平台列表"]
GetPlatforms --> LoopPlatforms{"遍历平台"}
LoopPlatforms --> CreateTask["创建或获取QueryTask"]
CreateTask --> UpdateStatus["更新任务状态为running"]
UpdateStatus --> ExecutePlatform["执行单个平台查询"]
ExecutePlatform --> BrandMatch["品牌匹配检测"]
BrandMatch --> CompetitorDetect["竞争品牌检测"]
CompetitorDetect --> CreateRecord["创建CitationRecord"]
CreateRecord --> UpdateTaskSuccess["更新任务状态为success"]
UpdateTaskSuccess --> NextPlatform{"还有平台吗?"}
NextPlatform --> |是| LoopPlatforms
NextPlatform --> |否| UpdateQueryTime["更新查询时间字段"]
UpdateQueryTime --> End([结束])
ExecutePlatform --> |异常| CreateFailedRecord["创建失败记录"]
CreateFailedRecord --> UpdateTaskFailed["更新任务状态为failed"]
UpdateTaskFailed --> NextPlatform
```

**图表来源**
- [citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [citation_engine.py:236-266](file://backend/app/workers/citation_engine.py#L236-L266)

#### 数据模型

```mermaid
erDiagram
QUERY {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
datetime last_queried_at
datetime next_query_at
datetime created_at
datetime updated_at
}
CITATION_RECORD {
uuid id PK
uuid query_id FK
string platform
boolean cited
integer citation_position
text citation_text
jsonb competitor_brands
text raw_response
datetime created_at
datetime updated_at
}
QUERY_TASK {
uuid id PK
uuid query_id FK
string platform
string status
datetime started_at
datetime completed_at
text error_message
datetime created_at
datetime updated_at
}
USER ||--o{ QUERY : creates
QUERY ||--o{ CITATION_RECORD : generates
QUERY ||--o{ QUERY_TASK : tracks
```

**图表来源**
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)

**章节来源**
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)

### Scheduler 调度器

QueryScheduler负责定时执行查询任务，确保系统能够自动运行。

#### 核心特性

- **定时执行**：每小时检查一次到期的查询任务
- **异步处理**：使用AsyncIOScheduler支持异步操作
- **错误隔离**：单个查询失败不影响其他任务
- **优雅关闭**：提供资源清理机制

#### 生命周期管理

```mermaid
stateDiagram-v2
[*] --> 初始化
初始化 --> 启动 : start()
启动 --> 运行中 : 添加定时任务
运行中 --> 执行检查 : 每小时触发
执行检查 --> 处理查询 : 发现到期任务
处理查询 --> 运行中 : 继续监控
处理查询 --> 错误 : 异常处理
错误 --> 运行中 : 记录日志继续
运行中 --> 关闭 : shutdown()
关闭 --> [*]
```

**图表来源**
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

**章节来源**
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

### 前端集成

前端系统提供了完整的用户界面，支持平台选择和结果展示。

#### 平台映射

前端使用PLATFORM_MAP和PLATFORMS常量来管理平台信息：

| 平台键 | 中文名称 | 用途 |
|--------|----------|------|
| wenxin | 文心一言 | 百度AI平台 |
| kimi | Kimi | Moonshot AI平台 |
| tongyi | 通义千问 | 阿里云AI平台 |
| baidu_ai | 百度AI搜索 | 百度搜索服务 |
| yuanbao | 腾讯元宝 | 腾讯AI平台 |
| qingyan | 智谱清言 | 智谱AI平台 |

#### 图表可视化

平台图表组件使用Recharts库展示各平台的引用率统计：

```mermaid
graph LR
subgraph "数据处理"
RAW[原始统计数据]
TRANSFORM[数据转换]
end
subgraph "可视化组件"
CHART[柱状图]
XAXIS[X轴: 平台名称]
YAXIS[Y轴: 引用率百分比]
TOOLTIP[工具提示]
end
RAW --> TRANSFORM
TRANSFORM --> CHART
CHART --> XAXIS
CHART --> YAXIS
CHART --> TOOLTIP
```

**图表来源**
- [platform-chart.tsx:34-68](file://frontend/components/charts/platform-chart.tsx#L34-L68)
- [platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)

**章节来源**
- [platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)

## 依赖关系分析

### 组件依赖图

```mermaid
graph TB
subgraph "外部依赖"
PW[Playwright]
APS[APScheduler]
SQLA[SQLAlchemy]
FAST[FastAPI]
end
subgraph "核心模块"
BASE[BasePlatformAdapter]
KIMI[KimiAdapter]
WENXIN[WenxinAdapter]
CE[CitationEngine]
SCH[QueryScheduler]
API[FastAPI API]
end
subgraph "数据模型"
QUERY[Query模型]
CITE[CitationRecord模型]
TASK[QueryTask模型]
end
PW --> KIMI
PW --> WENXIN
APS --> SCH
SQLA --> CE
FAST --> API
BASE --> KIMI
BASE --> WENXIN
CE --> BASE
API --> CE
CE --> QUERY
CE --> CITE
CE --> TASK
```

**图表来源**
- [kimi.py:4-6](file://backend/app/workers/platforms/kimi.py#L4-L6)
- [wenxin.py:4-6](file://backend/app/workers/platforms/wenxin.py#L4-L6)
- [scheduler.py:13-20](file://backend/app/workers/scheduler.py#L13-L20)
- [citation_engine.py:7-14](file://backend/app/workers/citation_engine.py#L7-L14)

### 耦合度分析

该系统展现了良好的内聚性和低耦合性：

- **高内聚**：每个适配器专注于单一平台的实现
- **低耦合**：通过抽象基类实现松散耦合
- **清晰边界**：各层职责明确，接口清晰
- **可测试性**：依赖注入和抽象接口便于单元测试

**章节来源**
- [base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)
- [citation_engine.py:148-157](file://backend/app/workers/citation_engine.py#L148-L157)

## 性能考虑

### 异步编程模型

系统全面采用异步编程模式，提升了并发处理能力：

- **异步适配器**：所有适配器方法都使用async/await
- **异步数据库**：使用SQLAlchemy异步会话
- **异步调度**：APScheduler的异步版本
- **异步HTTP**：FastAPI的异步路由

### 资源管理策略

```mermaid
flowchart TD
InitBrowser["初始化浏览器"] --> UseBrowser["使用浏览器"]
UseBrowser --> CloseBrowser["关闭浏览器"]
CloseBrowser --> CleanupResources["清理系统资源"]
CleanupResources --> End([资源释放完成])
InitBrowser --> Error["异常发生"]
Error --> CleanupOnError["异常时清理资源"]
CleanupOnError --> End
```

**图表来源**
- [kimi.py:17-31](file://backend/app/workers/platforms/kimi.py#L17-L31)
- [kimi.py:198-206](file://backend/app/workers/platforms/kimi.py#L198-L206)

### 缓存和重试机制

- **指数退避**：最多3次重试，间隔呈指数增长
- **超时控制**：页面加载和操作都有超时限制
- **资源池化**：浏览器实例复用，减少启动开销

## 故障排除指南

### 常见问题及解决方案

#### Playwright浏览器问题

**症状**：启动浏览器失败，提示需要安装Playwright浏览器

**解决方案**：
1. 安装Playwright浏览器：`python -m playwright install chromium`
2. 检查网络连接和代理设置
3. 确认Docker环境中的浏览器可用性

#### 页面元素定位失败

**症状**：无法找到输入框或发送按钮

**解决方案**：
1. 检查平台URL是否正确
2. 更新选择器表达式以适应页面变化
3. 实现更健壮的元素等待机制

#### 超时问题

**症状**：页面加载或响应超时

**解决方案**：
1. 增加超时时间配置
2. 检查网络连接稳定性
3. 实现重试机制

**章节来源**
- [kimi.py:27-31](file://backend/app/workers/platforms/kimi.py#L27-L31)
- [kimi.py:116-118](file://backend/app/workers/platforms/kimi.py#L116-L118)
- [wenxin.py:27-31](file://backend/app/workers/platforms/wenxin.py#L27-L31)

### 调试技巧

1. **启用详细日志**：查看适配器的详细执行过程
2. **检查数据库状态**：验证查询任务的状态更新
3. **监控资源使用**：观察浏览器进程和内存使用情况
4. **测试独立适配器**：单独测试某个平台的适配器

## 结论

该适配器架构设计成功地实现了以下目标：

### 架构优势

1. **高度可扩展**：新增平台只需实现BasePlatformAdapter接口
2. **统一管理**：通过CitationEngine集中管理所有平台
3. **资源优化**：统一的资源管理和清理机制
4. **错误处理**：完善的异常处理和重试机制

### 最佳实践建议

1. **遵循接口契约**：严格实现BasePlatformAdapter的所有抽象方法
2. **资源管理**：确保close()方法能够正确清理所有资源
3. **错误处理**：实现适当的异常处理和重试逻辑
4. **配置管理**：将平台特定的配置参数化
5. **测试覆盖**：为新适配器编写充分的单元测试

### 扩展指南

要为新平台创建适配器，需要：

1. 继承BasePlatformAdapter类
2. 设置platform_name和platform_url属性
3. 实现query()方法的平台特定逻辑
4. 实现close()方法清理资源
5. 在CitationEngine中注册新适配器
6. 编写相应的测试用例

该架构为AI平台集成提供了一个稳健、可扩展的基础，能够支持未来更多的平台集成需求。