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/de manutenção (clear-queue, purge-queue, cleanup-no-client, sync-orphans) exigem também perfil administrador ou diretoria (require_perfil) no realm interno. As operações do dia a dia (cancel, retry, move, reorder) não exigem perfil de gestão - continuam acessíveis a funcionario, mediante autenticação e escopo worker_automation:write.

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

GET /worker-automation/

Lista paginada de workers com filtros opcionais. Cada item vem enriquecido com client_name (razão social do cliente) e display_name (nome amigável da automação).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Workers recuperados com sucesso",
  "data": {
    "items": [
      {
        "id": 812,
        "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
        "cliente_id": 1024,
        "usuario_id": 42,
        "path_file": null,
        "status": "EXECUTANDO",
        "data_inicio": "2026-07-08T09:15:00-03:00",
        "data_fim": null,
        "mensagem_erro": null,
        "automation_type": "certidao_trabalhista",
        "queue": "certidao",
        "priority": 0,
        "retry_count": 0,
        "progress": 45,
        "metadata_json": null,
        "display_name": "Certidão Trabalhista (CNDT)",
        "client_name": "Comércio de Alimentos Ltda"
      }
    ],
    "total": 137,
    "page": 1,
    "per_page": 20,
    "pages": 7
  }
}

Escopo: worker_automation:read

GET /worker-automation/stats

Dashboard de estatísticas agregadas - total geral e contagens por status e por fila. Ideal para alimentar contadores e gráficos do gerenciador.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Estatisticas recuperadas com sucesso",
  "data": {
    "total": 1342,
    "by_status": {
      "AGENDADO": 18,
      "EXECUTANDO": 5,
      "CONCLUIDO": 1290,
      "FALHA": 22,
      "CANCELADO": 7
    },
    "by_queue": {
      "certidao": 640,
      "scraping": 512,
      "scan": 130,
      "observer": 40,
      "ui_automation": 20
    }
  }
}

Escopo: worker_automation:read

GET /worker-automation/active

Lista os workers atualmente com status EXECUTANDO, já enriquecidos com client_name e display_name. Retorna a lista completa, sem paginação.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Workers ativos recuperados com sucesso",
  "data": [
    {
      "id": 812,
      "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
      "cliente_id": 1024,
      "usuario_id": 42,
      "status": "EXECUTANDO",
      "data_inicio": "2026-07-08T09:15:00-03:00",
      "data_fim": null,
      "automation_type": "certidao_trabalhista",
      "queue": "certidao",
      "priority": 0,
      "progress": 45,
      "display_name": "Certidão Trabalhista (CNDT)",
      "client_name": "Comércio de Alimentos Ltda"
    }
  ]
}

Escopo: worker_automation:read

GET /worker-automation/queued

Lista os workers com status AGENDADO, ordenados por prioridade e paginados. A paginação segue o contrato items + total + page + per_page + pages.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Workers na fila recuperados com sucesso",
  "data": {
    "items": [
      {
        "id": 845,
        "task_id": null,
        "cliente_id": 1099,
        "usuario_id": 42,
        "status": "AGENDADO",
        "automation_type": "simples_nacional",
        "queue": "scraping",
        "priority": 0,
        "progress": 0,
        "display_name": "Simples Nacional",
        "client_name": "Transportadora Horizonte ME"
      }
    ],
    "total": 18,
    "page": 1,
    "per_page": 10,
    "pages": 2
  }
}

Escopo: worker_automation:read

GET /worker-automation/search-automations

Busca inteligente de automações no AUTOMATION_REGISTRY com fuzzy matching (RapidFuzz). Sem q, retorna todas as automações agrupadas por categoria e em lista plana. Com q, retorna apenas os resultados com score ≥ 60, ordenados do mais relevante para o menos.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "2 automacao(oes) encontrada(s)",
  "data": {
    "results": [
      {
        "key": "certidao_trabalhista",
        "display_name": "Certidão Trabalhista (CNDT)",
        "category": "Certidões",
        "queue": "certidao",
        "requires_selenium": true,
        "score": 100
      }
    ]
  }
}

Escopo: worker_automation:read

GET /worker-automation/queue-live-status

Estado em tempo real de cada fila configurada, com as tasks ativas e pendentes enriquecidas, além de contagens de carga (load_percent) e um summary com os totais do dia.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Status das filas recuperado com sucesso",
  "data": {
    "queues": [
      {
        "queue_name": "certidao",
        "workers_count": 2,
        "active_tasks": [],
        "pending_tasks": [],
        "active_count": 1,
        "pending_count": 4,
        "capacity": 2,
        "load_percent": 50.0
      }
    ],
    "summary": {
      "total_active": 5,
      "total_pending": 18,
      "total_completed_today": 87,
      "total_errors_today": 3
    }
  }
}

