Worker Automation

Gestão de tasks Celery e workers da plataforma Alcance — listagem, monitoramento em tempo real, controle de filas e operações administrativas sobre execuções assíncronas.

Base path

Todos os endpoints abaixo estão prefixados por:

/api/v1/worker-automation

Escopos

A API Key deve conter os escopos recurso:acao apropriados:

Operações realmente destrutivas (clear-queue, purge-queue, cleanup-no-client, sync-orphans) exigem também a role administrativa admin na WebApi.

Estados de uma task

Os estados seguem o ciclo de vida padrão do Celery. Para a referência completa, veja /conceitos/tasks-celery.

Filas configuradas

A plataforma opera com 5 filas Celery dedicadas, espelhadas em task_routes do celery_app.py:

• certidao — 2 workers (emissão de CNDs federal, estadual, municipal, FGTS).
• scraping — 2 workers (raspagem de portais oficiais, SEFAZ, Receita).
• scan — 1 worker (varreduras programadas, integridade de dados).
• observer — 1 worker (jobs de observação, watchers e healthchecks).
• ui_automation — 1 worker (automações Selenium / pyautogui que exigem display).

Endpoints principais

GET /worker-automation/

Lista paginada de workers com filtros opcionais por status, automation_type, queue, date_from, date_to. Paginação via page (≥1) e per_page (1–100, default 20). Retorno enriquecido com client_name e display_name da automação.

GET /worker-automation/stats

Dashboard de estatísticas agregadas — contagens por status, fila e tipo de automação. Ideal para alimentar contadores e gráficos do gerenciador.

GET /worker-automation/active

Workers atualmente com status EXECUTANDO. Retorna a lista completa sem paginação.

GET /worker-automation/queued

Workers com status AGENDADO, ordenados por prioridade e paginados (page, per_page 1–100, default 10).

GET /worker-automation/status/{task_id}

Consulta o estado atual de uma task Celery pelo task_id (UUID). É o endpoint que alimenta o tool MCP consultar_status_task — o LLM usa esta rota para acompanhar tasks longas (CNDs, scrapers) sem bloquear o chat.

GET /worker-automation/{worker_id}

Detalhe completo de um worker pelo ID interno (int). Inclui client_name, display_name, timestamps e mensagem de erro quando aplicável.

POST /worker-automation/{worker_id}/cancel

Cancela a task via celery_app.control.revoke (com terminate=True se estiver EXECUTANDO) e atualiza o status no banco para CANCELADO. Requer admin.

POST /worker-automation/{worker_id}/retry

Re-enfileira um worker em estado FALHA ou CANCELADO. Cria nova task Celery e devolve o worker atualizado. Requer admin.

POST /worker-automation/{worker_id}/move

Migra o worker para outra fila Celery. Body: { "target_queue": "scraping" }. Útil para realocar carga manualmente. Requer admin.

POST /worker-automation/{worker_id}/reorder

Altera a prioridade de execução do worker. Body: { "new_priority": <int> }. Quanto menor o número, mais cedo é processado. Requer admin.

POST /worker-automation/clear-queue

Operação destrutiva. Cancela em massa workers conforme o parâmetro scope:

• queued — apenas AGENDADO.
• running — apenas EXECUTANDO (com terminate=True).
• all (default) — ambos.

Cada worker é marcado como CANCELADO e tem sua task revogada no broker. Requer admin.

Endpoint dashboard agregado

GET /worker-automation/dashboard substitui 5 chamadas de polling do frontend (stats, queue-live-status, broker-status, active, queued) por uma única requisição. O payload contém as seções:

• stats — contagens agregadas por status e fila.
• queues — estado por fila com active_tasks, pending_tasks, capacity e load_percent.
• summary — totais (total_active, total_pending, total_completed_today, total_errors_today).
• broker — snapshot LLEN/inspect do Redis/Celery.
• active — workers EXECUTANDO enriquecidos (cap de 50).
• queued — primeira página de AGENDADO (10 itens, formato items + total + page + per_page + pages).
• history — últimos 20 workers em estado terminal (CONCLUIDO, FALHA, CANCELADO).

Cada seção tem fallback isolado: falha em uma fonte (ex.: Redis offline) não derruba o payload todo — apenas a seção afetada retorna vazia.

Schema típico de task status

Resposta de GET /worker-automation/status/{task_id}:

{
  "status": "success",
  "message": "Status da task recuperado com sucesso",
  "data": {
    "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
    "state": "SUCCESS",
    "result": {
      "certidao_id": 1234,
      "url_pdf": "/api/v1/certidao-negativa/1234/pdf",
      "tempo_execucao_s": 47.2
    }
  }
}

Em estados não terminais (PENDING, STARTED, RETRY), result pode vir como null ou conter metadados parciais. Em FAILURE, result traz exc_type, exc_message e, quando disponível, o traceback resumido.

Notas