docs

2025-08-02 00:18:09 +03:00
parent adda2b30f9
commit ea92a376ed
32 changed files with 3360 additions and 280 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,196 @@
+# Архитектура
+
+## Обзор системы
+
+Quoter - это микросервис для управления файлами с поддержкой квот, миниатюр и интеграции с S3 хранилищами.
+
+## Компоненты системы
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Web Client    │    │   Mobile App    │    │   API Client    │
+└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
+          │                      │                      │
+          └──────────────────────┼──────────────────────┘
+                                 │
+                    ┌─────────────▼─────────────┐
+                    │      Quoter Service       │
+                    │    (Actix Web Server)     │
+                    └─────────────┬─────────────┘
+                                  │
+          ┌───────────────────────┼───────────────────────┐
+          │                       │                       │
+    ┌─────▼─────┐         ┌───────▼──────┐         ┌─────▼─────┐
+    │   Redis   │         │  Core API    │         │   S3/Storj│
+    │ (Quotas & │         │(Auth & Shout)│         │ (Storage) │
+    │  Cache)   │         │              │         │           │
+    └───────────┘         └──────────────┘         └───────────┘
+```
+
+## Основные модули
+
+### 1. AppState (`src/app_state.rs`)
+Центральное состояние приложения, содержащее:
+- Подключения к Redis, Storj S3, AWS S3
+- Методы для работы с квотами
+- Кэширование списка файлов
+
+### 2. Handlers (`src/handlers/`)
+Обработчики HTTP запросов:
+- `upload.rs` - загрузка файлов
+- `proxy.rs` - получение файлов и генерация миниатюр
+- `quota.rs` - управление квотами
+- `serve_file.rs` - обслуживание файлов
+
+### 3. Auth (`src/auth.rs`)
+Аутентификация через GraphQL API ядра:
+- Валидация JWT токенов
+- Управление файлами пользователей в Redis
+
+### 4. Core (`src/core.rs`)
+Интеграция с API ядра:
+- Получение данных shout для оверлеев
+
+### 5. Thumbnail (`src/thumbnail.rs`)
+Обработка изображений:
+- Создание миниатюр различных размеров
+- Поддержка различных форматов
+
+### 6. S3 Utils (`src/s3_utils.rs`)
+Утилиты для работы с S3:
+- Загрузка/скачивание файлов
+- Определение MIME типов
+- Генерация ключей
+
+## Поток данных
+
+### Загрузка файла
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Quoter
+    participant Core API
+    participant Redis
+    participant S3
+
+    Client->>Quoter: POST / (file + token)
+    Quoter->>Core API: Validate token
+    Core API-->>Quoter: User ID
+    Quoter->>Redis: Check quota
+    Redis-->>Quoter: Current quota
+    Quoter->>S3: Upload file
+    S3-->>Quoter: Success
+    Quoter->>Redis: Update quota
+    Quoter->>Redis: Save file info
+    Quoter-->>Client: Filename
+```
+
+### Получение файла
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Quoter
+    participant Redis
+    participant S3
+
+    Client->>Quoter: GET /filename
+    Quoter->>Redis: Get file path
+    Redis-->>Quoter: File path
+    Quoter->>S3: Check file exists
+    S3-->>Quoter: File exists
+    Quoter->>S3: Download file
+    S3-->>Quoter: File data
+    Quoter-->>Client: File content
+```
+
+## Структура данных
+
+### Redis схемы
+
+#### Квоты пользователей
+```
+Key: quota:{user_id}
+Type: String
+Value: bytes_used (u64)
+TTL: None (permanent)
+```
+
+#### Файлы пользователей
+```
+Key: {user_id}
+Type: Set
+Value: [filename1, filename2, ...]
+TTL: None (permanent)
+```
+
+#### Маппинг путей файлов
+```
+Key: filepath_mapping
+Type: Hash
+Field: filename
+Value: filepath
+TTL: None (permanent)
+```
+
+#### Информация о файлах
+```
+Key: files:{filename}
+Type: String
+Value: mime_type
+TTL: None (permanent)
+```
+
+### S3 структура
+
+```
+bucket/
+├── original_files/
+│   ├── image1.jpg
+│   ├── image2.png
+│   └── document.pdf
+├── thumbnails/
+│   ├── image1_10.jpg
+│   ├── image1_40.jpg
+│   ├── image1_110.jpg
+│   ├── image1_300.jpg
+│   ├── image1_600.jpg
+│   ├── image1_800.jpg
+│   └── image1_1400.jpg
+└── webp_thumbnails/
+    ├── image1_10.jpg/webp
+    ├── image1_40.jpg/webp
+    └── ...
+```
+
+## Безопасность
+
+### Аутентификация
+- JWT токены через GraphQL API ядра
+- Валидация токенов для всех операций записи
+
+### Авторизация
+- Проверка квот перед загрузкой
+- Изоляция файлов по пользователям
+
+### CORS
+- Настроен для кросс-доменных запросов
+- Поддержка credentials
+
+## Масштабирование
+
+### Горизонтальное масштабирование
+- Stateless архитектура
+- Redis как общее хранилище состояния
+- S3 как общее файловое хранилище
+
+### Производительность
+- Асинхронная обработка запросов
+- Кэширование списка файлов
+- Ленивая генерация миниатюр
+
+### Мониторинг
+- Структурированное логирование
+- Метрики использования квот
+- Отслеживание ошибок