# План миграции с Sanic на FastAPI для uploader-bot

## Обзор текущей архитектуры

### Статус миграции
**ЧАСТИЧНО МИГРИРОВАН** - В проекте уже используются оба фреймворка одновременно:
- ✅ Основное приложение FastAPI уже создано в [`main.py`](main.py:46-141)
- ✅ Частично реализованы FastAPI роуты в [`fastapi_v3_routes.py`](app/api/fastapi_v3_routes.py) и [`fastapi_node_routes.py`](app/api/fastapi_node_routes.py)
- ⚠️ Основная функциональность все еще на Sanic

### Гибридная архитектура
Приложение запускается в одном из режимов (определяется в [`main.py:19-44`](main.py:19-44)):
1. **FastAPI режим** - если доступен FastAPI или установлена переменная `USE_FASTAPI=true`
2. **Sanic режим** - fallback к Sanic приложению
3. **Минимальный режим** - если ни один фреймворк недоступен

## Инвентаризация Sanic эндпоинтов

### 1. Аутентификация и авторизация ([`auth_routes.py`](app/api/routes/auth_routes.py))
**Blueprint:** `auth_bp = Blueprint("auth", url_prefix="/api/v1/auth")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| POST | `/register` | [`register_user()`](app/api/routes/auth_routes.py:36-184) | Регистрация пользователя с валидацией |
| POST | `/login` | [`login_user()`](app/api/routes/auth_routes.py:186-336) | Вход с JWT токенами |
| POST | `/refresh` | [`refresh_tokens()`](app/api/routes/auth_routes.py:338-440) | Обновление access токенов |
| POST | `/logout` | [`logout_user()`](app/api/routes/auth_routes.py:442-495) | Выход с инвалидацией сессии |
| GET | `/me` | [`get_current_user()`](app/api/routes/auth_routes.py:497-587) | Информация о текущем пользователе |
| PUT | `/me` | [`update_current_user()`](app/api/routes/auth_routes.py:590-679) | Обновление профиля |
| POST | `/api-keys` | [`create_api_key()`](app/api/routes/auth_routes.py:681-755) | Создание API ключей |
| GET | `/sessions` | [`get_user_sessions()`](app/api/routes/auth_routes.py:757-811) | Список активных сессий |
| DELETE | `/sessions/<session_id>` | [`revoke_session()`](app/api/routes/auth_routes.py:813-870) | Отзыв сессии |

**Особенности:**
- Rate limiting декораторы
- Комплексная валидация с Pydantic схемами
- JWT токены с ротацией
- Поддержка API ключей
- Управление сессиями

### 2. Управление контентом ([`content_routes.py`](app/api/routes/content_routes.py))
**Blueprint:** `content_bp = Blueprint("content", url_prefix="/api/v1/content")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| POST | `/` | [`create_content()`](app/api/routes/content_routes.py:32-135) | Создание контента с метаданными |
| GET | `/<content_id>` | [`get_content()`](app/api/routes/content_routes.py:137-238) | Получение контента с кешированием |
| PUT | `/<content_id>` | [`update_content()`](app/api/routes/content_routes.py:240-313) | Обновление метаданных |
| POST | `/search` | [`search_content()`](app/api/routes/content_routes.py:315-440) | Поиск с фильтрами и пагинацией |
| GET | `/<content_id>/download` | [`download_content()`](app/api/routes/content_routes.py:442-518) | Скачивание с контролем доступа |

**Особенности:**
- Комплексная система разрешений
- Redis кеширование
- Streaming downloads
- Квоты пользователей
- Статистика доступа

