teqo-backup/docs/plans/escala-dry-pos-b2.md
Francisco Ignácio Fontoura Solla 75cdea38b4 Register the B8 F2 review debts as B8+.
The three /simplify reviewers reported after the merge, so their findings
became a fill-in instead of a fix. The lot is anchored on a measurement that
contradicts "small mesh, small artifact": the 19 Salvador zones carry 9,120 arc
points against 9,139 for ALL 417 Bahia municipalities, because both simplify
constants are relative to the file's own bbox and were copied verbatim from the
sibling script -- the same "1e4 grid" is ~103 m statewide and ~3.9 m in a city
26x narrower, on a map that stops at maxZoom 10.

That measurement inverts one reviewer's recommendation, which is why it is
written down rather than left to be re-derived: extracting the shared constants
as they stand would cement the defect and give it the authority of a policy, so
what gets shared between the two build scripts is the ground scale.

The other three: nothing runs featureMapKey over a real feature outside the
e2e, so the three spellings of the map key can drift and paint grey with no
error anywhere; Promise.all over both meshes plus the memoized rejection turned
a 19-polygon chunk into a single point of failure for the whole map, where the
municipal mesh alone used to suffice; and the "approximate, not the official TSE
boundary" caveat hangs off the zone LIST's render condition, so it vanishes in
comparison mode while the approximate mesh is still painted.

Also records what this delivery orphaned (getTerritoryFeature lost its last
production caller when fitMapToHighlights stopped consulting geometry modules,
and knip cannot see it because specs are entry points), and bumps B5 F2's
call-site counter to five.
2026-07-26 23:35:49 -03:00

9.7 KiB
Raw Blame History

Escala e DRY pós-B2 (geometrias + scripts CLI)

Status: Fase 1 entregue com B3 (2026-07-19); Fases 2–3 pendentes Atualizado em: 2026-07-20 (capture-review-debts pós-A8: build-bahia-demographics.mjs reforça gatilho F2 como 4º call site) Item do roadmap: docs/roadmap.md (Trilha B, item B5) Responsável: —

Contexto

O B2 (mapa-bahia-geometrias.md Fase 1) entregou a fundação estática do mapa: *.topo.json de municípios e Territórios de Identidade, bahiaMunicipalityCodes, helpers em bahiaGeometries.ts, script pnpm build:geometries. A passagem /simplify de 2026-07-18 limpou dead code e churns baratos no script/codegen, mas deixou de fora dois follow-ups que os revisores (performance / reuse) marcaram como importantes e maiores que cleanup pontual:

  1. Carregamento eager de geometrias no cliente. src/lib/bahiaGeometries.ts importa os dois TopoJSON, roda topojson-client feature() em 417+27 polígonos e monta índices no load do módulo — custo de bundle/memória antes de qualquer superfície Leaflet (B3).
  2. Cache de download duplicado nos CLIs. ensureCachedJson em scripts/build-bahia-geometries.mjs é estruturalmente o mesmo que ensureCachedZip em scripts/seed-tse-results.mjs (mkdir → hit → downloadToBuffer → SHA-256 → write), só muda extensão/parse. Pós-A7 F2: scripts/build-bahia-tse-city-codes.mjs (pnpm build:tse-city-codes) clona o mesmo padrão ensureCachedZip — terceiro call site. Pós-A8 (capture-review-debts 2026-07-20): scripts/build-bahia-demographics.mjs (pnpm build:demographics) clona ensureCachedJson — quarto call site; reforça prioridade da Fase 2 sem novo ID de roadmap. Pós-B8 F2 (capture-review-debts 2026-07-26): scripts/build-municipality-zone-geometries.mjs clona o padrão como ensureCachedBinary (devolve o buffer cru, porque a entrada é um SHP e não um JSON) — quinto call site, e o primeiro que valida a decisão de cacheDir por chamada com um segundo consumidor real da mesma pasta (GEOMETRIES_CACHE_DIR, default data/geometries/). O bloco todo (die/log/sha256/cacheDir/writeJson) veio junto, então a Fase 2 tem hoje 5 cópias a colapsar, não 4.
  3. Factory duplicada mun/TI pós-B3 F1. bahiaMunicipalityGeometries.ts e bahiaTerritoryGeometries.ts repetem o mesmo pipeline topojson.feature → array → Map por chave → export do módulo indexado — só mudam topology object, propriedade de chave (codarea vs code) e getter.

