mnemo_cards/plans/микросервисная_архитектура.md

name	overview	todos
Микросервисная архитектура Mnemo Cards	План разделения монолитного backend на микросервисы с учетом независимого деплоя, разных технологий и организации команды. Используется гибридный подход к базам данных.	id content status analyze_dependencies Проанализировать зависимости между модулями и создать карту зависимостей pending id content status design_api_gateway Спроектировать API Gateway для маршрутизации запросов к микросервисам pending id content status create_shared_jwt_lib Создать shared библиотеку для валидации JWT токенов pending id content status plan_database_migration Спланировать миграцию базы данных (схемы/отдельные БД) pending id content status extract_auth_service Выделить Auth Service как первый микросервис pending id content status extract_payment_service Выделить Payment Service как второй микросервис pending id content status setup_service_communication Настроить коммуникацию между сервисами (синхронная/асинхронная) pending id content status setup_monitoring Настроить мониторинг и логирование для микросервисов pending id content status create_docker_compose Создать docker-compose для локальной разработки всех микросервисов pending

План разделения на микросервисы

Анализ текущей архитектуры

Текущий монолит включает следующие доменные области:

1. Authentication & User Management - JWT, Telegram auth, пользователи
2. Content Management - Packs, Cards, Tests, Games
3. Payments & Subscriptions - YooKassa, Google Play, RuStore
4. Statistics & Analytics - User statistics, achievements, word statistics
5. Admin Panel - Админские функции
6. Telegram Bot - Бот для авторизации
7. Cron Jobs & Background Tasks - Фоновые задачи

Предлагаемое разделение на микросервисы

1. Auth Service (Сервис аутентификации)

Ответственность:

• JWT токены (access/refresh)
• Регистрация/логин пользователей
• Telegram авторизация (генерация кодов)
• Управление пользователями (CRUD)
• ACL и авторизация

База данных:

• users, auth, tokens, refresh_tokens, telegram_auth_codes

API Endpoints:

• /api/v2/auth/* (register, login, refresh, logout, telegram)
• /api/v2/users/* (CRUD пользователей)

Зависимости:

• PostgreSQL (собственная схема)
• Telegram Bot API (для авторизации)

Технологии:

• Dart + Shelf (можно оставить или перейти на Go/Node.js)

Особенности:

• Критический сервис - должен быть высокодоступным
• Низкая задержка критична для всех запросов

---

2. Content Service (Сервис контента)

Ответственность:

• Управление паками карточек (CardPacks)
• Управление карточками (GameCards)
• Управление тестами (Tests)
• Управление играми (Games assets)
• Голоса карточек (CardVoices)
• Доступ к контенту (проверка прав доступа через Auth Service)

База данных:

• card_packs, game_cards, card_pack_cards, card_voices, tests, tasks

API Endpoints:

• /api/v2/packs/*
• /api/v2/tests/*
• /api/v2/games/*
• /api/v2/voice/*

Зависимости:

• PostgreSQL (собственная схема или shared с Payments для связей)
• Auth Service (проверка доступа через API или shared token validation)

Технологии:

• Dart + Shelf (можно перейти на Python/FastAPI для удобства работы с контентом)

Особенности:

• Статические файлы (изображения, аудио) - можно вынести в CDN/Storage
• Высокая нагрузка на чтение

---

3. Payment Service (Сервис платежей)

Ответственность:

• Обработка платежей через YooKassa
• Обработка IAP (Google Play, RuStore)
• Управление промокодами
• Управление скидками (discounts)
• Покупка паков
• Webhooks от платежных систем

База данных:

• payments, promo_codes, discounts, subscriptions (или отдельный сервис)

API Endpoints:

• /api/v2/purchases/*
• /api/v2/promocodes/*
• /api/v2/discounts/*
• /api/webhooks/yookassa, /api/webhooks/google-play, /api/webhooks/rustore

Зависимости:

• PostgreSQL (собственная схема)
• Auth Service (проверка пользователя)
• Content Service (информация о паках для покупки)
• YooKassa API, Google Play API, RuStore API

Технологии:

• Dart + Shelf или Node.js/TypeScript (удобная работа с webhooks)

Особенности:

• Высокие требования к безопасности
• Идемпотентность операций
• Обработка webhooks

---

4. Subscription Service (Сервис подписок)

Ответственность:

• Управление подписками пользователей
• Проверка активности подписки
• Фичи подписки
• Автопродление (через cron)

База данных:

• subscriptions (может быть shared с Payment Service на этапе миграции)

API Endpoints:

• /api/v2/subscriptions/*

Зависимости:

• PostgreSQL (собственная схема или shared с Payment)
• Auth Service (проверка пользователя)
• Payment Service (создание подписки через платеж)

Технологии:

• Dart + Shelf или отдельный микросервис

Вариант: Можно объединить с Payment Service на первом этапе, если логика тесно связана.

---

5. Statistics Service (Сервис статистики)

Ответственность:

• Статистика пользователей (user statistics)
• Статистика по словам (word statistics)
• Достижения (achievements)
• Сессии обучения (study sessions)
• Аналитика и отчеты

База данных:

• user_datas, word_statistics, achievements, study_sessions, pack_progress

API Endpoints:

• /api/v2/users/me/statistics/*
• /api/v2/users/me/achievements
• /api/v2/users/me/sessions

Зависимости:

• PostgreSQL (собственная схема или отдельная БД для аналитики - TimescaleDB/ClickHouse)
• Auth Service (проверка пользователя)
• Content Service (информация о паках/карточках)

Технологии:

• Dart + Shelf или Python (удобно для аналитики) или Go (высокая производительность)

Особенности:

• Высокая нагрузка на запись (tracking событий)
• Возможность использовать TimescaleDB для временных рядов
• Отложенная обработка данных (бэтчинг)

---

6. Admin Service (Админ панель)

Ответственность:

• Админская авторизация
• Управление контентом (CRUD паков, карточек)
• Аналитика для админов
• Управление пользователями
• Audit логирование

База данных:

• audit (отдельная таблица для логирования действий)
• Использует данные из других сервисов

API Endpoints:

• /api/v2/admin/*

Зависимости:

• Auth Service (проверка админ прав)
• Content Service (управление контентом)
• Payment Service (управление платежами)
• Statistics Service (аналитика)

Технологии:

• Dart + Shelf (можно оставить текущий стек)

Особенности:

• Агрегирует данные из нескольких сервисов
• Требует высоких прав доступа

---

7. Telegram Bot Service (Сервис Telegram бота)

Ответственность:

• Обработка команд Telegram бота
• Генерация кодов авторизации для веба
• Интеграция с Auth Service

База данных:

• Может использовать shared telegram_auth_codes или собственную

API Endpoints:

• /api/v2/telegram-bot/*
• Telegram Bot API webhook

Зависимости:

• Auth Service (создание/проверка кодов)
• Telegram Bot API

Технологии:

• Dart + Shelf или Node.js/TypeScript (удобные библиотеки для Telegram)

Особенности:

• Относительно изолированный сервис
• Может работать независимо

---

8. Background Jobs Service (Сервис фоновых задач)

Ответственность:

• Cron задачи (backup, проверка платежей, генерация промокодов, etc.)
• Асинхронная обработка задач
• Очереди задач (опционально)

Зависимости:

• Все остальные сервисы (для выполнения задач)

Технологии:

• Dart (текущий стек) или перейти на специализированное решение (Bull/BullMQ на Node.js, Celery на Python)

Альтернатива: Можно интегрировать в каждый сервис отдельно или использовать общий Job Queue (Redis + Worker).

---

Стратегия миграции

Фаза 1: Подготовка (1-2 недели)

1. Выделить общие компоненты:

   • Общие DTO/models в mnemo_cards_common
   • Shared database connection pool
   • API Gateway (опционально, можно использовать nginx/kong)

2. Создать API Gateway:

   • Единая точка входа для клиентов
   • Маршрутизация к микросервисам
   • Агрегация запросов (если нужно)
   • Rate limiting, CORS

Фаза 2: Выделение критических сервисов (2-4 недели)

Приоритет 1: Auth Service

• Выделить аутентификацию в отдельный сервис
• Создать JWT validation library для других сервисов
• Мигрировать пользователей

Приоритет 2: Payment Service

• Выделить платежи
• Изолировать webhooks
• Мигрировать платежные данные

Фаза 3: Выделение остальных сервисов (4-8 недель)

Приоритет 3: Content Service

• Выделить управление контентом
• Вынести статические файлы в CDN/Storage

Приоритет 4: Statistics Service

• Выделить статистику
• Оптимизировать запись данных (бэтчинг)

Приоритет 5: Остальные сервисы

• Admin Service
• Telegram Bot Service
• Background Jobs Service

Фаза 4: Оптимизация (ongoing)

• Разделение баз данных (Database per Service)
• Кэширование (Redis)
• Message Queue для асинхронной коммуникации
• Мониторинг и логирование (ELK, Prometheus)

---

Схема коммуникации между сервисами

graph TB
    Client[Web Client] --> Gateway[API Gateway]
    
    Gateway --> AuthService[Auth Service]
    Gateway --> ContentService[Content Service]
    Gateway --> PaymentService[Payment Service]
    Gateway --> SubscriptionService[Subscription Service]
    Gateway --> StatisticsService[Statistics Service]
    Gateway --> AdminService[Admin Service]
    
    TelegramBot[Telegram Bot] --> AuthService
    TelegramBot --> Gateway
    
    PaymentService --> AuthService
    PaymentService --> ContentService
    SubscriptionService --> AuthService
    SubscriptionService --> PaymentService
    StatisticsService --> AuthService
    StatisticsService --> ContentService
    AdminService --> AuthService
    AdminService --> ContentService
    AdminService --> PaymentService
    AdminService --> StatisticsService
    
    BackgroundJobs[Background Jobs] --> AuthService
    BackgroundJobs --> PaymentService
    BackgroundJobs --> StatisticsService
    
    AuthService --> AuthDB[(Auth DB)]
    ContentService --> ContentDB[(Content DB)]
    PaymentService --> PaymentDB[(Payment DB)]
    SubscriptionService --> SubscriptionDB[(Subscription DB)]
    StatisticsService --> StatisticsDB[(Statistics DB)]

---

Рекомендации по базам данных (гибридный подход)

Вариант 1: Shared Database на первом этапе

• Все сервисы используют одну БД, но разные схемы (namespaces)
• Упрощает миграцию
• Позволяет постепенно разделять

Вариант 2: Database per Service (целевое состояние)

Auth Service:

• auth_db - users, tokens, refresh_tokens, telegram_auth_codes

Content Service:

• content_db - card_packs, game_cards, card_voices, tests, tasks

Payment Service:

• payment_db - payments, promo_codes, discounts

Subscription Service:

• subscription_db - subscriptions

Statistics Service:

• statistics_db - user_datas, word_statistics, achievements, study_sessions
• Или TimescaleDB для временных рядов

Переходные связи:

Для связей между сервисами использовать:

• API calls - синхронная коммуникация (для проверки доступа, получения данных)
• Event-driven - асинхронная коммуникация (опционально, через message queue)
• Shared IDs - использование UUID для связи между сервисами

---

Технологические рекомендации

API Gateway

• Kong или nginx - для маршрутизации
• Или Istio для более сложных сценариев

Service Mesh (опционально)

• Istio или Linkerd - для управления трафиком, безопасности, observability

Message Queue (для асинхронной коммуникации)

• Redis Pub/Sub или RabbitMQ или NATS
• Для событий: payment_completed, user_registered, etc.

Мониторинг

• Prometheus + Grafana - метрики
• ELK Stack (Elasticsearch, Logstash, Kibana) - логи
• Jaeger или Zipkin - distributed tracing

Кэширование

• Redis - для кэширования токенов, контента, статистики

---

Файлы, которые нужно будет изменить/создать

Новые директории для микросервисов:

• services/auth-service/
• services/content-service/
• services/payment-service/
• services/subscription-service/
• services/statistics-service/
• services/admin-service/
• services/telegram-bot-service/
• services/background-jobs-service/

Общие компоненты:

• shared/jwt-validator/ - библиотека для валидации JWT
• shared/database-migrations/ - миграции БД
• shared/common-models/ - общие модели (уже есть в mnemo_cards_common)

Конфигурация:

• docker-compose.microservices.yml - оркестрация всех сервисов
• infrastructure/ - terraform/k8s конфигурации

---

Критерии успешности разделения

1. ✅ Каждый сервис можно деплоить независимо
2. ✅ Сервисы могут использовать разные технологии
3. ✅ Отказ одного сервиса не ломает остальные
4. ✅ Легко масштабировать отдельные сервисы
5. ✅ Четкое разделение ответственности
6. ✅ Тестируемость каждого сервиса отдельно

---

Риски и митигация

Риск 1: Сложность отладки распределенной системы

Митигация: Использовать distributed tracing (Jaeger), централизованное логирование

Риск 2: Сетевая задержка между сервисами

Митигация: Кэширование, асинхронная коммуникация где возможно, оптимизация API calls

Риск 3: Консистентность данных между сервисами

Митигация: Event-driven архитектура, eventual consistency, saga pattern для транзакций

Риск 4: Усложнение деплоя

Митигация: Docker Compose для разработки, Kubernetes для продакшена, CI/CD для каждого сервиса