### 3. Файловое хранилище ([`storage_routes.py`](app/api/routes/storage_routes.py))
**Blueprint:** `storage_bp = Blueprint("storage", url_prefix="/api/v1/storage")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| POST | `/upload` | [`initiate_upload()`](app/api/routes/storage_routes.py:28-126) | Инициация chunked upload |
| POST | `/upload/<upload_id>/chunk` | [`upload_chunk()`](app/api/routes/storage_routes.py:128-218) | Загрузка chunk'а файла |
| GET | `/upload/<upload_id>/status` | [`get_upload_status()`](app/api/routes/storage_routes.py:220-290) | Статус загрузки |
| DELETE | `/upload/<upload_id>` | [`cancel_upload()`](app/api/routes/storage_routes.py:292-374) | Отмена загрузки |
| DELETE | `/files/<content_id>` | [`delete_file()`](app/api/routes/storage_routes.py:376-456) | Удаление файла |
| GET | `/quota` | [`get_storage_quota()`](app/api/routes/storage_routes.py:458-530) | Информация о квоте |
| GET | `/stats` | [`get_storage_stats()`](app/api/routes/storage_routes.py:532-609) | Статистика хранилища |
| POST | `/cleanup` | [`cleanup_orphaned_files()`](app/api/routes/storage_routes.py:611-708) | Очистка (админ) |

**Особенности:**
- Chunked uploads с прогрессом
- Валидация файлов и типов
- Управление квотами
- Background cleanup

### 4. Блокчейн интеграция ([`blockchain_routes.py`](app/api/routes/blockchain_routes.py))
**Blueprint:** `blockchain_bp = Blueprint("blockchain", url_prefix="/api/v1/blockchain")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| GET | `/wallet/balance` | [`get_wallet_balance()`](app/api/routes/blockchain_routes.py:29-111) | Баланс TON кошелька |
| GET | `/wallet/transactions` | [`get_wallet_transactions()`](app/api/routes/blockchain_routes.py:113-208) | История транзакций |
| POST | `/transaction/send` | [`send_transaction()`](app/api/routes/blockchain_routes.py:210-347) | Отправка TON транзакций |
| GET | `/transaction/<tx_hash>/status` | [`get_transaction_status()`](app/api/routes/blockchain_routes.py:349-458) | Статус транзакции |
| POST | `/wallet/create` | [`create_wallet()`](app/api/routes/blockchain_routes.py:460-543) | Создание кошелька |
| GET | `/stats` | [`get_blockchain_stats()`](app/api/routes/blockchain_routes.py:545-634) | Статистика блокчейна |

**Особенности:**
- TON блокчейн интеграция
- Безопасное хранение приватных ключей
- Лимиты транзакций
- Monitoring и статистика

### 5. Системное здоровье ([`health_routes.py`](app/api/routes/health_routes.py))
**Blueprint:** `health_bp = Blueprint("health", version=1)`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| GET | `/health` | [`health_check()`](app/api/routes/health_routes.py:23-31) | Базовая проверка |
| GET | `/health/detailed` | [`detailed_health_check()`](app/api/routes/health_routes.py:34-115) | Детальная проверка компонентов |
| GET | `/health/ready` | [`readiness_check()`](app/api/routes/health_routes.py:118-135) | Kubernetes readiness |
| GET | `/health/live` | [`liveness_check()`](app/api/routes/health_routes.py:138-144) | Kubernetes liveness |
| GET | `/metrics` | [`prometheus_metrics()`](app/api/routes/health_routes.py:147-160) | Prometheus метрики |
| GET | `/stats` | [`system_stats()`](app/api/routes/health_routes.py:163-193) | Системная статистика |
| GET | `/debug/info` | [`debug_info()`](app/api/routes/health_routes.py:196-226) | Debug информация |

