teqo-backup/docs/plans/wizard-municipio-sugestoes-geo.md
Cursor Agent c53add3f8f
docs: registra B92–B94 (Issues #92–#94) pós-gate
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.
2026-08-01 06:57:30 +00:00

7.3 KiB
Raw Blame History

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 prop accessibleMunicipalities: 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 dispara requestCurrentPosition em prompt/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 exige municipality atômico. Rejeitado: deep-link para lista filtrada (sai do ritual).
  • i18n: reusar formatDistanceKm; reason “Perto de você”; helpers useWizardNearestMunicipality se 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? } ou null.
  • Merge (contrato com B93): fonte geo tem 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