teqo-backup/docs/plans/escala-percentual-mapa-pracas.md
Francisco Ignácio Fontoura Solla adc0f31f5b Sync all project docs with the deployed remodel and hardening; compile roadmap
- 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.
2026-07-24 02:04:45 -03:00

120 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 rotas `pracas/` → `municipios/`; os nomes neste plano são os da época. Nomes atuais: ver [remodelagem-municipios.md](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](../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 `votosValidos` do 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**). ~~`setStyle` incremental~~ → **B6 ✓**.
**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 `scaleMode`~~ → **B6 ✓** [escala-dry-pos-b3.md](escala-dry-pos-b3.md).
## Objetivos
- Controle no painel do mapa: escala **Total (votos)** | **% dos válidos** (rótulos pt-BR).
- Em `% dos válidos`: cor = `votos_candidato / votosValidos` da geografia da Praça (células `cityCode × zone` no escopo), com `max` fixo = **1** (legenda 0–100%), não o máximo observado entre Praças.
- Anos TSE (2014/2018/2022): denominador = `electionTally.votosValidos` do **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: true` após assert, como `loadCandidateVotesByCityZone`).
- 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`, legenda `0` … `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 === 0` ou 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
```mermaid
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`** (em `src/utilities/plazaElectoralBaseline.ts`, ao lado de `loadCandidateVotesByCityZone`): para um `year`, retorna `Map<cityCode:zone, votosValidos>` a partir de `electionTally` (federal T1). Reusar `sumVotesForGeography` (mesmo shape de chave) — depth check: não criar `plazaMapPercent.ts` pass-through.
- **`loadPlazaMapBundle`** (`src/utilities/plazaMapData.ts`): preencher `validVotesByYear: Record<string, Record<string, number>>` (codarea → válidos agregados por geografia no escopo), espelhando o loop de `valuesByYear` para 2014/2018/2022; para a chave `'2022'` reutilizar no modo 2026. Estender o tipo `PlazaMapBundle`.
- **`PlazaMapPanel`**: `NativeSelect` (ou segmented leve já usado no tema) `scaleMode`; quando `percentValid` e não-compare, derivar `values` como shares 0–1 e passar `max={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 (`formatElectionNumber` vs `100%` / `percentFormatter`) — prop opcional `maxLabel` ou `formatMax`, 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 `electionTally` nos anos do mapa (já no fluxo `pnpm 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](mapa-pracas-filtrado.md)).
- Hover com readout → **B10** ([hover-mapa-pracas.md](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**.
- ~~`setStyle` incremental~~ → **B6 ✓**.
- 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ó `votosValidos` federal 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 para `year`).
- **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 por `ibgeCode`
- `src/utilities/plazaElectoralBaseline.ts` — `loadCandidateVotesByCityZone` / `sumVotesForGeography` / tally no detalhe
- `src/lib/choroplethColorScale.ts` — `choroplethFillColor(value, max)`
- `src/components/campaign/PlazaMapPanel.tsx` / `ChoroplethLegend.tsx` / `BahiaMap.tsx`
- `src/components/campaign/PlazaBaselineCard.tsx` — precedente de “% dos válidos” na UI
- `src/collections/ElectionTally.ts` — campo `votosValidos`
- 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