Este plano é o registro canônico desses follow-ups. Sem ele, o B3 pode embarcar o mapa com payload desnecessário no path default, e o próximo script de dado aberto volta a clonar o cache.

Explicitamente fora (revisores pediram skip): helpers genéricos de localeCompare('pt-BR') e de checksum/evidence nos testes int — a duplicação com bahiaTseZones.int.spec.ts é intencional e legível por domínio.

Objetivos

  • Superfícies de mapa (B3) carregam geometria só sob demanda: município e território podem ser importados em separado; nenhum path de /campanha que não mostre mapa paga o decode TopoJSON→GeoJSON.
  • Scripts CLI de dado aberto (build:geometries, db:seed:tse, futuros) compartilham um helper de cache em disco + download, sem mudar proveniência/SHA nem guards de banco.
  • Guardrails: sem migration, sem collection, sem Consent, sem server action de produto; B2 permanece a fonte dos artefatos estáticos versionados.

Decisões travadas

  • Um item B5, três fases ordenadas. Mesmo racional do C6/C7/A7: um ID de roadmap, PRs por fase. Ordem: lazy load (impacta B3) → helper de cache CLI (barato, sem UI) → factory geometrias mun/TI (DRY pós-split B3).
  • Dependência dura de B2. Este item só faz sentido com os *.topo.json e bahiaGeometries já commitados; não reabre o escopo de geração/simplificação das malhas.
  • 2026-07-19 (Fase 1 entregue com B3): lazy load split mun/TI via loadMunicipalityGeometryModule / loadTerritoryGeometryModule; map islands dynamic(..., { ssr: false }).
  • Cortável se o mapa permanecer fora do caminho crítico. B3 já é corte seguro no roadmap; B5 F2 (cache CLI) é ainda mais cortável — a duplicação atual é ~20 linhas. F1 só é “não cortável” no sentido de qualidade do B3 (bundle), não de calendário eleitoral.
  • Não extrair helpers de sort pt-BR nem de evidence SHA nos testes. Decisão dos revisores do simplify (2026-07-18): indirection sem ganho.
  • i18n e naming (AGENTS.md): identificadores em inglês (loadMunicipalityFeatures, loadTerritoryFeatures, ensureCachedDownload), strings visíveis em pt-BR só se algum log de CLI for user-facing (hoje são logs de build).

Questões em aberto

  • API pública pós-lazy: manter getMunicipalityFeature sync após warm, ou só async loaders? Recomendação: loaders async (loadMunicipalityGeometryModule() / loadTerritoryGeometryModule()) que resolvem o módulo já indexado; os getters sync atuais viram métodos do módulo carregado (ou ficam em submodule lazy). Evitar Promise em cada hover do mapa.
  • Onde vive o helper de cache CLI? Recomendação: src/lib/cliCachedDownload.ts (ou scripts/lib/cached-download.mjs se quiser zero risco de import no app). Preferir src/lib/ só se tipado e importado só pelos scripts via --import=tsx/esm — não expor no client bundle.
  • Unificar env TSE_CACHE_DIR / GEOMETRIES_CACHE_DIR? Recomendação: não — um parâmetro cacheDir por chamada; cada script mantém sua env e pasta sob data/.

Abordagem proposta

flowchart TD
    B2["B2 geometrias ✓"] --> F1
    F1["Fase 1 — Lazy geometrias<br/>split mun/TI + dynamic import"]
    F1 --> F2["Fase 2 — ensureCachedDownload<br/>CLI compartilhado"]
    F1 --> F3["Fase 3 — buildGeometryModuleFromTopology<br/>(mun/TI DRY)"]
    F1 -.preferencialmente.-> B3["B3 Leaflet"]
    B2 --> B3

