PAV-127 — [Front Admin] Implementar dashboard Scraper Health e métricas de classificação

[hltav]

Linear
PAV-127 — [Front Admin] Implementar dashboard Scraper Health e métricas de classificação

Objetivo
Implementar no Front Admin uma visão operacional completa do Jobs Processor, consumindo os contratos de observabilidade existentes e expondo de forma clara o estado de execução, saúde dos serviços, progresso do pipeline, providers, catálogo e métricas de classificação.

A entrega também consolida ajustes necessários no backend e no Jobs Processor para suportar os dados consumidos pelo painel administrativo e reorganiza os arquivos Docker Compose utilizados no ambiente local.

Resumo das alterações
A PAV-127 transforma o Front Admin em uma interface operacional para acompanhamento do Jobs Processor.

A implementação adiciona e refina:

visão geral de saúde da plataforma;
estado atual do Jobs Processor;
execução atual e run_id;
origem e estágio da execução;
lock distribuído;
concorrência global e por provider;
progresso do pipeline;
métricas de coleta;
métricas de classificação;
métricas de persistência;
métricas de indexação;
catálogo de vagas persistidas;
resumo operacional de providers;
polling compartilhado e cancelável;
tratamento de dados parciais, indisponíveis e stale;
distinção entre valor 0 e dado indisponível;
melhorias de UX na tela de Observabilidade;
melhorias de UX na tela de Processamento de Vagas;
integração entre Front Admin, backend e Jobs Processor.
Front Admin
Observabilidade
A tela de Observabilidade foi reorganizada para priorizar o estado operacional atual.

Foram adicionadas ou refinadas as seções de:

Saúde geral;
Execução atual do Processor;
Pipeline;
Infraestrutura;
métricas operacionais;
histórico.
A visão de saúde apresenta de forma compacta o estado de:

API;
PostgreSQL;
Valkey;
Jobs Processor;
taxa de erro HTTP;
latência HTTP p95.
A execução atual apresenta informações como:

run_id;
estágio;
duração;
lock;
concorrência;
progresso da execução.
O pipeline passou a representar de forma explícita:

Coleta;
Classificação;
Persistência;
Indexação.
Também foi implementado tratamento visual consistente para:

dados indisponíveis;
dados parciais;
snapshots stale;
valor zero válido.
Polling operacional
Foi criada uma camada compartilhada de polling para evitar múltiplas consultas concorrentes ao mesmo recurso.

O polling:

compartilha o snapshot entre consumidores;
permite cancelamento;
controla atualização periódica;
trata falhas de API;
evita duplicação de requisições entre telas.
Processamento de Vagas
A antiga visão de Scrapers foi refinada para representar melhor o domínio operacional.

Na interface:

o menu passou a utilizar o nome Processamento;
a página utiliza o título Processamento de Vagas;
referências internas de rota e código continuam compatíveis com scrapers.
A tela passou a apresentar informações operacionais dos providers de forma estruturada.

A tabela da execução exibe:

provider;
tarefas;
vagas coletadas;
falhas;
tarefas ativas ou em espera;
último resultado;
detalhes expansíveis.
Catálogo
Os cards de catálogo passaram a utilizar os totais reais persistidos no PostgreSQL.

O PostgreSQL é tratado como fonte de verdade do catálogo.

O Valkey permanece como camada de índice/cache e não é utilizado como fonte de verdade para a quantidade total de vagas persistidas.

Combinações equivalentes de fontes/providers são normalizadas de forma determinística.

Exemplos equivalentes:

Adzuna,Gupy;
Gupy,Adzuna;
Adzuna,Gupy,Adzuna.
Essas combinações passam a representar um único agrupamento lógico, com contagem agregada.

Backend
Foram realizados ajustes no contrato administrativo utilizado pelo Front Admin.

As alterações incluem:

extensão dos tipos de observabilidade;
ajustes no cliente do Jobs Processor;
suporte aos dados utilizados pelo snapshot operacional;
suporte às contagens utilizadas pelo catálogo;
testes adicionais dos contratos administrativos.
Jobs Processor
O Jobs Processor foi ajustado para fornecer dados adicionais necessários ao Front Admin.

Foram incluídos ou refinados:

snapshot da execução atual;
métricas associadas ao run_id;
estado do pipeline;
contagem de vagas por origem;
informações utilizadas pelo catálogo;
dados operacionais de providers;
testes do snapshot;
testes das contagens por origem.
A implementação mantém o snapshot operacional em memória.

