- snapshot drizzle da migration regenerado pós-rebase (inclui as tabelas do S27; sem ele o próximo migrate:create recriaria content_piece) - manifest e2e: CampaignFooter/jingleReads/campaignTime acordam o frontendShareLink; dynamicParams inerte removido da rota .ics - anúncio: dl válido (Local sem dd), aria-live só no status/chip, sem hasImage/cast; hook direct deixa o erro de URL falar antes (+ teste int) - débitos triados no impl plan (folding .ics -> #1281; deferidos com gatilho) Related #1268
23 KiB
Impl: Link de compartilhamento com destino trocável e página de anúncio da atividade
Status: aprovado
Atualizado em: 2026-09-23
Issue: #1268
Intenção: docs/plans/link-compartilhamento-destino-trocavel-anuncio.md
Appetite restante: herdado (~2–3 dias eng) — cortes explícitos desta fatia: sem componente admin custom (o "Destino no ar" vira checkbox nativo por linha), sem ETag/304 no .ics, sem SSE, sem agenda pública/analytics/UTM, sem PII/Consent novo.
Leitura da intenção
- Outcome: qualquer
jorgesolla1313.com.br/<slug>pode virar página de anúncio (título, imagem, data/hora Bahia, local, "Entrar" desativado, agenda, compartilhar) configurada pelo painel; a equipe troca o destino "no ar" sem digitar URL; com destino no ar o link volta a levar direto (S19), e quem já está na página vê o botão ativar em ~1 min sem recarregar. Nada hardcoded para 03/10. - O que NÃO negociar: contrato de URL inalterado (1 segmento na raiz); comportamento dos links S19 existentes idêntico; fail-closed (despublicado → 404 uniforme, noindex, destino só
http/https, modo direto sem destino no ar recusado no formulário); sem Consent/PII (não há pessoa); sem analytics/UTM; virada é decisão humana; corpo da página não é CMS; fusoAmerica/Bahia, duração padrão 2h. - O que reavaliar (e fica registrado):
- O
select"Destino no ar" da cena 05 do design não é nativo no Payload (SelectField.optionsé estático;filterOptionssó reduz no servidor). Trigger (b) resolvido com odesigner(tier primário, certificado): a cena 05 foi estendida para checkbox "Destino no ar" por linha do array (linha marcada em destaque; nenhuma = pré-transmissão; apenas um no ar) — o storage é o flaglivena própria linha, sem id órfão. O artefato é a fonte de verdade do port. - A URL do arquivo
.icsnão está fixada pela intenção; decidida em D2 como/<slug>/evento.ics(subpath do próprio slug, rota estática irmã de[category]). - A copy do estado desativado é proposta; o design manda ("A transmissão ainda não começou." / "A transmissão começou.").
- O
Abordagem recomendada
flowchart LR
A["GET /<slug>"] --> B{"publicado?"}
B -- "não" --> N["404 uniforme (mesmo not-found)"]
B -- "sim" --> C{"mode"}
C -- "direct" --> D{"destino no ar?"}
D -- "não (estado inválido)" --> N
D -- "sim" --> R["ShareLinkRedirect S19 intacto (meta refresh + script)"]
C -- "announcement" --> E{"destino no ar?"}
E -- "sim" --> R
E -- "não" --> P["ShareLinkAnnouncement (noindex)"]
P -. "poll 30s, tab visível" .-> S["rota fail-closed lê o DB"]
S -. "live" .-> L["Entrar ativa + rótulo do destino, sem reload"]
L -. "troca de destino no painel" .-> S
G["GET /<slug>/evento.ics"] --> I["route handler: 404 sem Início; senão text/calendar"]
Opções consideradas (decisões caras):
- D1 — como escolher o "no ar": A)
select+liveDestinationId(id da linha) com componente admin custom (useField/useAllFormFields); B) collection novashareLinkDestination+ relationships; C) checkboxlivepor linha do arraydestinations. Recomendação: C — decidido pelodesignerno trigger (b) e certificado na cena 05 estendida: nativo (o repo só tem 2 componentes de campo admin, ambos para algo sem equivalente nativo), sem id órfão (duplicar documento/copiar/remover linha não quebra nada — o flag viaja com a linha), e entrega a mesma ação do dia: marcar um + salvar; nenhum = pré-transmissão. Rejeitadas: A — armazenar id de linha cria classe de bug (duplicate/copy/delete) e acopla o form state interno do Payload, com custo de componente + e2e admin; B — collection nova (access, grupo, tela, migration) para um pool que pertence a um único link, overkill; ambas rejeitadas por robustez/appetite, não por impossibilidade. - D2 — URL do
.ics: A)src/app/(frontend)/[type]/evento.ics/route.ts→/<slug>/evento.ics(segmento estático irmão de[category]; estático vence o dinâmico, sem colisão com a listing); B)/api/share-link/<slug>/evento.ics; C) Blob gerado no cliente. Recomendação: A — fica no namespace do slug, comContent-Type/Content-Dispositionno servidor e 404 fail-closed para link sem data; o manifest já cobresrc/app/(frontend)/[type]. Rejeitadas: B — sai do namespace e não ganha nada (fica como fallback se o Next recusar o sibling estático); C — sem URL real, sem header de download para Apple/Outlook/desktop e a garantia de "nunca arquivo vazio" viraria só do cliente. - D3 — ativação sem reload: A) rota pública fail-closed (
GET /api/share-link/<slug>/live,no-store) + poll de 30s porfetch(imediato ao montar/voltar à aba visível, pausa em hidden); B) SSE/WebSocket; C) server action pública + poll (moldegetSignatureCount); D)router.refresh(). Recomendação: A — o padrão do site é polling; a rota devolve só{ target }e não acopla a resposta a RSC. Rejeitadas: B — infra inexistente, overkill para ~1 min; C — medido em e2e: a resposta de server action faz o Next re-renderizar a árvore da rota e, com o link já no ar, o refresh aplica o redirect no cliente e tira o visitante da página em vez de ativar o botão (além do Fast Refresh de compilação em dev); D — idem C por construção (o refresh puxaria o redirect). A rota mantém a página cacheada; quem chega depois é resolvido no servidor. - D4 — compartilhar: A) menu local
ShareLinkShareMenureusandosrc/lib/contentShare.ts+useCopyFeedback+Popover/WhatsAppIcon; B) generalizarContentShareButtoncom variante de trigger. Recomendação: A — oContentShareButtoné o botão-ícone de canto do card (1 call site na home) e o design pede um botão rotulado com chevron e popover próprio; a lógica compartilhada (mensagem/link/feedback) já está em lib, então a duplicação é só apresentação. Rejeitada: B — mexer no controle da home cujo e2e (frontend) não roda no PR de alto risco (migration ⇒ curated only), risco sem rede de browser por 2 call sites. - D5 — coluna
destination: A) dropar depois do backfill (pool é a fonte única; modo direto = destino no ar do pool); B) manter como fonte do modo direto. Recomendação: A — a cena 05 não tem campo escalar de destino e duas fontes para a mesma URL é dívida; backfill lossless no up, down lossy por política (precedente20260811_111828_add_contact_phones_array.ts). Rejeitada: B — exigeadmin.conditionextra,NOT NULLcondicional e deixa o "direct exige no-ar" com duas formas. - D6 — header da página: A) extrair
CampaignPageHeaderdeJinglePageHeader(brand + badge opcional) e usar nos dois; B) duplicar. Recomendação: A — 30 linhas movidas, cobertas pelo e2e curadofrontendJingles(afirma o badge "Jingles oficiais"); duplicar seria o gêmeo que a doutrina proíbe.
Recomendação (resumo): D1-C (certificado pelo designer) · D2-A · D3-A · D4-A · D5-A · D6-A — schema e URL públicos resolvidos agora; sem abstração nova (as libs puras têm ≥1 dono real e testes), sem custom admin.
Componentes / mudanças
ShareLink(src/collections/ShareLink.ts) — dono do cadastro. Campos novos (ordem do design):mode(select, required, defaultValue'direct', label "Modo do link", options "Levar direto ao destino"|"Página de anúncio");destinations(array, label "Destinos",admin.description"Pré-cadastre os lugares para trocar sem digitar URL no dia. Marque 'Destino no ar' em um único destino; nenhum marcado = pré-transmissão.") comlabel(text, required, "Rótulo"),url(text, required, "URL do destino", trim +validateDestinationexistente reusandoSHARE_LINK_DESTINATION_INVALID_MESSAGE) elive(checkbox, "Destino no ar", defaultValue false);startsAt/endsAt(date, "Início"/"Fim", opcionais,admin.date.pickerAppearance: 'dayAndTime', description "Horário da Bahia."/"Opcional. Sem fim, a agenda usa duração padrão de 2 horas.") elocation(text, "Local", opcional, ex.: "Online"), os três comadmin.condition: (_, siblingData) => resolveShareLinkMode(siblingData?.mode) === 'announcement'(precedenteAllocationDecision.ts:136).destinationsai. HookbeforeValidatevalidateShareLinkConfiguration(moldeActivity.ts:109-151, merge{...originalDoc, ...data}): >1live→ APIErrorSHARE_LINK_LIVE_DUPLICATE_MESSAGE;directsem live →SHARE_LINK_DIRECT_WITHOUT_LIVE_MESSAGE;startsAt/endsAtcom fim ≤ início →SHARE_LINK_EVENT_END_BEFORE_START_MESSAGE(mesma frase do Activity).defaultColumns: ['title','slug','mode','published']eadmin.descriptionatualizada para os dois modos. Access inalterado (publishedOrPanelAccess/canManagePublishedContent); docstring S19 atualizada.src/lib/shareLink.ts— dono do contrato puro.resolveShareLinkMode(value)(null/desconhecido →'direct'),resolveLiveShareLinkDestination(destinations)(primeira linhalivecom URLhttp/httpsválida; tipo estrutural, sem importar Payload),shareLinkIcsPath(slug) => '/<slug>/evento.ics', mensagens novas. Nada de I/O.src/lib/ical.ts(novo) — extração dos primitivosescapeICalTexteformatICalDatehoje privados emsrc/utilities/calendarFeed.ts:22-26;calendarFeed.tspassa a importar daqui (comportamento pinado portests/unit/calendarFeed.unit.spec.ts). Evita duas implementações de escape.src/lib/calendarEvent.ts(novo) — builders puros de evento:DEFAULT_EVENT_DURATION_MS(2h),resolveCalendarEventWindow(startsAt, endsAt)(fallback 2h;endsAtinválido/≤ início cai no default),buildGoogleCalendarEventUrl({title, details, location, startsAt, endsAt})(calendar.google.com/calendar/render?action=TEMPLATE, datas UTCYYYYMMDDTHHMMSSZ,URLSearchParams) ebuildCalendarEventIcs({uid, title, description, location, startsAt, endsAt, updatedAt})(VCALENDAR de um VEVENT, CRLF,UID:<slug>@teqo.jorgesolla.com.br, null semstartsAt).src/lib/campaignTime.ts— dono do fuso; novoformatBahiaEventDateLabel(iso)→ "Sábado, 3 de outubro · 19h" (minutos só quando ≠ 00), ao lado dos formatadores existentes (formatBahiaDateTimeLabeletc.).src/lib/shareLinkAnnouncement.ts(novo) — view model serializável para o client (moldesrc/lib/jingle.ts):ShareLinkAnnouncementView(slug,title,description,imageUrl,imageAlt,eventLabel,startsAt,endsAt,location) ebuildShareLinkAnnouncementView({ link, imageUrl }).src/utilities/shareLinkReads.ts— dono das leituras. NovoloadPublishedShareLinkLiveTarget(slug):payload.findsem cache,where {slug, published:true}, depth 0, comentário de justificativa do bypass (exigido pelocodebaseConventions), retorno{ href, label } | nullviaresolveLiveShareLinkDestination. O loader cacheado (getCachedPublishedShareLinkBySlug, tagshareLinks) continua sendo o das páginas.src/app/(frontend)/api/share-link/[slug]/live/route.ts(novo) —GETfina fail-closed (D3-A): validaisValidShareLinkSlug, delega paraloadPublishedShareLinkLiveTargetcomtry/catch→{ target: null }(nunca 5xx nem campo privado),Cache-Control: no-storeedynamic = 'force-dynamic'.src/app/(frontend)/[type]/page.tsx— dono do slug de 1 segmento.loadPublishedShareLinkpassa a devolver{ link, live };generateMetadatainalterado no conteúdo (OG card viaresolveShareLinkOgImageUrl, noindex,{}sem link); noPage:live→<ShareLinkRedirect destination={live.href} />(S19 intacto); announcement sem live →<ShareLinkAnnouncement view={...} />com a URL relativa do media proxy para renderizar (o absoluto do deployment origin fica só no card OG — mesmo-origem evita depender deremotePatterns); direct sem live →notFound().src/app/(frontend)/[type]/evento.ics/route.ts(novo) —GETcomparams.type= slug; loader cacheado depth 0; 404 (semstartsAt, draft ou slug desconhecido);Content-Type: text/calendar; charset=utf-8,Content-Disposition: attachment; filename="<slug>.ics",Cache-Control: public, no-cache; corpo porbuildCalendarEventIcs.src/components/CampaignPageHeader.tsx(novo, extraído) — brand +badge?: ReactNode(o atualJinglePageHeadergeneralizado);jingles/page.tsxpassabadge="Jingles oficiais"; a página de anúncio passabadge="Ao vivo"(só no estado live).src/components/jingles/JinglePageHeader.tsxsai.src/components/shareLink/ShareLinkAnnouncement.tsx(novo, client) — corpo da página (port classe-a-classe do design): wrapperdata-theme="campaign-site"+min-h-full bg-(--campaign-cream)dentro do scroll do[type]/layout.tsx; header, card (imagem opcional sem caixa vazia, eyebrow "Transmissão"→"Ao vivo agora", título, descrição,dlcomview.eventLabel+ "Horário da Bahia" e local, chip "Destino no ar" quando live), CTA "Entrar" (<button disabled aria-disabled>→<a href>), aviso, menus,CampaignFooter. Estadolive: {href,label}|null; efeito: poll imediato +setInterval30s com pausa emhiddene checagem ao voltar (moldeSignatureCounter.tsx:63-106); para de atualizar só ao desmontar (troca Meet→YouTube atualiza o href).src/components/shareLink/ShareLinkAgendaMenu.tsx(novo, client) — botão rotulado +Popover(design cena 04): "Google Agenda" (buildGoogleCalendarEventUrl, nova abanoopener noreferrer) e "Baixar arquivo .ics" (shareLinkIcsPath(slug)); não renderiza semstartsAt(nunca arquivo vazio).src/components/shareLink/ShareLinkShareMenu.tsx(novo, client) — botão rotulado +Popover: "Compartilhar no WhatsApp" (buildContentShareWhatsAppUrl('event', title, link)) e "Copiar link" (useCopyFeedback+buildContentShareLink); compartilha o link curto com o título.src/lib/contentShare.ts—ContentShareKindganha'event'com prefixo'Participe: '(mensagem =Participe: {title} — {link});Record<ContentShareKind,…>garante exaustividade no typecheck.- Migration:
pnpm migrate:create add_share_link_announcement(gerashare_link_destinationscomid varchar PK,_order,_parent_id,label,url,live; colunasmodeenum +starts_at/ends_at/location; drop dedestination) e edição à mão:INSERT INTO share_link_destinations (id,_parent_id,_order,label,url,live) SELECT gen_random_uuid()::text, id, 0, 'Destino', destination, true FROM share_link WHERE destination IS NOT NULLantes doDROP COLUMN destination;modecomDEFAULT 'direct'/backfill para as linhas antigas (modo null = direct é só defesa). Down lossy por política: restauradestinationda linha live (fallback_order 0) e derruba tabela/colunas. Rodarpnpm migratelocal epnpm generate:types. - Access / Consent: inalterados —
publishedOrPanelAccessno read (owherepublicado é a barreira anônima),canManagePublishedContentna escrita; sem Consent/PII novo, sem join com Contact; sem transação multi-collection (escritas são de um doc). - UI (Impeccable D): superfícies = página de anúncio (desktop 1280 e mobile 390, pré e no-ar), menus de agenda/compartilhar e cadastro admin. Port classe-a-classe do HTML aprovado (
docs/plans/...-ui-design.html, cenas 01–05, cena 05 estendida pelo designer no trigger b) usando os tokens destyles.css:168-196; ciclo shape→craft→critique→polish na fase 2, com a crítica final dodesigner(tier primário) CERTIFICADA. Admin é formulário nativo Payload (sem navegação paralela): "Destino no ar" é checkbox por linha certificado na cena 05; a densidade da cena usarownativo (Rótulo 30% / URL 45% / checkbox 25%, Slug+Modo 50/50, Início+Fim 50/50), a seção "Dados do evento" é umcollapsiblenativo aberto com helper, e o cabeçalho de cada destino é umRowLabelread-only (src/components/admin/ShareLinkDestinationRowLabel.tsx,useRowLabel) que mostra01 · Google Meet+ pill "no ar" na linha ativa — o container do array é chrome nativo sem hook de estilo por linha, adaptação aceita na crítica.
Dados → forma
Não se aplica — a intenção não apresenta dado agregado (sem contagem/analytics); a página mostra horário/local do evento.
Fases verificáveis
- Tracer / schema+server (quota ~1 dia): libs puras (
shareLinkresolvers/mensagens/shareLinkIcsPath,icalextraído,calendarEvent,campaignTimeformatter) + unit; migration/collection/hook +generate:types+pnpm migratelocal;loadPublishedShareLinkLiveTarget+ rotalive+ branch do[type]/page.tsx(anúncio ainda sem estilo) + rota.ics; atualizar seeds de int/e2e para o shape novo e ver o S19 redirect/404/kill-switch verde (regressão). Critério: link direct continua idêntico; anúncio sem live responde 200 sem interstício;.icsresponde 200/404 certo. - UI (quota ~1 dia):
ShareLinkAnnouncement+CampaignPageHeaderextraído + menus, port classe-a-classe; labels/descriptions/condition do admin; unit dos contratos puros; screenshots 1280/390 contra as cenas (crítica final do designer); a ativação sem reload é coberta pelo e2e;frontendJinglesverde (header extraído). - Gates (quota ~0.5 dia): e2e novos em
frontendShareLink; entradas do manifest;pnpm gate:fast(lint+typecheck+unit) +pnpm test:int+ e2e selecionado (lembrar: PR com migration é alto risco ⇒ curated, que incluifrontendShareLink/frontendJingles); entrada emdocs/changelog/2026-09-23-s29-link-anuncio.md;pnpm push(PR pronta).
Rabbit holes / Não escopo (engenharia)
- Não criar rota raiz nova (
evento.icsé subpath sob[type]; a raiz é o contrato do slug) nem entrada emSHARE_LINK_RESERVED_SLUGS— o drift test varre só segmentos estáticos da raiz de(frontend). - Não manter
destinationem paralelo ao pool (duas fontes) nem usarpush/edição manual de schema: schema só por migration. - Não depender de
revalidateTagpara a ativação: a página segue cacheada e o poll lê o DB; quem chega depois resolve no servidor. - Não mexer no 404 uniforme: sem
[type]/not-found.tsx; anúncio sem live é 200; link ausente/rascunho é o not-found padrão do Next. - Não trocar a origem da imagem OG (
resolveShareLinkOgImageUrl= deployment origin); não usar a URL canônica do global. - Não expor
activityda campanha (PUB3), nem richText/CMS da página, nem embed/chat/RSVP, nem agendamento automático/expiração, nem analytics/UTM/QR/múltiplos links, nem picker de data customizado em Bahia no admin (fase futura se o time pedir), nem ETag/304 no.ics. - Não criar arquivo novo em
src/utilities/top-level (ocodebaseConventionspina a lista): a leitura fresca entra emshareLinkReads.ts.
Riscos e mitigação
- Sibling estático
[type]/evento.icsrecusado pelo Next → fallback imediato para/api/share-link/[slug]/evento.ics(só muda o href do menu; contrato do slug intacto). Verificar no build da fase 1. - Shape REST do
shareLinkmuda (somedestination, entramdestinations/mode): consumidores são só o admin e os testes (int/e2e atualizados); nenhum integrador externo conhecido. - Migration irreversível na prática (drop de
destination): backfill antes do drop, down lossy documentado no próprio arquivo (precedentecontact_phones). - Poll + cache: ativação nunca depende do cache; chegada pós-live depende do contrato de tag já provado pelo e2e de kill-switch do S19. Falha de poll é tick perdido (silencioso), e a rota nunca devolve 5xx nem campo privado.
- Fuso do admin: o picker nativo mostra o fuso do browser; a página sempre formata em Bahia (descrição "Horário da Bahia."). Se o time pedir lock, é follow-up.
- Manifest drift: entradas novas —
src/components/shareLink,src/components/CampaignPageHeader.tsx(→ tambémfrontendJingles),src/app/(frontend)/api/share-linkesrc/lib/calendarEvent.ts/src/lib/ical.ts(esta também emcampaignAgendaFeed),src/lib/contentShare(→frontend);src/components/CampaignFooter.tsx,src/collections/ShareLink.ts,src/utilities/shareLinkReads.ts,src/app/(frontend)/[type]esrc/lib/shareLink*já estão mapeados. - Sem risco de PII/Consent (não há pessoa) e sem novo write multi-collection.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (modo por link; pool com rótulo; direct sem no-ar recusado; anúncio com data/local; Entrar desativado→ativo ~1 min; agenda Google+.ics com data e sem data esconde o botão; compartilha o link curto; despublicado 404; nada hardcoded para 03/10)
- Invariantes AGENTS/engineering-standards (URL pública intacta; S19 sem mudança de comportamento; fail-closed/noindex; sem Consent/PII; schema só por migration
push:false;overrideAccessdocumentado; lib→utilities→components→app; pt-BR em copy, inglês em identificador) - Testes de domínio previstos (unit/int) onde access/write paths mudam — obrigatórios: unit
shareLink(modo/live/shareLinkIcsPath), unitcalendarEvent(Google/ICS/2h), unitshareLinkAnnouncement(view model), unitcontentShare(event); intshareLink(hook cross-field com mensagens, loader publicado, live target fail-closed). Discricionários: admin e2e do checkbox; ETag do.ics. E2E obrigatório estendendofrontendShareLink: página de anúncio 200/noindex/sem refresh,.ics200/404, redirect pós-live, e a regressão S19 (redirect/meta/no-JS/404/republicação) — o spec já é do conjunto curado. A ilha de ativação é coberta por e2e (client real, prod e dev) em vez de unit jsdom.
Self-score (decision-quality)
- Decisões caras com rejeitadas: 5 — D1 (A/B/C), D2 (A/B/C), D3 (A/B/C), D4 (A/B), D5 (A/B), D6 (A/B), todas com recomendação e porquê.
- Cabe no appetite: 4 — ~2–3 dias com tracer cedo e cortes explícitos (sem custom admin/SSE/ETag); o teto é a extração do header + rota
.ics+ 3 libs puras, todos pequenos e testáveis. - Rabbit holes nomeados: 5 — rota raiz/reserved slug, duas fontes de destino, ativação via cache, 404 uniforme, origem OG, agenda/CMS/analytics, lista pinada de utilities.
- Reusa shells/helpers: 5 —
shareLinkReads,calendarFeed/primitivos iCal,campaignTime,CampaignFooter, padrão de polling,contentShare/useCopyFeedback/Popover,CampaignPageHeader; nenhuma abstração nova com <3 call sites. - Intenção satisfeita: 5 — todos os bullets do aceite mapeados em componentes/fases/testes, incluindo a questão em aberto aprovada (B: link volta a levar direto).
Média 4.8/5 — plano aprovado no modo --auto.
Débitos triados (review do PR #1280)
- Folding RFC 5545 (75 octets) no
.ics— registrado como #1281 (S29-FOLLOWUP, kind chore, P3): ownersrc/lib/ical.ts, 2 call sites (lib/calendarEvent.ts,utilities/calendarFeed.ts). importMap.jstracked apesar do OPS99 — descartado: dívida pré-existente domain, classe já rastreada em #772/#791 + postmortem 2026-09-12; reavaliargit rm --cachedquando o guard do #772 fechar.- Rate limiting da rota
live— deferido: gatilho = pico anômalo de requisições na rota (mitigação barata: cache in-memory de 5–10s no loader). - Settle dev-only de 6s no e2e
frontendShareLink— deferido: gatilho = primeira flake local do spec (trocar por condição observável); o SQL cru é deliberado e documentado (isola a race de revalidação/HMR).