# B14 — Município mais próximo (acesso rápido por geolocalização) Status: entregue (2026-07-26); débito B8 F2-D1 (ZE exata em Salvador) fechado em 2026-07-29 Atualizado em: 2026-07-29 Item do roadmap: [docs/roadmap.md](../roadmap.md) (Demais itens abertos, B14; superfície de coordenação) Impeccable: B — encaixe no dashboard staff (`/campanha`), sem rota nova Appetite: ~1 dia eng (gasto ~0,75d: o artefato de centroides e seu script saíram do escopo); ilha cliente no Início; sem migration, sem collection, sem Consent Responsável: — ## Como ficou (as-built, 2026-07-26) O casamento é **point-in-polygon**, não centroide: a premissa do plano original (polígonos explodem o bundle) caiu ao medir o repositório de hoje — [`MunicipalityMapPanel`](../../src/components/campaign/map/MunicipalityMapPanel.tsx) monta sempre em `mode="municipality"` e `BahiaMap` chama `loadMunicipalityGeometryModule()` no mount, então os 417 polígonos (132 KB crus, **41 KB gzip**, chunk próprio memoizado) já estão no browser de quem abre `/campanha`. Com isso o card responde "o município **onde estou**" em vez de "o mais próximo", e caíram do escopo `pnpm build:municipality-centroids`, `src/lib/municipalityCentroids/` e o snapshot test do artefato. Centroide sobrevive apenas como critério de ordenação do fallback (`featureCentroid` + Haversine), onde errar por quilômetros não muda a decisão. Entregue: - [`src/lib/municipalityProximity.ts`](../../src/lib/municipalityProximity.ts) — matemática pura sobre as features que o chamador já tem: `haversineKm`, ray casting com buracos (`featureContainsPoint`), `featureCentroid` (média ponderada por área) e `resolveNearbyMunicipality` devolvendo união discriminada `inScope | zoneCity | outOfScope | outsideBahia`. Carteira vazia **não** é um caso desta função: o card não renderiza nem pede posição nessa situação, e duplicar a política aqui custava ramos inalcançáveis (removido no `/simplify`). - [`src/utilities/campaignGeolocation.ts`](../../src/utilities/campaignGeolocation.ts) — irmão de `recentVisits.ts`: flag `teqo:campaign:geo-prompted-session`, leitura de permissão guardada (Safari sem o descriptor → `unknown`, que é resposta normal) e `requestCurrentPosition` com falha tipada. `COARSE_ACCURACY_M = 10 km` separa fix de aparelho de chute de rede. - [`NearestMunicipalityCard`](../../src/components/campaign/dashboard/NearestMunicipalityCard.tsx), ao lado de `RecentlyVisitedCard` numa linha de duas colunas escrita **direto em `CampaignDashboard`** e escondida em CSS (`hidden … has-[>*]:grid`) quando os dois cards renderizam `null`. Houve um wrapper `DashboardShortcuts` no meio do caminho; sem estado nem lógica ele era só um `div`, e o `/simplify` o inlinou. - `StaffDashboardView` publica `accessibleMunicipalities` (slug/name/ibgeCode); o href da lista de zonas é serializado por `CampaignDashboard` (o RSC que já monta hrefs de lista) e desce como prop `zoneCityHrefs` — o loader Payload não guarda URL. **Decisão de produto nova (usuário, 2026-07-26):** assessor fisicamente fora da carteira é informado de onde está **e** recebe o município mais próximo que pode abrir, com a distância; acima de 150 km (`NEAREST_IN_SCOPE_MAX_KM`) a sugestão vira ruído e o card diz que não há nada por perto. **Medições (as-built).** Payload RSC de `/campanha` com 435 entradas: ~6,6 KB gzip — abaixo do teto de ~10 KB do plano, então o campo ficou como objetos legíveis em vez de tuplas. First Load JS de `/campanha`: **265 kB → 268 kB**. A primeira versão chegou a 286 kB porque o card chamava `buildMunicipalityListHref` para o link das zonas de Salvador, e o serializador canônico arrasta `bahiaTerritories` + `municipalityCatalog` (que puxa códigos IBGE e zonas TSE) para o bundle do cliente: **21 kB por um único link**. Corrigido serializando o href no servidor (`zoneCityHrefs`, chaveado por IBGE, uma entrada só quando o ator enxerga mais de uma zona da cidade) — a regra "client components não importam módulos de dado do servidor para obter valores" também vale para serializadores de URL. No `/simplify` esse cálculo saiu do loader `server-only` para `CampaignDashboard`, reusando `buildMunicipalitiesByIbgeCode` (o índice por código IBGE que o painel do mapa já usa) em vez de contar linhas à mão. **Medições de CPU (feitas no `/simplify`, sobre o artefato real — não estimadas).** A malha decodifica em **417 features, todas `Polygon` simples**: 417 anéis, **zero buracos, zero MultiPolygon**, 15.111 pares de coordenadas, anel mais longo com 147 pontos. Varredura point-in-polygon completa (o caminho "fora da Bahia", sem acerto): **0,106 ms**; até acertar Salvador: 0,143 ms; `resolveNearbyMunicipality` inteiro com carteira de 435: **0,32 ms**, dos quais 0,26 ms são os 417 centroides. Com penalidade de 6× para celular médio, ~2,6 ms — **um oitavo de um frame**, então não há caminho quente aqui e o artefato de centroides continuaria sem se pagar. Construir um `Map` novo por chamada mediu **0,337 ms, mais lento** que o `find`; o índice `getMunicipalityFeature` é usado porque o módulo **já o construiu** para o mapa, não como otimização. Chunk de geometria no build: 134.488 B crus / **42.158 B gzip**, referenciado por um único arquivo (o chunk da página), confirmando um download e um decode (1,69 ms) para os dois consumidores. O que muda com o card é o **agendamento**: a geometria passa a ser pedida na hidratação da página, competindo com Leaflet (42.675 B gzip), em vez de só depois do chunk do painel. Aceito — mas **não** porque o `Promise.all` esconderia o decode atrás do fix de GPS: o decode roda no topo do módulo, ou seja, quando o chunk baixa e executa, independente do fix. Ele é aceito porque é **barato** (`JSON.parse` 1,62 ms + `topojson.feature()` 0,41 ms ≈ 2 ms no desktop, ~10 ms num celular 5× mais lento — abaixo da barra de 50 ms de long task) e porque a alternativa sequencial (fix primeiro, geometria depois) é **pior** no caso comum: com `maximumAge` de 5 min um fix em cache volta em milissegundos e aí os 42 KB cairiam inteiros no caminho crítico do card. O download também nunca é especulativo — `MunicipalityMapPanel` monta sempre em `mode="municipality"`, então todo staff em `/campanha` precisa desse chunk de qualquer forma. **Débito registrado (não corrigido aqui).** As 435 linhas de `accessibleMunicipalities` (~6,6 KB gzip) duplicam o `municipalitiesByIbgeCode` que `MunicipalityMapBundle` já serializa na mesma página, a partir do mesmo `loadMunicipalityScope`. Unificar exige mexer na fronteira de Suspense do mapa (o painel só monta atrás dela, e pode ser `null`), o que é reestruturação, não limpeza. Tuplas em vez de objetos economizariam apenas 398 B gzip — medido, e não vale o tipo auto-descritivo. A 3ª rodada de `/simplify` afiou o caminho da correção: publicar `MunicipalitiesByIbgeCode` no lugar do array plano faria `resolveNearbyMunicipality` trocar o `filter` sobre 435 linhas por uma busca por chave, e a página pararia de montar o mesmo agrupamento duas vezes (`buildZoneCityHrefs` reconstrói o índice a partir do array). Só que exige mover `municipalityMapNavigation.ts` para `src/lib/` — hoje em `utilities/` **sem nenhum import**, portanto já puro e mal-alojado — e tocar os importadores do domínio do mapa. Continua reestruturação, não limpeza. ## Design (Impeccable) Âncoras: `PRODUCT.md` (princípios 2 — clareza sob pressão — e 8 — Feel the action) / `DESIGN.md` (register `product`; Field Desk) · tema `data-theme='campaign'` · precedente de ilha client-side [`RecentlyVisitedCard`](../plans/visitados-recentemente.md). Na implementação (`implement-roadmap-item`): craft compacto → critique → polish. Brief compacto: - **Persona / contexto:** assessor ou CG em campo (telefone, deslocamento entre municípios), abrindo o Início sob pressão de tempo — precisa chegar na ficha do município onde está sem digitar na lista. - **Job principal:** com um toque, abrir o município operacional mais próximo da localização atual. - **Estratégia de cor:** Restrained — card/atalho sóbrio ao lado de "Visitados recentemente", sem mapa embutido nem badge de GPS gamificado. - **Edit where you see:** não — só leitura/navegação (atalho); sem mutação de dados. - **Anti-goals:** segundo mapa; lista "próximos N" tipo Places; sync de localização no servidor; prompt de permissão em loop; superfície para `leader` (lockdown). ## Dados → decisão → apresentação - **Vou apresentar dados?** Sim, superfície neste item — um resultado geo (município mais próximo ± distância opcional), não série/KPI eleitoral. - **Decisões desbloqueadas:** - Staff (assessor/CG/candidato): "abrir agora a ficha do município em que estou (ou o mais próximo no meu escopo)?" - **Forma escolhida:** **número + contexto mínimo** (nome do município + CTA "Abrir" + distância relativa opcional, ex. "~8 km") — **por quê:** uma decisão, um destino; degrau mais pobre que resolve. **Rejeitado:** mapa de proximidade (já há mapa no Início com outro job); ranking dos 5 mais próximos (ruído); chart/gauge. - **Profile:** geo pontual → 1 entidade do catálogo (ou lista filtrada Salvador); tamanho típico = 1 sugestão; absoluto (km) só como contexto de confiança, não como KPI. - **Anti-goals de dado:** sem telemetria de posição; sem choropleth de "densidade de visitas"; sem % estadual. Self-check dados: 5/5. ## Contexto O Início staff já oferece mapa, KPIs, filas curtas e **Visitados recentemente** (histórico local). Em deslocamento, o atalho que falta é "onde estou → ficha do município". O catálogo tem 435 unidades (`municipalityCatalog.ts`); Salvador é 19 Municípios-zona com o mesmo IBGE — a proximidade por centroide de município IBGE não desambigua ZE. Geolocalização é API do browser (`navigator.geolocation`); a posição **não precisa** ir ao servidor se o matching for client-side sobre um artefato de centroides. Decisão de produto (2026-07-24, pedido explícito): sugerir acesso rápido ao município mais próximo e, **uma vez por sessão**, pedir automaticamente a permissão de localização se ainda não houver. ## Objetivos - No dashboard staff (`/campanha`), card/atalho **"Município mais próximo"** (ou copy equivalente) com link para `/campanha/municipios/[slug]` (ou lista filtrada quando a cidade for multi-zona). - **Uma vez por sessão de aba:** se a permissão de geolocalização ainda não estiver concedida/negada de forma estável, disparar automaticamente o pedido do browser; marcar em `sessionStorage` que o prompt automático já ocorreu (não repetir na mesma sessão). - Se a permissão já estiver `granted`, resolver a posição sem prompt e mostrar a sugestão. - Se `denied` / indisponível / fora da Bahia / sem match no escopo: card ausente ou estado curto com CTA manual "Usar minha localização" (sem loop de prompt). - Matching **só no cliente**; coordenadas nunca enviadas a server actions/API Payload. - Filtrar candidatos ao **escopo de acesso** do ator (advisor: só municípios administrados; coordinator/candidate: catálogo completo do que a UI já enxerga). - Sem migration, sem collection, sem server action de escrita, sem nova chave `Consent`. - Staff only; `leader` permanece no `LeaderContactsPanel` (sem mudança). ## Decisões travadas - **Client-only, casando contra a malha que o mapa já carrega (sem modelo no servidor).** Posição fica no browser; containment por point-in-polygon sobre o chunk memoizado de `bahiaMunicipalityGeometries`, e Haversine sobre centroides derivados na hora só para ordenar o fallback. Análogo a visitados recentes. **Rejeitado:** POST de lat/lng ao servidor (PII de localização + Consent + superfície de abuso); reverse-geocode comercial (custo/vendor); PostGIS (fora de escopo do AGENTS.md sem query espacial real); **artefato commitado de centroides** — era a decisão de 2026-07-24 e foi revertida em 2026-07-26 por ser menos precisa a custo de bundle zero (o chunk já está no browser). - **Prompt automático no máximo 1× por sessão (`sessionStorage`).** Cumpre o pedido de produto sem martelar o usuário a cada navegação no Início. Chave estável: `teqo:campaign:geo-prompted-session`. **Rejeitado:** prompt a cada mount do card; `localStorage` "nunca mais perguntar" como único gate (impediria retry legítimo em sessão nova após o usuário mudar a permissão no SO). - **Sem `Consent` / sem lote jurídico.** Tratamento local da própria localização do usuário autenticado, sem transmissão — mesmo racional de visitados. **Rejeitado:** chave `Consent` só para UX de GPS (multiplica lead time jurídico sem dado no servidor). - **Malha de matching = município IBGE (417), depois ZE em Salvador (B8 F2).** Containment na malha municipal; cidades multi-zona usam `bahia-municipality-zones` quando o card carrega o chunk — link direto à ZE acessível, ou ZE mais próxima (≤ `NEAREST_ZONE_MAX_KM` = 30 km), ou lista filtrada (`zoneCityHrefs`). **Rejeitado:** chute de ZE sem polígonos; lista sempre. - **Staff only no Início.** Leader lockdown intacto. **Rejeitado:** expor municípios ao leader via atalho geo. - **i18n e naming:** identificadores em inglês (`NearestMunicipalityCard`, `municipalityProximity`, `resolveNearbyMunicipality`, `GEO_PROMPT_SESSION_KEY`); strings visíveis em pt-BR (título "Onde estou", "Abrir ", "Usar minha localização", "Ver zonas de Salvador"). - **Precisão declarada, nunca escondida.** Fix com raio acima de 10 km (rede/IP, típico de desktop) mostra o resultado com a ressalva "Localização aproximada — confira o município antes de agir", entre o título e o CTA. **Rejeitado:** descartar o fix grosseiro (o município costuma estar certo) e confiar nele em silêncio (nomear o município errado com confiança total é o pior dos dois). ## Questões em aberto Todas resolvidas na entrega: - **Posição no Início:** B — o card fica ao lado de `RecentlyVisitedCard` (`grid gap-6 lg:grid-cols-2`, primeiro no mobile), e a linha inteira desaparece quando os dois cards não têm o que dizer. - **Mostrar distância em km?** Só no fallback ("Mais próximo na sua carteira: X, a 38 km"). Quando o ponto cai **dentro** de um município não há distância a mostrar — containment não é aproximação. - **Limiar "fora do teatro"?** 150 km do centroide para a sugestão de carteira (`NEAREST_IN_SCOPE_MAX_KM`). Fora da malha da Bahia o card diz que está fora, e só oferece atalho se houver algo dentro desse raio. ## Abordagem (como implementada) ```mermaid flowchart LR Scope["loadMunicipalityScope
(slug, name, ibgeCode)"] --> View["StaffDashboardView
accessibleMunicipalities"] View --> Hrefs["CampaignDashboard (RSC)
zoneCityHrefs"] Hrefs --> Card View --> Card["NearestMunicipalityCard
(client island)"] Card --> Perm["permissions + sessionStorage
prompt 1x por sessao"] Perm --> Fix["getCurrentPosition"] Fix --> Geo["loadMunicipalityGeometryModule
(chunk compartilhado com o mapa)"] Geo --> Resolve["resolveNearbyMunicipality
(point-in-polygon + fallback)"] Resolve --> Link["Link /campanha/municipios/[slug]
ou lista filtrada (Salvador)"] ``` Componentes: - **`src/lib/municipalityProximity.ts`** (puro, client-safe, recebe a malha já carregada — `features` + o índice memoizado `getMunicipalityFeature` — em vez de importar geometria ou re-varrer as 417 features por município da carteira): `haversineKm`, `featureContainsPoint`, `featureCentroid`, `findContainingMunicipality`, `resolveNearbyMunicipality`. - **`src/utilities/campaignGeolocation.ts`**: flag de sessão, permissão guardada, `requestCurrentPosition` com resultado tipado (`denied | unavailable | timeout | unsupported`). - **`NearestMunicipalityCard`** (`src/components/campaign/dashboard/`, `'use client'`): - Props: `{ accessible: { slug, name, ibgeCode }[]; zoneCityHrefs }` — nada de doc Payload inteiro, nada de serializador de URL no cliente. - No mount: estado `starting` (explicação sem CTA, para não convidar um toque que dispararia um segundo pedido de posição), lê permissão; `granted` resolve silencioso; `prompt`/`unknown` ainda não perguntado na sessão → **uma** chamada e marca a flag; `denied` → estado acionável com "Tentar de novo", sem re-prompt. Guarda de `useRef` para o Strict Mode não pedir posição duas vezes. - Pending honesto (`aria-busy` + spinner) e um `aria-live="polite"` `sr-only` montado desde o início, para o desfecho ser anunciado. - **Encaixe** em `CampaignDashboard.tsx`; `page.tsx` já separa staff de leader. - **Sem migration, sem collection, sem server action.** ## Dependências - Nenhuma dura de outro item aberto. Reusa B2 (TopoJSON), catálogo `municipalityCatalog.ts`, shells do dashboard, padrão client-storage de visitados. - **Suave:** **B8 F2** (polígonos das ZE de Salvador) — quando existir, permite point-in-polygon para desambiguar ZE; até lá, lista filtrada Salvador. ## Não escopo - Geolocalização para `leader` / ferramenta de contatos. - Enviar ou armazenar posição no servidor / analytics. - Navegação turn-by-turn, ranking dos N mais próximos, mapa de "perto de mim". - Matching por seção eleitoral ou bairro (fora de escopo AGENTS; B8 F2 é zona Salvador apenas). - Pedir permissão em outras rotas além do Início staff (v1). ## Rabbit holes - ~~**Point-in-polygon no client com TopoJSON completo.** Explode bundle e conflita com lazy do mapa (B5).~~ **Não era rabbit hole:** o dashboard já monta o mapa, que carrega o mesmo chunk memoizado no mount. O card reusa `loadMunicipalityGeometryModule()` e não adiciona um byte de geometria. O rabbit hole real, encontrado ao medir, foi **importar o serializador da lista** no cliente (+21 KB) — resolvido serializando o href no servidor. - **"Completar" Salvador por ZE sem malha.** Chute de ZE erra operação de campo. **Mitigação:** lista filtrada até B8 F2. - **Abstração genérica de "location services".** Um card, um helper. **Mitigação:** sem provider/context até 3º call site. - **Consent/RIPD por precaução.** Sem dado no servidor não há lote jurídico. **Mitigação:** boundary explícito no plano; se no futuro houver sync, aí sim Consent + defer. ## Adiado com gatilho - ~~**Desambiguação Salvador ZE por ponto-em-polígono.**~~ **Resolvido 2026-07-29** (débito B8 F2-D1): `NearestMunicipalityCard` carrega `loadMunicipalityZoneGeometryModule()` de forma opcional; falha do chunk degrada para `zoneCity`. - **Atalho também na lista `/campanha/municipios`.** Revisitar quando: evidência de uso no Início (campo pede o mesmo atalho na lista). - **Lembrar última sugestão em `sessionStorage` para paint imediato.** Revisitar quando: critique acusar flash/vazio perceptível no card. _(Não acusou: o chunk de geometria costuma estar resolvido antes do fix chegar.)_ - **Atalho geo também para `leader`.** Permanece fora: liderança não sai do `LeaderContactsPanel`. - **Reusar a navegação do mapa no branch `inScope|zoneCity|outOfScope`.** Revisitar quando: um 3º chamador precisar do `zoneCount`/da entrada casada. Encerrado como reuso possível pelo **B8+** F4: `resolveMunicipalityMapNavigation` e sua união de estados morreram — o mapa lê `municipalitiesByMapKey[key]` direto, um `Record` que não carrega nada do que este card precisa. - **Helper compartilhado para flags de sessão (`sessionStorage`).** Revisitar quando: nascer a 3ª flag. Hoje são duas (`campaignGeolocation` e `InstallPwaToast`) e elas **discordam de propósito** no fallback de leitura — em modo privado o geo suprime o prompt automático e o toast continua aparecendo —, o que é a maior parte do que o helper faria. ## Referências - `docs/roadmap.md` (B14; Demais itens abertos; grafo; cortes) - [visitados-recentemente.md](visitados-recentemente.md) — precedente client-storage + card no dashboard - [poligonos-pracas-zona.md](poligonos-pracas-zona.md) — B8 F2 (gatilho Salvador ZE) - [mapa-bahia-geometrias.md](mapa-bahia-geometrias.md) — TopoJSON fonte dos centroides - `src/components/campaign/dashboard/CampaignDashboard.tsx`, `RecentlyVisitedCard.tsx`, `src/utilities/recentVisits.ts` - `src/lib/municipalityCatalog.ts`, `src/lib/bahiaMunicipalityCodes.ts`, `src/lib/bahiaGeometries.ts`, `src/lib/geometries/bahia-municipalities.topo.json` - Testes: `tests/unit/municipalityProximity.unit.spec.ts`, `tests/unit/campaignGeolocation.unit.spec.ts`, `tests/int/bahiaGeometries.int.spec.ts`, `tests/e2e/campaignNearestMunicipality.e2e.spec.ts` - `PRODUCT.md` / `DESIGN.md` — Field Desk, clareza sob pressão, Feel the action - AGENTS.md — leader lockdown, naming, sem PostGIS sem query espacial, artefatos commitados via script (não no `pnpm build`)