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

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

---

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

```mermaid
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 для каждого сервиса