teqo-backup/docs/plans/escala-dry-pos-visitados-recentemente.md
Francisco Ignácio Fontoura Solla b75daab498 Refactor campaign dashboard UX and add product discovery artifacts.
Extract dashboard cards into focused components (queues, upcoming plans, leadership status, recently visited, choropleth legend), compile the roadmap for outcome-oriented tracking, document the customer job and improve-app journey, and tighten roadmap skills with decision-quality gates.
2026-07-19 21:56:01 -03:00

106 lines
8.8 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.

# Escala e DRY pós-visitados recentemente
Status: registrado no roadmap (fases pendentes)
Atualizado em: 2026-07-20
Item do roadmap: [docs/roadmap.md](../roadmap.md) (VR+, fill-in de engenharia pós-MVP)
Responsável: —
## Contexto
O fill-in **Visitados recentemente** ([visitados-recentemente.md](visitados-recentemente.md)) entregou o MVP client-side: `recentVisits.ts` + `RecentVisitTracker` + `RecentlyVisited` no dashboard `/campanha`, integração em detalhe/listagem de núcleos, `buildNucleusListVisitLabel` / `buildNucleusListVisitHref`, labels de cobertura/estimativa compartilhados com `NucleusFilters`, e limpeza no logout (`CampaignSidebar`). Três passagens `/simplify` (2026-07-19) aplicaram cleanup pontual; os revisores (quality / performance / reuse) deixaram débitos **maiores que cleanup** — registrados aqui.
**Já resolvido no simplify (não reabrir):** `formatRelativeAge` extraído para `src/utilities/formatRelativeAge.ts` (evita puxar `campaignTime.ts` no client); prop `now` do servidor; remoção de `RECENT_VISITS_CHANGED_EVENT` (morto — painel e tracker não coexistem na mesma rota); `nucleusListCoverageLabels` / `nucleusListEstimateLabels` compartilhados; `buildNucleusListVisitHref` sem `page` (dedup de paginação); `listVisitHref` lazy no branch com filtro.
**Já resolvido no ciclo dashboard (2026-07-19/20 — parcial vs F3/F4; não reabrir):** extração de **`RecentlyVisitedCard`** (`compact`/`labeled`, `onVisitCountChange`, hidratação SSR); **`RecentlyVisited`** compõe `RecentlyVisitedCard` + `UpcomingActionPlansCard`; **`GeneralDashboardTopRow`** hoista recentes no top-row `geral` (3:2:1). **F1 (`pageshow`/`storage`) continua pendente** — listeners ainda não registrados em `RecentlyVisitedCard`.
## Objetivos
- Painel reflete visitas recentes após navegação back/forward (bfcache) e escrita em outra aba do mesmo origin.
- Um único helper de tempo relativo no dashboard (substituir `lastUpdateLabel` / `relativeDateLabel` locais onde fizer sentido).
- Linha de lista do dashboard reutiliza shell compartilhado (`QueueList` ↔ `RecentlyVisited`) sem duplicar markup.
- `RecentlyVisited` montado uma vez no wrapper do dashboard, respeitando `max-width` por role.
- Guardrails: sem collection/migration/Consent; histórico continua client-only; comportamento de dwell/dedup inalterado salvo bugs encontrados.
## Decisões travadas
- **Um plano VR+, quatro fases ordenadas.** Mesmo racional de O0+/B5/C8: um registro no roadmap, PRs por fase. Ordem: refresh confiável → DRY tempo relativo → DRY row shell → DRY layout dashboard.
- **Dependência suave do fill-in Visitados recentemente ✓.** Não bloqueia uso do MVP; melhora UX em back-navigation e consistência visual.
- **Sem sync servidor.** Histórico multi-dispositivo, poda reativa de acesso e histórico de planos/apoiadores permanecem fora de escopo (exigiriam modelo + `Consent`).
- **Cortável:** Fases 3–4 (row shell + layout wrapper) até o dashboard ganhar mais painéis do mesmo padrão; Fase 2 (relative time) é barata e reduz drift — preferir se houver folga.
- **i18n e naming** (AGENTS.md): identificadores em inglês (`useRecentVisits`, `CampaignLinkListRow`, `formatLastUpdateLabel`), strings visíveis em pt-BR.
## Questões em aberto
- **`pageshow` + `storage` vs reintroduzir evento custom?** O evento foi removido porque tracker e painel não montam juntos; bfcache e multi-tab são os casos reais restantes. **Recomendação:** `pageshow` (`event.persisted`) + `window.addEventListener('storage', …)` filtrando `STORAGE_KEY` — sem event bus custom.
- **Unificar `floor` (dias) vs `round` (minutos/horas)?** `lastUpdateLabel` usa dias inteiros; `formatRelativeAge` arredonda minutos/horas/dias. **Recomendação:** exportar variantes explícitas em `formatRelativeAge.ts` (`formatRelativeAgeDays`, `formatRelativeAge`) em vez de forçar um único comportamento.
- **Extrair row shell agora?** Só dois consumidores (`ActionQueuesCard`/`QueueSection`, `RecentlyVisitedCard`) com diferenças (ícone leading vs `ArrowRight`, prefixo "Última atualização"). **`RecentlyVisitedCard` já extrai o painel de visitas.** **Recomendação:** extrair `CampaignLinkListRow` quando um terceiro painel de atalhos aparecer, ou na Fase 3 se o drift visual incomodar produto (defer no triage 2026-07-20).
- **`next/dynamic` no painel?** **Recomendação:** só se Lighthouse mostrar o chunk como relevante no `/campanha`; o painel já retorna `null` quando vazio.
## Abordagem proposta
```mermaid
flowchart TD
VR["Visitados recentemente MVP ✓"] --> F1
F1["Fase 1 — Refresh confiável<br/>pageshow + storage listener"]
F1 --> F2["Fase 2 — DRY tempo relativo<br/>formatRelativeAge variants"]
F2 --> F3["Fase 3 — CampaignLinkListRow<br/>(QueueList + RecentlyVisited)"]
F3 --> F4["Fase 4 — Dashboard shell<br/>(RecentlyVisited hoisted)"]
```
### Fase 1 — Refresh confiável do painel
- **`RecentlyVisitedCard`** (`src/components/campaign/RecentlyVisitedCard.tsx`): no `useEffect` de mount, registrar `pageshow` (refresh quando `event.persisted`) e `storage` (quando `e.key === STORAGE_KEY` ou `e.key === null` para `clear()`).
- Opcional: extrair `useRecentVisits()` (`useState` + listeners + `listRecentVisits`) se Fase 1 crescer — hoje um hook de ~15 linhas é suficiente.
### Fase 2 — DRY de tempo relativo no dashboard
- **`formatRelativeAge.ts`**: adicionar `formatRelativeAgeInDays(timestampMs, nowMs)` (floor, como `lastUpdateLabel`) além do bucketing atual.
- **`CampaignDashboard.tsx`**: migrar `lastUpdateLabel` para helper compartilhado (manter prefixo "Última atualização" no call site).
- **`NucleusListOverview.tsx`**: migrar `relativeDateLabel` para o mesmo helper (dia-only).
- **`NucleusUpdateFeed.tsx`**: substituir `new Intl.RelativeTimeFormat` por instância do módulo compartilhado (hoje aloca formatter a cada call).
### Fase 3 — DRY de linha de lista
- Extrair **`CampaignLinkListRow`** (ex. `src/components/campaign/CampaignLinkListRow.tsx`): props `href`, `title`, `subtitle?`, `leadingIcon?`, `trailingIcon?` (`ArrowRightIcon` default para filas).
- Refatorar **`QueueSection`** em `ActionQueuesCard.tsx` e **`RecentlyVisitedCard`** para usar o componente; alinhar classes (`truncate` no subtítulo, `min-h-11`).
- **Defer (triage 2026-07-20):** só quando 3º painel de atalhos ou drift visual incomodar produto.
### Fase 4 — Shell do dashboard por role
- Introduzir wrapper **`CampaignDashboardShell`** com prop `maxWidthClass` (`max-w-screen-2xl` / `max-w-5xl` / `max-w-4xl`) renderizando header slot + painel recentes + children.
- `CoordinatorDashboard` / `LeadershipDashboard` passam a compor o shell em vez de repetir o painel.
- **`GeneralDashboardTopRow` já cobre o layout `geral`** (top-row 3:2:1) — F4 foca coordenador/liderança; **defer** até produto pedir paridade.
### Fase 5 — Micro-perf (opcional, cortável)
- **`next/dynamic`** com `ssr: false` para `RecentlyVisited` em `CampaignDashboard.tsx` se o bundle do dashboard for gargalo.
- **`recordRecentVisit`**: leitura interna sem re-validação completa no write path (`_readRaw`) — só se profiling mostrar custo (improvável com `MAX_ENTRIES = 8`).
- **`nucleos/page.tsx`**: deduplicar `resolveNucleusListUrl` (pré-existente, fora do core visitados) — registrar junto com A7/C10 se virar padrão de lista.
## Dependências
- **Visitados recentemente MVP ✓** (fill-in entregue em branch local; merge pendente).
- Reusa `formatRelativeAge.ts`, `recentVisits.ts`, `CampaignDashboard.tsx`, `NucleusListOverview.tsx`, `NucleusUpdateFeed.tsx`.
- Sem migration, sem collection, sem `Consent`.
## Não escopo
- Sync multi-dispositivo / histórico no servidor → exigiria collection + `Consent` (permanece no [visitados-recentemente.md](visitados-recentemente.md)).
- Histórico de planos/apoiadores/outras rotas → item separado se produto pedir.
- Poda reativa ao perder acesso (best-effort no MVP) → só se virar confusão recorrente.
- Telemetria/analytics de navegação.
- `buildNucleusDetailHref` — inline `/campanha/nucleos/${slug}` é o padrão do codebase hoje.
## Referências
- [visitados-recentemente.md](visitados-recentemente.md) — MVP entregue
- [escala-dry-pos-onda0.md](escala-dry-pos-onda0.md) — precedente de registro pós-`/simplify`
- `src/utilities/recentVisits.ts`, `src/utilities/formatRelativeAge.ts`
- `src/components/campaign/RecentlyVisited.tsx`, `RecentlyVisitedCard.tsx`, `RecentVisitTracker.tsx`
- `src/components/campaign/GeneralDashboardTopRow.tsx`
- `src/components/campaign/ActionQueuesCard.tsx` (`QueueSection`)
- `src/components/campaign/CampaignDashboard.tsx` (`lastUpdateLabel`)
- `src/components/campaign/NucleusListOverview.tsx`, `NucleusUpdateFeed.tsx`
- `src/utilities/nucleusUi.ts` (`buildNucleusListVisitLabel`, `buildNucleusListVisitHref`)
- `docs/roadmap.md` (fill-ins VR+)
- AGENTS.md — naming, sem migration para este item