theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-django-celery/SKILL.md

@@ -0,0 +1,456 @@
+---
+name: patrones-django-celery
+description: Patrones de tareas asíncronas con Django + Celery — configuración, diseño de tareas, programación con Beat, reintentos, flujos canvas, monitoreo y testing. Úsala al añadir trabajos en segundo plano, tareas programadas o procesamiento asíncrono a una app Django.
+---
+
+# Patrones de tareas asíncronas con Django + Celery
+
+Patrones de nivel producción para procesamiento de tareas en segundo plano en Django usando Celery con Redis o RabbitMQ.
+
+## Cuándo activarla
+
+- Añadir trabajos en segundo plano o procesamiento asíncrono a una app Django
+- Implementar tareas periódicas o programadas
+- Sacar operaciones lentas (correo, generación de PDF, llamadas a API) del ciclo de request
+- Configurar Celery Beat para programación tipo cron
+- Depurar fallos de tareas, reintentos o colas atascadas
+- Escribir tests para tareas Celery
+
+## Configuración del proyecto
+
+### Instalación
+
+```bash
+pip install 'celery[redis]' django-celery-results django-celery-beat
+```
+
+### `celery.py` — punto de entrada de la app
+
+```python
+# config/celery.py
+import os
+from celery import Celery
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.development')
+
+app = Celery('miproyecto')
+app.config_from_object('django.conf:settings', namespace='CELERY')
+app.autodiscover_tasks()  # Descubre tasks.py en cada INSTALLED_APP
+
+@app.task(bind=True, ignore_result=True)
+def debug_task(self):
+    print(f'Request: {self.request!r}')
+```
+
+```python
+# config/__init__.py
+from .celery import app as celery_app
+
+__all__ = ('celery_app',)
+```
+
+### Settings de Django
+
+```python
+# config/settings/base.py
+
+# Broker (Redis recomendado para producción)
+CELERY_BROKER_URL = env('CELERY_BROKER_URL', default='redis://localhost:6379/0')
+CELERY_RESULT_BACKEND = env('CELERY_RESULT_BACKEND', default='django-db')
+
+# Serialización
+CELERY_ACCEPT_CONTENT = ['json']
+CELERY_TASK_SERIALIZER = 'json'
+CELERY_RESULT_SERIALIZER = 'json'
+
+# Comportamiento de las tareas
+CELERY_TASK_TRACK_STARTED = True
+CELERY_TASK_TIME_LIMIT = 30 * 60        # Límite duro: 30 min
+CELERY_TASK_SOFT_TIME_LIMIT = 25 * 60   # Límite suave: lanza SoftTimeLimitExceeded
+CELERY_WORKER_PREFETCH_MULTIPLIER = 1   # Evita que un worker acapare tareas largas
+CELERY_TASK_ACKS_LATE = True            # Reencola si el worker se cae
+
+# Persistencia de resultados
+CELERY_RESULT_EXPIRES = 60 * 60 * 24   # Conserva resultados 24 horas
+
+# Planificador Beat (tareas periódicas)
+CELERY_BEAT_SCHEDULER = 'django_celery_beat.schedulers:DatabaseScheduler'
+
+# Apps instaladas
+INSTALLED_APPS += [
+    'django_celery_results',
+    'django_celery_beat',
+]
+```
+
+### Ejecución de workers
+
+```bash
+# Iniciar worker (desarrollo)
+celery -A config worker --loglevel=info
+
+# Iniciar planificador beat (tareas periódicas)
+celery -A config beat --loglevel=info --scheduler django_celery_beat.schedulers:DatabaseScheduler
+
+# Worker + beat combinados (solo dev, nunca producción)
+celery -A config worker --beat --loglevel=info
+
+# Producción: varios workers con concurrencia
+celery -A config worker --loglevel=warning --concurrency=4 -Q default,high_priority
+```
+
+## Patrones de diseño de tareas
+
+### Tarea básica
+
+```python
+# apps/notifications/tasks.py
+from celery import shared_task
+import logging
+
+logger = logging.getLogger(__name__)
+
+@shared_task(name='notifications.send_welcome_email')
+def send_welcome_email(user_id: int) -> None:
+    """Envía el correo de bienvenida al usuario recién registrado."""
+    from apps.users.models import User
+    from apps.notifications.services import EmailService
+
+    try:
+        user = User.objects.get(pk=user_id)
+    except User.DoesNotExist:
+        logger.warning('send_welcome_email: usuario %s no encontrado', user_id)
+        return  # Idempotente — no lances excepción, la tarea ya es imposible de completar
+
+    EmailService.send_welcome(user)
+    logger.info('Correo de bienvenida enviado al usuario %s', user_id)
+```
+
+### Tarea con reintentos
+
+```python
+@shared_task(
+    bind=True,
+    name='integrations.sync_to_crm',
+    max_retries=5,
+    default_retry_delay=60,       # segundos antes del primer reintento
+    autoretry_for=(ConnectionError, TimeoutError),
+    retry_backoff=True,           # backoff exponencial
+    retry_backoff_max=600,        # tope de 10 minutos
+    retry_jitter=True,            # aleatoriza para evitar avalanchas
+)
+def sync_contact_to_crm(self, contact_id: int) -> dict:
+    """Sincroniza el contacto con el CRM externo, con reintento ante fallos transitorios."""
+    from apps.crm.services import CRMClient
+
+    try:
+        result = CRMClient().sync(contact_id)
+        return result
+    except CRMClient.RateLimitError as exc:
+        # Retraso de reintento específico tomado del header de la respuesta
+        raise self.retry(exc=exc, countdown=int(exc.retry_after))
+```
+
+### Patrón de tarea idempotente
+
+Diseña las tareas para que puedan ejecutarse varias veces con los mismos inputs sin efectos duplicados:
+
+```python
+@shared_task(name='orders.mark_shipped')
+def mark_order_shipped(order_id: int, tracking_number: str) -> None:
+    """Marca el pedido como enviado — segura de ejecutar varias veces."""
+    from apps.orders.models import Order
+
+    updated = Order.objects.filter(
+        pk=order_id,
+        status=Order.Status.PROCESSING,    # Guarda: solo actualiza si aún no está enviado
+    ).update(
+        status=Order.Status.SHIPPED,
+        tracking_number=tracking_number,
+    )
+
+    if not updated:
+        logger.info('mark_order_shipped: pedido %s ya enviado o no encontrado', order_id)
+```
+
+### Tarea con límite de tiempo suave
+
+```python
+from celery.exceptions import SoftTimeLimitExceeded
+
+@shared_task(
+    bind=True,
+    name='reports.generate_pdf',
+    soft_time_limit=120,
+    time_limit=150,
+)
+def generate_pdf_report(self, report_id: int) -> str:
+    """Genera un informe PDF con manejo elegante del timeout."""
+    from apps.reports.services import PDFGenerator
+
+    try:
+        path = PDFGenerator.build(report_id)
+        return path
+    except SoftTimeLimitExceeded:
+        # Limpia archivos parciales antes del kill duro
+        PDFGenerator.cleanup(report_id)
+        raise
+```
+
+## Invocación de tareas
+
+```python
+from datetime import timedelta
+from django.utils import timezone
+
+# Disparar y olvidar (asíncrono)
+send_welcome_email.delay(user.pk)
+
+# Programar en el futuro
+send_reminder.apply_async(args=[user.pk], countdown=3600)  # en 1 hora
+send_reminder.apply_async(args=[user.pk], eta=timezone.now() + timedelta(days=1))
+
+# Enrutar a una cola específica
+sync_contact_to_crm.apply_async(args=[contact.pk], queue='high_priority')
+
+# Ejecutar de forma síncrona (solo tests / depuración)
+result = generate_pdf_report.apply(args=[report.pk])
+```
+
+## Programación con Beat (tareas periódicas)
+
+### Cronograma definido en código
+
+```python
+# config/settings/base.py
+from celery.schedules import crontab
+
+CELERY_BEAT_SCHEDULE = {
+    'cleanup-expired-sessions': {
+        'task': 'users.cleanup_expired_sessions',
+        'schedule': crontab(hour=2, minute=0),   # todos los días a las 2am
+    },
+    'sync-inventory': {
+        'task': 'products.sync_inventory',
+        'schedule': 60.0,                         # cada 60 segundos
+    },
+    'weekly-digest': {
+        'task': 'notifications.send_weekly_digest',
+        'schedule': crontab(day_of_week='monday', hour=8, minute=0),
+    },
+}
+```
+
+### Cronograma definido en base de datos (django-celery-beat)
+
+```python
+# Gestiona tareas periódicas desde el admin de Django o desde código
+from django_celery_beat.models import PeriodicTask, CrontabSchedule
+import json
+
+schedule, _ = CrontabSchedule.objects.get_or_create(
+    hour='*/6', minute='0',
+    timezone='UTC',
+)
+
+PeriodicTask.objects.update_or_create(
+    name='Sincronizar inventario cada 6 horas',
+    defaults={
+        'crontab': schedule,
+        'task': 'products.sync_inventory',
+        'args': json.dumps([]),
+        'enabled': True,
+    }
+)
+```
+
+## Canvas: encadenar y agrupar tareas
+
+```python
+from celery import chain, group, chord
+
+# Chain: ejecuta tareas en secuencia, pasando resultados
+pipeline = chain(
+    fetch_data.s(source_id),
+    transform_data.s(),          # recibe el resultado de fetch_data como primer argumento
+    load_to_warehouse.s(),
+)
+pipeline.delay()
+
+# Group: ejecuta tareas en paralelo
+parallel = group(
+    send_welcome_email.s(user_id)
+    for user_id in new_user_ids
+)
+parallel.delay()
+
+# Chord: tareas en paralelo + callback cuando todas terminan
+result = chord(
+    group(process_chunk.s(chunk) for chunk in data_chunks),
+    aggregate_results.s(),       # se llama con la lista de resultados de los chunks
+)
+result.delay()
+```
+
+## Manejo de errores y cola de mensajes muertos
+
+```python
+# apps/core/tasks.py
+from celery.signals import task_failure
+
+@task_failure.connect
+def on_task_failure(sender, task_id, exception, args, kwargs, traceback, einfo, **kw):
+    """Registra todos los fallos de tareas en Sentry / alertas."""
+    import sentry_sdk
+    with sentry_sdk.new_scope() as scope:
+        scope.set_context('celery', {
+            'task': sender.name,
+            'task_id': task_id,
+            'args': args,
+            'kwargs': kwargs,
+        })
+        sentry_sdk.capture_exception(exception)
+```
+
+```python
+# Deriva las tareas fallidas a una cola de mensajes muertos tras agotar los reintentos
+@shared_task(
+    bind=True,
+    max_retries=3,
+    name='payments.charge_card',
+)
+def charge_card(self, order_id: int) -> None:
+    from apps.payments.models import Order, FailedCharge
+
+    try:
+        _do_charge(order_id)
+    except Exception as exc:
+        if self.request.retries >= self.max_retries:
+            # Persiste en tabla de mensajes muertos para revisión manual
+            FailedCharge.objects.create(
+                order_id=order_id,
+                error=str(exc),
+                task_id=self.request.id,
+            )
+            return  # No relances — la tarea falló de forma permanente
+        raise self.retry(exc=exc)
+```
+
+## Testing de tareas Celery
+
+### Tests unitarios (sin broker)
+
+```python
+# tests/test_tasks.py
+import pytest
+from unittest.mock import patch, MagicMock
+from apps.notifications.tasks import send_welcome_email
+
+class TestSendWelcomeEmail:
+
+    @pytest.mark.django_db
+    def test_envia_correo_a_usuario_existente(self, user):
+        with patch('apps.notifications.services.EmailService') as mock_email:
+            send_welcome_email(user.pk)
+            mock_email.send_welcome.assert_called_once_with(user)
+
+    @pytest.mark.django_db
+    def test_omite_usuario_inexistente_sin_fallar(self):
+        """No debe lanzar excepción si el usuario se borró entre el encolado y la ejecución."""
+        send_welcome_email(99999)  # Usuario inexistente — no debe fallar
+```
+
+### Tests de integración con CELERY_TASK_ALWAYS_EAGER
+
+```python
+# config/settings/test.py
+CELERY_TASK_ALWAYS_EAGER = True      # Ejecuta las tareas de forma síncrona en tests
+CELERY_TASK_EAGER_PROPAGATES = True  # Relanza las excepciones de las tareas
+
+# tests/test_integration.py
+@pytest.mark.django_db
+def test_registro_dispara_correo_bienvenida(client):
+    with patch('apps.notifications.services.EmailService') as mock_email:
+        response = client.post('/api/users/', {
+            'email': 'nuevo@example.com',
+            'password': 'strongpass123',
+        })
+
+    assert response.status_code == 201
+    mock_email.send_welcome.assert_called_once()
+```
+
+### Testing de reintentos
+
+```python
+@pytest.mark.django_db
+def test_tarea_reintenta_ante_error_de_conexion():
+    with patch('apps.crm.services.CRMClient.sync') as mock_sync:
+        mock_sync.side_effect = ConnectionError('timeout')
+
+        with pytest.raises(ConnectionError):
+            sync_contact_to_crm.apply(args=[1], throw=True)
+
+        assert mock_sync.call_count == 1  # Solo el primer intento en modo eager
+```
+
+## Monitoreo
+
+```bash
+# Inspeccionar workers y colas activas
+celery -A config inspect active
+celery -A config inspect stats
+celery -A config inspect reserved
+
+# Revisar longitud de colas (Redis)
+redis-cli llen celery
+
+# Flower: monitor web en tiempo real
+pip install flower
+celery -A config flower --port=5555
+```
+
+## Antipatrones
+
+```python
+# MAL: pasar instancias de modelos — pueden estar desactualizadas al ejecutarse
+send_welcome_email.delay(user)        # Nunca pases objetos del ORM
+send_welcome_email.delay(user.pk)     # Pasa siempre PKs
+
+# MAL: invocar tareas de forma síncrona en vistas de producción
+result = generate_report.apply()      # Bloquea el hilo del request
+
+# MAL: tarea no idempotente sin guardas
+@shared_task
+def charge_and_fulfill(order_id):
+    order.charge()     # ¡Puede cobrar dos veces si la tarea reintenta!
+    order.fulfill()
+
+# BIEN: idempotente con guarda de estado
+@shared_task
+def charge_and_fulfill(order_id):
+    order = Order.objects.select_for_update().get(pk=order_id)
+    if order.status != Order.Status.PENDING:
+        return  # Ya procesado
+    order.charge()
+    order.fulfill()
+```
+
+## Lista de verificación de producción
+
+| Verificación | Configuración |
+|--------------|---------------|
+| Workers se reinician tras un crash | unidad de `supervisord` o `systemd` |
+| `CELERY_TASK_ACKS_LATE = True` | Reencola tareas si el worker se cae |
+| `CELERY_WORKER_PREFETCH_MULTIPLIER = 1` | Distribución justa de tareas largas |
+| Colas separadas por prioridad | `-Q default,high_priority,low_priority` |
+| `CELERY_TASK_SOFT_TIME_LIMIT` definido | Timeout elegante antes del kill duro |
+| Integración con Sentry | Captura todas las señales `task_failure` |
+| Flower u otro monitor | Visibilidad de la profundidad de las colas |
+| Beat corre en un solo nodo | Evita ejecución duplicada de tareas programadas |
+
+## Skills relacionadas
+
+- `patrones-django` — ORM, capa de servicios y estructura de proyecto
+- `tdd-django` — Testing de modelos, vistas y servicios Django
+- `testing-python` — Configuración de pytest y fixtures