teqo-backup/docs/plans/escala-dry-pos-b2.md
2026-07-18 22:14:26 -03:00

7.3 KiB

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

Status: registrado no roadmap (fases pendentes) Atualizado em: 2026-07-18 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.

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, duas fases ordenadas. Mesmo racional do C6/C7: um ID de roadmap, PRs por fase. Ordem: lazy load (impacta B3) → helper de cache CLI (barato, sem UI).
  • 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.
  • Fase 1 preferencialmente junto com B3. Se o implementador de B3 aplicar o carregamento lazy no mesmo PR das superfícies Leaflet, a Fase 1 deste plano fecha ali (marcar B5 F1 ✓ e seguir só a F2). Se B3 embarcar import estático por pressa, a F1 permanece como débito explícito.
  • 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 -.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 e scripts/seed-tse-results.mjs; sem mudança de comportamento nem de pastas data/geometries/ / data/tse/.

Migration: nenhuma. 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.
  • 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 — eager feature() + índices
  • scripts/build-bahia-geometries.mjs — ensureCachedJson
  • scripts/seed-tse-results.mjs — ensureCachedZip
  • src/lib/electionResultsZip.ts — downloadToBuffer
  • AGENTS.md — naming inglês; Bahia implícita; dado estático versionado