Wiki do fluxo de extração de dados

1. Visão geral do pipeline

O Atlas BR coleta dados de APIs e portais oficiais do governo brasileiro. Existem dois sistemas de coleta que compartilham o mesmo registro de execução (tabelas atlas_collection_runs e atlas_collection_steps):

• Hermes (indicadores por ente) — quatro coletores de KPI por UF/município: ibge, siconfi, obrasgov e pncp. Escrevem em atlas_observations, sempre com proveniência completa por linha.
• Adapters de evidência (nível de registro) — sete coletores linha-a-linha (sanções CEIS/CNEP, contratos PNCP, licitações TCE-RS, despesas TCE-SP, acórdãos TCU, transferências TransfereGov, normas LexML). Cada registro bruto vira snapshot com hash SHA-256, evidência canônica em atlas_evidences e projeção de domínio (contratos, sanções, despesas, obras, transferências).

Sobre as evidências roda um motor de regras com 7 regras versionadas em atlas_rules (ex.: limite de despesa de pessoal da LRF, sanção vigente em contrato, concentração de fornecedores), que produz comparações auditáveis em atlas_comparison_runs. Tudo é servido pela API pública: GET /api/public/atlas/:codigoIbge, GET /api/public/atlas/evidencia/:ref e GET /api/public/atlas/comparacao/:uid.

2. Diagrama do fluxo

agendamento                 coleta                       evidência
-----------                 ------                       ---------
CLI manual ───────────► hermes/orchestrator ──► atlas_observations
(cli/collect.ts)        (ente x hermes,           (proveniência por linha)
                         runlog em
atlas_jobs ──────────►  atlas_collection_runs
(fila; worker PM2        + collection_steps)
 tdibr-atlas-worker,
 tick 15 s)             adapters/run.ts ───────► atlas_snapshots (bytes + sha256)
                         (pace por rpm)           └► atlas_evidences (canônico,
                                                      content_hash, versao, URN)
                                                  └► projeções: atlas_contratos,
                                                      atlas_sancoes, atlas_despesas,
                                                      atlas_obras, atlas_transferencias
                                                  └► atlas_entities (+aliases,
                                                      +relations)
                             regras                       publicação
                             ------                       ----------
                        comparison/engine.ts ──► atlas_comparison_runs
                         (atlas_rules, 7 regras)   (estado, manifesto, hash)
                                                       │
                                                       ▼
                                             GET /api/public/atlas/...
                                             relatórios (atlas_reports)

3. Inventário de fontes

Status conforme atlas_sources.status_operacional e ultima_coleta_ok em 2026-07-05.

Coletores Hermes (indicadores)

Adapters de evidência

Backlog: a tabela atlas_source_candidates guarda 36 fontes candidatas qualificadas e 1 bloqueada, semeadas por atlas_source_backlog.sql. Nenhuma candidata foi promovida a fonte integrada até hoje.

4. Ciclo de vida de uma coleta

1. Disparo. Manual via CLI (cli/collect.ts) ou por job na fila atlas_jobs, consumida pelo worker (tick de 15 s, claim atômico, backoff exponencial com máximo de 3 tentativas).
2. Run. Cada execução abre um registro em atlas_collection_runs (status running); cada par ente × coletor gera um passo em atlas_collection_steps (ok, skip ou error, com contagem de gravados, latência e mensagem de erro); o fechamento marca done ou error.
3. Evidência. Registro coletado vira snapshot dos bytes exatos + SHA-256, é canonicalizado de forma determinística e gravado em atlas_evidences com content_hash, versão e URN estável; depois vem a projeção de domínio e a resolução de entidades.
4. Regra. O motor aplica regras versionadas (parâmetros, estados possíveis e base legal) e grava atlas_comparison_runs com estado categórico (ex.: DENTRO_DA_REFERENCIA, EVIDENCIA_INSUFICIENTE, REVISAO_HUMANA_NECESSARIA), trilha de cálculo, uids de evidência e manifesto com hash.
5. Achado e relatório. Comparações e evidências são resolvidas pela API pública e pelos relatórios (atlas_reports).

Números reais em 2026-07-05: 45 runs concluídos, 7 presos em running, 1 em erro; 56.000 evidências; 5.942 observações; 43 comparison runs; fila de jobs vazia.

5. Proveniência e auditabilidade

• Observação: cada linha de atlas_observations carrega fonte_nome, fonte_url, metodo_coleta, hash_raw (SHA-256 do payload bruto, também persistido), confianca (alta/media/baixa; valores derivados entram como media com nota metodológica) e ano_base.
• Evidência: snapshots guardam os bytes exatos de cada recoleta; o payload canônico tem chaves ordenadas e content_hash = SHA256(payload_canonico) — qualquer pessoa pode recomputar o hash a partir do payload publicado.
• URN: urn:atlas:br:<fonte>:<tipo>:<chave>, com a chave vinda do identificador primário da própria fonte, nunca de serial interno. O evidence_uid (ev_...) deriva de URN + versão.
• Comparação: cada cmp_... cita regra (slug, versão, base legal), escopo, resultado bruto, trilha de cálculo, uids de evidência e manifesto com hash — reproduzível byte a byte.
• Regras editoriais fixas: nenhum número fabricado; ausência de dado nunca vira zero; só fontes oficiais; derivação sempre marcada; o portal não julga.

6. Limitações conhecidas

Avaliação honesta do estado em 2026-07-05, verificável no banco e no código:

1. Não há coleta agendada. Nenhum cron de coleta do Atlas está ativo e a fila de jobs está vazia; o worker está online, mas ocioso — toda coleta é invocação manual. Consequência: das 5.942 observações, 5.627 têm ano-base 2025 e apenas 112 são de 2026.
2. Runs órfãos sem watchdog. 7 execuções presas em running (a mais antiga de 2026-06-29). Se o processo morre no meio, nada varre nem fecha runs órfãos.
3. Retry frágil nos coletores Hermes. O retry é único e cego (sem delay, sem distinguir erro transitório de permanente). Os coletores ibge e siconfi fazem fetch sem timeout, sem User-Agent e sem tratamento de 429 — um request pendurado trava o run inteiro. Apenas pncp (pace de 1200 ms, 5 retries com backoff) e obrasgov (timeout de 90 s) endurecem o fetch.
4. Rate limiting só de intervalo fixo nos adapters. O pace é um intervalo fixo por rpm, sem jitter e sem reação a 429/5xx. Além disso, o run do adapter fecha como done mesmo com erros — coleta parcial com falhas aparece como sucesso no nível do run.
5. Fontes mortas ou nunca limpas, e backlog parado. lexml está bloqueada; tce-sp e tcu nunca completaram uma coleta limpa. Zero das 36 candidatas qualificadas foram promovidas. 23 dos 43 comparison runs terminam em EVIDENCIA_INSUFICIENTE — o motor de regras roda com evidência escassa.