# GEO 平台 - 系统架构设计

## 整体架构

GEO 平台采用分层架构设计，由以下四层组成：

```
┌─────────────────────────────────────────────────────────────────┐
│                        Presentation Layer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Next.js    │  │  React 19   │  │  Tailwind CSS + shadcn  │  │
│  │  App Router │  │  Components │  │  UI Components           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                         API Gateway Layer                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  FastAPI    │  │  REST API   │  │  JWT / OAuth2           │  │
│  │  Routers    │  │  Endpoints  │  │  Authentication          │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                      Service & Agent Layer                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │ Citation │ │ Content  │ │   Rule   │ │  Competitor      │   │
│  │ Detector │ │Generator │ │ Checker  │ │  Analyzer        │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐   │
│  │Performance│ │  Task    │ │  Query   │ │   Report         │   │
│  │ Tracker  │ │ Scheduler│ │  Engine  │ │  Generator       │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                      Infrastructure Layer                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
│  │PostgreSQL│  │  Redis   │  │  Celery  │  │   Docker       │  │
│  │  (Data)  │  │ (Cache)  │  │ (Queue)  │  │ (Container)    │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

### 四层架构说明

#### 1. 表现层（Presentation Layer）

- **Next.js App Router**：基于文件系统的路由，支持服务端渲染（SSR）和静态生成（SSG）
- **React 19**：最新 React 特性，包括 Server Components、Actions、Form 状态管理
- **Tailwind CSS + shadcn/ui**：原子化 CSS + 可复用无头组件库，支持快速构建一致化 UI

**关键设计决策**：
- 采用 BFF（Backend for Frontend）模式，前端通过 API Client 与后端通信
- 认证状态使用 NextAuth.js 管理，支持 Credentials + OAuth 双模式
- 数据获取优先使用 Server Components 减少客户端 JavaScript 体积

#### 2. API 网关层（API Gateway Layer）

- **FastAPI**：高性能 Python Web 框架，原生支持异步和自动 API 文档
- **RESTful API**：标准的 REST 接口设计，返回 JSON 格式数据
- **认证授权**：JWT Token + OAuth2 密码流，支持角色权限控制

**模块划分**：
| 模块 | 职责 | 对应文件 |
|------|------|----------|
| Auth API | 用户注册、登录、Token 刷新、权限验证 | `api/auth.py` |
| Query API | 查询创建、执行、结果获取 | `api/queries.py` |
| Citation API | 引用记录管理、统计分析 | `api/citations.py` |
| Report API | 报告生成、导出、查看 | `api/reports.py` |
| Admin API | 用户管理、系统配置、订阅管理 | `api/admin.py` |
| Subscription API | 订阅计划、支付、限额管理 | `api/subscriptions.py` |

#### 3. 服务与 Agent 层（Service & Agent Layer）

本层是 GEO 平台的核心业务逻辑层，包含传统 Service 和 AI Agent 两大类组件。

**传统 Service**：
| Service | 职责 |
|---------|------|
| QueryService | 查询生命周期管理、AI 平台调用、结果聚合 |
| CitationService | 引用检测算法执行、引用记录存储、置信度评估 |
| ReportService | 报告模板渲染、数据聚合、多种格式导出 |
| UserService | 用户 CRUD、角色权限、订阅状态管理 |
| SubscriptionService | 订阅计划管理、配额控制、升级降级 |

**AI Agent 集群**：详见 `docs/02-design/agent-framework.md`

#### 4. 基础设施层（Infrastructure Layer）

| 组件 | 用途 | 技术选型 |
|------|------|----------|
| PostgreSQL | 主数据库，存储业务数据 | PostgreSQL 15+ |
| Redis | 缓存、Celery Broker、会话存储 | Redis 7+ |
| Celery | 异步任务队列、定时任务调度 | Celery 5+ |
| Docker | 应用容器化部署 | Docker + Compose |

## 模块解耦原则

### 1. 领域驱动设计（DDD）

- **领域模型独立**：核心业务模型（Query、Citation、User、Subscription）不依赖任何框架
- **边界上下文清晰**：每个模块维护自己的数据模型和业务规则
- **防腐层（ACL）**：外部 AI 平台适配器通过防腐层与核心领域隔离

### 2. 依赖倒置原则

```
API Layer → Service Layer → Repository Layer → Database
     ↑              ↑              ↑
   依赖接口      依赖接口      依赖接口