### 6. MY Network API ([`my_network_sanic.py`](app/api/routes/my_network_sanic.py))
**Blueprint:** `bp = Blueprint("my_network", url_prefix="/api/my")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| GET | `/node/info` | [`get_node_info()`](app/api/routes/my_network_sanic.py:32-54) | Информация о ноде |
| GET | `/node/peers` | [`get_node_peers()`](app/api/routes/my_network_sanic.py:57-83) | Список пиров |
| POST | `/node/peers/connect` | [`connect_to_peer()`](app/api/routes/my_network_sanic.py:86-116) | Подключение к пиру |
| DELETE | `/node/peers/<peer_id>` | [`disconnect_peer()`](app/api/routes/my_network_sanic.py:119-146) | Отключение пира |
| GET | `/content/list` | [`get_content_list()`](app/api/routes/my_network_sanic.py:149-220) | Список контента в сети |
| GET | `/content/<content_hash>/exists` | [`check_content_exists()`](app/api/routes/my_network_sanic.py:223-262) | Проверка существования |
| GET | `/sync/status` | [`get_sync_status()`](app/api/routes/my_network_sanic.py:265-286) | Статус синхронизации |
| POST | `/sync/start` | [`start_network_sync()`](app/api/routes/my_network_sanic.py:289-310) | Запуск синхронизации |
| GET | `/network/stats` | [`get_network_stats()`](app/api/routes/my_network_sanic.py:313-383) | Статистика сети |
| GET | `/health` | [`health_check()`](app/api/routes/my_network_sanic.py:386-426) | Здоровье сети |

### 7. Мониторинг MY Network ([`my_monitoring_sanic.py`](app/api/routes/my_monitoring_sanic.py))
**Blueprint:** `bp = Blueprint("my_monitoring", url_prefix="/api/my/monitor")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| GET | `/` | [`monitoring_dashboard()`](app/api/routes/my_monitoring_sanic.py:32-79) | HTML дашборд |
| GET | `/ascii` | [`get_ascii_status()`](app/api/routes/my_monitoring_sanic.py:82-107) | ASCII статус |
| GET | `/live` | [`live_monitoring_data()`](app/api/routes/my_monitoring_sanic.py:110-149) | Живые данные |

### 8. Межузловое общение ([`node_communication.py`](app/api/node_communication.py))
**Blueprint:** `node_bp = Blueprint("node", url_prefix="/api/node")`

| Метод | Путь | Функция | Описание |
|-------|------|---------|----------|
| POST | `/handshake` | [`node_handshake()`](app/api/node_communication.py:63-142) | Хэндшейк между нодами |
| POST | `/content/sync` | [`content_sync()`](app/api/node_communication.py:145-238) | Синхронизация контента |
| POST | `/network/ping` | [`network_ping()`](app/api/node_communication.py:241-289) | Пинг между нодами |
| GET | `/network/status` | [`network_status()`](app/api/node_communication.py:292-324) | Статус ноды |
| POST | `/network/discover` | [`network_discover()`](app/api/node_communication.py:327-378) | Обнаружение нод |

### 9. Простые роуты
- [`account.py`](app/api/routes/account.py:4-8) - одна функция `s_api_v1_account_get()`
- [`_system.py`](app/api/routes/_system.py) - системные функции с git info и статусами

## Анализ существующих FastAPI роутов

### 1. V3 API совместимость ([`fastapi_v3_routes.py`](app/api/fastapi_v3_routes.py))
**Уже реализовано:**
- `/api/v3/node/status` - статус ноды
- `/api/v3/network/stats` - статистика сети  
- `/api/v3/content/list` - список контента
- `/api/v1/node` - совместимость с v1
- `/api/my/monitor` - мониторинг MY Network
- `/api/my/handshake` - хэндшейк MY Network

### 2. Межузловое общение ([`fastapi_node_routes.py`](app/api/fastapi_node_routes.py))
**Уже реализовано:**
- `/api/node/handshake` - обработка хэндшейка
- `/api/node/content/sync` - синхронизация контента
- `/api/node/network/ping` - пинг между нодами
- `/api/node/network/status` - статус ноды (GET)
- `/api/node/network/discover` - обнаружение нод

**⚠️ ДУБЛИРОВАНИЕ:** Межузловое общение реализовано И в Sanic, И в FastAPI!

## Анализ Middleware

### Текущий Sanic Middleware ([`middleware.py`](app/api/middleware.py))

**Критически важные компоненты:**
1. **SecurityMiddleware** - CORS, CSP, безопасные заголовки
2. **RateLimitMiddleware** - лимитирование запросов через Redis
3. **AuthenticationMiddleware** - JWT токены, API ключи, права
4. **CryptographicMiddleware** - ed25519 подписи для межузлового общения
5. **RequestContextMiddleware** - контекст запроса, логирование

**Middleware Pipeline:**
1. [`maintenance_middleware()`](app/api/middleware.py:605-612) - режим обслуживания
2. [`request_middleware()`](app/api/middleware.py:443-526) - основной пайплайн
3. [`response_middleware()`](app/api/middleware.py:529-554) - обработка ответов
4. [`exception_middleware()`](app/api/middleware.py:557-601) - обработка ошибок

