Corp/docs/in-progress/CELERY_INTEGRATION_PLAN.md

План интеграции Celery в проект EUSRR

📋 Текущее состояние

• ✅ Celery 5.5.3 установлен в requirements.txt
• ❌ Нет конфигурации Celery
• ❌ Нет celery.py в проекте
• ❌ Нет workers
• ⚠️ documents/tasks.py - закомментирован код с @shared_task

🎯 Цели интеграции

Основные задачи:

1. Уведомления - перенести отправку Email/Telegram/Push в фон
2. Документы - отложенная отправка уведомлений для массовых рассылок
3. Периодические задачи - напоминания, очистка, синхронизация

Метрики успеха:

• Скорость отклика API увеличится в 3-5 раз
• Возможность обработки 1000+ уведомлений без блокировки
• Мониторинг выполнения задач

---

🏗️ Архитектура решения

Компоненты:

┌─────────────────┐
│  Django API     │ ← HTTP requests
└────────┬────────┘
         │ создает задачи
         ↓
┌─────────────────┐
│  Redis (Broker) │ ← очередь задач
└────────┬────────┘
         │ получает задачи
         ↓
┌─────────────────┐
│  Celery Worker  │ ← выполняет задачи
└────────┬────────┘
         │ результаты
         ↓
┌─────────────────┐
│  Redis (Backend)│ ← хранит результаты
└─────────────────┘

Очереди (Queues):

1. default - обычные задачи
2. notifications - уведомления (высокий приоритет)
3. emails - отправка email (низкий приоритет)
4. periodic - периодические задачи (cron)

---

📝 План реализации

Этап 1: Базовая настройка (День 1)

1.1. Создать структуру Celery

• backend/eusrr_backend/celery.py - конфигурация Celery
• Обновить backend/eusrr_backend/__init__.py - автозагрузка
• Добавить Redis в settings.py

1.2. Настроить Redis

• Установить Redis локально или через Docker
• Настроить CELERY_BROKER_URL
• Настроить CELERY_RESULT_BACKEND

1.3. Тестовая задача

• Создать простую test_task
• Запустить worker
• Проверить выполнение

---

Этап 2: Уведомления (День 2)

2.1. Перенести отправку уведомлений

• notifications/tasks.py - создать задачи
  • send_notification_async(notification_id)
  • send_email_notification(notification_id)
  • send_telegram_notification(notification_id)
  • send_push_notification(notification_id)

2.2. Обновить NotificationService

• Изменить send_notification() - использовать Celery
• Добавить параметр use_celery=True
• Fallback на синхронную отправку при ошибке

2.3. Тестирование

• Проверить отправку уведомлений через Celery
• Измерить время отклика API (было/стало)

---

Этап 3: Документы (День 3)

3.1. Раскомментировать tasks.py

• documents/tasks.py - восстановить функционал
• Адаптировать под новую архитектуру

3.2. Массовые рассылки

• Батчинг: группировать уведомления по N штук
• Прогресс-бар для админа (сколько отправлено)

---

Этап 4: Периодические задачи (День 4)

4.1. Celery Beat

• Настроить celery beat
• Создать schedule в settings.py

4.2. Задачи

• Напоминания о документах (раз в день)
• Очистка старых уведомлений (раз в неделю)
• Синхронизация LDAP (если нужно)
• Backup базы данных (раз в сутки)

---

Этап 5: Мониторинг (День 5)

5.1. Flower

• Установить Flower
• Настроить доступ
• Дашборд для мониторинга

5.2. Логирование

• Structured logging для задач
• Алерты при сбоях (опционально - Sentry)

5.3. Метрики

• Время выполнения задач
• Количество успешных/неуспешных
• Размер очереди

---

⚙️ Конфигурация

Redis settings (в .env):

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1

Celery settings (в settings.py):

CELERY_BROKER_URL = os.getenv('CELERY_BROKER_URL', 'redis://localhost:6379/0')
CELERY_RESULT_BACKEND = os.getenv('CELERY_RESULT_BACKEND', 'redis://localhost:6379/1')
CELERY_ACCEPT_CONTENT = ['json']
CELERY_TASK_SERIALIZER = 'json'
CELERY_RESULT_SERIALIZER = 'json'
CELERY_TIMEZONE = 'Europe/Moscow'
CELERY_TASK_TRACK_STARTED = True
CELERY_TASK_TIME_LIMIT = 30 * 60  # 30 минут

Запуск worker:

# Development
celery -A eusrr_backend worker -l info -Q default,notifications,emails

# Production (with autoscale)
celery -A eusrr_backend worker -l info --autoscale=10,3

Запуск beat:

celery -A eusrr_backend beat -l info

Запуск Flower:

celery -A eusrr_backend flower --port=5555

---

🚀 Deployment

Docker Compose (пример):

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  celery_worker:
    build: .
    command: celery -A eusrr_backend worker -l info
    volumes:
      - .:/app
    depends_on:
      - redis
      - db
    environment:
      - CELERY_BROKER_URL=redis://redis:6379/0

  celery_beat:
    build: .
    command: celery -A eusrr_backend beat -l info
    volumes:
      - .:/app
    depends_on:
      - redis
      - db

  flower:
    build: .
    command: celery -A eusrr_backend flower --port=5555
    ports:
      - "5555:5555"
    depends_on:
      - redis
      - celery_worker

---

⚠️ Риски и меры минимизации

Риск 1: Redis недоступен

Решение: Fallback на синхронную обработку

Риск 2: Worker умер

Решение: Supervisor/systemd для автоперезапуска

Риск 3: Очередь переполнена

Решение: Rate limiting + мониторинг через Flower

Риск 4: Долгие задачи блокируют

Решение: Разделение на очереди + task time limit

---

📊 Метрики для отслеживания

До внедрения:

• Время отправки сообщения в групповой чат: ~500ms
• Время создания документа с 100 получателями: ~10s

После внедрения (цель):

• Время отправки сообщения: <50ms
• Время создания документа: <200ms
• Уведомления в фоне: не блокируют API

---

✅ Критерии готовности к продакшену

• Все задачи выполняются стабильно
• Worker автоматически перезапускается при сбое
• Flower доступен для мониторинга
• Логирование настроено
• Redis backup настроен
• Тестирование под нагрузкой пройдено
• Документация для деплоя готова

---

🔄 Откат изменений

Если что-то пойдет не так:

1. Вернуться к синхронной отправке в NotificationService
2. Закомментировать Celery задачи
3. Переключиться обратно на ветку master

Git: git checkout master && git branch -D feature/celery-integration