```

- Service 层定义接口，Repository 层实现接口
- 便于单元测试时 Mock 依赖
- 支持未来数据库迁移或替换

### 3. 配置与代码分离

- 所有环境相关配置通过环境变量注入
- 应用配置集中管理在 `app/config.py`
- 不同环境（dev / staging / prod）使用不同的 `.env` 文件

### 4. 异步解耦

- 耗时操作（AI 查询执行、报告生成）通过 Celery 异步处理
- 前端通过轮询或 WebSocket 获取任务状态更新
- 任务执行状态持久化，支持断点续传和失败重试

## AI Agent 解耦通信协议设计

### 通信模型

GEO 平台的 AI Agent 之间采用 **基于消息队列的异步通信协议**，确保 Agent 之间松耦合、可独立部署和扩展。

```
┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   Agent A   │────▶│  Message    │────▶│   Agent B       │
│  (生产者)    │     │   Queue     │     │  (消费者)        │
└─────────────┘     └─────────────┘     └─────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │  Registry   │
                    │  (注册中心)  │
                    └─────────────┘
```

### 消息格式

```json
{
  "message_id": "uuid",
  "timestamp": "2026-01-01T00:00:00Z",
  "sender": "agent_name",
  "recipient": "agent_name_or_broadcast",
  "message_type": "task_request | task_result | status_update | heartbeat",
  "payload": {
    "task_id": "uuid",
    "task_type": "detect_citations | generate_content | check_rules | analyze_competitors | track_performance",
    "parameters": {},
    "data": {},
    "priority": 1
  },
  "correlation_id": "uuid",
  "reply_to": "agent_name"
}
```

### 通信模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| 点对点 | Agent A 直接发送任务给 Agent B | 明确的一对一任务分配 |
| 广播 | Agent 向所有订阅者发送消息 | 状态更新、配置变更通知 |
| 发布/订阅 | Agent 向特定主题发布消息 | 事件驱动架构 |
| 请求/响应 | 同步等待返回结果 | 需要即时反馈的短任务 |

### Agent 注册与发现

- **注册中心**：Redis 作为轻量级注册中心
- **注册机制**：Agent 启动时向注册中心注册自己的能力和状态
- **健康检查**：定期发送心跳，失效 Agent 自动从注册中心移除
- **负载均衡**：任务分发时根据 Agent 负载状态选择执行节点

### 错误处理与重试

- 消息消费失败时自动进入死信队列（DLQ）
- 支持配置重试次数和重试间隔（指数退避）
- 失败任务可手动重新触发或自动补偿

## 双模式权限设计

### 用户角色模型

```
                    ┌─────────────┐
                    │    User     │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │  EndUser   │  │   Admin    │  │   Agent    │
    │  (终端用户) │  │  (管理员)   │  │  (运营人员) │
    └─────┬──────┘  └────────────┘  └─────┬──────┘
          │                                │
          ▼                                ▼
   ┌──────────────┐                ┌──────────────┐
   │ Self-Service │                │ Proxy-Service│
   │   自主订阅    │                │   代理运营    │
   └──────────────┘                └──────────────┘
