Dashboard MA

public/index.html é gerado (não versionado) — não edite à mão. Edite src/ e rode:

npm install      # uma vez
npm run build    # gera public/index.html (arquivo único, funciona offline)
npm run watch    # rebuild automático ao salvar

src/index.ejs          esqueleto da página
src/partials/          cabeçalho, rodapé, overlays (tooltip, gaveta)
src/views/             uma view por aba (overview, map, cities, compare, analysis, secoes, deputados)
src/styles/main.css    estilos
src/scripts/NN-*.ejs   JS em módulos, concatenados na ordem numérica
data/mapa_ma.json      malha dos municípios (IBGE) já projetada em SVG, chave = código TSE
data/legislativo_*.json resultados de Deputado Federal/Estadual e Senador por município (gerados do TSE)
tools/tse-deputados.js baixa os dados do TSE e gera data/legislativo_*.json
tools/tse-secoes.js    baixa os boletins de urna (BU) do TSE e gera resultados_governador_por_secao.csv
build.js               lê o CSV + mapa e renderiza o EJS

Para ver localmente, abra public/index.html depois do build. No Vercel o build roda sozinho (vercel.json).

Para atualizar os resultados, troque resultados_governador_por_municipio.csv (mesmas colunas) e rode o build.

Legislativo (deputados federal e estadual e senador)

A aba Legislativo usa data/legislativo_{federal,estadual,senador}.json, gerados a partir dos arquivos públicos de resultado do TSE (eleição 6259, 1º turno 2026, cargos 6, 7 e 5). Para atualizar:

npm run dados:legislativo   # baixa do TSE (~650 requisições) e regrava data/legislativo_*.json
npm run build

Zonas e seções

A aba Zonas e seções filtra o resultado de Governador, Senador, Deputado Federal e Deputado Estadual por município, zona e número da seção (com busca de candidato, visão agrupada por zona e exportação CSV). Os dados vêm de resultados_governador_por_secao.csv (uma linha por seção: Braide, Orleans, Felipe Camarão, outros, brancos e nulos), gerado a partir dos boletins de urna públicos do TSE. Para atualizar:

npm run dados:secoes   # baixa ~20 mil BUs (~30 min) e regrava o CSV; confere a soma com o CSV por município
npm run build

O mesmo comando gera data/secoes_{senador,federal,estadual}.json (votos nominais por candidato e seção, formato esparso), copiados para public/data/ e carregados sob demanda — por isso a aba precisa ser aberta por um servidor (Vercel ou npx serve public), não direto pelo arquivo.

Local de votação e detalhes da seção

Clicar numa linha (modo "Por seção") abre a gaveta com local de votação, endereço, bairro, CEP, acessibilidade, eleitores, seções agregadas, comparecimento/abstenção e o resultado da seção. Há também a busca por local ou bairro. Os dados vêm de locais_votacao_por_secao.csv, gerado a partir do arquivo aberto do TSE "Eleitorado por local de votação" (zip de ~170 MB com todas as UFs; só o MA e o 1º turno são mantidos):

npm run dados:locais   # baixa o zip do TSE e regrava locais_votacao_por_secao.csv
npm run build          # gera public/data/locais.json (carregado em segundo plano)

Rode dados:locais sempre depois de dados:secoes: o build exige que os dois CSV tenham as mesmas seções, na mesma ordem.

Presidente

A aba Presidente mostra o resultado de Presidente (1º turno) no Maranhão, comparado ao Brasil, e como cada município votou (mapa por líder ou por candidato, tabela e gaveta com o detalhe). Os dados ficam em data/presidente.json, gerado a partir dos arquivos públicos do TSE (eleição 6257, cargo 1):

npm run dados:presidente   # baixa Brasil, Maranhão e os 217 municípios (~220 requisições)
npm run build

O npm run dados:presidente baixa os dois turnos (o código do 2º turno vem do catálogo do TSE). Enquanto o 2º turno não tem votos apurados, a aba mostra "aguardando"; depois da apuração basta rodar o comando de novo, o build e publicar.

Governador (percentuais do TSE)

resultados_governador_por_municipio.csv traz o resultado completo de Governador, com os percentuais calculados como o TSE divulga: votos do candidato / votos válidos computados (válidos + anulados sub judice), considerando todos os candidatos (Braide, Orleans, Felipe Camarão e demais). As colunas *_%_entre_os_dois (só Braide × Orleans) foram mantidas por compatibilidade, mas o painel usa *_%_validos. Para atualizar:

npm run dados:governador   # baixa os 217 municípios e regrava o CSV (confere a soma com o total do estado)
npm run build

Apuração voto a voto

O gráfico Apuração voto a voto (Visão geral) mostra como o percentual de cada candidato evoluiu conforme as seções chegaram ao TSE (horário de recebimento de cada seção), por estado ou por município. Os horários ficam em data/apuracao.json, na mesma ordem de resultados_governador_por_secao.csv:

npm run dados:apuracao   # ~18 mil requisições pequenas (~15 min); rode depois de dados:secoes
npm run build

Percentuais de deputados e senador

Os percentuais seguem a base do TSE: votos do candidato / votos válidos computados (válidos + anulados sub judice). Nos municípios, vc (em data/legislativo_*.json) guarda essa base; por seção, a base é nominais + legenda (lg em data/secoes_*.json). Cinco números de candidato a Deputado Federal (76 votos no total) aparecem nos boletins de urna mas não no resultado do TSE (registro anulado/indeferido); o TSE não os soma nos válidos. A ferramenta de seções os conta como nulos, para que a base de cada município bata exatamente com os votos válidos computados.

Abstenção

O painel mostra eleitorado apto, comparecimento e abstenção. Os valores oficiais vêm do TSE (arquivos por município e por zona): resultados_governador_por_municipio.csv (colunas eleitores_aptos, comparecimento, abstencao) e resultados_governador_por_zona.csv, ambos gerados por npm run dados:governador. Em Zonas e seções, recortes de estado, município ou zona usam o valor oficial; recortes de seção (ou com filtro de líder) são estimados pelo cadastro de locais de votação, porque o boletim de urna só informa o comparecimento (o cadastro difere ~0,1% do eleitorado da eleição).

Endereços das abas

#visao-geral, #mapa, #municipios, #comparar, #analises, #presidente, #zonas-e-secoes e #legislativo. Os endereços antigos em inglês (#overview, #map, #pres...) continuam funcionando e são convertidos.

Compartilhar

O botão de compartilhar (cabeçalho e dentro de cada gaveta) usa o compartilhamento nativo do celular (Web Share) e, onde ele não existe, copia o link. O endereço de um município é #municipios/sao-luis e abre direto a gaveta dele.

Imagem de prévia

src/assets/og-image.png (1200×630) é a imagem que aparece ao colar o link no WhatsApp e nas redes; o build a copia para public/og-image.png. Para regerar: powershell -ExecutionPolicy Bypass -File tools\gerar-og-image.ps1. A meta tag usa o endereço absoluto do site: SITE_URL ou, no Vercel, VERCEL_PROJECT_PRODUCTION_URL (automática).

Versão publicada

Cada build gera public/version.json (hash do conteúdo) e embute o mesmo id na página. O painel confere essa versão ao abrir, ao voltar para a aba e a cada 5 minutos; se houver uma nova, mostra "Há uma nova versão do painel" com o botão Atualizar agora. O vercel.json manda o navegador sempre revalidar a página e nunca guardar o version.json.

Qualidade, validações e operação

Comando	Para que serve
npm run validar	Confere todos os dados (somas município × zona × seção × estado, base dos percentuais, alinhamento de locais e apuração, presidente, legislativo). Erro = sai com código 1.
npm run build	Roda a validação antes e, depois de gerar a página, confere a sintaxe dos scripts e dos JSON embutidos. Qualquer problema derruba o build e o Vercel mantém o deploy anterior.
npm run conferir:tse	Compara os totais publicados com os arquivos atuais do TSE (detecta dados desatualizados). Roda diariamente no GitHub Actions.
npm run dados:rapido	Atualiza governador, legislativo e presidente e valida.
npm run dados:tudo	Atualiza tudo na ordem correta (inclui boletins de urna e apuração); use --locais para incluir o cadastro de locais.

Ordem dos dados (cada etapa depende da anterior): governador → legislativo → presidente → seções → locais → apuração → validar → build. O CI (.github/workflows/ci.yml) roda validação e build em cada push; dados-tse.yml confere os dados com o TSE todo dia.

Limitações conhecidas (avisadas pelo validador, não bloqueiam): 2 locais de votação sem coordenada válida e 47 seções com mais votos que eleitores no cadastro de locais — nesses casos a abstenção por seção é tratada como estimativa.

Testes de interface

tests/interface.test.js abre o painel gerado (public/) num Chrome/Edge sem interface e confere: todas as abas sem erro, endereços em português, percentuais do TSE com duas casas, busca de candidato, link direto de município, compartilhar, Presidente (1º turno e 2º aguardando), filtro de Zonas e seções, Comparar candidatos (inclusive por município), menu mobile sem rolagem horizontal e aviso de nova versão.

npm run build
npm run teste:instalar   # uma vez (as dependências ficam em tests/, fora do build do Vercel)
npm run teste            # usa o Chrome/Edge instalado; CHROME_PATH sobrescreve

O CI roda esses testes em cada push (job interface).

Configuração

site.config.json guarda o ID do Google Analytics (gaId). A variável GA_ID sobrescreve (vazia desativa) e o formato é validado no build. O endereço público vem de SITE_URL ou das variáveis do Vercel.