**Особенности:**
- Ed25519 криптографические подписи для межузлового общения
- Rate limiting с различными паттернами
- Комплексная аутентификация
- Детальное логирование и метрики

### Совместимость с FastAPI
**✅ Совместимые компоненты:**
- Логирование и контекст
- Базовая безопасность
- CORS

**⚠️ Требуют адаптации:**
- Rate limiting (Sanic-специфичный код)
- Аутентификация (декораторы и middleware)
- Ed25519 криптография (заголовки и проверка подписей)
- Обработка исключений (Sanic exceptions)

## Зависимости и совместимость

### Анализ requirements.txt
```python
fastapi==0.104.1          # ✅ Уже включен
uvicorn==0.24.0           # ✅ ASGI сервер
sanic==23.12.1            # ⚠️ Нужно удалить после миграции
sqlalchemy==2.0.23        # ✅ Совместим
redis==5.0.1              # ✅ Совместим
PyNaCl==1.5.0            # ✅ Ed25519 криптография
pyjwt==2.8.0             # ✅ JWT токены
bcrypt==4.1.2            # ✅ Хеширование паролей
```

**Конфликтов зависимостей НЕТ** - обе библиотеки могут сосуществовать.

## Детальный план миграции

### Фаза 1: Подготовка (1-2 дня)

#### 1.1 Создание FastAPI Middleware
```python
# app/api/fastapi_middleware.py
from fastapi import FastAPI, Request, Response
from fastapi.middleware.base import BaseHTTPMiddleware

class FastAPISecurityMiddleware(BaseHTTPMiddleware):
    # Адаптация SecurityMiddleware
    
class FastAPIRateLimitMiddleware(BaseHTTPMiddleware):
    # Адаптация RateLimitMiddleware
    
class FastAPIAuthMiddleware(BaseHTTPMiddleware):
    # Адаптация AuthenticationMiddleware
    
class FastAPICryptoMiddleware(BaseHTTPMiddleware):
    # Адаптация CryptographicMiddleware
```

#### 1.2 Создание FastAPI Dependencies
```python
# app/api/fastapi_dependencies.py
from fastapi import Depends, HTTPException, Request
from typing import Optional

async def get_current_user(request: Request) -> Optional[User]:
    # Извлечение пользователя из токена
    
async def require_auth(user: User = Depends(get_current_user)) -> User:
    # Требование авторизации
    
async def check_permissions(permission: str):
    # Проверка разрешений
    
async def check_rate_limit(pattern: str = "api"):
    # Проверка rate limit
```

#### 1.3 Создание Pydantic моделей
```python
# app/api/fastapi_models.py
from pydantic import BaseModel
from typing import List, Optional
from datetime import datetime

class UserResponse(BaseModel):
    id: str
    username: str
    email: str
    # ... остальные поля

class ContentResponse(BaseModel):
    id: str
    title: str
    # ... остальные поля
```

### Фаза 2: Миграция маршрутов по модулям (7-10 дней)

#### 2.1 Приоритет 1: Аутентификация (2 дня)
```python
# app/api/fastapi_auth_routes.py
from fastapi import APIRouter, Depends, HTTPException
from fastapi.security import HTTPBearer

router = APIRouter(prefix="/api/v1/auth", tags=["auth"])

@router.post("/register")
async def register_user(user_data: UserRegistrationSchema):
    # Миграция register_user()
    
@router.post("/login") 
async def login_user(credentials: UserLoginSchema):
    # Миграция login_user()
```

**Ключевые изменения:**
- Sanic `response.json()` → FastAPI return dict
- Sanic `request.json` → FastAPI Pydantic models
- Sanic декораторы → FastAPI `Depends()`
- Sanic `Blueprint` → FastAPI `APIRouter`

#### 2.2 Приоритет 2: Контент и хранилище (3 дня)
```python
# app/api/fastapi_content_routes.py
# app/api/fastapi_storage_routes.py
```

**Сложности:**
- Streaming responses для downloads
- File uploads с validation
- Chunked uploads