Consequentemente, o snapshot representa a execução observada pela instância atual e pode ser reiniciado junto com o processo.

As métricas operacionais representam eventos observados durante o processamento e não devem ser interpretadas automaticamente como contagem de entidades únicas.

Docker / ambiente local
A organização dos arquivos Docker Compose foi consolidada.

Os arquivos específicos foram movidos para:

docker/docker-compose.app.yml;
docker/docker-compose.infra.yml;
docker/docker-compose.migrate.yml;
docker/docker-compose.observability.yml.
Também foi adicionado:

docker-full.docker-compose.yml.
O docker-compose.yml principal foi ajustado para acompanhar essa organização.

Essa alteração reduz a dispersão dos arquivos de ambiente e deixa mais explícita a separação entre aplicação, infraestrutura, migração e observabilidade.

Compatibilidade
A implementação preserva:

rotas administrativas existentes;
nomenclaturas internas necessárias para compatibilidade;
contratos já entregues pelas PAVs anteriores;
funcionamento do Jobs Processor;
PostgreSQL como fonte de verdade do catálogo;
Valkey como índice/cache.
A mudança de nomenclatura de Scrapers para Processamento é apenas de interface.

Não houve renomeação estrutural de rotas ou módulos internos nesta entrega.

Testes
A suíte do Front Admin foi executada com cobertura.

Resultado:

47 arquivos de teste aprovados;
212 testes aprovados;
cobertura global de statements: 95,72%;
cobertura global de branches: 87,81%;
cobertura global de functions: 96,29%;
cobertura global de lines: 98,29%.
Entre os componentes principais:

ObservabilityPage.tsx: 100% de statements, functions e lines;
OperationalSnapshotPanels.tsx: 100% de statements, functions e lines;
ScrapersPage.tsx: 100% de statements, functions e lines.
Também foram validados anteriormente os contratos e testes relacionados no backend e no Jobs Processor.

Foi executado:

git diff --check.
Não foram encontrados erros de whitespace no diff preparado para commit.

Arquivos principais
Front Admin
front_admin/src/modules/observability/**
front_admin/src/modules/scrapers/**
front_admin/src/modules/dashboard/**
front_admin/src/lib/polling/**
front_admin/src/lib/api/**
testes correspondentes em front_admin/tests/**
Backend
backend/src/modules/admin/observability/**
backend/src/modules/admin/scrapers/**
testes administrativos relacionados
Jobs Processor
scraper-go/cmd/server/**
scraper-go/internal/catalog/**
scraper-go/internal/jobstore/**
scraper-go/internal/metrics/**
scraper-go/internal/pipeline/**
Docker
docker-compose.yml
docker-full.docker-compose.yml
docker/docker-compose.app.yml
docker/docker-compose.infra.yml
docker/docker-compose.migrate.yml
docker/docker-compose.observability.yml
Fora do escopo
Esta entrega não inclui:

renomeação estrutural de scraper-go;
renomeação das rotas internas /admin/scrapers;
persistência histórica do snapshot operacional;
transformação do snapshot em armazenamento permanente;
utilização do Valkey como fonte de verdade do catálogo.
Riscos
O snapshot operacional do Jobs Processor é mantido em memória.

Em caso de reinicialização da instância, o estado da execução anteriormente observada não permanece disponível no snapshot atual.

Algumas métricas representam eventos acumulados do processamento e não necessariamente entidades únicas.

Essas características são refletidas na apresentação do Front Admin para evitar interpretação incorreta dos dados.

Rollback
O rollback pode ser realizado revertendo o commit desta PR.

Não existem migrações destrutivas de banco de dados associadas a esta entrega.

Checklist
Dashboard operacional integrado
Saúde geral dos serviços
Estado atual do Jobs Processor
run_id exibido
Estágio da execução exibido
Lock distribuído representado
Concorrência representada
Pipeline de coleta
Pipeline de classificação
Pipeline de persistência
Pipeline de indexação
Métricas de classificação
Polling compartilhado
Tratamento de estado stale
Tratamento de dados parciais
Distinção entre 0 e indisponível
Tela de Processamento de Vagas refinada
Providers da execução estruturados
Catálogo baseado em PostgreSQL
Combinações de providers normalizadas
Backend administrativo atualizado
Snapshot do Processor atualizado
Contagens por origem implementadas
Testes do Front Admin
212 testes aprovados
Cobertura acima de 80%
Docker Compose reorganizado
git diff --check