Metodologia e interpretação

Atualização Node — 24/10/2026: as referências históricas ao agente Python abaixo não autorizam sua execução neste projeto. A implementação Node preserva conceitos e adiciona fila segregada e checkpoints. Novos vínculos Transferegov exigem emenda CGU do mesmo ano, código/denominação oficial exatos e official_identifiers numérico inequívoco; não se associa um perfil por nome civil. O arquivo anual CEAP prevalece sobre a resposta individual da API no mesmo perfil/ano, mantendo a observação alternativa separada. Recoletar conteúdo idêntico atualiza o instante da observação sem criar nova versão. Sucesso de testes não certifica cobertura em produção.

1. Identidade: vínculos são feitos pelo identificador oficial de cada fonte, não por comparação aproximada de nomes. Bens declarados do TSE apontam para candidate_records por SQ_CANDIDATO e ano eleitoral; se houver registros em mais de um turno, o turno inicial é usado como referência canônica. Registros de bens sem candidatura correspondente permanecem salvos sem vínculo. A associação posterior ao perfil do político depende de candidate_politician_links. official_identifiers mantém o vínculo de cada identificador à ficha local. A migration incremental 0002_person_identity_crosswalks oferece tabelas para agrupar fichas somente após revisão com evidência oficial; não insere vínculos automaticamente. Correspondências name_exact ou aproximadas não bastam para fundir perfis. Até que os vínculos oficiais sejam revisados e cadastrados, fichas distintas continuam separadas.
2. Mandato e exercício: uma legislatura com registro não comprova atuação durante quatro anos inteiros. A Câmara fornece estados cadastrais com data/hora; o aplicativo usa o último estado de cada dia para intervalos de exercício. Limita cada intervalo pela próxima alteração, pelo fim da legislatura e pela data da coleta. Filiações são reconstruídas por mudança de partido, com resolução diária. Ausência de um registro anterior não permite concluir quando ocorreu uma filiação antes do primeiro estado recebido. O Senado fornece datas de filiação, mandato e exercício explicitamente.
3. Média mensal: dias cobertos por intervalos de exercício são unidos, sem contar sobreposições duas vezes, e divididos por 365,2425 / 12. A média monetária divide a despesa registrada pelos meses equivalentes. Não é simplesmente dividir por 12 e não é uma medida de eficiência. Intervalos inferidos da Câmara são identificados no perfil. Se não houver intervalo de exercício, a média é indisponível.
4. Despesas: Câmara usa valorLiquido na CEAP; Senado usa valorReembolsado na CEAPS. Valores são armazenados como NUMERIC, e os gráficos recebem as agregações. Ajustes negativos são mantidos. Despesas parlamentares, emendas e contas de campanha são grandezas distintas. Não há gráfico de contas de campanha nesta versão.
5. Rankings: exigem cargo selecionado e o mesmo ano. Despesa/média mensal só ordenam fichas que tenham coleta completa do conjunto anual solicitado. Isso é um ranking dos políticos com dados coletados, não uma declaração sobre todos os representantes brasileiros. O ano corrente pode estar em andamento e a fonte pode publicar com atraso. Proposições e votos podem apresentar conjuntos parciais; as contagens são de registros coletados e não de qualidade ou produtividade.
6. Proposições: autores são identificados por URI na Câmara; primeiro signatário é exibido como autor principal, demais como coautores/signatários. O Senado, na consulta atual usada, não certifica ordem de assinatura e mostra essa limitação. Situação é a mais recente coletada. Não se presume que proposição aprovada seja lei sancionada. Requerimentos e outros tipos podem ter naturezas distintas; use o filtro de tipo.
7. Votos: são votos registrados em votações nominais. Contagem de votos não é frequência parlamentar; ausência de voto não comprova falta. O Senado pode devolver participação em votação secreta, que é rotulada sem inventar um voto Sim/Não. Votos secretos não revelam posicionamento.
8. Emendas: indicação, autorização, empenho, liquidação e pagamento são etapas diferentes. A CGU fornece valores agregados de execução por emenda/autor, sem beneficiário final garantido; o código do autor é obrigatório para vínculo ao perfil. O resumo mostra empenhado, liquidado e pago da CGU como totais separados. O Transferegov cobre apenas transferências especiais e preserva planos, empenhos, documentos, ordens e relatórios em conjuntos separados, ligados pelos IDs oficiais. A interface apresenta empenhos e valores de pagamento informados nos documentos de liquidação em bloco separado, por político e ano; não os soma aos totais CGU. Valores de relatório de gestão representam execução declarada pelo ente e não são necessariamente pagamentos da União. Dados sem vínculo confiável permanecem preservados sem associação. Não se usa nome aproximado para atribuir valores. Para planos de Transferências Especiais, o agente valida o código de autor no mesmo ano e o nome oficial entre Transferegov e CGU; associa a um perfil somente com nome civil exato e correspondência única, preservando a evidência e os registros sem vínculo para revisão futura. A consulta individual do SIOP por autor depende de credenciais autorizadas; sem elas, indicação e autorização ficam indisponíveis.
9. Ausente e zero: ausência de cobertura e de registros vira null / “Não disponível”. Um período recebido por completo, mas sem registros, pode mostrar zero. Isso representa a resposta da fonte para o conjunto solicitado, não prova ausência de toda atividade política.
10. Versões e coleta: versões diferentes preservam conteúdo original em JSON com hash e data de captura. Reexecução bem-sucedida de conteúdo idêntico mantém o registro e o payload originais, sem criar nova versão, e atualiza captured_at e a URL da fonte. captured_at indica a última observação válida daquele conteúdo, não a primeira vez em que foi coletado nem a data do acontecimento; falhas não renovam esse instante. Cada conjunto é salvo em transação após receber todas as suas páginas. Uma falha posterior em outro conjunto não desfaz o conjunto anterior já concluído; consulte a cobertura individual.
11. Importações: são incrementais e parciais. Invalidam a marca de coleta completa daquele conjunto/ano para evitar que uma alteração manual entre indevidamente nos rankings completos. A coleta oficial seguinte pode substituir o conjunto anual importado, preservando seu conteúdo no histórico. Confira a granularidade e os identificadores antes da importação.
12. Filiações históricas: o filtro por data usa os intervalos conhecidos. Lacunas retornam nenhum vínculo, sem preencher datas por estimativa. A foto e os demais dados de identificação continuam sendo os do último cadastro; isso não pretende reconstruir a aparência do político no ano escolhido.
13. Comparação em todos os anos: agrega despesas, proposições, votos e emendas por ficha de político, considerando somente os anos-calendário que intersectam intervalos registrados com effective=true. Anos sobrepostos são contados uma única vez. Cada ficha usa os próprios anos de exercício; perfis da Câmara e do Senado não são fundidos automaticamente. Os totais incluem os registros coletados e a interface informa, por indicador, em quantos anos há cobertura oficial. Cobertura parcial não é apresentada como total completo; o ano corrente pode estar incompleto.
14. Deputados estaduais no dashboard local: a aba administrativa do piloto PR/SC separa candidaturas e bens eleitorais do TSE da atividade parlamentar das assembleias. Os cartões ALEP/ALESC contam somente registros estaduais gravados em official_data_records e sua cobertura registrada; candidaturas e bens não significam mandato ou atividade legislativa. Registros sem vínculo permanecem disponíveis e são contados sem atribuição. O site público não apresenta essa aba nem esses dados nesta fase. A integração estadual não deve ser considerada completa até validar paginação, período, chaves oficiais e reimportação idempotente de cada fonte.
15. Apuração eleitoral por turno: votos, seções totalizadas e liderança vêm dos arquivos oficiais do TSE. O 1º turno e o 2º turno de 2026 têm códigos de eleição próprios e ficam em resultados_apuracao_primeiro_turno e resultados_apuracao_segundo_turno, respectivamente; a API escolhe a tabela pelo parâmetro turno e não combina snapshots entre elas. No 2º turno estão implementados Presidente (6258) e Governador (6260). O modo por região soma somente as UFs disponíveis naquela eleição e mostra quantas foram publicadas; uma região incompleta não é tratada como cobertura total. Os polígonos vêm da malha oficial do IBGE, consultada para visualização, sem persistência nem participação no cálculo dos votos. No mapa do 2º turno, selecionar uma UF abre o modal estadual. O código eleitoral municipal do TSE é associado ao limite geográfico pelo código IBGE presente no arquivo de configuração municipal (cdi/cdmi), nunca por comparação de nomes. Selecionar uma cidade consulta apenas o arquivo daquela cidade; não há varredura nem dezenas/centenas de chamadas em paralelo para colorir o mapa. Assim, os municípios permanecem neutros até a tela mostrar o resultado municipal selecionado. A origem configurável em dashboard_preferences.election_apuration_first_turn vale para o 1º turno: database lê snapshots locais, tse consulta arquivos oficiais e both serve snapshots locais e tenta atualizá-los após duas horas. O 2º turno sincroniza os arquivos do TSE com a tabela própria e reconsulta quando o snapshot passa de 30 segundos. Se a consulta TSE falhar ou retornar conteúdo inválido, o último snapshot válido é preservado e indicado como desatualizado, inclusive na capital e no mapa. Localidade sem arquivo permanece indisponível/aguardando publicação, não zero. A leitura local ordena candidaturas por votos, nunca por identificador, e pode aproveitar o snapshot estadual do mapa somente para a mesma eleição, cargo e UF. Uma resposta vazia contraditória não substitui candidaturas anteriormente publicadas.
16. Biografias: são sínteses determinísticas de fatos declarados pela Casa, sem geração por modelo ou busca por nome. Cadastro detalhado e complementos estruturados do mesmo ID têm precedência; a página oficial acrescenta campos explícitos. Profissões, formação e trajetória podem ter cobertura incompleta. Falhas mantêm a última biografia válida, com data de origem preservada e estado da tentativa separado. Uma biografia disponível não certifica que todos os fatos da pessoa tenham sido coletados. Consulte Produtores auxiliares.
17. Sessões ativas no site: o contador estima sessões efêmeras com heartbeat nos últimos 180 segundos, não pessoas nem presença parlamentar. Instâncias da API deduplicam o mesmo token por HMAC temporário; somente a contagem por intervalo UTC de 30 segundos entra no histórico. Falha de medição não vira zero e o navegador deixa de exibir o valor antigo como atual. Retenção e limites estão em Privacidade e segurança.
18. Candidaturas por esfera e trajetória eleitoral: a interface consulta em modo somente leitura as linhas TSE já existentes em candidate_records, agrupadas como presidencial, federal, estadual ou municipal. Essa consulta não muda os agentes, não cria gravações nem amplia a cobertura armazenada; filtros e totais refletem apenas os ciclos presentes no banco. Candidatura, situação eleitoral e resultado não comprovam posse ou exercício efetivo. O clique abre o perfil consolidado quando a candidatura tem vínculo official_review; os demais vínculos, inclusive os baseados apenas em nome, não são promovidos automaticamente. No perfil, candidaturas de cargos diferentes são concatenadas apenas por um vínculo explícito revisado em candidate_politician_links e fichas institucionais distintas só são agrupadas pela tabela de identidade após revisão com evidência oficial. Fotos de candidaturas usam, quando publicadas, a URL pública oficial de resultados do TSE; não são baixadas nem persistidas pelos agentes. A foto da ficha parlamentar aparece como alternativa. Mandatos confirmados por fonte legislativa permanecem identificados separadamente das candidaturas TSE.
19. Presidentes, perfis e comparação do CPGF: /presidentes/:slug abre um perfil interno com retrato e link à biografia oficial do Arquivo Nacional; não cria vínculo com ficha parlamentar por nome. /presidentes/comparar compara até quatro ocupantes individuais usando somente períodos com valor publicado e atribuível individualmente. A fonte de 2003–2018 publica Dilma Rousseff e Michel Temer em um total conjunto para 2015–2018; esse registro aparece separado, sem rateio nem soma aos totais individuais. O total 2019–2022 é apresentado como total do período citado pelo TCU. Os CSVs anuais da Casa Civil cobrem 2023 em diante e são consultados sob demanda pela API, com cache temporário em memória; os workers não leem nem persistem essa nova categoria. Um CSV do ano corrente pode cobrir somente parte dos meses, e arquivos consolidados podem sofrer ajustes. A comparação mostra períodos lado a lado sem normalizar inflação ou duração e não classifica desempenho. CPGF é despesa institucional, não gasto pessoal nem prova de uso pessoal pelo presidente. Antes de 2003 ou em períodos sem publicação, o valor é “não disponível”, nunca zero inferido. O índice biográfico pode incluir juntas e pessoas eleitas que não assumiram; presença no acervo não comprova exercício individual do cargo.