```

### 权限矩阵

| 功能 | EndUser (Basic) | EndUser (Pro) | EndUser (Enterprise) | Admin | Agent |
|------|----------------|---------------|---------------------|-------|-------|
| 创建查询 | 10/月 | 50/月 | 无限制 | 无限制 | 无限制 |
| 引用检测 | 有 | 有 | 有 | 有 | 有 |
| 策略生成 | 基础 | 高级 | 定制化 | 全部 | 全部 |
| 内容生成 | 5/月 | 20/月 | 无限制 | 无限制 | 无限制 |
| 报告导出 | PDF | PDF + Excel | 全部格式 | 全部格式 | 全部格式 |
| 团队管理 | 无 | 无 | 有 | 有 | 有 |
| 代理客户管理 | 无 | 无 | 无 | 有 | 有 |
| 白标报告 | 无 | 无 | 无 | 有 | 有 |
| 系统配置 | 无 | 无 | 无 | 有 | 无 |
| 用户管理 | 无 | 无 | 无 | 有 | 无 |

### 权限实现

- **基于角色的访问控制（RBAC）**：用户通过角色获得一组权限
- **基于属性的访问控制（ABAC）**：结合用户订阅等级、团队归属等属性进行细粒度控制
- **中间件校验**：FastAPI 依赖注入实现统一的权限校验中间件
- **前端联动**：前端路由和组件根据用户权限动态渲染

### API 权限控制示例

```python
# FastAPI 依赖注入实现权限控制
async def require_admin(current_user: User = Depends(get_current_user)):
    if not current_user.is_admin:
        raise HTTPException(status_code=403, detail="需要管理员权限")
    return current_user

async def require_subscription(min_tier: str):
    async def checker(current_user: User = Depends(get_current_user)):
        if not current_user.subscription.meets(min_tier):
            raise HTTPException(status_code=403, detail="订阅等级不足")
        return current_user
    return checker

# 路由使用
@router.post("/queries")
async def create_query(
    data: QueryCreate,
    user: User = Depends(require_subscription("pro"))
):
    ...
```

## 数据流架构

### 查询执行数据流

```
用户创建查询 ──▶ API 接收 ──▶ 验证权限/配额 ──▶ 创建查询记录
                                              │
                                              ▼
                                         提交 Celery 任务
                                              │
                                              ▼
                                    ┌─────────────────┐
                                    │  Worker 执行查询 │
                                    │  - 调用 AI 平台  │
                                    │  - 聚合响应结果  │
                                    └────────┬────────┘
                                             │
                                             ▼
                                    ┌─────────────────┐
                                    │ CitationDetector │
                                    │  - 解析引用内容  │
                                    │  - 评估置信度    │
                                    └────────┬────────┘
                                             │
                                             ▼
                                    保存引用记录 ──▶ 更新查询状态
                                                          │
                                                          ▼
                                                    通知前端完成
```

### 报告生成数据流

```
用户请求报告 ──▶ API 接收 ──▶ 收集相关数据
                                    │
                                    ▼
                              ReportService 聚合数据
                                    │
                                    ▼
                              应用报告模板
                                    │
                                    ▼
                              生成 PDF/Excel/HTML
                                    │
                                    ▼
                              返回下载链接
```

## 扩展性设计

### 水平扩展

- **无状态服务**：API 服务无状态设计，可通过负载均衡水平扩展
- **数据库读写分离**：未来支持主从复制，读操作分散到从库
- **缓存层**：Redis 缓存热点数据，减少数据库压力

### AI 平台适配器扩展

GEO 平台需要对接多种 AI 搜索引擎平台，适配器设计遵循开闭原则：

```
┌─────────────────────────────────────────┐
│           PlatformAdapter (抽象基类)      │
│  - execute_query()                      │
│  - parse_response()                     │
│  - validate_config()                    │
└─────────────────────────────────────────┘
           │           │           │
           ▼           ▼           ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ ChatGPT  │ │  Kimi    │ │  Perplex │
    │ Adapter  │ │ Adapter  │ │ Adapter  │
    └──────────┘ └──────────┘ └──────────┘
```

新增 AI 平台只需实现 `PlatformAdapter` 接口，无需修改现有代码。

---

*本文档描述 GEO 平台的整体系统架构设计，详细模块设计请参考各子系统设计文档。*
