diff --git a/docs/plans/escala-dry-pos-b2.md b/docs/plans/escala-dry-pos-b2.md index 36165b28..0fc73029 100644 --- a/docs/plans/escala-dry-pos-b2.md +++ b/docs/plans/escala-dry-pos-b2.md @@ -1,7 +1,7 @@ # 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) +Atualizado em: 2026-07-27 (`capture-review-debts` pós-B8+: `scripts/lib/topology.mjs` resolve por precedente onde o helper da F2 vive — `scripts/lib/`, não `src/lib/`; 2026-07-26 pós-B8 F2: 5º call site; 2026-07-20 pós-A8: `build-bahia-demographics.mjs` reforça o gatilho da F2 como 4º call site) Item do roadmap: [docs/roadmap.md](../roadmap.md) (Trilha B, item B5) Responsável: — @@ -35,7 +35,7 @@ Este plano é o registro canônico desses follow-ups. Sem ele, o B3 pode embarca ## 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. +- ~~**Onde vive o helper de cache CLI?**~~ **RESOLVIDO POR PRECEDENTE (`capture-review-debts` pós-B8+, 2026-07-27):** `scripts/lib/`. O B8+ precisou compartilhar a política de escala de chão entre os dois scripts de geometria e criou **`scripts/lib/topology.mjs`** — o primeiro módulo da pasta. A F2 **pousa nele** (`scripts/lib/cached-download.mjs`) em vez de abrir um segundo endereço: dois lares para código de CLI é exatamente a duplicação que esta fase existe para remover. A recomendação anterior (`src/lib/cliCachedDownload.ts`) fica **rejeitada** — `src/lib/` é client-safe por contrato (`.cursor/rules/codebase-map.mdc`) e um helper que faz `mkdir`/`fetch`/`writeFile` não pertence a uma pasta que o bundle do browser pode alcançar, mesmo que hoje ninguém o importe de lá. - **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 diff --git a/docs/plans/escala-dry-pos-b8f2.md b/docs/plans/escala-dry-pos-b8f2.md index 8eb3b090..5aa89fe9 100644 --- a/docs/plans/escala-dry-pos-b8f2.md +++ b/docs/plans/escala-dry-pos-b8f2.md @@ -135,6 +135,7 @@ Componentes: - **Helper `createCampaignUser` para os e2e** — a criação inline de `campaignUser` está na 19ª cópia (`campaignZoneMap.e2e.spec.ts:1618-1629` é a mais nova), e o int já tem o helper (`tests/helpers/campaignFixtures.ts:542-559`). Pré-existente em `main` e inerte, portanto fora deste lote. Revisitar quando: o próximo spec e2e nascer — ele paga o helper em `campaignE2EFixtures.ts` e migra os vizinhos que tocar. - **Genérico para `MunicipalityZoneGeometryModule`/`MunicipalityGeometryModule`/`TerritoryGeometryModule`** com `getFeature(key)` uniforme. Revisitar quando: **a 4ª malha** entrar — a três, o rename atravessa `municipalityProximity.ts`, dois int specs e um e2e por ganho estético. - **Um único laço sobre `municipalities` em `municipalityMapData.ts`** (hoje quatro, cada um chamando `mapKeyForMunicipality`). Revisitar quando: o bundle ganhar um 5º campo por município — abaixo disso, juntar o laço histórico com o de cenários custa legibilidade e economiza microssegundos. +- **A grade de quantização é exata em um eixo só** (achado do revisor de perf no `/simplify` desta entrega, 2026-07-27). `quantize` aceita **um** número de dígitos e o aplica aos dois eixos, então `GROUND_GRID_METRES` é honrado em longitude e a latitude segue o aspect ratio do bbox: medido, **102,8×109,2 m** nas duas malhas estaduais e **102,9×80,1 m** na de Salvador. Ancorar em X não é acidente — é o que mantém `bahia-municipalities.topo.json` byte-idêntico ao build pré-política, que é a prova de que F1 não mexeu na malha que todo mundo baixa. Tornar os dois eixos exatos exige passar um `{scale, translate}` explícito e **reescrever os três artefatos**, perdendo essa prova por um erro de ±9% num eixo, num mapa que para em `maxZoom: 10`. Registrado, não corrigido: o comentário de `quantizeDigitsFor` carrega o número e `describeGroundScale` imprime os dois passos em todo build. Revisitar quando: uma malha precisar de precisão métrica isotrópica (medida de área/distância **a partir do artefato**, não da fonte) — ou de graça, se algum outro motivo já obrigar a reescrever os três artefatos. ## Explicitamente fora (descartes deste triage)