teqo-backup/docs/plans/agenda-do-link-de-anuncio-com-link-e-assinatura-impl.md

199 lines
18 KiB
Markdown

# 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 1313` uma única vez e apresentam o horário no fuso `America/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 `.ics` também tem `URL` de `VEVENT`; 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
```mermaid
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 1313` ao 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 reutiliza `getCachedGlobal('metadata')`, `resolveSiteMetadata`, `absoluteSitePath` e `shareLinkPath`; devolve a URL canônica ou `undefined`. Não altera o reader de publicados nem o filtro `published: 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. Manter `resolveShareLinkMetadata`, `noindex`, redirect de link direto, poll de live e branch de destino sem alteração.
- **`src/lib/shareLinkAnnouncement.ts`**: adicionar `canonicalUrl: string | null` ao view e ao builder do view. A função continua pura e client-safe; não importa metadata, environment ou `window`.
- **`src/components/shareLink/ShareLinkAnnouncement.tsx`**: encaminhar `view.canonicalUrl` para `ShareLinkAgendaMenu`. 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 ao `buildGoogleCalendarEventUrl`. O menu continua condicionado a `startsAt`; uma URL ausente não pode esconder o menu. O href do download continua `shareLinkIcsPath(slug)`, que é um path de navegação e não a URL descrita no VEVENT.
- **`src/lib/calendarEvent.ts`**:
- estender `CalendarEventInput` com `url` opcional;
- centralizar sufixo, composição da descrição e validação de URL absoluta;
- formatar os instantes como horário civil de `America/Bahia` para os campos de evento;
- emitir `ctz=America/Bahia` no Google, sem `Z` em `dates`;
- emitir `VTIMEZONE`, `TZID` e campos locais no ICS;
- manter `METHOD`, `PRODID`, `UID`, `DTSTAMP`, `LOCATION`, `resolveCalendarEventWindow`, o fallback de 2h e o retorno `null` sem início válido;
- continuar usando `escapeICalText` e `foldICalLine` em todas as linhas lógicas do ICS.
- **`src/lib/campaignTime.ts`**: adicionar um export puro para data/hora local IANA com segundos, reaproveitando `getZonedParts`; não alterar `formatIsoAsBahiaDateTimeInput`, `formatBahiaEventDateLabel` nem os contratos usados pelo admin.
- **`src/lib/shareLink.ts`, `src/lib/ical.ts` e `src/utilities/seo.ts`**: reutilizar `shareLinkPath`, os primitivos iCal e o resolver de SEO; não criar helpers gêmeos.
- **`src/utilities/calendarFeed.ts` e `src/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 executar `migrate:create`, `migrate` ou `generate: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
1. **Tracer de domínio puro (~40% do appetite)**
- Atualizar `calendarEvent.ts` e 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.000Z` vira `19:00` da Bahia no Google e no ICS, enquanto `DTSTAMP` permanece 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.
2. **Wiring server/client (~35%)**
- Adicionar o reader de canonical e alimentar `canonicalUrl` no 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.URL` sobre `NEXT_PUBLIC_SITE_URL`, o caminho `/<slug>` e o retorno ausente sem URL.
- Rodar:
- `pnpm test:int -- tests/int/shareLink.int.spec.ts`
- `pnpm 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`.
3. **Integração e fechamento (~25%)**
- Atualizar `tests/e2e/frontendShareLink.e2e.spec.ts` para abrir o menu no browser e verificar o `href` do Google sem abrir o serviço externo.
- No mesmo spec, baixar o `.ics` e verificar, após unfold, `SUMMARY`, `DESCRIPTION`, `URL`, `VTIMEZONE`, `TZID`, `DTSTART` e `DTEND` locais; 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.ts`
- `pnpm test:e2e:affected`
- `pnpm gate:fast`
- `pnpm push`
- `pnpm push` fecha a entrega e executa o gate de CI; não usar `git push` diretamente.
## 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_URL` ou de novo env:** cortar. A origem segue o contrato de metadata/SEO.
- **Usar `window.location.origin`, host da requisição ou `resolveDeploymentOrigin`:** cortar. Nenhum deles representa o canonical público.
- **Colocar a URL em `LOCATION` do Google:** cortar. O local continua sendo o local configurado.
- **Adicionar `URL` ao Google template:** cortar. Google recebe a URL na descrição; `.ics` recebe 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.ts` ou `src/lib/googleCalendarEventMapping.ts`:** cortar. O `VTIMEZONE` novo 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 em `resolveShareLinkCanonicalUrl`, usar `shareLinkPath` e comparar no e2e a URL da descrição com `URL:` 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 sem `Z`; `DTSTAMP` é o único campo de evento que continua com `Z`. Os testes verificam a consulta e o corpo após unfold.
- **Cliente não reconhecer `TZID`:** o `.ics` inclui `VTIMEZONE` completo, `TZID` e offsets fixos de `-0300`; não confiar apenas em um `X-WR-TIMEZONE` nã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 de `ical.unit.spec.ts` confirma 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 `calendarFeed` como regressão, sem esperar mudança no formato atual.
- **Regressão de página, redirect ou kill switch:** o e2e existente de `frontendShareLink` continua verificando noindex, redirect pós-live, 404 e republicação.
- **Metadata ausente no build:** `resolveSiteMetadata` e `absoluteSitePath` mantê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:** `resolveShareLinkCanonicalUrl` terá consumidores na página e na rota; o formatter Bahia terá consumidores no builder e teste. `knip` e `check:cycles` entram no gate.
## Aceite de engenharia
- [ ] Google Agenda e `.ics` usam a URL canônica do anúncio, nunca o destino, o `.ics` ou 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 `.ics` contém `URL` de `VEVENT`; o Google não recebe um campo de URL paralelo.
- [ ] Google usa horário local da Bahia com `ctz=America/Bahia`; o ICS usa `TZID` e `VTIMEZONE` fixo `America/Bahia`/UTC-3, sem DST.
- [ ] `DTSTAMP` e 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 `URL` no 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 `ShareLink` não ganham campo, seção, rótulo ou fluxo novo.
- [ ] `calendarFeed.ts` e `googleCalendarEventMapping.ts` permanecem intocados.
- [ ] Unit, int e e2e afetados cobrem a matriz acima; `pnpm gate:fast` e `pnpm push` ficam verdes.
- [ ] Não há migration, alteração de schema, `Consent` novo, escrita multi-collection ou acesso a DB de produção.
## Self-score (decision-quality)
1. **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.
2. **Cabe no appetite:** 5/5 — helpers puros, duas frontiers server/client e atualização de specs; sem schema, admin ou UI nova.
3. **Rabbit holes nomeados:** 5/5 — domínio paralelo, feed público, sync da campanha, parser, recurrence, RSVP e integração externa estão fora.
4. **Depth check:** 5/5 — reusa `shareLinkPath`, o reader server-only, o resolver de SEO, `campaignTime`, `ical` e os consumers existentes; não cria uma agenda gêmea.
5. **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`.**