Tareas programadas y colas

---
name: tareas-programadas-y-colas
description: hacer trabajo después, reintentarlo y saber cuándo dejó de funcionar.
---

# Tareas programadas y colas

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando el
trabajo no deba terminar dentro de una petición web o tenga que ocurrir en el futuro.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Generas archivos, importas datos, envías lotes o llamas una API lenta.
- Algo debe correr cada hora, cada noche o en una fecha elegida por el usuario.
- Un fallo temporal debe reintentarse sin que la persona repita la acción.
- Necesitas limitar concurrencia o respetar la tasa de un proveedor externo.

Si el trabajo tarda milisegundos y no tiene efectos externos, ejecútalo en la petición.
Una cola agrega operación; úsala porque necesitas sus garantías, no por arquitectura.

## Cómo armarla

Usa **pg-boss sobre Postgres** con un worker siempre activo. Si el proyecto es totalmente
serverless, usa **Inngest** o **Trigger.dev** y conserva las mismas reglas de idempotencia.

1. El endpoint valida, guarda el cambio de negocio y encola un id de recurso. No metas
   documentos completos ni secretos en el payload.
2. Define por tipo de job: esquema versionado, timeout, máximo de intentos, concurrencia
   y llave de idempotencia. Rechaza payloads con una versión desconocida.
3. Haz cada handler idempotente. Antes de cobrar, enviar o crear, busca el efecto por su
   llave; marca terminado solo después de confirmar el resultado externo.
4. Reintenta errores temporales con espera exponencial y jitter. Manda errores
   permanentes a fallidos de inmediato y conserva una cola muerta operable.
5. Usa leases o visibilidad con vencimiento para recuperar trabajos de un worker caído.
   Asume entrega al menos una vez, nunca exactamente una vez.
6. Haz que el cron solo encole. Usa UTC para disparadores del sistema y guarda la zona
   IANA cuando el horario pertenece a una persona o negocio.
7. Registra espera, duración, intentos, error y correlación. Alerta por edad del job más
   viejo y por crecimiento de fallidos, no solo por CPU.
8. Agrega cancelar y reintentar desde una vista protegida. Reintentar debe conservar la
   llave original o declarar explícitamente una nueva operación.

## En qué te vas a trabar

- **El worker muere a mitad del efecto externo.** Por eso el handler consulta antes de
  repetir y el proveedor recibe una llave de idempotencia cuando la soporta.
- **Un cron puede dispararse dos veces o no dispararse.** Pon un registro único por
  periodo y un reconciliador que encuentre ejecuciones faltantes.
- **Los jobs viejos cambian de forma cuando despliegas código nuevo.** Versiona payloads
  y mantén un adaptador mientras quede trabajo con la versión anterior.
- **La cola también cuesta.** Mide retención, Redis o Postgres, workers encendidos y
  llamadas reintentadas antes de vender procesamiento ilimitado.

## Qué NO hacer

- No uses `setTimeout` en un proceso web para trabajo importante.
- No reintentes sin límite ni a intervalos fijos contra un proveedor caído.
- No guardes tokens, archivos binarios o datos personales innecesarios en el payload.
- No marques el job terminado antes de persistir el efecto que el usuario espera.

## Checklist

- [ ] Cada tipo de job tiene esquema, timeout, intentos, concurrencia e idempotencia.
- [ ] Un worker que muere a mitad del proceso no pierde ni duplica el efecto.
- [ ] Cron duplicado y cron omitido tienen pruebas y reconciliación.
- [ ] Errores permanentes llegan a una cola muerta visible y reintentable.
- [ ] Métricas y alertas cubren espera, duración, fallos y edad del trabajo más viejo.
- [ ] Los horarios del usuario conservan su zona IANA y los del sistema usan UTC.
- [ ] Un despliegue nuevo puede procesar payloads antiguos todavía en cola.