mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-20 18:24:45 +00:00
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.
96 lines
5 KiB
Markdown
96 lines
5 KiB
Markdown
# Etapa de busca de município nos wizards
|
||
|
||
Status: rascunho
|
||
Atualizado em: 2026-07-29
|
||
Item do roadmap: [docs/roadmap.md](../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](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
|
||
|
||
```mermaid
|
||
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
|
||
|
||
- [busca-global-inicio-input.md](busca-global-inicio-input.md) · [busca-global-resultados-municipios.md](busca-global-resultados-municipios.md) · [chassis-wizard-campanha.md](chassis-wizard-campanha.md) · `lib/wordStartFilter.ts` · `recentVisits` utilities
|
||
- AGENTS.md — access advisor; `overrideAccess: false`
|
||
- `PRODUCT.md` / `DESIGN.md`
|