# 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/` 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; fuso `America/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; `filterOptions` só reduz no servidor). **Trigger (b) resolvido com o `designer` (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 flag `live` na própria linha, sem id órfão. O artefato é a fonte de verdade do port. - A URL do arquivo `.ics` não está fixada pela intenção; decidida em D2 como `//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."). ## Abordagem recomendada ```mermaid 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 nova `shareLinkDestination` + relationships; C) checkbox `live` por linha do array `destinations`. **Recomendação: C** — decidido pelo `designer` no 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` → `//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//evento.ics`; C) Blob gerado no cliente. **Recomendação: A** — fica no namespace do slug, com `Content-Type`/`Content-Disposition` no servidor e 404 fail-closed para link sem data; o manifest já cobre `src/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//live`, `no-store`) + poll de 30s por `fetch` (imediato ao montar/voltar à aba visível, pausa em hidden); B) SSE/WebSocket; C) server action pública + poll (molde `getSignatureCount`); 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 `ShareLinkShareMenu` reusando `src/lib/contentShare.ts` + `useCopyFeedback` + `Popover`/`WhatsAppIcon`; B) generalizar `ContentShareButton` com variante de trigger. **Recomendação: A** — o `ContentShareButton` é 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 (precedente `20260811_111828_add_contact_phones_array.ts`). **Rejeitada:** B — exige `admin.condition` extra, `NOT NULL` condicional e deixa o "direct exige no-ar" com duas formas. - **D6 — header da página:** A) extrair `CampaignPageHeader` de `JinglePageHeader` (brand + badge opcional) e usar nos dois; B) duplicar. **Recomendação: A** — 30 linhas movidas, cobertas pelo e2e curado `frontendJingles` (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.") com `label` (text, required, "Rótulo"), `url` (text, required, "URL do destino", trim + `validateDestination` existente reusando `SHARE_LINK_DESTINATION_INVALID_MESSAGE`) e `live` (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.") e `location` (text, "Local", opcional, ex.: "Online"), os três com `admin.condition: (_, siblingData) => resolveShareLinkMode(siblingData?.mode) === 'announcement'` (precedente `AllocationDecision.ts:136`). `destination` **sai**. Hook `beforeValidate` `validateShareLinkConfiguration` (molde `Activity.ts:109-151`, merge `{...originalDoc, ...data}`): >1 `live` → APIError `SHARE_LINK_LIVE_DUPLICATE_MESSAGE`; `direct` sem live → `SHARE_LINK_DIRECT_WITHOUT_LIVE_MESSAGE`; `startsAt`/`endsAt` com fim ≤ início → `SHARE_LINK_EVENT_END_BEFORE_START_MESSAGE` (mesma frase do Activity). `defaultColumns: ['title','slug','mode','published']` e `admin.description` atualizada 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 linha `live` com URL `http`/`https` válida; tipo estrutural, sem importar Payload), `shareLinkIcsPath(slug) => '//evento.ics'`, mensagens novas. Nada de I/O. - **`src/lib/ical.ts` (novo)** — extração dos primitivos `escapeICalText` e `formatICalDate` hoje privados em `src/utilities/calendarFeed.ts:22-26`; `calendarFeed.ts` passa a importar daqui (comportamento pinado por `tests/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; `endsAt` inválido/≤ início cai no default), `buildGoogleCalendarEventUrl({title, details, location, startsAt, endsAt})` (`calendar.google.com/calendar/render?action=TEMPLATE`, datas UTC `YYYYMMDDTHHMMSSZ`, `URLSearchParams`) e `buildCalendarEventIcs({uid, title, description, location, startsAt, endsAt, updatedAt})` (VCALENDAR de um VEVENT, CRLF, `UID:@teqo.jorgesolla.com.br`, null sem `startsAt`). - **`src/lib/campaignTime.ts`** — dono do fuso; novo `formatBahiaEventDateLabel(iso)` → "Sábado, 3 de outubro · 19h" (minutos só quando ≠ 00), ao lado dos formatadores existentes (`formatBahiaDateTimeLabel` etc.). - **`src/lib/shareLinkAnnouncement.ts` (novo)** — view model serializável para o client (molde `src/lib/jingle.ts`): `ShareLinkAnnouncementView` (`slug`, `title`, `description`, `imageUrl`, `imageAlt`, `eventLabel`, `startsAt`, `endsAt`, `location`) e `buildShareLinkAnnouncementView({ link, imageUrl })`. - **`src/utilities/shareLinkReads.ts`** — dono das leituras. Novo `loadPublishedShareLinkLiveTarget(slug)`: `payload.find` **sem cache**, `where {slug, published:true}`, depth 0, comentário de justificativa do bypass (exigido pelo `codebaseConventions`), retorno `{ href, label } | null` via `resolveLiveShareLinkDestination`. O loader cacheado (`getCachedPublishedShareLinkBySlug`, tag `shareLinks`) continua sendo o das páginas. - **`src/app/(frontend)/api/share-link/[slug]/live/route.ts` (novo)** — `GET` fina fail-closed (D3-A): valida `isValidShareLinkSlug`, delega para `loadPublishedShareLinkLiveTarget` com `try/catch` → `{ target: null }` (nunca 5xx nem campo privado), `Cache-Control: no-store` e `dynamic = 'force-dynamic'`. - **`src/app/(frontend)/[type]/page.tsx`** — dono do slug de 1 segmento. `loadPublishedShareLink` passa a devolver `{ link, live }`; `generateMetadata` inalterado no conteúdo (OG card via `resolveShareLinkOgImageUrl`, noindex, `{}` sem link); no `Page`: `live` → `` (S19 intacto); announcement sem live → `` com a **URL relativa** do media proxy para renderizar (o absoluto do deployment origin fica só no card OG — mesmo-origem evita depender de `remotePatterns`); direct sem live → `notFound()`. - **`src/app/(frontend)/[type]/evento.ics/route.ts` (novo)** — `GET` com `params.type` = slug; loader cacheado depth 0; 404 (sem `startsAt`, draft ou slug desconhecido); `Content-Type: text/calendar; charset=utf-8`, `Content-Disposition: attachment; filename=".ics"`, `Cache-Control: public, no-cache`; corpo por `buildCalendarEventIcs`. - **`src/components/CampaignPageHeader.tsx` (novo, extraído)** — brand + `badge?: ReactNode` (o atual `JinglePageHeader` generalizado); `jingles/page.tsx` passa `badge="Jingles oficiais"`; a página de anúncio passa `badge="Ao vivo"` (só no estado live). `src/components/jingles/JinglePageHeader.tsx` sai. - **`src/components/shareLink/ShareLinkAnnouncement.tsx` (novo, client)** — corpo da página (port classe-a-classe do design): wrapper `data-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, `dl` com `view.eventLabel` + "Horário da Bahia" e local, chip "Destino no ar" quando live), CTA "Entrar" (`