#### 2.3 Приоритет 3: Блокчейн интеграция (2 дня)
```python  
# app/api/fastapi_blockchain_routes.py
```

#### 2.4 Приоритет 4: MY Network и мониторинг (3 дня)
```python
# app/api/fastapi_my_network_routes.py
# app/api/fastapi_monitoring_routes.py
```

**Сложности:**
- HTML templates для monitoring dashboard
- WebSocket connections (если есть)

### Фаза 3: Удаление дублирования (1-2 дня)

#### 3.1 Объединение межузлового общения
- Удалить [`node_communication.py`](app/api/node_communication.py) (Sanic версия)
- Оставить [`fastapi_node_routes.py`](app/api/fastapi_node_routes.py)
- Проверить совместимость ed25519 подписей

#### 3.2 Консолидация роутинга
- Удалить регистрацию Sanic blueprints из [`__init__.py`](app/api/__init__.py:237-285)
- Добавить все FastAPI роутеры в main FastAPI app

### Фаза 4: Обновление инициализации (1 день)

#### 4.1 Модификация main.py
```python
# Удалить create_sanic_app() и run_sanic_server()
# Сделать FastAPI режимом по умолчанию
def get_app_mode():
    return 'fastapi'  # Принудительно FastAPI
```

#### 4.2 Обновление lifecycle управления
```python
# Перенести EnhancedSanic функциональность в FastAPI
@app.on_event("startup")
async def startup_event():
    # Инициализация БД, Redis, ed25519, MY Network
    
@app.on_event("shutdown") 
async def shutdown_event():
    # Graceful shutdown
```

### Фаза 5: Тестирование и оптимизация (2-3 дня)

#### 5.1 Тестирование
- Unit тесты для всех endpoints
- Integration тесты для межузлового общения
- Load testing для performance
- Тестирование ed25519 криптографии

#### 5.2 Очистка кодовой базы
- Удалить Sanic imports
- Удалить sanic из requirements.txt
- Обновить docker configurations
- Обновить documentation

## Потенциальные проблемы и решения

### 1. Ed25519 криптографические подписи
**Проблема:** Sanic-специфичная обработка заголовков и контекста
**Решение:** 
- Создать FastAPI middleware для ed25519
- Использовать FastAPI dependency injection
- Сохранить полную совместимость протокола

### 2. Rate Limiting
**Проблема:** Sanic-специфичные декораторы и middleware
**Решение:**
- Портировать на FastAPI middleware + dependencies
- Сохранить Redis backend
- Использовать slowapi библиотеку как альтернативу

### 3. File Uploads и Streaming
**Проблема:** Разные API для file handling
**Решение:**
- FastAPI UploadFile для uploads
- StreamingResponse для downloads
- Сохранить chunked upload логику

### 4. WebSocket connections (если есть)
**Проблема:** Потенциальные WebSocket endpoints
**Решение:**
- FastAPI имеет нативную поддержку WebSocket
- Портировать с минимальными изменениями

### 5. HTML Templates
**Проблема:** Jinja2 templates в monitoring
**Решение:**
- FastAPI совместим с Jinja2
- Использовать FastAPI templating patterns

## Mermaid диаграммы архитектуры

### Текущая гибридная архитектура
```mermaid
graph TB
    Client[Client Requests] --> Main[main.py]
    Main --> Mode{App Mode}
    
    Mode -->|FastAPI| FastAPI[FastAPI App]
    Mode -->|Sanic| Sanic[Sanic App] 
    Mode -->|Minimal| Minimal[Minimal Server]
    
    FastAPI --> FV3[fastapi_v3_routes.py]
    FastAPI --> FNode[fastapi_node_routes.py]
    
    Sanic --> SAuth[auth_routes.py]
    Sanic --> SContent[content_routes.py] 
    Sanic --> SStorage[storage_routes.py]
    Sanic --> SBlockchain[blockchain_routes.py]
    Sanic --> SHealth[health_routes.py]
    Sanic --> SMyNet[my_network_sanic.py]
    Sanic --> SMonitor[my_monitoring_sanic.py]
    Sanic --> SNode[node_communication.py]
    
    subgraph "Shared Components"
        DB[(Database)]
        Redis[(Redis Cache)]
        Ed25519[Ed25519 Crypto]
        MyNetwork[MY Network Service]
    end
    
    FastAPI --> DB
    FastAPI --> Redis
    FastAPI --> Ed25519
    FastAPI --> MyNetwork
    
    Sanic --> DB
    Sanic --> Redis  
    Sanic --> Ed25519
    Sanic --> MyNetwork
```

