- Compile docs/roadmap.md into a next-steps document (277→206 lines): R0–R5/M1–M5 tables and the delivered map/list item paragraphs compressed into 'Já entregue'; janelas, grafo and cortes list only open IDs; C10/C11/C8 fill-ins keep their original triggers; C5 moved under 'A validar'. - Record the production deploy of the destructive remodel chain (2026-07-23 Vercel builds) across roadmap, AGENTS.md, the project notebook and plans — supersedes every 'deploy pendente'; smoke pós-deploy + onboarding remain the open blockers. - Fix AGENTS.md internal contradictions: Município locked-decisions bullet (435, Camaçari whole, candidate role), campaignUser role enum, deploy-checklist item 7 as historical, access/* structure note, election-aggregates artifact + election-tse revalidate runbook. - Sync open plans to real identifiers (plaza*/nucleus* → municipality*): the intelligence program (master + E8–E15/B13/C12 with artifact/caching context and satisfied deps), B8 rescoped to Salvador ZE 1–19 only, WhatsApp D3–D5, D2, A6 (now the insight layer over stateDeputy), RS+, onda-0 smoke step. - Close items verified done in code: C8 F4 (DRY de forms) complete, filtros-auto shared pending shell, petition generateStaticParams select/depth; ledger the surviving user-visible 'Praça' copy in src as new P2 debt. - Banner delivered praça-era plans (production note + rename pointer); mark remodelagem-pracas.md superseded and remodelagem-municipios.md delivered. - TECH-DEBT smell statuses, TESTING RBAC row, README quality gates, campanha UI rules updated to current component names.
12 KiB
Escala percentual no Mapa das Praças (0–100% dos válidos)
Nota (2026-07-24): entregue na era Praças e em produção desde 2026-07-23. A remodelagem M1 renomeou os identificadores
plaza*→municipality*e as rotaspracas/→municipios/; os nomes neste plano são os da época. Nomes atuais: ver remodelagem-municipios.md.
Status: entregue 2026-07-21 (em produção desde 2026-07-23)
Atualizado em: 2026-07-21 (implementação B11 + capture-review-debts pós-/simplify)
Item do roadmap: docs/roadmap.md (Trilha B, item B11)
Impeccable: B — encaixe em PlazaMapPanel / BahiaMap / ChoroplethLegend (sem rota nova)
Appetite: ~0,5–1 dia eng; tally por ano no bundle + seletor de escala + legenda 0–100%
Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md / DESIGN.md (register product — Field Desk) · tema data-theme='campaign' · shells existentes (PlazaMapPanel, BahiaMap, ChoroplethLegend, NativeSelect).
Na implementação (implement-roadmap-item): craft compacto → critique → polish (controle + copy da legenda; sem shape longo).
Brief compacto:
- Persona / contexto: Assessor/Coordenador Geral (Alex) compara municípios de portes muito diferentes e hoje o coroplético é dominado pelo total absoluto (Salvador “pinta” a escala).
- Job principal: escolher ver a cor como participação nos votos válidos da Praça (0–100%), não como total relativo à maior Praça.
- Estratégia de cor: Restrained — mesma rampa vermelha sequencial; só muda o domínio da métrica. Modo comparar (divergente) inalterado neste item.
- Anti-goals: não segunda paleta; não hero-metric SaaS; não redesenhar o mapa; não inventar denominador fora de
votosValidosdo TSE.
Contexto
O Mapa das Praças (PlazaMapPanel em /campanha/pracas) pinta municípios com choroplethFillColor(value, max) onde max = choroplethMaxValue(values) — o maior total absoluto no escopo (src/lib/choroplethColorScale.ts). Municípios pequenos com boa penetração ficam pálidos; Salvador/grandes centros saturam a escala.
Os votos nominais já vêm de loadCandidateVotesByCityZone + sumVotesForGeography em plazaMapData.ts. O denominador pedido — votos válidos (sem nulos, brancos nem abstenções) — já existe em electionTally.votosValidos (seed TSE; usado no detalhe via plazaElectoralBaseline / PlazaBaselineCard). Pedido de produto (2026-07-21): opção de escala percentual na Praça, domínio fixo 0% → 100%.
Não cobre: filtro URL (B7), hover (B10), polígonos-zona (B8). → B6 ✓.setStyle incremental
Já resolvido no simplify/critique (não reabrir): bug legenda 0–100% vs mapa normalizado pelo max local (scaleMax em BahiaMap); lookup 2026→2022 redundante no panel (bundle já aliasa validVotesByYear['2026']); PLAZA_MAP_SCALE_MODES; displayMax memoizado; Promise.all nos loads TSE por ano (+ compare) em loadPlazaMapBundle; guard valid > 0 em computeValidVoteShares; polish leve de copy/controle (sem critique P0–P3 formal).
Explicitamente fora (triage capture-review-debts 2026-07-21 pós-B11): formatValidVoteShare compartilhado com PlazaBaselineCard (gatilho: 3ª superfície com % válidos); loader genérico loadTallyByCityZone (gatilho: 3ª variante de tally); primitivo validVoteShare em electionInsights (gatilho: 3º call site); maxLabel em vez de formatMax na legenda; mover computeValidVoteShares de módulo; int test de agregação share além de keys 2026→2022 (gatilho: próximo toque em plazaMapData); cache cross-request de tally (gatilho: profiling TTFB); rebuild GeoJSON ao trocar → B6 ✓ escala-dry-pos-b3.md.scaleMode
Objetivos
- Controle no painel do mapa: escala Total (votos) | % dos válidos (rótulos pt-BR).
- Em
% dos válidos: cor =votos_candidato / votosValidosda geografia da Praça (célulascityCode × zoneno escopo), commaxfixo = 1 (legenda 0–100%), não o máximo observado entre Praças. - Anos TSE (2014/2018/2022): denominador =
electionTally.votosValidosdo mesmo ano + mesmo cargo/turno federal T1 já usados no mapa. - Guardrails: sem migration, sem collection, sem Consent, sem server action; leituras de tally com o mesmo padrão de access do baseline (
assertCanReadElectionData/overrideAccess: trueapós assert, comoloadCandidateVotesByCityZone). - Modo Comparar (divergente): permanece em diferença absoluta; o seletor de escala percentual some ou fica desabilitado com copy curta (não misturar % e diff no v1).
Decisões travadas
- Item próprio B11 (não absorver em B7/B10/B6 nem R6). É semântica da métrica do coroplético, não filtro, hover, perf nem polish genérico. (2026-07-21, roadmap-item.) Rejeitado: fill-in sem plano (denominador + 2026 + compare precisam de decisão); fase de classificação territorial A5 (já usa % no detalhe, não no mapa).
- Denominador =
electionTally.votosValidos(TSE). Exclui nulos, brancos e quem não compareceu (abstenção). Alinha ao card de baseline (“% dos válidos”). Rejeitado:aptos(inclui abstenção);comparecimento(inclui nulos/brancos); denominador “votos nominais totais do cargo” sem tally (mais query, mesma intenção do campo oficial). - Escala fixa 0–100%, não max-of-shares.
choroplethFillColor(share, 1)(ou equivalente). Um município com 8% dos válidos fica igualmente claro em qualquer escopo. Rejeitado: normalizar pelo maior % do mapa (ainda distorce leitura entre filtros). - 2026 (estimativas): denominador = válidos 2022 da mesma geografia. Não há tally 2026. Copy da legenda: “% dos válidos 2022”. Rejeitado: desabilitar % em 2026 (perde o ano operacional); usar
voteGoals/metas (outra semântica); inventar eleitorado IBGE. - Comparar (divergente) fora do modo % neste item. Diff absoluto Solla − outro permanece; percentual de shares (ou diff de %) é rabbit hole. Rejeitado: forçar % no compare no v1.
- Default da UI =
% dos válidos. Absoluto continua disponível. (assumido — validar com produto; se preferirem preservar o comportamento atual, inverter o default sem mudar o resto.) Rejeitado: só absoluto com “avançado” escondido (o pedido é a leitura útil). - i18n e naming (AGENTS.md): identificadores em inglês (
scaleMode: 'absolute' | 'percentValid',validVotesByYear,percentValues); strings visíveis em pt-BR (Total (votos),% dos válidos, legenda0…100%).
Questões em aberto
- Persistir escala na URL (
?scale=percent|absolute)? Opções: A) só estado local (como o seletor Ano) | B) query string. Recomendação: A no v1 — barato; B se a coordenação começar a compartilhar links do mapa com a escala (gatilho abaixo). - Praça com
votosValidos === 0ou tally ausente? Opções: A) tratar como sem dado (cinza, como valor ausente) | B) 0%. Recomendação: A — evita divisão por zero e “0%” falso quando falta seed. - Salvador/Camaçari agregados no polígono municipal: % = soma dos votos das Praças-zona no escopo / soma dos válidos das mesmas células (já é o padrão do absoluto). Breakdown textual continua em votos (ou mostra % se barato). Recomendação: breakdown em votos no v1; % só no coroplético + legenda.
Abordagem proposta
flowchart LR
tally["electionTally.votosValidos<br/>por year × cityZone"] --> bundle["PlazaMapBundle.validVotesByYear"]
votes["valuesByYear<br/>(já existe)"] --> panel["PlazaMapPanel"]
bundle --> panel
panel -->|"scaleMode absolute"| abs["values + max=max(values)"]
panel -->|"scaleMode percentValid"| pct["share = votes/valid · max=1"]
abs --> map["BahiaMap + ChoroplethLegend"]
pct --> map
Componentes:
loadValidVotesByCityZone(emsrc/utilities/plazaElectoralBaseline.ts, ao lado deloadCandidateVotesByCityZone): para umyear, retornaMap<cityCode:zone, votosValidos>a partir deelectionTally(federal T1). ReusarsumVotesForGeography(mesmo shape de chave) — depth check: não criarplazaMapPercent.tspass-through.loadPlazaMapBundle(src/utilities/plazaMapData.ts): preenchervalidVotesByYear: Record<string, Record<string, number>>(codarea → válidos agregados por geografia no escopo), espelhando o loop devaluesByYearpara 2014/2018/2022; para a chave'2022'reutilizar no modo 2026. Estender o tipoPlazaMapBundle.PlazaMapPanel:NativeSelect(ou segmented leve já usado no tema)scaleMode; quandopercentValide não-compare, derivarvaluescomo shares 0–1 e passarmax={1}à legenda;metricLabel→participação nos válidos (…)/ copy 2026 com “válidos 2022”. Em compare: forçar absoluto + ocultar/desabilitar o seletor.ChoroplethLegend: aceitar formatação de extremo direito (formatElectionNumbervs100%/percentFormatter) — prop opcionalmaxLabelouformatMax, sem segundo componente de legenda.- Testes: unit de
share = votes/valid(0, 1, divisão por zero → omitir); smoke mental/checklist: ano TSE, 2026, compare desliga %, Salvador agregado. - Migration: Sem migration, sem collection, sem server action.
Dependências
- Dura: R2 (mapa Praças) — entregue.
- Suave: seed TSE com
electionTallynos anos do mapa (já no fluxopnpm db:seed:tse); A9 só se a métrica 2026 do numerador mudar (expectedVotes) — o denominador % continua 2022. - Reusa:
plazaMapData.ts,plazaElectoralBaseline.ts,choroplethFillColor,PlazaMapPanel,ChoroplethLegend,electionTally.votosValidos.
Não escopo
- Filtrar mapa pela URL → B7 (mapa-pracas-filtrado.md).
- Hover com readout → B10 (hover-mapa-pracas.md); quando ambos existirem, o readout em modo % deve mostrar % (não só votos) — coordenar na implementação do que estiver segundo.
- Diff percentual no modo Comparar → adiado (rabbit hole abaixo).
- Polígonos Praças-zona → B8.
→ B6 ✓.setStyleincremental- Alterar classificação territorial A5 / limiares — já entregue; só compartilha a noção de
% dos válidos.
Rabbit holes
- Diff de shares no modo Comparar. Se alguém “só completar”: segunda escala divergente em pp, legenda bipolar em %, e copy confusa com o vermelho/azul atual. Mitigação: compare = absoluto apenas neste item.
- Denominador por cargo majoritário ou aptos. Muda a leitura política e quebra paridade com o baseline. Mitigação: só
votosValidosfederal T1. - Persistir preferência por usuário / cookie. Fora do appetite. Mitigação: estado local; URL só com gatilho.
Adiado com gatilho
?scale=na URL. Revisitar quando: alguém pedir link compartilhável do mapa já em % (ou o mesmo padrão for adotado parayear).- Modo Comparar em pontos percentuais (Solla% − outro%). Revisitar quando: a coordenação usar o compare e reclamar que o diff absoluto favorece municípios grandes.
- Breakdown por zona em %. Revisitar quando: B8 pintar Praças-zona ou B10 mostrar readout em % e a lista de zonas ficar inconsistente.
Referências
docs/roadmap.md(Trilha B / Janela 1 — B11)src/utilities/plazaMapData.ts— bundle e agregação poribgeCodesrc/utilities/plazaElectoralBaseline.ts—loadCandidateVotesByCityZone/sumVotesForGeography/ tally no detalhesrc/lib/choroplethColorScale.ts—choroplethFillColor(value, max)src/components/campaign/PlazaMapPanel.tsx/ChoroplethLegend.tsx/BahiaMap.tsxsrc/components/campaign/PlazaBaselineCard.tsx— precedente de “% dos válidos” na UIsrc/collections/ElectionTally.ts— campovotosValidos- AGENTS.md — Campaign Praças model (mapa /
plazaMapData); naming EN/pt-BR PRODUCT.md/DESIGN.md— Field Desk; inteligência a serviço da organização