teqo-backup/docs/plans/wizard-municipio-sugestoes-continuity.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

126 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Empty state do wizard — continuity (visitados + última ação)
Status: ready
Atualizado em: 2026-08-01
Issue: #93
Priority: P2
Model: composer-2.5
Impeccable: B — prefixo client no empty de `WizardMunicipalitySearchStep` (após B92)
Appetite: ~0,75–1 dia eng; merge client de recentVisits + last-acted localStorage; sem migration
Responsável: —
## Design (Impeccable)
Âncoras: `PRODUCT.md` (Feel the action; Clarity under pressure) / `DESIGN.md` · tema `campaign` · B92 chassis · `recentVisits.ts` · Quadro `RecentlyVisitedCard`.
Na implementação: craft compacto → critique → polish.
Brief compacto:
- **Persona:** staff que **acabou** de mexer num município ou voltou ao ritual no mesmo aparelho — quer repetir o local sem re-digitar.
- **Job principal:** no idle do passo 1, ver no topo “onde eu estava / onde eu agi” antes dos esquecidos server.
- **Estratégia de cor:** Restrained; secondary discreto na linha (“Visitado”, “Última ação”).
- **Edit where you see:** não.
- **Anti-goals:** sync multi-dispositivo; POST de histórico ao servidor; misturar continuity com hits tipados; redesign do card do Quadro.
### Wireframe (texto)
```text
┌─ Wizard passo município (idle, pós-B92) ───────────────┐
│ [input busca…] │
│ · Itabuna · … · Última ação │
│ · Cairu · … · Visitado │
│ · Valença · … · Visitado │
│ · … (fill B92 esquecidos, dedup) │
└────────────────────────────────────────────────────────┘
Sem título de seção. Geo (B94) pode ocupar 1 slot acima.
```
## Dados → decisão → apresentação
- **Vou apresentar dados?** Sim — atalhos de continuidade (client) mesclados à lista server B92.
- **Decisões:** “volto ao município em que eu **agi** ou que **abri** há pouco?”
- **Forma:** mesmas linhas `HomeSearchHitRow` + secondary/reason curto. **Rejeitado:** seção separada com cards; timeline.
- **Profile:** 1 última ação + até ~3–5 visitados município; dedup com geo/esquecidos; cap total da lista ~8.
- **Anti-goals:** sem enviar `localStorage` ao servidor; sem PII além do que já vive no device (padrão visitados).
## Contexto
B92 entrega o idle com esquecidos server. O pedido de produto (2026-08-01) também pede: (a) **últimos municípios acessados**; (b) **último município em que o usuário executou qualquer ação**.
Já existe `teqo:campaign:recent-visits` (`recentVisits.ts`, Quadro). B68 **adiou** visitados no suggest do Início por hidratação — no wizard o idle já é client (`WizardMunicipalitySearchStep`), então o merge é natural **depois** do mount.
“Última ação” **não** tem índice server hoje (autores espalhados: `municipalityUpdate.author`, `votePledge.declaredBy`/`estimatedBy`, `campaignDemand.createdBy`, …). Índice unificado = migration/query cara. Neste item: **localStorage device-local**, escrito nos success paths dos wizards/actions de município.
## Objetivos
- Após mount, com `!query.isActive`: mesclar no topo da lista B92:
1. **Última ação** (0–1) — slug gravado em storage dedicado.
2. **Visitados recentes** (`kind === 'municipality'`) — extrair slug do `href`, filtrar ao escopo se o server já devolveu o universo **ou** validar contra hits suggest / lista acessível passada como prop.
- Dedup estável: geo (B94) > última ação > visitados > esquecidos B92; uma linha por slug.
- Reason labels pt-BR curtos na secondary ou trailing textual.
- Gravar `lastActedMunicipality` (nome final no craft) ao **sucesso** de writes do ritual (ajuste votos, sinal, tendência, liderança, demanda — paths que já fecham wizard com município). Fail-soft se storage bloquear.
- Sem migration / Consent / envio de lat-lng ou histórico ao server.
## Decisões travadas
- **Continuity 100% client (localStorage), não query server “last modified by me”.** Barato, mesmo padrão de visitados; cross-device fica Adiado. **Rejeitado:** UNION multi-collection por `author`/`declaredBy` neste appetite (latência + índices + access); collection `municipalityActorTouch` (migration cara sem evidência).
- **Gravar última ação no success do write, não no select do passo 1.** Select sem commit não é “executou ação”. **Rejeitado:** gravar no `router.push(?municipio=)` (falso positivo se abandonar).
- **Reusar `recentVisits` para acessos; storage separado para last-acted.** Semânticas diferentes (dwell 2s vs write). **Rejeitado:** sobrecarregar `RecentVisitEntry` com `kind: 'acted'`.
- **Merge só no idle; search tipado ignora continuity.** Paridade B68/B92.
- **Sem título de seção** (gate 2026-08-01) — só linhas na região de resultados, com reason na secondary.
- **i18n:** `campaignLastActedMunicipality` / `recordLastActedMunicipality` / `listWizardContinuitySlugs`; copy “Última ação”, “Visitado”.
- **Prefixo: 1 last-acted + até 3 visitados**; filtrar fora da carteira. Cap total da lista ~8 com B92/B94.
## Questões em aberto
- Nenhuma após gate 2026-08-01.
## Abordagem proposta
```mermaid
flowchart LR
Mount["client mount idle"] --> Server["hits B92"]
Mount --> Local["recentVisits + lastActed"]
Local --> Merge["mergeWizardMunicipalitySuggestions"]
Server --> Merge
Merge --> Rows["HomeSearchHitRow + reason"]
Write["wizard action success"] --> Record["recordLastActedMunicipality(slug)"]
```
Componentes:
- **`src/lib/campaignLastActedMunicipality.ts`** (client-safe storage helpers, irmão fino de `recentVisits.ts`).
- **`src/lib/wizardMunicipalitySuggestMerge.ts`** (puro): ordena/dedup fontes `{ source, slug }[]` + hits server → lista final com `reason`.
- **`WizardMunicipalitySearchStep`**: após fetch B92, merge client; skeleton/idle sem flash errado (não render continuity no SSR).
- **Hooks de gravação:** pontos de sucesso já existentes nos formActions/wizards (votos, sinal, tendência, liderança, demanda) — uma chamada `recordLastActedMunicipality(slug)`; sem abstração genérica se <3 sites usar helper inline até o 3º.
- **Migration:** nenhuma.
## Dependências
- Dura: **B92**.
- Soft: visitados ✓; wizards A1–A5 ✓.
## Não escopo
- Geo → **B94**.
- Last-acted server / multi-device.
- Continuity no empty do Início (B68 adiou; gatilho separado).
- Alterar card do Quadro.
## Rabbit holes
- **Helper genérico “campaignLocalShortcuts”.** **Mitigação:** dois módulos pequenos até 3º consumidor.
- **Gravar last-acted em toda mutation Payload via hook global.** Blast radius. **Mitigação:** só success paths do ritual de ação.
## Adiado com gatilho
- **Last-acted server (cross-device).** Revisitar se o mesmo CG reportar “no celular não aparece o que fiz no notebook” em sessão observada.
- **Visitados no suggest do Início (B68 adiado).** Revisitar com evidência de sessão; não neste item.
## Referências
- GitHub Issue #93
- [`recentVisits.ts`](../../src/utilities/recentVisits.ts) · [`visitados-recentemente.md`](visitados-recentemente.md)
- [`wizard-municipio-sugestoes-chassis.md`](wizard-municipio-sugestoes-chassis.md) (B92)
- AGENTS.md — sem Consent para storage local de UX autenticada (precedente B14/visitados)