🐜 Workers (Cloud Functions)

Los workers son Google Cloud Functions que ejecutan tareas asíncronas pesadas. Son disparados por Cloud Tasks (en respuesta a acciones del usuario) o por Cloud Scheduler (tareas programadas). Viven en el repo rial-workers/.

Resumen

images-download

Qué hace

Genera signed URLs de Google Cloud Storage para las imágenes que el cliente quiere descargar. Procesa las imágenes en lotes para evitar timeouts y actualiza el Job en la BD a medida que avanza.

Cómo se dispara

1. El cliente hace clic en “Descargar” en la plataforma
2. El backend (POST /downloads/project-images) crea un Job y encola una tarea en Cloud Tasks con el jobId y los filtros de búsqueda
3. Cloud Tasks dispara la Cloud Function

Comportamiento

1. Recibe: { jobId, query: { projectFolderId, statuses, ... } }
2. Consulta la BD para obtener la lista de imágenes filtradas
3. Por cada lote de N imágenes:
   a. Llama a GCS para generar signed URLs (expiración: 1 hora)
   b. Llama a PUT /jobs/:jobId para actualizar progress + batch parcial
4. Al terminar todos los lotes:
   a. Llama a PUT /jobs/:jobId con status=COMPLETED y result: { signedUrls[] }
5. El frontend, que estaba en polling, recibe COMPLETED y descarga los archivos

Manejo de fallos

• Si falla al generar URLs para un lote: actualiza el Job con status=FAILED y un mensaje de error
• Cloud Tasks reintenta automáticamente la tarea si la Cloud Function no responde con HTTP 200
• Para evitar doble procesamiento, el worker verifica que el Job esté en estado PENDING o RUNNING antes de procesar

admin-metrics

Qué hace

Calcula las métricas de rendimiento de todas las compañías y marcas: SKUs por generar, aprobaciones, rechazos, tiempos promedio. Guarda los resultados en Redis vía el endpoint interno POST /cache/admin-metrics.

Cómo se dispara

• Automáticamente: Cloud Scheduler dispara la tarea 2 veces al día (aprox. 06:00 y 18:00 UTC)
• Manualmente: Se puede disparar manualmente desde la consola de GCP si las métricas están desactualizadas

Comportamiento

1. Consulta la BD con queries agregadas para calcular métricas de:
   - Companies: casos activos, SKUs totales, tasa de aprobación
   - Brands: rendimiento por marca
   - Projects: desglose por proyecto
   - ProjectFolders: estado y KPIs por caso
2. Formatea el payload como un Job completado con result = metricsData
3. Llama a POST /cache/admin-metrics (con header secret) para cada tipo de métrica
4. El API guarda en Redis con TTL (~12 horas)

Autenticación interna

El worker incluye un header secreto que el API verifica:

ADMIN_METRICS_BRANDS_REFRESH_SECRET: [valor-del-secret]

Cada tipo de métrica tiene su propio secret. Si el header no coincide, el API rechaza la petición con 401.

Manejo de fallos

• Si Redis está caído: el worker puede fallar y Cloud Tasks reintentará
• Si la BD está lenta: el worker tiene timeout extendido; Cloud Scheduler lo reintentará al siguiente ciclo
• Las métricas antiguas se mantienen en Redis hasta que expira el TTL — el cliente verá datos del último ciclo exitoso

faceswap-recognition

Qué hace

Procesa el reconocimiento facial para proyectos de tipo FACESWAP. Analiza las imágenes de la sesión original y las imágenes de referencia de los modelos de la marca para generar los datos necesarios para el reemplazo de rostros.

Cómo se dispara

1. Cuando se crea un proyecto FACESWAP, el backend encola una tarea en Cloud Tasks
2. Cloud Tasks dispara la Cloud Function con los parámetros del proyecto

Comportamiento

1. Recibe: jobId, projectId, referenceImages[], sourceImages[]
2. Procesa el reconocimiento facial (modelo de ML)
3. Actualiza el Job con los resultados intermedios
4. Al terminar: Job status=COMPLETED con los datos de reconocimiento
5. El equipo Rial usa estos datos para el paso de generación

Manejo de fallos

• Si falla el reconocimiento en una imagen: marca esa imagen como error y continúa con las demás
• El Job registra el error en errorMessage y puede quedar en estado PARTIAL_COMPLETE
• En caso de fallo total, Cloud Tasks reintenta la tarea hasta el límite configurado

Estructura del repositorio

rial-workers/
├── images-download/
│   ├── src/
│   │   └── index.ts       — Entry point de la Cloud Function
│   ├── package.json
│   └── Dockerfile
├── admin-metrics/
│   ├── src/
│   │   └── index.ts
│   ├── package.json
│   └── Dockerfile
└── faceswap-recognition/
    ├── src/
    │   └── index.ts
    ├── package.json
    └── Dockerfile

Cómo agregar un nuevo worker

1. Crear una nueva carpeta en rial-workers/
2. Implementar la Cloud Function que procese el Job y llame al API para actualizarlo
3. Crear la cola correspondiente en Cloud Tasks (GCP Console o Terraform)
4. Agregar el endpoint de encole en el backend (cloud-tasks.service.ts)
5. Agregar el tipo de Job en el enum JobType del schema Prisma y correr migración

Logs y monitoreo

Los workers emiten logs a Cloud Logging (GCP). Para ver los logs de un worker en ejecución:

gcloud functions logs read images-download \
  --region=southamerica-east1 \
  --limit=50

Los errores también aparecen en New Relic si el worker llama al backend, ya que las traces se propagan a través del API.