### Целевая FastAPI архитектура
```mermaid
graph TB
    Client[Client Requests] --> FastAPI[FastAPI App]
    
    FastAPI --> Auth[auth_routes.py]
    FastAPI --> Content[content_routes.py]
    FastAPI --> Storage[storage_routes.py] 
    FastAPI --> Blockchain[blockchain_routes.py]
    FastAPI --> Health[health_routes.py]
    FastAPI --> MyNet[my_network_routes.py]
    FastAPI --> Monitor[monitoring_routes.py]
    FastAPI --> Node[node_routes.py]
    FastAPI --> V3Compat[v3_compat_routes.py]
    
    subgraph "FastAPI Middleware Stack"
        Security[Security Middleware]
        RateLimit[Rate Limit Middleware]
        AuthMW[Auth Middleware]
        Crypto[Crypto Middleware]
        Context[Context Middleware]
    end
    
    FastAPI --> Security
    Security --> RateLimit
    RateLimit --> AuthMW
    AuthMW --> Crypto
    Crypto --> Context
    
    subgraph "Shared Services"
        DB[(Database)]
        Redis[(Redis Cache)]
        Ed25519[Ed25519 Crypto]
        MyNetwork[MY Network Service]
    end
    
    Context --> DB
    Context --> Redis
    Context --> Ed25519
    Context --> MyNetwork
```

## Оценка трудозатрат

| Фаза | Компонент | Время | Сложность |
|------|-----------|--------|-----------|
| 1 | Middleware адаптация | 2 дня | Высокая |
| 2.1 | Auth routes | 2 дня | Средняя |
| 2.2 | Content + Storage | 3 дня | Высокая |
| 2.3 | Blockchain | 2 дня | Средняя |
| 2.4 | MY Network + Monitoring | 3 дня | Высокая |
| 3 | Удаление дублирования | 1 день | Низкая |
| 4 | Обновление инициализации | 1 день | Средняя |
| 5 | Тестирование | 3 дня | Высокая |
| **Итого** | | **17 дней** | |

## Рекомендации

### 1. Поэтапная миграция
- НЕ делать big bang migration
- Мигрировать по одному модулю
- Поддерживать работоспособность на каждом этапе

### 2. Сохранение совместимости
- Сохранить все API endpoints и форматы
- Особое внимание к ed25519 межузловому протоколу
- Сохранить все headers и форматы ответов

### 3. Тщательное тестирование
- Unit tests для каждого migrated endpoint
- Integration tests для межузлового общения
- Performance testing
- Backwards compatibility testing

### 4. Мониторинг миграции
- Логирование всех изменений
- Метрики производительности
- Error tracking
- Rollback plan для каждой фазы

### 5. Документация
- Обновить API документацию
- Автоматическая генерация OpenAPI docs
- Обновить deployment guides

## Заключение

Проект уже находится в **переходном состоянии** с частичной поддержкой FastAPI. Основная сложность миграции заключается в:

1. **Сложном middleware stack** с ed25519 криптографией
2. **Большом количестве endpoints** (40+ эндпоинтов)
3. **Межузловом протоколе** который требует точной совместимости
4. **File upload/download** функциональности

Однако, благодаря:
- ✅ Уже частично созданной FastAPI инфраструктуре
- ✅ Отсутствию конфликтов зависимостей  
- ✅ Хорошо структурированному коду
- ✅ Использованию SQLAlchemy (framework-agnostic)

Миграция **выполнима в течение 2-3 недель** при правильном планировании и поэтапном подходе.

**Ключевой фактор успеха:** Сохранение полной совместимости ed25519 межузлового протокола для корректной работы распределенной MY Network.