Tasks Celery (processamento assíncrono)

Algumas operações da WebApiAlcance levam dezenas de segundos ou minutos — gerar PDF de certidão, converter extrato bancário, fazer scraping em portal de receita estadual, executar automações de UI via Selenium. Mantê-las síncronas seria custoso em dois eixos: amarra o request HTTP do cliente e torna o sistema vulnerável a timeouts do gateway (a Vercel corta em 300s no plano Pro).

A solução é o Celery — fila de tarefas distribuídas em Python, com broker Redis e workers que consomem em background. Quando o cliente chama um endpoint que precisa processar algo longo, a API enfileira a tarefa, recebe um task_id instantâneo e devolve esse id imediatamente. O processamento real acontece num worker à parte, e o cliente consulta o status quando quiser.

Para o LLM esse desacoplamento é fundamental: nenhuma tool MCP pode bloquear o usuário esperando 2 minutos por um resultado. O contrato é sempre devolver o task_id na hora e ensinar o modelo a acompanhar.

Fluxo padrão

   ┌──────────────┐   1. POST /automation/...      ┌──────────────────┐
   │ MCP Alcance  │ ─────────────────────────────▶ │ WebApiAlcance    │
   │ (Vercel)     │ ◀───────────────────────────── │ FastAPI          │
   └──────────────┘   2. devolve task_id imediato  └──────┬───────────┘
                                                          │ 3. enfileira
                                                          ▼
                                                   ┌──────────────────┐
                                                   │ Redis broker     │
                                                   │ + Celery workers │
                                                   └──────┬───────────┘
                                                          │ 4. processa
                                                          │    e atualiza
                                                          ▼
   ┌──────────────┐   5. GET /worker-automation/    ┌──────────────────┐
   │ MCP Alcance  │      status/{task_id}          │ Result backend   │
   │              │ ─────────────────────────────▶ │ (Redis/DB)       │
   └──────────────┘ ◀───────────────────────────── └──────────────────┘
                       6. estado + resultado

1. Cliente chama o endpoint da automação → a API valida, enfileira a task no broker e responde com task_id.
2. Worker Celery pega a task da fila, executa o trabalho real, atualiza o estado no result backend.
3. Cliente consulta task_id na rota de status — a API lê o estado atual e devolve.

Estados possíveis

Celery padroniza 6 estados, que a tool MCP consultar_status_task propaga literalmente:

Tool MCP consultar_status_task

Endpoint upstream: GET /api/v1/worker-automation/status/{task_id}. A tool MCP é readOnly e devolve um markdown estruturado:

• Estado em negrito para leitura rápida.
• Em SUCCESS, o result aparece como bloco de código (JSON serializado e truncado em 500 chars).
• Em FAILURE, mensagem do erro + traceback parcial.
• Em RETRY/PENDING/STARTED, instrução para consultar novamente em alguns segundos.

O task_id típico é um UUID v4 — o LLM deve copiá-lo literalmente da resposta da tool que disparou a automação.

Filas configuradas

A WebApiAlcance roteia tasks por categoria — cada fila tem um pool dedicado para não deixar uma automação pesada (Selenium) bloquear consultas leves:

• certidao — 2 workers, geração e busca de certidões negativas.
• scraping — 2 workers, raspagem de portais externos (receitas estaduais, prefeituras).
• scan — 1 worker, varredura periódica de status.
• observer — 1 worker, watchdogs e eventos do sistema.
• ui_automation — 1 worker, automações via Selenium (UI real, mais lentas e frágeis).

Os números acima vivem em app/worker/celery_app.py e o queue-live-status do dashboard mostra a ocupação em tempo real.