Fase 1 — Lazy load de geometrias (antes ou com B3)

  • Partir src/lib/bahiaGeometries.ts: deixar de avaliar feature() + Maps no top-level do entry que o app importa por padrão.
  • Submódulos ou dynamic import() separados para municípios vs territórios (dashboard só TI; overview pode precisar dos dois sob toggle).
  • BahiaMap / superfícies B3: dynamic(() => import(...), { ssr: false }) já previsto no plano do mapa; o import interno deve apontar para o loader lazy, não para um barrel que decoda tudo.
  • Testes int: importar o submodule (ou await loader) — ambiente node, sem regressão de cobertura 417/27.
  • Critério de verificação: nenhum import estático de página /campanha (exceto a ilha do mapa) puxa os *.topo.json no grafo de módulo (inspecionar bundle / pnpm build + analysis leve).

Fase 2 — Helper de cache CLI

  • Extrair ensureCachedDownload({ cacheDir, key, url, ext?, logPrefix }) a partir de ensureCachedJson / ensureCachedZip.
  • Retorno: { url, buffer, hash } (parse JSON/ZIP fica no caller — build-bahia-geometries já faz JSON.parse; seed TSE usa readZipEntry).
  • Continuar usando downloadToBuffer (src/lib/electionResultsZip.ts).
  • Migrar scripts/build-bahia-geometries.mjs, scripts/seed-tse-results.mjs, scripts/build-bahia-tse-city-codes.mjs e scripts/build-bahia-demographics.mjs; sem mudança de comportamento nem de pastas data/geometries/ / data/tse/ / data/demographics/.

Fase 3 — Factory compartilhada mun/TI

  • Extrair buildGeometryModuleFromTopology<TProps, TKey>({ topology, objectName, keyProperty, getFeature }) em src/lib/bahiaGeometryModuleFactory.ts (ou ao lado de bahiaGeometriesTypes.ts).
  • bahiaMunicipalityGeometries.ts / bahiaTerritoryGeometries.ts ficam como thin wrappers: import JSON + chamada à factory com codarea / code.
  • Testes int existentes (bahiaGeometries.int.spec.ts) permanecem verdes — sem mudança de API pública dos loaders async.
  • Não fundir os dois JSON num único bundle (mantém split lazy B5 F1).

Migration: nenhuma nas três fases. Sem collection, sem Consent, sem server action de produto.

Dependências

  • Dura: B2 Mapa Fase 1 (geometrias) — já entregue.
  • Suave: B3 Leaflet — consome a Fase 1; se B3 implementar o lazy load, fecha F1 neste plano.
  • Reusa: downloadToBuffer (src/lib/electionResultsZip.ts), artefatos em src/lib/geometries/, padrões de script de scripts/seed-tse-results.mjs.

Não escopo

  • Implementação Leaflet / componentes de mapa → B3 (mapa-bahia-geometrias.md Fase 2).
  • Camada de zonas TSE no mapa → B4.
  • Helper genérico de localeCompare('pt-BR') ou de evidence SHA nos testes int — rejeitado no simplify.
  • BahiaMap setStyle incremental → B6 (escala-dry-pos-b3.md).
  • Query duplicada lista+coroplético 2022 → A7 F4 (escala-dry-pos-a4.md).
  • Mudança de qualidade/simplificação das malhas IBGE ou re-download obrigatório — só se a F2 tocar proveniência (não deve).

Referências

  • docs/roadmap.md (Trilha B, item B5; B2/B3)
  • docs/plans/mapa-bahia-geometrias.md — plano pai; B3 deve preferir a F1 deste item
  • docs/plans/escala-dry-pos-c2.md / escala-dry-pos-c3.md — precedente de registro pós-/simplify
  • src/lib/bahiaGeometries.ts — lazy loaders async
  • src/lib/bahiaMunicipalityGeometries.ts / bahiaTerritoryGeometries.ts — near-duplicate pós-F1
  • src/lib/bahiaGeometriesTypes.ts — tipos *GeometryModule
  • scripts/build-bahia-geometries.mjs — ensureCachedJson
  • scripts/build-bahia-demographics.mjs — ensureCachedJson (4º call site; A8)
  • scripts/seed-tse-results.mjs — ensureCachedZip
  • src/lib/electionResultsZip.ts — downloadToBuffer
  • AGENTS.md — naming inglês; Bahia implícita; dado estático versionado