18 KiB
Impl: S41 — Agenda do link de anúncio: evento leva o próprio link, assinatura "Jorge Solla 1313" e fuso da Bahia
Status: aprovado — autoaprovado pela invocação --auto
Atualizado em: 2026-09-25
Issue: #1335
Intenção: docs/plans/agenda-do-link-de-anuncio-com-link-e-assinatura.md
Priority: P2
Impeccable: A — sem UI nova; somente o conteúdo gerado para Google Agenda e .ics
Design UI: N/A — a página, o menu e o cadastro não mudam visualmente
Appetite restante: herdado (~0,5 dia eng); sem migration, sem schema e sem novos owners de produto
Responsável: —
Leitura da intenção
- Outcome: os dois caminhos de agenda carregam a URL canônica do anúncio, acrescentam a assinatura
- Jorge Solla 1313uma única vez e apresentam o horário no fusoAmerica/Bahia, sem alterar a página ou o cadastro. - O que não negociar: a descrição configurada vem antes de
Página do evento: <url>; o.icstambém temURLdeVEVENT; a ausência de URL canônica remove apenas o link; duração padrão de 2h, ausência de início, 404 de despublicado e fail-closed permanecem; sem Consent, PII, RSVP, convite, agenda pública ou API do Google. - O que reavaliar: a intenção escreve o domínio público de produção como literal, enquanto o código usa a cadeia global-first de SEO; os dois caminhos atualmente serializam UTC e não há precedente local para
TZID/VTIMEZONE; a composição de título e descrição precisa ficar em um único owner.
Abordagem recomendada
flowchart LR
L[Link publicado] --> W{Início válido?}
W -- não --> H[Menu ausente ou ICS 404]
W -- sim --> C[Resolver URL canônica]
C --> U[URL absoluta do anúncio]
C --> N[Sem URL: canonical ausente]
U --> P[Google: título, detalhes, horário local, ctz]
U --> R[ICS: TZID, VTIMEZONE, URL, descrição]
N --> P
N --> R
Opções macro: A) manter os dois caminhos em UTC e acrescentar apenas texto | B) serializar o mesmo instante no fuso Bahia, com ctz no Google e TZID/VTIMEZONE no ICS | C) criar um segundo modelo de evento para a agenda pública.
Recomendação: B, com as transformações de conteúdo centralizadas em calendarEvent e a URL canônica resolvida no servidor. É a menor mudança que satisfaz o aceite sem criar uma agenda paralela.
Decisões de engenharia
D1 — Domínio canônico fixo versus metadata configurável
Opções: A) hardcode de https://jorgesolla1313.com.br em cada builder/rota | B) usar a cadeia canônica existente: getCachedGlobal('metadata') → resolveSiteMetadata → absoluteSitePath(siteUrl, shareLinkPath(slug)) | C) usar window.location.origin ou o host da requisição.
Recomendação: B — em produção, o valor global deve resolver https://jorgesolla1313.com.br, preservando o contrato S19/S29. NEXT_PUBLIC_SITE_URL continua sendo o fallback de worktree, staging e ambiente sem global; a origem é configuração do site, não um novo campo por link. A política fica em resolveShareLinkCanonicalUrl, no reader server-only, e a página e a rota do .ics consomem o mesmo resultado.
O reader devolve undefined quando não há siteUrl; nenhum builder recebe shareLinkPath(slug) como se fosse uma URL. Também não usar resolveDeploymentOrigin, que é a origem de assets e pode ser diferente do domínio canônico.
Alternativas rejeitadas: A duplica a política em vários arquivos e quebraria staging/testes ao apontar para produção. C transforma a origem atual de navegação em canonical, podendo gerar URLs diferentes entre visitors, página e download.
D2 — Representação do fuso nos consumidores
Opções: A) manter DTSTART/dates em UTC e apenas adicionar uma dica de timezone | B) converter o instante para horário civil de America/Bahia, usar horário local sem Z no Google com ctz=America/Bahia, e usar TZID=America/Bahia mais um VTIMEZONE fixo no ICS | C) escrever offsets numéricos -0300 em todo lugar.
Recomendação: B — startsAt e endsAt continuam instantes UTC; só a representação externa muda. O Google recebe 20261003T190000 e ctz=America/Bahia; o ICS recebe DTSTART;TZID=America/Bahia:20261003T190000 e DTEND;TZID=America/Bahia:20261003T210000, com VTIMEZONE contendo um bloco STANDARD fixo em -0300, sem DAYLIGHT. DTSTAMP continua em UTC, pois representa o instante de gravação, não o horário do evento.
A conversão usa o owner de horário Bahia já existente em campaignTime.ts, sem nova dependência. O feed público da campanha e googleCalendarEventMapping.ts mantêm seus próprios contratos UTC/offset; não serão compartilhados nem alterados.
Alternativas rejeitadas: A preserva o instante, mas não informa ao leitor qual fuso deve ser exibido. C não é a forma padrão para DTSTART/DTEND de um VEVENT e não oferece a definição IANA que alguns clientes esperam.
D3 — Dono do título, descrição e URL do evento
Opções: A) cada caller monta título e descrição antes de chamar o builder | B) calendarEvent.ts recebe título/descrição crus e uma url opcional, aplicando as transformações uma vez | C) criar um serviço paralelo de conteúdo de calendário.
Recomendação: B — CalendarEventInput ganha url?: string | null, mas não conhece origem, environment ou slug. O builder:
- acrescenta
- Jorge Solla 1313ao final apenas quando esse sufixo exato ainda não está no fim; - compõe a descrição como descrição configurada, linha em branco,
Página do evento: <url>quando houver URL; - mantém a descrição original, sem linha extra, quando a URL não for resolvida;
- deixa o título e a descrição da página intocados.
Assim, o menu e a rota passam o mesmo dado bruto e recebem a mesma saída. O nome Jorge Solla 1313 é copy do produto; os identificadores permanecem em inglês.
Alternativas rejeitadas: A permite divergência entre Google e ICS e duplica a regra anti-sufixo. C cria um segundo owner para um domínio que já tem um builder puro.
D4 — Campo de URL do VEVENT
Opções: A) URL somente na descrição | B) URL na descrição e em URL:<url> dentro do VEVENT | C) colocar a URL no campo de local do Google ou forçar um campo de URL equivalente.
Recomendação: B — o .ics usa a propriedade padrão URL; o Google recebe a URL apenas na descrição, porque o template não tem um campo de URL de evento equivalente. A URL do VEVENT e a linha Página do evento devem ser o mesmo valor absoluto. Sem canonical resolvido, as duas posições devem ser omitidas.
Alternativas rejeitadas: A deixa de cobrir o requisito explícito do ICS. C mistura papel de local e destination, altera a semântica do evento e não resolve o Google.
D5 — Testes
Opções: A) unit para a serialização, int para a resolução server-side e e2e para a página/rota | B) somente e2e | C) somente unit.
Recomendação: A — a serialização é pura e deve ser rápida; o reader server-only e o contrato de publicado/404 ficam no int; o menu real e o download precisam do fluxo e2e. Não criar teste de browser para o Google Calendar externo, apenas inspecionar o href gerado.
Alternativas rejeitadas: B deixa a composição de URL e timezone sem feedback rápido. C não prova a integração entre metadata, página client e rota .ics.
Componentes / mudanças
resolveShareLinkCanonicalUrl(src/utilities/shareLinkReads.ts): helper server-only que reutilizagetCachedGlobal('metadata'),resolveSiteMetadata,absoluteSitePatheshareLinkPath; devolve a URL canônica ouundefined. Não altera o reader de publicados nem o filtropublished: true.src/app/(frontend)/[type]/page.tsx: usar o helper na resolução do canonical de metadata e no ramo de anúncio; passar a URL para o view. ManterresolveShareLinkMetadata,noindex, redirect de link direto, poll de live e branch de destino sem alteração.src/lib/shareLinkAnnouncement.ts: adicionarcanonicalUrl: string | nullao view e ao builder do view. A função continua pura e client-safe; não importa metadata, environment ouwindow.src/components/shareLink/ShareLinkAnnouncement.tsx: encaminharview.canonicalUrlparaShareLinkAgendaMenu. Não alterar markup, rótulos, layout, heading ou CTA.src/components/shareLink/ShareLinkAgendaMenu.tsx: receber a URL canônica como prop e passá-la aobuildGoogleCalendarEventUrl. O menu continua condicionado astartsAt; uma URL ausente não pode esconder o menu. O href do download continuashareLinkIcsPath(slug), que é um path de navegação e não a URL descrita no VEVENT.src/lib/calendarEvent.ts:- estender
CalendarEventInputcomurlopcional; - centralizar sufixo, composição da descrição e validação de URL absoluta;
- formatar os instantes como horário civil de
America/Bahiapara os campos de evento; - emitir
ctz=America/Bahiano Google, semZemdates; - emitir
VTIMEZONE,TZIDe campos locais no ICS; - manter
METHOD,PRODID,UID,DTSTAMP,LOCATION,resolveCalendarEventWindow, o fallback de 2h e o retornonullsem início válido; - continuar usando
escapeICalTextefoldICalLineem todas as linhas lógicas do ICS.
- estender
src/lib/campaignTime.ts: adicionar um export puro para data/hora local IANA com segundos, reaproveitandogetZonedParts; não alterarformatIsoAsBahiaDateTimeInput,formatBahiaEventDateLabelnem os contratos usados pelo admin.src/lib/shareLink.ts,src/lib/ical.tsesrc/utilities/seo.ts: reutilizarshareLinkPath, os primitivos iCal e o resolver de SEO; não criar helpers gêmeos.src/utilities/calendarFeed.tsesrc/lib/googleCalendarEventMapping.ts: nenhum toque. O feed de campanha continua em UTC e o mapeamento da API Google continua com seu offset próprio.- Migration: nenhuma. Não alterar
ShareLink, Payload types, hooks, access ou banco; não executarmigrate:create,migrateougenerate:types. - Access / Consent: nenhuma mudança. Não há escrita, PII, pessoa ou nova chave de consentimento; o reader público continua fail-closed para rascunho.
- UI: Impeccable A. Nenhum componente, shell, token, CSS, designer ou screenshot novo; a mudança é limitada ao href gerado e ao corpo do
.ics. - Changelog: uma entrada curta em
docs/changelog/2026-09-25-s41.md, sem editar o agregado.
Dados → forma
- data-presentation: não aplicável. Não há métrica, gráfico, série, ranking ou painel; o dado alterado é o payload de um evento de calendário, não uma visualização de dados.
Fases verificáveis
-
Tracer de domínio puro (~40% do appetite)
- Atualizar
calendarEvent.tse o export de data/hora Bahia. - Fechar a matriz de título já assinado, título simples, descrição vazia, URL presente/ausente, URL relativa/inválida, escape, newline, URL longa, início ausente, fim inválido e duração de 2h.
- O exemplo de boundary deve confirmar que
2026-10-03T22:00:00.000Zvira19:00da Bahia no Google e no ICS, enquantoDTSTAMPpermanece UTC. - Rodar:
pnpm test:unit -- tests/unit/calendarEvent.unit.spec.ts tests/unit/ical.unit.spec.ts tests/unit/shareLinkAnnouncement.unit.spec.ts
- Critério: os dois builders produzem o mesmo título/descrição/fuso e o ICS continua com CRLF, escape e folding válidos.
- Atualizar
-
Wiring server/client (~35%)
- Adicionar o reader de canonical e alimentar
canonicalUrlno view, menu e rota. - Preservar a página sem canonical, o menu com início válido, a ausência de menu sem início, o 404 de despublicado/desconhecido e o comportamento de link direto/live.
- Cobrir no int a precedência
metadata.URLsobreNEXT_PUBLIC_SITE_URL, o caminho/<slug>e o retorno ausente sem URL. - Rodar:
pnpm test:int -- tests/int/shareLink.int.spec.tspnpm test:unit -- tests/unit/calendarEvent.unit.spec.ts tests/unit/ical.unit.spec.ts tests/unit/shareLinkAnnouncement.unit.spec.ts
- Critério: a rota e a página usam a mesma origem canônica; nenhum link gerado usa destino, path relativo ou
window.origin.
- Adicionar o reader de canonical e alimentar
-
Integração e fechamento (~25%)
- Atualizar
tests/e2e/frontendShareLink.e2e.spec.tspara abrir o menu no browser e verificar ohrefdo Google sem abrir o serviço externo. - No mesmo spec, baixar o
.icse verificar, após unfold,SUMMARY,DESCRIPTION,URL,VTIMEZONE,TZID,DTSTARTeDTENDlocais; confirmar que o<h1>continua sem o sufixo e que os textos visíveis não mudaram. - Manter os casos sem data, slug desconhecido, despublicado e live redirect intactos.
- Rodar:
pnpm test:e2e --no-deps -- tests/e2e/frontendShareLink.e2e.spec.tspnpm test:e2e:affectedpnpm gate:fastpnpm push
pnpm pushfecha a entrega e executa o gate de CI; não usargit pushdiretamente.
- Atualizar
Rabbit holes / Não escopo (engenharia)
- Novo campo de URL no
ShareLink: cortar. A URL vem do slug e do canonical já existente. - Hardcode de
NEXT_PUBLIC_EVENT_URLou de novo env: cortar. A origem segue o contrato de metadata/SEO. - Usar
window.location.origin, host da requisição ouresolveDeploymentOrigin: cortar. Nenhum deles representa o canonical público. - Colocar a URL em
LOCATIONdo Google: cortar. O local continua sendo o local configurado. - Adicionar
URLao Google template: cortar. Google recebe a URL na descrição;.icsrecebe a propriedade própria. - Criar um segundo calendário, feed público ou registry de eventos: cortar. A agenda pública é PUB3 e o motor/sync de campanha tem owner separado.
- Alterar
src/utilities/calendarFeed.tsousrc/lib/googleCalendarEventMapping.ts: cortar. OVTIMEZONEnovo pertence apenas ao evento do link de anúncio. - Adicionar recorrência, convidados, múltiplas sessões, dia inteiro, mapa/endereço, RSVP, lembrete, notificação, analytics, UTM ou encurtador: fora da intenção.
- Mudar o heading, os rótulos, a posição do menu ou o cadastro: fora do escopo. A assinatura aparece somente no evento exportado.
- Truncar título ou descrição para respeitar limite de um calendário consumidor: fora. O cadastro tem seus limites; o evento deve preservar o texto e o link.
- Criar parser de ICS, biblioteca de timezone ou importador de calendário: YAGNI; esta entrega só serializa um VEVENT.
Riscos e mitigação
- Origem canônica divergir entre página e
.ics: centralizar a política emresolveShareLinkCanonicalUrl, usarshareLinkPathe comparar no e2e a URL da descrição comURL:do ICS. - Fallback para URL relativa quando o metadata está ausente: o reader devolve
undefined; builders mantêm título, descrição e horário, mas não inventam origem. O caso é coberto por unit e int. - Misturar horário local com
Z: Google e ICS recebem valores locais semZ;DTSTAMPé o único campo de evento que continua comZ. Os testes verificam a consulta e o corpo após unfold. - Cliente não reconhecer
TZID: o.icsincluiVTIMEZONEcompleto,TZIDe offsets fixos de-0300; não confiar apenas em umX-WR-TIMEZONEnão padronizado. - Sufixo duplicado: a transformação é idempotente para um título que já termina no literal; não procura a assinatura no meio do título nem reescreve o texto configurado.
- Linha de descrição com espaço ou quebra inesperado: compor a descrição antes de escapar, usar uma linha em branco entre as partes e testar descrição vazia, multilinha e URL ausente.
- URL ou descrição longa quebrar o ICS: continuar passando todas as linhas por
foldICalLine; o teste deical.unit.spec.tsconfirma limite de 75 octets e unfold sem alteração. - Mudança involuntária no feed de campanha: não editar seus owners; rodar os testes de
calendarFeedcomo regressão, sem esperar mudança no formato atual. - Regressão de página, redirect ou kill switch: o e2e existente de
frontendShareLinkcontinua verificando noindex, redirect pós-live, 404 e republicação. - Metadata ausente no build:
resolveSiteMetadataeabsoluteSitePathmantêm a degradação existente; a ausência de URL é um estado válido do evento, não motivo para 404. - Export novo não usado:
resolveShareLinkCanonicalUrlterá consumidores na página e na rota; o formatter Bahia terá consumidores no builder e teste.knipecheck:cyclesentram no gate.
Aceite de engenharia
- Google Agenda e
.icsusam a URL canônica do anúncio, nunca o destino, o.icsou uma origem relativa. - O título exportado termina uma única vez com
- Jorge Solla 1313, sem alterar o título da página. - A descrição configurada vem antes de uma linha em branco e de
Página do evento: <url>. - O
.icscontémURLdeVEVENT; o Google não recebe um campo de URL paralelo. - Google usa horário local da Bahia com
ctz=America/Bahia; o ICS usaTZIDeVTIMEZONEfixoAmerica/Bahia/UTC-3, sem DST. DTSTAMPe o restante do contrato iCal continuam válidos; escape, CRLF e folding são preservados.- Sem canonical resolvido, o evento continua válido com título e fuso, mas sem linha de link e sem
URLno ICS. - Duração padrão de 2h, início obrigatório para o menu e 404 para link despublicado/desconhecido continuam iguais.
- Página, menu visível, cadastro e dados do
ShareLinknão ganham campo, seção, rótulo ou fluxo novo. calendarFeed.tsegoogleCalendarEventMapping.tspermanecem intocados.- Unit, int e e2e afetados cobrem a matriz acima;
pnpm gate:fastepnpm pushficam verdes. - Não há migration, alteração de schema,
Consentnovo, escrita multi-collection ou acesso a DB de produção.
Self-score (decision-quality)
- Decisões caras com rejeitadas: 5/5 — canonical, fuso,
VTIMEZONE, URL do VEVENT, owner das transformações e camadas de teste têm opções explícitas. - Cabe no appetite: 5/5 — helpers puros, duas frontiers server/client e atualização de specs; sem schema, admin ou UI nova.
- Rabbit holes nomeados: 5/5 — domínio paralelo, feed público, sync da campanha, parser, recurrence, RSVP e integração externa estão fora.
- Depth check: 5/5 — reusa
shareLinkPath, o reader server-only, o resolver de SEO,campaignTime,icale os consumers existentes; não cria uma agenda gêmea. - Intenção preservada: 5/5 — todos os bullets do aceite têm arquivo, formato de saída e verificação correspondentes.
Média: 5,0/5 — gate de decisão aprovado para execução --auto.