Gate 2026-08-01: sem título de seção; geo só se permission granted; fatia em três entregáveis confirmada. Planos ready com Issue #N.
7.3 KiB
Empty state do wizard — município mais próximo (geo)
Status: ready
Atualizado em: 2026-08-01
Issue: #94
Priority: P2
Model: composer-2.5
Impeccable: B — 1 linha prefixada no empty de WizardMunicipalitySearchStep (após B92)
Appetite: ~1 dia eng; reuso B14 (campaignGeolocation + municipalityProximity) no idle do wizard; sem migration / Consent
Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md (Feel the action) / DESIGN.md · tema campaign · B14 NearestMunicipalityCard · B92 chassis · B93 merge order.
Na implementação: craft compacto → critique → polish. Gatilho harden se permission/prompt edge cases vazarem copy inconsistente com B14.
Brief compacto:
- Persona: staff em deslocamento (carro/praça) abre uma ação no celular e quer o município onde está.
- Job principal: no idle, um toque no “mais próximo” avança o wizard com o município resolvido.
- Estratégia de cor: Restrained; reason “Perto de você” / distância se B14 já formata.
- Edit where you see: não.
- Anti-goals: mapa embutido no wizard; POST de lat/lng; Consent novo; prompt agressivo a cada abertura de ação; card GPS gamificado.
Wireframe (texto)
┌─ Wizard passo município (idle) ────────────────────────┐
│ [input…] │
│ · Salvador — ZE 5 · … · Perto de você (~1,2 km) │
│ · … (B93 continuity) │
│ · … (B92 esquecidos) │
└────────────────────────────────────────────────────────┘
Sem título de seção. Só resolve se permission já granted
(prompt de geo já ocorre ao abrir o Quadro — produto 2026-08-01).
Sem permissão / fora da BA / unsupported: linha some.
Dados → decisão → apresentação
- Vou apresentar dados? Sim — 0–1 município resolvido por geo no escopo do ator.
- Decisões: “executo a ação aqui (onde estou)?”
- Forma: uma linha na lista (pobre). Rejeitado: card “Onde estou” duplicando o Quadro; mapa Leaflet no passo.
- Profile: 1 item; client-only position; match contra malha já usada em B14.
- Anti-goals: sem transmitir posição ao servidor; sem reverse-geocode vendor.
Contexto
B14 ✓ no Quadro (NearestMunicipalityCard): posição no browser, containment na malha municipal (+ ZE Salvador), fallback Haversine, prompt 1× por sessão de aba, sem Consent.
O pedido (2026-08-01) inclui o mesmo sinal no empty do wizard. O passo 1 hoje não carrega geometrias nem lista AccessibleMunicipality — B92 traz hits server; este item acrescenta a resolução client e o slot no merge (ordem: geo → continuity B93 → esquecidos).
Objetivos
- No idle do wizard, tentar resolver município mais próximo no escopo do ator reusando
requestCurrentPosition/resolveNearbyMunicipality/ loaders lazy de geometria. - Página
acoes/[slug](passo busca) passa propaccessibleMunicipalities: AccessibleMunicipality[](slug/name/ibgeCode) a partir do scope — ou o client usa só os slugs do suggest B92 mais um payload mínimo RSC (recomendação: prop RSC, porque suggest é top-8 e o nearest pode estar fora do top frio). - Só resolve se a permissão já está
granted(gate 2026-08-01): o prompt de geo já ocorre ao abrir (Quadro B14). Wizard não dispararequestCurrentPositionemprompt/denied/unknown— zero surpresa no ritual. - Falhas / não-granted / fora da BA / outOfScope sem nearest: silêncio — não montar linha de erro nem CTA; usuário digita.
kind: 'inScope'→ uma hit row com reason; select = auto-avanço.- Sem migration / Consent / POST de coordenadas.
Decisões travadas
- Client-only matching (paridade B14). Rejeitado: POST lat/lng; PostGIS; artefato de centroides commitado (já revertido em B14).
- Prop RSC de municípios acessíveis para o matcher (não só top-8 do suggest). Rejeitado: resolver só dentro dos 8 esquecidos (falso “perto” se o município real ficou de fora do rank frio).
- Geo no wizard = só
granted(produto 2026-08-01). Prompt já foi dado ao abrir o app/Quadro; não re-pedir nem CTA no ritual. Rejeitado: prompt automático no mount do wizard; CTA “Usar localização” neste item. - Fail soft sem UI de erro no wizard. Ritual não deve virar troubleshooting de GPS. Rejeitado: copiar o card B14 inteiro para dentro do shell.
- Uma linha, não card; sem título de seção. Rejeitado: embutir
NearestMunicipalityCard; heading “Prováveis”. - Salvador multi-ZE
zoneCity/ ambíguo: omitir a linha — wizard exigemunicipalityatômico. Rejeitado: deep-link para lista filtrada (sai do ritual). - i18n: reusar
formatDistanceKm; reason “Perto de você”; helpersuseWizardNearestMunicipalityse o efeito merecer nome (senão lógica no step até extrair no 2º call site).
Questões em aberto
- Nenhuma após gate 2026-08-01.
Abordagem proposta
flowchart LR
Page["acoes/slug page RSC"] --> Prop["accessibleMunicipalities"]
Prop --> Step["WizardMunicipalitySearchStep"]
Step --> Geo["permission + position B14 utils"]
Geo --> Mesh["lazy bahiaGeometries + zones"]
Mesh --> Resolve["resolveNearbyMunicipality"]
Resolve --> Merge["slot geo no merge B93/B92"]
Componentes:
acoes/[slug]/page.tsx: ao renderizar o search step, carregar scope enxuto (id/slug/name/ibgeCode) e passar como prop.- Ilha no step / hook: permission + optional locate; dynamic import geometria; resolver; emitir
{ slug, reason, distanceKm? }ounull. - Merge (contrato com B93): fonte
geotem precedência máxima de ordenação. - Reuse:
campaignGeolocation.ts,municipalityProximity.ts,loadMunicipalityGeometryModule,formatDistanceKm. - Migration: nenhuma. Consent: nenhum.
Dependências
- Dura: B92.
- Soft: B93 (merge order — se B94 landar antes, step aceita geo sem continuity; merge helper pode nascer em qualquer um e o outro consome).
- Soft: B14 ✓.
Não escopo
- Continuity → B93.
- Ranking esquecidos → B92.
- Mudanças no card do Quadro.
- Geo para
leader.
Rabbit holes
- Extrair
NearestMunicipalityCard→ package compartilhado pesado. Mitigação: reusar utils puros; UI do wizard é uma hit row. - Prefetch da malha no Início para o wizard. Mitigação: lazy no mount do step; memo do módulo já ajuda se Quadro carregou antes.
Adiado com gatilho
- CTA “Usar localização” quando permission ≠ granted. Revisitar se sessão observada pedir botão explícito no wizard (hoje o prompt vive só no Quadro).
- Centroid artifact só se o lazy da malha pesar no mid-tier Android em campo.
Referências
- GitHub Issue #94
municipio-mais-proximo.md(B14)campaignGeolocation.ts·municipalityProximity.tswizard-municipio-sugestoes-chassis.md(B92)- AGENTS.md — sem Consent para geo local autenticada (B14)