7.9 KiB
Escala e DRY pós-visitados recentemente
Status: registrado no roadmap (fases pendentes) Atualizado em: 2026-07-19 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.
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 (
QueueList,RecentlyVisited) com diferenças (ícone leading vsArrowRight, prefixo "Última atualização"). Recomendação: extrair quando um terceiro painel de atalhos aparecer, ou na Fase 3 se o drift visual incomodar produto. 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
RecentlyVisited(src/components/campaign/RecentlyVisited.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
QueueListemCampaignDashboard.tsxeRecentlyVisitedpara usar o componente; alinhar classes (truncateno subtítulo,min-h-11).
Fase 4 — Shell do dashboard por role
- Introduzir wrapper
CampaignDashboardShellcom propmaxWidthClass(max-w-screen-2xl/max-w-5xl/max-w-4xl) renderizando header slot +<RecentlyVisited now={now} />+ children. GeneralDashboard/CoordinatorDashboard/LeadershipDashboardpassam a compor o shell em vez de repetir o painel.
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,RecentVisitTracker.tsxsrc/components/campaign/CampaignDashboard.tsx(QueueList,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