Jobs Assíncronos — studyAI

Decisões operacionais para workers, retry, progress e failure handling.

---

Índice

1. Worker framework
2. Tipos de jobs
3. Retry e failure strategy
4. Progress updates
5. Tabela jobs (operacional)

---

Diagrama: ciclo de vida de jobs

A carregar diagrama…

Retry e backoff

A carregar diagrama…

---

Worker framework

Decisão: Celery + Redis

Escolha: Celery + Redis.

Rationale:

• Retry, dead-letter, rate limiting nativos
• Escala com workers
• Redis já usado para rate limit e cache
• Fase 0/MVP: pode começar com BackgroundTasks do FastAPI para ingestão simples; migrar para Celery na Fase 1

MVP fallback: Background tasks inline para ingestão (1 worker). Sem fila persistente. Adequado para validar fluxo antes de Celery.

---

Tipos de jobs

---

Retry e failure strategy

Retry

• Backoff: Exponencial: 1min, 5min, 15min, 1h
• Max retries: 5 (ingest), 3 (generate)
• Retry quando: Erro de rede, timeout LLM, rate limit 429
• Não retry: Erro de validação, ficheiro corrompido

Dead-letter / failure

• Após max retries: Job marcado failed, error preenchido
• Dead-letter queue: Opcional. Celery pode guardar em Redis ou log. Para MVP: só marcar failed em DB
• Notificação: Log estruturado. Futuro: alerta se taxa de falha > X%
• Recovery manual: Endpoint POST /jobs/:id/retry para admin re-disparar

Ingest específico

• files.retry_count: Incrementar a cada tentativa
• files.last_error: Guardar última mensagem
• files.status: error após max retries
• Cron opcional: Job que retenta files com status=error e retry_count < 5

---

Progress updates

Estratégia: Polling + SSE opcional

Decisão: Implementar polling primeiro (GET /jobs/:id). SSE como melhoria futura se UX exigir.

Formato do progress (jobs.progress, jobs.result):

{
  "progress": 45,
  "message": "A escrever secção 2 de 5...",
  "current_section": 2,
  "total_sections": 5,
  "document_id": "uuid"  // quando criado
}

---

Tabela jobs (operacional)

Celery: task_id (opcional) para correlacionar com Celery result backend.