# 架构概述

> **文档版本**：v1.0  
> **最后更新**：2025-01-27

---

## 目录

1. [系统特点](#系统特点)
2. [架构设计原则](#架构设计原则)
3. [整体架构图](#整体架构图)
4. [核心模块](#核心模块)

---

## 系统特点

Jointo是一个 AI 驱动的视频创作平台，具有以下核心特点：

### 1. AI 驱动

- 大量使用 AI 生成功能（图片、视频、音效、字幕、配音）
- 支持多种 AI 模型和服务提供商
- 异步处理 AI 任务，支持进度查询

### 2. 文件密集

- 需要处理大量图片、视频、音频文件
- 支持多种文件格式（图片、视频、音频、文档）
- 使用对象存储管理文件资源

### 3. 异步任务

- AI 生成和视频导出都是耗时操作
- 使用任务队列（Celery）处理异步任务
- 支持任务重试、优先级、进度追踪

### 4. 协作支持

- 支持多人协同编辑项目
- 基于角色的权限管理（owner、editor、viewer）
- 实时通知和状态同步

### 5. 实时性要求

- 部分功能需要实时反馈（WebSocket）
- 缓存热点数据提升响应速度
- 优化数据库查询性能

---

## 架构设计原则

### 1. 微服务化

- 核心服务解耦，便于扩展
- 每个服务职责单一，易于维护
- 支持独立部署和升级

### 2. 异步优先

- 耗时操作异步处理，避免阻塞
- 使用消息队列解耦服务
- 支持任务重试和错误处理

### 3. 可扩展性

- 支持水平扩展（增加服务器节点）
- 数据库读写分离
- 使用缓存减轻数据库压力

### 4. 高可用性

- 关键服务冗余部署
- 数据库主从复制
- 自动故障转移

### 5. 安全性

- 完善的认证授权机制（JWT）
- 基于角色的访问控制（RBAC）
- 数据加密和安全传输（HTTPS）

---

## 整体架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        前端 (React)                          │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTPS
┌───────────────────────────▼─────────────────────────────────┐
│                    API Gateway / Nginx                       │
│              (负载均衡、SSL终止、路由)                        │
└───────────────┬───────────────────────────┬─────────────────┘
                │                           │
    ┌───────────▼──────────┐    ┌───────────▼──────────┐
    │   API 服务 (FastAPI) │    │   WebSocket 服务      │
    │   - RESTful API      │    │   - 实时协作          │
    │   - 认证授权         │    │   - 实时通知          │
    └───────────┬──────────┘    └──────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              业务逻辑层 (Services)                     │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │项目管理  │ │分镜管理  │ │资源管理  │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │视频管理  │ │AI服务    │ │导出服务  │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └───────────┬───────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              数据访问层 (Repositories)                 │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │PostgreSQL │ │  Redis   │ │ SQLModel │            │
    │  │(主数据库) │ │ (缓存)   │ │  (ORM)   │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └────────────────────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              异步任务层 (Celery)                       │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │  Celery  │ │ RabbitMQ │ │  Worker  │            │
    │  │ (任务队列)│ │ (消息队列)│ │ (任务执行)│            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └───────────┬───────────────────────────────────────────┘
                │
    ┌───────────▼───────────────────────────────────────────┐
    │              外部服务层                                │
    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
    │  │对象存储   │ │ AI API   │ │ 视频处理 │            │
    │  │(MinIO/   │ │(AIHubMix)│ │(FFmpeg)  │            │
    │  │ S3)      │ │          │ │          │            │
    │  └──────────┘ └──────────┘ └──────────┘            │
    └────────────────────────────────────────────────────────┘
```

---

## 核心模块

### 1. API 服务层

- **职责**：接收 HTTP 请求，路由分发，参数验证
- **技术**：FastAPI
- **特点**：高性能、自动生成文档、类型安全

### 2. 业务逻辑层

- **职责**：实现业务规则，协调数据访问和外部服务
- **模块**：
  - 项目管理服务
  - 分镜管理服务
  - 剧本管理服务
  - 资源管理服务
  - AI 生成服务
  - 视频导出服务

### 3. 数据访问层

- **职责**：数据库操作、缓存管理、查询优化
- **技术**：SQLAlchemy ORM、Redis
- **特点**：统一数据访问接口，支持事务

### 4. 异步任务层

- **职责**：处理耗时任务（AI 生成、视频导出）
- **技术**：Celery + RabbitMQ
- **特点**：支持重试、优先级、定时任务

### 5. 外部服务层

- **对象存储**：MinIO / AWS S3（文件管理）
- **AI 服务**：OpenAI、Stable Diffusion（内容生成）
- **视频处理**：FFmpeg（视频合成、转码）

---

## 数据流示例

### 用户创建项目流程

```
1. 前端发送 POST /api/v1/projects 请求
   ↓
2. API 层验证请求参数（Pydantic）
   ↓
3. 业务逻辑层（ProjectService）
   - 检查用户权限
   - 创建项目记录
   ↓
4. 数据访问层（ProjectRepository）
   - 写入 PostgreSQL
   - 更新 Redis 缓存
   ↓
5. 返回项目信息给前端
```

### AI 生成图片流程

```
1. 前端发送 POST /api/v1/ai/generate-image 请求
   ↓
2. API 层验证参数
   ↓
3. 业务逻辑层（AIService）
   - 创建 AI 任务记录
   - 提交异步任务到 Celery
   ↓
4. 返回任务 ID 给前端
   ↓
5. Celery Worker 执行任务
   - 调用 AI API（Stable Diffusion）
   - 上传生成的图片到对象存储
   - 更新任务状态
   ↓
6. 前端轮询任务状态，获取结果
```

---

## 相关文档

- [技术栈选型](./02-tech-stack.md)
- [系统架构设计](./03-system-design.md)
- [数据库设计](./04-database-design.md)

---

**文档版本**：v1.0  
**最后更新**：2025-01-27