teqo-backup/docs/plans/busca-municipio-wizard.md
Francisco Ignácio Fontoura Solla 72084f1e56 docs: registrar planos B59–B63 dos wizards UX-1 no Início.
Detalha chassis, busca de município, ajuste de votos, simplificação do sinal e fluxo de registro; atualiza o rascunho de fluxos e o roadmap.
2026-07-29 15:43:15 -03:00

5 KiB
Raw Blame History

Etapa de busca de município nos wizards

Status: rascunho Atualizado em: 2026-07-29 Item do roadmap: docs/roadmap.md (Trilha B, item B60 — UX-1 wizards) Impeccable: B — encaixe da UX da busca do Início (B47/B48) numa etapa de wizard, só municípios Appetite: ~1 dia eng; input + lista de hits + auto-avanço; soft reuso do loader B48 Responsável: —

Design (Impeccable)

Âncoras: PRODUCT.md / DESIGN.md · B47 CampaignHomeSearch / B48 linhas de município · tema campaign.

Na implementação: craft compacto → critique → polish.

Brief compacto:

  • Persona: CG digita “Cairu” no meio do ritual A1/A2 e quer o município em 1 toque.
  • Job principal: achar o município no escopo do ator e avançar sozinho ao selecionar.
  • Estratégia de cor: Restrained.
  • Edit where you see: não — seleção é navegação de fluxo.
  • Anti-goals: grupos (TI/lideranças/…); botão “Continuar” após selecionar; card por linha.

Dados → decisão → apresentação

  • Vou apresentar dados? Sim — hits de município (nome, TI, opcional “2022” se B48 já tiver o readout).
  • Decisões: escolher qual município entra no fluxo.
  • Forma: lista ranqueada por nome (word-start), igual espírito B48. Rejeitado: mapa; grupos multi-entidade.
  • Profile: scoped ao access; tipicamente <20 hits.
  • Anti-goals de dado: sem inventar métrica; sem TIs neste passo (wizard precisa de unidade operacional municipality).

Contexto

No Início, B47 ✓ entrega input + modo focado; B48 lista Municípios (+ TIs no mesmo grupo). Nos wizards (pedido 2026-07-29): mesma experiência de busca, com duas diferenças — (1) sem grupos: só municípios; (2) selecionar = avançar ao próximo passo, sem confirmar.

Serve A1 (votos), A2 (sinal), A3/A4/A5 e qualquer fluxo que precise de local cedo (fluxos-acao-primeiro-inicio.md § contrato #2).

Objetivos

  • Etapa reutilizável (ex. WizardMunicipalitySearchStep) montada no B59: input debounce (mesmo espírito 250 ms de B47), lista de hits apenas municipality, escopo overrideAccess: false.
  • Clique/Enter no hit → callback/router.push para o próximo passo com município escolhido (slug ou id na URL/query do fluxo).
  • Sem botão “Continuar” / “Confirmar município”.
  • Recentres / prioritários opcionais acima da busca (soft; cortável) — 3 recentes se recentVisits já existir no Início.
  • Match: matchesAtWordStart / normalizeSearchPhrase (lib/wordStartFilter.ts).
  • Sem migration / Consent.
  • Se B48 já tiver searchHomeMunicipalities, filtrar/omitir TIs e reusar o loader; senão, loader mínimo só de municípios (depth: não duplicar fuzzy).

Decisões travadas

  • Só municípios — TIs fora deste passo (wizard grava em municipality). Rejeitado: copiar B48 com TIs (não há municipality para um TI).
  • Select = auto-avanço. Rejeitado: seleção + “Continuar” (pedido explícito; atrito no ritual).
  • Mesma linguagem visual da busca do Início (linha sem card, tipografia). Rejeitado: Command/Combobox de lista (B27) como UI primária — é outro modelo mental.
  • i18n: WizardMunicipalitySearch, copy “Em qual município?”.

Questões em aberto

  • Mostrar votos 2022 à direita no wizard? Opções: A sim (paridade B48) | B só nome+TI. Recomendação: B no v1 se B48 ainda não landou; A quando o readout existir e não atrasar o appetite. (assumido)

Abordagem proposta

flowchart LR
  Shell["B59 Shell"] --> Input["input debounce"]
  Input --> Loader["searchMunicipalitiesScoped"]
  Loader --> Hits["lista só município"]
  Hits -->|select| Next["próximo passo + slug"]

Componentes:

  • WizardMunicipalitySearchStep (client island): input + results; registra seleção.
  • Loader — reuso B48 ou utilities/municipality/ com overrideAccess: false.
  • Reuso: useHomeSearchQuery pattern / debounce B47; não importar o chrome focado do Início inteiro.
  • Migration: Sem migration.

Dependências

  • Dura: B59. Soft: B48 (UX/loader), B47 ✓ (debounce/modo focado como referência).

Não escopo

  • Grupos lideranças/assessores/… → B49–B53 (só Início). Ajuste de votos → B61. Chassis → B59.

Rabbit holes

  • Um único componente de busca para Início e wizard. Mitigação: compartilhar loader + row renderer; chrome (grupos vs só município, onSelect vs Link) fica nos wrappers — extrair shared só com 2 call sites reais medidos.

Adiado com gatilho

  • Chips de recentes/prioritários acima do input. Revisitar se o CG pedir atalho sem digitar (sessão).

Referências