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.
8.8 KiB
Escala e DRY pós-visitados recentemente
Status: registrado no roadmap (fases pendentes) Atualizado em: 2026-07-20 Item do roadmap: docs/roadmap.md (VR+, fill-in de engenharia pós-MVP) Responsável: —
Contexto
O fill-in Visitados recentemente (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/relativeDateLabellocais onde fizer sentido). - Linha de lista do dashboard reutiliza shell compartilhado (
QueueList↔RecentlyVisited) sem duplicar markup. RecentlyVisitedmontado uma vez no wrapper do dashboard, respeitandomax-widthpor 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+storagevs 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', …)filtrandoSTORAGE_KEY— sem event bus custom.- Unificar
floor(dias) vsround(minutos/horas)?lastUpdateLabelusa dias inteiros;formatRelativeAgearredonda minutos/horas/dias. Recomendação: exportar variantes explícitas emformatRelativeAge.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 vsArrowRight, prefixo "Última atualização").RecentlyVisitedCardjá extrai o painel de visitas. Recomendação: extrairCampaignLinkListRowquando um terceiro painel de atalhos aparecer, ou na Fase 3 se o drift visual incomodar produto (defer no triage 2026-07-20). next/dynamicno painel? Recomendação: só se Lighthouse mostrar o chunk como relevante no/campanha; o painel já retornanullquando vazio.
Abordagem proposta
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): nouseEffectde mount, registrarpageshow(refresh quandoevent.persisted) estorage(quandoe.key === STORAGE_KEYoue.key === nullparaclear()).- 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: adicionarformatRelativeAgeInDays(timestampMs, nowMs)(floor, comolastUpdateLabel) além do bucketing atual.CampaignDashboard.tsx: migrarlastUpdateLabelpara helper compartilhado (manter prefixo "Última atualização" no call site).NucleusListOverview.tsx: migrarrelativeDateLabelpara o mesmo helper (dia-only).NucleusUpdateFeed.tsx: substituirnew Intl.RelativeTimeFormatpor 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): propshref,title,subtitle?,leadingIcon?,trailingIcon?(ArrowRightIcondefault para filas). - Refatorar
QueueSectionemActionQueuesCard.tsxeRecentlyVisitedCardpara usar o componente; alinhar classes (truncateno 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
CampaignDashboardShellcom propmaxWidthClass(max-w-screen-2xl/max-w-5xl/max-w-4xl) renderizando header slot + painel recentes + children. CoordinatorDashboard/LeadershipDashboardpassam a compor o shell em vez de repetir o painel.GeneralDashboardTopRowjá cobre o layoutgeral(top-row 3:2:1) — F4 foca coordenador/liderança; defer até produto pedir paridade.
Fase 5 — Micro-perf (opcional, cortável)
next/dynamiccomssr: falseparaRecentlyVisitedemCampaignDashboard.tsxse 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 comMAX_ENTRIES = 8).nucleos/page.tsx: deduplicarresolveNucleusListUrl(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). - 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 — MVP entregue
- escala-dry-pos-onda0.md — precedente de registro pós-
/simplify src/utilities/recentVisits.ts,src/utilities/formatRelativeAge.tssrc/components/campaign/RecentlyVisited.tsx,RecentlyVisitedCard.tsx,RecentVisitTracker.tsxsrc/components/campaign/GeneralDashboardTopRow.tsxsrc/components/campaign/ActionQueuesCard.tsx(QueueSection)src/components/campaign/CampaignDashboard.tsx(lastUpdateLabel)src/components/campaign/NucleusListOverview.tsx,NucleusUpdateFeed.tsxsrc/utilities/nucleusUi.ts(buildNucleusListVisitLabel,buildNucleusListVisitHref)docs/roadmap.md(fill-ins VR+)- AGENTS.md — naming, sem migration para este item