Escopo: worker_automation:read

GET /worker-automation/broker-status

Snapshot real do broker Celery/Redis - tamanho LLEN de cada fila e resultado do inspect do Celery. Alimenta os indicadores de saúde do broker no gerenciador.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Snapshot do broker recuperado com sucesso",
  "data": {
    "available": true,
    "queues": {
      "certidao": 4,
      "scraping": 2,
      "scan": 0,
      "observer": 0,
      "ui_automation": 0
    }
  }
}

Escopo: worker_automation:read

GET /worker-automation/workers-inspect

Retorna o inspect cru do Celery (active, reserved, scheduled, stats, ping) com timeout de 3 segundos. Útil para diagnóstico direto dos processos worker. Quando o broker não responde, available vem false e as seções vêm vazias.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Inspect recuperado com sucesso",
  "data": {
    "active": {},
    "reserved": {},
    "scheduled": {},
    "stats": {},
    "ping": {
      "celery@certidao-1": { "ok": "pong" }
    },
    "available": true
  }
}

Escopo: worker_automation:read

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.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

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

Em estados não terminais (PENDING, STARTED, RETRY), result vem como null.

Escopo: worker_automation:read

GET /worker-automation/dashboard

Dashboard agregado - substitui 5 chamadas de polling do frontend (stats, queue-live-status, broker-status, active, queued) por uma única requisição. 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.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Dashboard recuperado com sucesso",
  "data": {
    "stats": {
      "total": 1342,
      "by_status": { "AGENDADO": 18, "EXECUTANDO": 5, "CONCLUIDO": 1290 },
      "by_queue": { "certidao": 640, "scraping": 512 }
    },
    "queues": [
      {
        "queue_name": "certidao",
        "workers_count": 2,
        "active_count": 1,
        "pending_count": 4,
        "capacity": 2,
        "load_percent": 50.0
      }
    ],
    "summary": {
      "total_active": 5,
      "total_pending": 18,
      "total_completed_today": 87,
      "total_errors_today": 3
    },
    "broker": { "available": true, "queues": { "certidao": 4 } },
    "active": [],
    "queued": { "items": [], "total": 18, "page": 1, "per_page": 10, "pages": 2 },
    "history": []
  }
}

O payload contém as seções: stats (contagens agregadas), queues (estado por fila), summary (totais do dia), broker (snapshot Redis/Celery), active (workers EXECUTANDO, cap de 50), queued (primeira página de AGENDADO, 10 itens) e history (últimos 20 workers em estado terminal CONCLUIDO, FALHA, CANCELADO).

Escopo: worker_automation:read

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. Quando não encontrado, retorna erro com a mensagem "Worker nao encontrado.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Worker encontrado com sucesso",
  "data": {
    "id": 812,
    "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
    "cliente_id": 1024,
    "usuario_id": 42,
    "path_file": null,
    "status": "EXECUTANDO",
    "data_inicio": "2026-07-08T09:15:00-03:00",
    "data_fim": null,
    "mensagem_erro": null,
    "automation_type": "certidao_trabalhista",
    "queue": "certidao",
    "priority": 0,
    "retry_count": 0,
    "progress": 45,
    "metadata_json": null,
    "display_name": "Certidão Trabalhista (CNDT)",
    "client_name": "Comércio de Alimentos Ltda"
  }
}

Escopo: worker_automation:read

POST /worker-automation/{worker_id}/cancel

Cancela a task via celery_app.control.revoke (com terminate=True) e atualiza o status no banco para CANCELADO. Operação do dia a dia - não exige perfil de gestão, apenas o escopo worker_automation:write.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Task cancelada com sucesso",
  "data": {
    "id": 812,
    "task_id": "a3f8c1e2-9b4d-4e7a-8c1f-2d5b6a8e9f0c",
    "cliente_id": 1024,
    "usuario_id": 42,
    "status": "CANCELADO",
    "data_inicio": "2026-07-08T09:15:00-03:00",
    "data_fim": "2026-07-08T09:31:00-03:00",
    "automation_type": "certidao_trabalhista",
    "queue": "certidao",
    "priority": 0,
    "retry_count": 0,
    "progress": 45
  }
}

Escopo: worker_automation:write

POST /worker-automation/{worker_id}/retry

