Mark baseline product delivery as merged in the roadmap, plans, AGENTS, and project notebook.
9.8 KiB
Escala e DRY pós-A4 (baseline TSE no produto)
Status: registrado no roadmap (fases pendentes) Atualizado em: 2026-07-19 Item do roadmap: docs/roadmap.md (Trilha A, item A7) Responsável: —
Contexto
O A4 (baseline-eleitoral-tse.md Fases 2–4) entregou o baseline TSE 2022 no detalhe do núcleo e no overview da lista — implementado e mesclado em main (2026-07-18): getNucleusElectoralBaseline / loadNucleusBaseline2022Overview, computeGapVs2022, UI NucleusElectoralBaseline + NucleusInsights, card "Baseline 2022". Três passagens /simplify no mesmo PR já limparam o que cabia em cleanup: papéis genéricos (BASELINE_TICKET_2022), geographyWhere por cidade com zoneNumber in […], overview só consulta núcleos com estimativa confirmada, helpers compartilhados (toNucleusElectionGeographyInput, formatElectionNumber, NO_ELECTION_BASELINE_MESSAGE).
Os revisores (performance / reuse / quality) marcaram como importantes e maiores que simplify os follow-ups abaixo. Sem registro, o A5 (insights) e o coroplético do B3 herdariam o mesmo custo de I/O no path do detalhe.
- Detalhe puxa todas as linhas nominais de dep. federal (1º turno) na geografia.
detailVoteWhere+loadElectionVotesemsrc/utilities/nucleusElectoralBaseline.tsbuscam o ranking local inteiro parawinnerFederalecandidate.rank. Em núcleo multi-município / TI inteiro isso pode ser milhares de rows por abertura da aba Visão geral (pagination: false). - Filtro geográfico por
cityName(texto), não porcityCodeTSE. O índice natural das collections de eleição é(year, office, turn, cityCode, zoneNumber); filtrar por nome impede o plano ótimo e complica OR grandes na união do overview (já mitigado no simplify, mas o detalhe/TI ainda sofre). - DRY de UI do Gap "acima".
NucleusInsightsusaAlert variant="pending"para abaixo/neutro, mas o estado "acima" aplica classes ad-hoc com tokens--estimate-confirmed*. OAlertjá tem o precedentependingespelhando o Badge; falta a variante simétrica. A barra do candidato no card também reimplementarole="progressbar"em vez de reusarProgress(NucleusListOverview).
Explicitamente fora (revisores pediram skip no simplify): map JSX de linhas Lula/Jerônimo, dropar candidate.rank / electorate.aptos / ratio do tipo público só por higiene (só fariam sentido se a F1 deixar de calcular rank), e o cast as unknown as RawOverviewNucleus da B1 (não é débito novo do A4).
Objetivos
- Abrir a aba Visão geral de um núcleo com TI/multi-município permanece barato: o loader de baseline não transferir o conjunto completo de candidatos federais da geografia.
- Filtros de geografia eleitoral preferem
cityCodeTSE quando o mapa nome→código existir, sem mudar a UX (continua resolvendo a partir decities/regionsdo núcleo). - Gap "acima" usa a mesma família de variantes do Alert que o âmbar (
pending); a barra do candidato reusaProgress. - Guardrails: preferir sem migration nas Fases 1 e 3; Fase 2 pode ser só tabela estática (como
bahiaMunicipalityCodes/ seed TSE) — se precisar de índice novo no Postgres, migration dedicada e cortável. Sem Consent (dado público TSE). Access continuaoverrideAccess: false+canReadElectionData.
Decisões travadas
- Um item A7, três fases ordenadas. Mesmo racional do B5/C7/C8: um ID de roadmap, PRs por fase. Ordem: agregação do detalhe (custo real) →
cityCode(escala BA-wide) → DRY de Alert/Progress (barato, UI). - Dependência dura de A4. Só faz sentido com o loader/UI já no produto; não reabre o escopo do Gap vs 2022 nem do card Baseline.
- Fase 1 não remove o "mais votado aqui" da UI. O produto do A4 inclui
winnerFederal; a otimização agrega no SQL/drizzle (ou limita o payload), não corta a feature. Se produto decidir que rank/winner saem do card, a F1 encolhe para "só o candidato da chapa + tallies". - Cortável se a geografia real dos núcleos permanecer pequena (1–2 municípios tipados). Vira não-cortável de qualidade quando A5/B3 passarem a martelar o mesmo helper em TI inteiro.
- Não registrar no A7 o cast
as unknowndo overview B1 — débito de tipagem do select Payload da lista; só tocar se um PR de A7 já estiver no arquivo. - i18n e naming (AGENTS.md): identificadores em inglês (
aggregateFederalTotalsByGeography,tseCityCodeForMunicipality,alertVariants.confirmed), strings visíveis em pt-BR inalteradas.
Questões em aberto
- Fase 1: Local API
find+ agregação em memória vspayload.db.drizzleGROUP BY? Recomendação: drizzle (como o seed TSE) paraSUM(votes) GROUP BY candidate_numberno escopo federal T1 + geografia, mais uma query estreita para presidente/governador da chapa; manteroverrideAccess/ACL lendo via Local API só se o drizzle for privilegiado — espelhar o padrão do import (overrideAccess: truesó em CLI). No app, preferir Local API comselectmínimo ou uma query drizzle encapsulada que ainda respeitecanReadElectionData(checagem explícita antes). Definir no PR da F1 com um teste int de TI grande (fixture expandida ou assert de limite de rows). - Fase 2: de onde vem o mapa nome canônico →
CD_MUNICIPIOTSE? Recomendação: extrair do próprio seed/electionTally/electionCandidateVote(já têmcityCode+cityName) para uma tabela estática gerada (src/lib/bahiaTseCityCodes.ts) no mesmo espírito debahiaMunicipalityCodes(IBGE) — não confundir com código IBGE. Script re-executável opcional; sem migration se for só arquivo versionado. - Fase 3: nome da variante Alert —
confirmedouestimate-confirmed? Recomendação:confirmed, alinhado aos tokens CSS--estimate-confirmed/ classe utilitária já usada pelo Badgeestimate-confirmed, sem inventar terceira nomenclatura.
Abordagem proposta
flowchart TD
A4["A4 Baseline no produto ✓"] --> F1
F1["Fase 1 — Agregar federal no detalhe<br/>(GROUP BY / payload estreito)"]
F1 --> F2["Fase 2 — Geografia por cityCode TSE"]
F1 --> F3["Fase 3 — Alert confirmed + Progress"]
F1 -.mesmo loader.-> A5["A5 Insights"]
F1 -.métricas.-> B3["B3 Leaflet coroplético"]
Fase 1 — Agregação do ranking federal no detalhe
- Em
src/utilities/nucleusElectoralBaseline.ts: deixar de materializar todas as rows nominais federais da geografia só paraaggregateFederalCandidateTotals. - Caminho preferido: query agregada (drizzle) → lista
{ candidateNumber, name, party, votes }já somada; candidato da chapa + winner/rank derivados dessa lista curta (N candidatos distintos, não N×zonas). - Manter query estreita para presidente/governador da
BASELINE_TICKET_2022(já filtrada por número). - Tallies: inalterado (já é 1 row por city×zone federal T1).
- Testes: unit da agregação pura; int com geografia multi-zona assertando winner/rank/solla votes e teto de rows transferidas (ou mock do finder).
- Critério: abrir overview de núcleo com ≥2 municípios / TI não escala linearmente com (#candidatos × #zonas) no wire.
Fase 2 — Filtro por cityCode TSE
- Gerar/commitar mapa canônico
cityName→cityCode(BA 2022) a partir dos dados já importados. resolveNucleusElectionGeography(ou camada ao lado) passa a exporcityZonePairscom código;geographyWhereusacityCode: { equals|in }+zoneNumber: { in }.- Overview union e detalhe compartilham o mesmo helper.
- Sem mudança de UX; fallback fail-closed se o município do núcleo não mapear (mesmo espírito de
canonicalizeMunicipalityName).
Fase 3 — Alert confirmed + Progress no card
src/components/ui/Alert.tsx: adicionar variantconfirmedespelhandopendingcom tokens--estimate-confirmed/ foreground.NucleusInsights: trocar ocn(...)ad-hoc porvariant={gap.status === 'above' ? 'confirmed' : 'pending'}(oudefaultsó se neutro — manter pending para noBaseline/noEstimate).NucleusElectoralBaseline: substituir a barra custom porProgress(já usado no overview), preservandoaria-label.
Migration: nenhuma nas Fases 1 e 3. Fase 2 preferencialmente só artefato estático versionado; índice Postgres extra só se o EXPLAIN ainda doer após cityCode (aí pnpm migrate:create cortável).
Dependências
- Dura: A4 Baseline no produto + Gap vs 2022 — implementado (loader + UI).
- Suave: A5 Insights e B3 coroplético — consomem/amplificam o mesmo helper; se A5 chegar antes da F1, herda o custo.
- Reusa:
BASELINE_TICKET_2022,ba2022Scope/geographyWhere, collectionselectionCandidateVote/electionTally, padrão drizzle doscripts/seed-tse-results.mjs, tokensestimate-confirmed/estimate-pending,Progress.
Não escopo
- Novos insights de produto → A5 (planos
insight-*.md). - Dobradinha 2026 → A6.
- Lazy load de geometrias / cache CLI → B5.
- Escala de apoiadores / agenda → C6/C7/C8.
- Remover rank/winner da UI por decisão de produto sem agregação — fora; se produto cortar, fechar F1 como "só chapa + tallies".
- Tipagem genérica dos
selectPayload do overview B1.
Referências
docs/roadmap.md(Trilha A, item A7; A4/A5/B3)docs/plans/baseline-eleitoral-tse.md— plano pai do A3/A4docs/plans/escala-dry-pos-b2.md/escala-dry-pos-c3.md/escala-dry-pos-c6.md— precedente pós-/simplifysrc/utilities/nucleusElectoralBaseline.ts—detailVoteWhere,loadElectionVotes,aggregateFederalCandidateTotalssrc/lib/electionInsights.ts/src/components/campaign/NucleusInsights.tsx— Gap UIsrc/components/campaign/NucleusElectoralBaseline.tsx— barra do candidatosrc/components/ui/Alert.tsx— variantpendinga espelharsrc/components/ui/Progress.tsx— reuso no card- AGENTS.md — Election baseline data; Local API
overrideAccess: false; naming inglês