fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/项目概述/系统架构.md

366 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 系统架构
<cite>
**本文档引用的文件**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.py)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/models/query.py](file://backend/app/models/query.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/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/components/providers.tsx](file://frontend/components/providers.tsx)
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本系统是一个学术查询与引用管理平台，采用前后端分离架构：前端使用 Next.js 构建用户界面，后端基于 FastAPI 提供 REST API，并通过 SQLAlchemy ORM 访问 PostgreSQL 数据库；AI 平台查询由后端工作器通过适配器模式对接不同平台（Kimi、文心一言），并通过 Redis 缓存与队列进行异步调度。系统通过 Docker Compose 将数据库、缓存、后端与前端容器化编排，便于开发与部署。
## 项目结构
系统分为四层：
- 表现层（前端 Next.js）：负责用户界面渲染与 API 调用
- 业务逻辑层（后端 FastAPI）：提供 REST 接口、业务服务与调度
- 数据访问层（SQLAlchemy ORM）：模型定义与数据库交互
- 基础设施层（Docker 容器）：PostgreSQL、Redis、后端与前端容器
```mermaid
graph TB
subgraph "表现层前端 Next.js"
FE_APP["Next.js 应用<br/>路由与页面"]
FE_LIB_API["API 客户端<br/>frontend/lib/api.ts"]
FE_PROVIDERS["会话提供者<br/>frontend/components/providers.tsx"]
end
subgraph "业务逻辑层后端 FastAPI"
BE_MAIN["应用入口<br/>backend/app/main.py"]
BE_ROUTERS["API 路由<br/>backend/app/api/*"]
BE_SERVICES["业务服务<br/>backend/app/services/*"]
BE_WORKERS["工作器与适配器<br/>backend/app/workers/*"]
end
subgraph "数据访问层SQLAlchemy ORM"
BE_MODELS["ORM 模型<br/>backend/app/models/*"]
end
subgraph "基础设施层Docker 容器"
DC_DB["PostgreSQL 容器"]
DC_REDIS["Redis 容器"]
DC_BE["后端容器"]
DC_FE["前端容器"]
end
FE_APP --> FE_LIB_API
FE_LIB_API --> BE_MAIN
BE_MAIN --> BE_ROUTERS
BE_ROUTERS --> BE_SERVICES
BE_SERVICES --> BE_MODELS
BE_WORKERS --> BE_MODELS
BE_MAIN --> DC_BE
BE_MODELS --> DC_DB
BE_WORKERS --> DC_REDIS
FE_APP --> DC_FE
```
图表来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [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/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [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)
## 核心组件
- 前端 Next.js：提供登录注册、查询管理、引用统计与报告导出等功能页面，通过统一 API 客户端发起请求。
- 后端 FastAPI：提供认证、查询词、引用数据、报告导出等接口；启动时初始化调度器并挂载 CORS 中间件。
- 工作器与适配器：以适配器模式封装不同 AI 平台（Kimi、文心一言）的查询行为，统一对外接口。
- ORM 模型：定义查询词、引用记录、任务等实体及索引，支撑业务数据持久化。
- 基础设施：PostgreSQL 存储业务数据，Redis 支持缓存与队列，Docker Compose 统一编排。
章节来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
## 架构总览
系统采用分层解耦与容器化部署，前端通过 REST API 与后端交互，后端通过工作器调用 AI 平台，数据库与缓存分别承担数据持久化与临时状态管理。下图展示从用户请求到 AI 平台查询再到结果返回的完整链路。
```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端 Next.js"
participant API as "后端 API 路由"
participant SVC as "业务服务"
participant ENG as "引用检测引擎"
participant ADP as "AI 平台适配器"
participant DB as "PostgreSQL"
U->>FE : "提交查询/触发查询"
FE->>API : "HTTP 请求带鉴权"
API->>SVC : "调用业务方法"
SVC->>ENG : "执行引用检测"
loop "遍历平台"
ENG->>ADP : "query(keyword)"
ADP-->>ENG : "返回平台响应文本"
end
ENG->>DB : "写入引用记录/更新任务状态"
DB-->>ENG : "确认写入"
ENG-->>SVC : "返回检测结果"
SVC-->>API : "组装响应"
API-->>FE : "返回结果"
FE-->>U : "展示引用统计/报告"
```
图表来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [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/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
## 详细组件分析
### 前端组件分析
- API 客户端：集中封装鉴权头、错误处理与基础路径，统一暴露认证、查询、引用、报告等接口。
- 会话提供者：为 NextAuth 集成提供会话上下文，保障页面与 API 调用的鉴权一致性。
- 布局与字体：全局样式与字体配置，保证一致的视觉体验。
```mermaid
flowchart TD
Start(["页面发起请求"]) --> BuildHeaders["构建请求头<br/>含 Authorization"]
BuildHeaders --> FetchAPI["调用 fetchWithAuth"]
FetchAPI --> RespOK{"响应成功?"}
RespOK --> |是| ParseJSON["解析 JSON 响应"]
RespOK --> |否| HandleError["抛出错误包含 HTTP 状态"]
ParseJSON --> ReturnData["返回数据给页面"]
HandleError --> ThrowErr["上抛错误供 UI 处理"]
```
图表来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
章节来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
### 后端组件分析
- 应用入口：注册路由、启用 CORS、启动/关闭调度器生命周期钩子。
- API 路由：提供认证、查询词、引用数据、报告导出等接口，统一前缀与标签。
- 业务服务：封装查询词的增删改查与配额校验、频率与下次查询时间计算。
- ORM 模型：定义查询词实体及其索引，关联用户、引用记录与任务。
```mermaid
classDiagram
class Query {
+UUID id
+UUID user_id
+string keyword
+string target_brand
+list brand_aliases
+list platforms
+string frequency
+string status
+datetime last_queried_at
+datetime next_query_at
+datetime created_at
+datetime updated_at
}
class User {
+UUID id
+string name
+string email
+int max_queries
}
class CitationRecord {
+UUID id
+UUID query_id
+string platform
+bool cited
+int citation_position
+string citation_text
+list competitor_brands
+string raw_response
}
class QueryTask {
+UUID id
+UUID query_id
+string platform
+string status
+datetime started_at
+datetime completed_at
+string error_message
}
User "1" --> "many" Query : "拥有"
Query "1" --> "many" CitationRecord : "生成"
Query "1" --> "many" QueryTask : "驱动"
```
图表来源
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
章节来源
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [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/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
### 工作器与适配器分析
- 引用检测引擎：根据查询词与目标品牌，遍历平台列表，调用对应适配器获取响应，执行品牌匹配与竞争品牌检测，生成引用记录并更新任务状态与查询时间。
- 适配器基类：定义平台名称、URL 与抽象查询方法，统一资源清理接口。
- Kimi 适配器：通过 Playwright 自动化模拟用户输入与提交，等待回复稳定后提取文本。
- 文心一言适配器：同 Kimi，但针对文心一言页面结构进行适配。
```mermaid
classDiagram
class BasePlatformAdapter {
<<abstract>>
+string platform_name
+string platform_url
+query(keyword) str
+close()
}
class KimiAdapter {
+platform_name = "kimi"
+platform_url = "https : //kimi.moonshot.cn"
+query(keyword) str
+close()
}
class WenxinAdapter {
+platform_name = "wenxin"
+platform_url = "https : //yiyan.baidu.com"
+query(keyword) str
+close()
}
class CitationEngine {
+execute_query(query, db) CitationRecord[]
+execute_single_platform(keyword, platform, target_brand, brand_aliases) dict
+close()
}
BasePlatformAdapter <|-- KimiAdapter
BasePlatformAdapter <|-- WenxinAdapter
CitationEngine --> BasePlatformAdapter : "使用"
```
图表来源
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
章节来源
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
### 数据流与处理流程
- 用户在前端提交查询或手动触发查询。
- 前端通过 API 客户端调用后端接口，携带鉴权信息。
- 后端路由将请求委派给业务服务，服务层执行权限与配额检查、频率计算等逻辑。
- 引用检测引擎根据平台列表逐个调用适配器，等待回复稳定后进行品牌匹配与竞争品牌检测。
- 结果写入数据库并更新任务状态，前端轮询或接收通知后刷新页面。
```mermaid
flowchart TD
A["用户提交查询"] --> B["前端 API 客户端"]
B --> C["后端 API 路由"]
C --> D["业务服务权限/配额/频率"]
D --> E["引用检测引擎"]
E --> F["Kimi 适配器"]
E --> G["文心一言适配器"]
F --> H["品牌匹配/竞争品牌检测"]
G --> H
H --> I["写入引用记录/更新任务状态"]
I --> J["返回结果给前端"]
J --> K["展示统计/报告"]
```
图表来源
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [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/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
## 依赖分析
- 组件内聚与耦合：后端 API 路由仅负责参数解析与委派，业务服务与模型解耦良好；工作器通过适配器模式与具体平台解耦。
- 外部依赖：后端依赖 PostgreSQL 与 Redis；前端依赖 Next.js 生态与 NextAuth；工作器依赖 Playwright 浏览器自动化。
- 容器编排：Compose 文件定义数据库、缓存、后端与前端服务，设置健康检查与端口映射，后端依赖数据库与缓存健康。
```mermaid
graph TB
FE["前端"] --> BE["后端"]
BE --> DB["PostgreSQL"]
BE --> RD["Redis"]
BE --> PW["Playwright 浏览器"]
DC["Docker Compose"] --> DB
DC --> RD
DC --> BE
DC --> FE
```
图表来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
## 性能考虑
- 异步与并发：后端使用异步数据库会话与异步适配器调用，提升 I/O 密集场景下的吞吐。
- 重试与指数退避：适配器对平台请求进行多轮重试与指数退避，降低偶发网络波动影响。
- 回复稳定性检测：等待 AI 回复文本稳定后再提取，减少因动态渲染导致的截断误差。
- 索引优化：查询词模型建立多字段索引，加速分页与过滤查询。
- 缓存与队列：建议结合 Redis 实现任务队列与结果缓存，进一步降低重复查询成本。
## 故障排查指南
- 健康检查：Compose 为数据库与缓存配置健康检查，若服务未就绪，前端将无法连接后端。
- Playwright 依赖：适配器需使用 Playwright 安装 Chromium，若启动失败请先安装浏览器依赖。
- CORS 限制：后端仅允许本地前端域名访问，跨域请求需调整中间件配置。
- 错误处理：前端客户端对非 2xx 响应抛出错误，后端路由对未找到与权限问题返回明确状态码。
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
## 结论
该系统通过清晰的分层架构与容器化部署，实现了从前端到后端、再到 AI 平台与数据库的完整闭环。适配器模式有效隔离平台差异，业务服务与 ORM 模型保障可维护性与扩展性。建议后续引入任务队列与缓存策略以进一步提升性能与用户体验。
## 附录
- 开发环境启动：使用 Compose 启动数据库、缓存、后端与前端服务，分别暴露 5432、6379、8000、3000 端口。
- 后端镜像：基于 Python slim 镜像，预装 Playwright 与系统依赖，暴露 8000 端口。
- 前端镜像：基于 Node Alpine 镜像，安装依赖后暴露 3000 端口。
章节来源
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
Reference in New Issue View Git Blame Copy Permalink