Re-enfileira um worker em estado FALHA ou CANCELADO. Resolve o nome real da task via AUTOMATION_REGISTRY, cria uma nova task Celery e devolve o worker atualizado com status AGENDADO e retry_count incrementado. Operação do dia a dia - não exige perfil de gestão, apenas o escopo worker_automation:write.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Task re-enfileirada com sucesso",
  "data": {
    "id": 812,
    "task_id": "b7e2d4a1-3c8f-4a6b-9d0e-1f2a3b4c5d6e",
    "cliente_id": 1024,
    "usuario_id": 42,
    "status": "AGENDADO",
    "data_inicio": null,
    "data_fim": null,
    "mensagem_erro": null,
    "automation_type": "certidao_trabalhista",
    "queue": "certidao",
    "priority": 0,
    "retry_count": 1,
    "progress": 0
  }
}

Escopo: worker_automation:write

POST /worker-automation/{worker_id}/move

Migra o worker para outra fila Celery, revogando a task antiga e reagendando-a na fila de destino. Útil para realocar carga manualmente. O target_queue é validado contra as filas conhecidas. Operação do dia a dia - não exige perfil de gestão, apenas o escopo worker_automation:write.

Parâmetros

O corpo segue o schema WorkerMoveQueue: target_queue (obrigatório).

Request

{
  "target_queue": "scraping"
}

Response 200 OK

{
  "status": "success",
  "message": "Worker migrado de fila com sucesso",
  "data": {
    "id": 812,
    "task_id": "c9f3e5b2-4d7a-4b8c-a1e2-3f4b5c6d7e8f",
    "cliente_id": 1024,
    "usuario_id": 42,
    "status": "AGENDADO",
    "automation_type": "certidao_trabalhista",
    "queue": "scraping",
    "priority": 0,
    "retry_count": 0,
    "progress": 0
  }
}

Escopo: worker_automation:write

POST /worker-automation/{worker_id}/reorder

Altera a prioridade de execução do worker. Quanto menor o número, mais cedo é processado. Operação do dia a dia - não exige perfil de gestão, apenas o escopo worker_automation:write.

Parâmetros

O corpo segue o schema WorkerReorder: new_priority (obrigatório).

Request

{
  "new_priority": 1
}

Response 200 OK

{
  "status": "success",
  "message": "Prioridade alterada com sucesso",
  "data": {
    "id": 845,
    "task_id": null,
    "cliente_id": 1099,
    "usuario_id": 42,
    "status": "AGENDADO",
    "automation_type": "simples_nacional",
    "queue": "scraping",
    "priority": 1,
    "retry_count": 0,
    "progress": 0
  }
}

Escopo: worker_automation:write

POST /worker-automation/clear-queue

Operação destrutiva. Cancela em massa os workers conforme o parâmetro scope. Cada worker é marcado como CANCELADO e tem sua task revogada no broker (com terminate=True para os que estão em execução). Exige perfil administrador ou diretoria (require_perfil), além do escopo.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "18 worker(s) cancelado(s) com sucesso",
  "data": {
    "cancelled": 18,
    "scope": "all"
  }
}

Escopo: worker_automation:write

POST /worker-automation/broker/purge-queue/{queue_name}

Operação destrutiva. Apaga fisicamente a fila no broker via Redis DEL, descartando todas as mensagens enfileiradas. Tasks já entregues a workers continuam executando. Exige ?confirm=true e perfil administrador ou diretoria (require_perfil).

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Fila 'scraping' purgada no broker",
  "data": {
    "queue_name": "scraping",
    "redis_keys_deleted": 2
  }
}

Escopo: worker_automation:write

DELETE /worker-automation/cleanup-no-client

Operação destrutiva. Remove do banco todos os workers AGENDADO/EXECUTANDO cujo cliente_id é nulo ou não existe na tabela de clientes, revogando a task no Celery antes de excluir. Exige perfil administrador ou diretoria (require_perfil).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "3 worker(s) sem cliente removido(s) do banco",
  "data": {
    "deleted": 3
  }
}

Escopo: worker_automation:write

POST /worker-automation/sync-orphans

Detecta workers AGENDADO/EXECUTANDO que perderam a task no Redis (sem task_id, ou antigos há mais de 2h e ainda PENDING) e os marca como CANCELADO. Útil após reiniciar o Redis. Exige perfil administrador ou diretoria (require_perfil).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "2 worker(s) orfao(s) detectado(s) e cancelado(s)",
  "data": {
    "orphans_found": 2,
    "total_checked": 23
  }
}

Escopo: worker_automation:write

Schemas

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