diff --git a/docs/CHANGELOG-AGENTS.md b/docs/CHANGELOG-AGENTS.md index b8c2337a..79c2cde8 100644 --- a/docs/CHANGELOG-AGENTS.md +++ b/docs/CHANGELOG-AGENTS.md @@ -4,6 +4,8 @@ Conteúdo movido do `AGENTS.md` em 2026-07-30 (fatiamento do paradigma de agente --- + +**Recently resolved (2026-08-11):** **C115** (Issue #636) — **Google Calendar → Teqo**: quem tem permissão no calendário remarca/renomeia/cancela o compromisso direto no Google e a mudança volta para a atividade (bidirecional sobre o espelho C114). **Motor único bidirecional** no `runSyncPass` do C114 (estende o dono): para cada evento nosso — conteúdo difere? → **regra do relógio** (`remote.updated` > `activity.updatedAt` + tolerância 2s, `googleEditIsNewer` puro): Google mais novo aplica **título + horário** (all-day incluído, `googleScheduleToActivityFields` via `activityAllDay`; prefixo `[Município] ` do summary só é destripado quando bate com o município — desfazemos só a nossa prefixação; título cap 160) com **registro auditável** no `updates` feed (`Google Calendar: …`, `author: null`, feed mostra "Google Calendar" como autor pelo prefixo) — senão o Teqo re-asserta (forward). **Cancelamento:** `listEvents` ganhou `showDeleted=true` — evento com `status: 'cancelled'` (lixeira do Google) + atividade `confirmado` → cancela a atividade no Teqo (próxima passada apaga o trashed; `realizado` é histórico protegido — no-op); **remoção permanente** distinguida de "nunca criado" por snapshot `lastSeenEventIds` (JSONB `{calendarId, ids}` na collection, gravado só em passada bem-sucedida — create falhou → próxima passada cria, não cancela; troca de `calendarId` → snapshot stale → cria tudo de novo sem cancelar). **Webhook público** `POST /campanha/agenda/google-webhook/[secret]` (fora de `(app)`, precedente `ical/[secret]`, `maxDuration=60`, `force-dynamic`, allowlist do `campaignJsonMutationRoute` com razão): validação fail-closed em lib pura testada (`isGooglePushNotificationValid` — secret da URL + `X-Goog-Channel-ID` + `X-Goog-Resource-ID` + `X-Goog-Channel-Token`, constant-time, 404; `not_exists` → estado de erro; `sync` → ignora); ping não traz payload → passa completa. **Canal lazy sem cron (Hobby):** `ensureGoogleCalendarPushChannel` em toda passada — watch com UUID novo, token=secret da URL, TTL 30d; expira em <48h → watch com **id novo** (doc oficial: id único por canal) + `channels.stop` do antigo; troca de calendário → re-watch; falha → `pushChannelError` (state), **nunca** pausa (o reverso roda em todo trigger local; canal só dá imediatismo — limitação de 30d de silêncio documentada). Campos novos na `googleCalendarSync` (system-write; migration **hand-written** — mesmo motivo do C114: gerador re-emitiria CREATE TABLE). **Título editável pelo Google** exigiu kind de contexto dedicado `mutationKind: 'googleCalendarSync'` no `setCanonicalActivitySlug` (título muda, slug canônico congelado — URLs públicas intactas; validação de schedule continua rodando). UI (Impeccable B): seção "Edições pelo Google" no dialog (copy + expiração do canal + erro). Testes: unit (reverse mapping 18, validação do webhook 7, allowlist), int (10 novos no motor com stub: Google novo aplica+converge, Teqo novo re-asserta, cancelled cancela+limpa, remoção permanente via snapshot, create falhou não cancela, troca de calendário não cancela+re-watch, realizado protegido, description-only não gera registro, ciclo do canal cria/renova/stop, falha de canal não pausa), e2e (webhook 404 fail-closed). 19/19 int do motor isolado; suíte completa verde. Intenção [`c115-google-calendar-edicao-bidirecional.md`](plans/c115-google-calendar-edicao-bidirecional.md); impl [`c115-google-calendar-edicao-bidirecional-impl.md`](plans/c115-google-calendar-edicao-bidirecional-impl.md). **Recently resolved (2026-08-11):** **C126** (Issue #686) — os int specs do espelho Google (C114) deixam de flakear sob a suíte paralela: o motor ganhou **escopo injetável** `activityWhere?: Where` em `CampaignCalendarSyncOptions` (`src/utilities/googleCalendarSync.ts`) — appendado ao `and` do push set (`loadSyncActivities`) **e** do delete-guard set (`loadAliveActivityIds`); produção (hooks + action) omite o param → espelho cheio byte-identical. A race era mais ampla que o par da Issue: **5** specs criam atividades in-window no banco compartilhado (`campaignActivity`, `calendarFeed`, `homeSearchActivities`, `municipalityDossierData` + `campaignSuggestions` com `realizado` no lookback — o 5º que a Issue não nomeou), e `outcome.created` global contava todas; serialização não era construtível (vitest não serializa par-a-par; `fileParallelism:false` mataria o paralelismo da suíte) e "nunca relaxar a asserção" foi mantido à letra. O spec roda cada pass via helper `runSync(client, reason)` com `activityWhere: { title: { like: 'C114%' } }` (mesmo filtro do afterEach) e ganhou **dois pins**: (1) atividade estrangeira in-window **não** é espelhada; (2) o delete-guard honra o escopo (evento de atividade alheia viva é removido — espelho escopado é autoritativo no seu escopo). **Conflito com o C122 (#705, mergeado antes):** o C122 endereçou a C126 pela abordagem oposta (asserções globais **removidas** em favor de scoping por event-id, com delegação explícita do desfecho: "quem a detém decide") — a resolução do rebase mantém o contrato da Issue (contagens globais restauradas e determinísticas via escopo) e absorve a infra do C122 (credential compartilhada `googleCalendarTestKey`, cleanup de config por owned id, datas C127 derivadas do agora). **Contraprova:** fix 3/3 rodadas × 5 arquivos verdes (62/62); motor antigo re-flakeia 3–5 testes/rodada nas mesmas condições, e o pin 1 falha 100% — regressão viva. Gates: unit 2050, int 747, lint/typecheck/format/knip/cycles/build verdes. Sem migration/access/Consent/UI. Débito C127/#688 (datas hardcoded) já resolvido pelo C122 (#705). Impl [`c126-espelho-google-int-flake-isolamento-impl.md`](plans/c126-espelho-google-int-flake-isolamento-impl.md) (Issue = spec, sem intenção própria). **Recently resolved (2026-08-11):** **OPS41** (Issue #689) — o `AGENTS.md` de main carregava **marcadores de conflito commitados** no bullet "Per-worktree environments" (` <<<<<<< HEAD` indentado + lado HEAD pré-OPS33 com artefato `- # ` + fechamento corrompido `> > > > > > > 9e18bec8`; o `=======` foi removido no próprio commit). Origem: o commit OPS33 f0f5b73f entrou com o arquivo **já conflitado** (resolve do conflito OPS33×OPS28/OPS31 commitado com marcadores); OPS37 herdou o estado. Resolução **perda zero validada por diff**: manter o lado superset (OPS28 + OPS31 + OPS33 — claim determinístico, `--issue N`, prompt citado) e descartar o lado HEAD; −3 linhas no diff; scan whitespace-tolerant de todos os arquivos trackeados confirmou `AGENTS.md` como único afetado. **Guardrail anti-reincidência** (2ª vez que marcador chega a main): novo describe `no conflict markers in committed files` em `tests/unit/codebaseConventions.unit.spec.ts` — varre `git ls-files`, falha em `<<<<<<<`/`>>>>>>>` (tolerante a indentação) e na forma corrompida commitada `^\s*(> ){7}`; roda no CI via `pnpm test:unit`. Sem migration/access/Consent/UI/schema. Intenção: body da Issue (sem plano linkado); impl [`agents-md-sem-marcadores-conflito-impl.md`](plans/agents-md-sem-marcadores-conflito-impl.md). @@ -16,6 +18,7 @@ Conteúdo movido do `AGENTS.md` em 2026-07-30 (fatiamento do paradigma de agente **Recently resolved (2026-08-11):** **B197+** (Issue #642) — o menu do picker de colunas de assessores nasce da **mesma fonte** que os `` do `AdvisorsTable` (fim do espelho): o módulo client declara `advisorTableColumns` (id/label/mandatory + `headerClassName` + `visuallyHiddenLabel` para o `sr-only` de Ações) e exporta `advisorPickerColumns = toCampaignColumnPickerColumns(...)` (precedente `supporterPickerColumns`); o header renderiza por `resolveVisibleColumns(advisorTableColumns, hiddenColumnIds)` — mesmo helper B17 das outras listas — e `emailHidden` deriva do mesmo `visibleColumns`. **Descoberta do /simplify incorporada:** o corpo só condiciona a coluna `email` (células à mão + exceção do draft), então `phone`/`municipalities`/`actions` são `mandatory: true` — esconder um deles (cookie velho do toggle inerte do B197) derrubaria o `` sobre um corpo de 5 células; os checkboxes viram "sempre visível" (honestos). `assessores/page.tsx` consome a fonte exportada e perdeu o array espelho + imports órfãos. Comportamento da tabela idêntico (ids/labels/ordem, exceção do draft intacta); e2e `campaignColumnPicker` ganhou pin dos mandatory. Sem migration/access/Consent/UI/cache. Observações de ambiente (não da mudança): o e2e do picker falha no harness dev sob carga desta máquina (painel do popover não monta; falha idêntica na base e em lideranças — intocado; conjunto falho deriva com a carga; verificado funcional em Chromium real); warning React de key pré-existente no assessores (`CampaignListOmnibox` — base também). Intenção [`escala-dry-pos-b197.md`](plans/escala-dry-pos-b197.md); impl [`escala-dry-pos-b197-impl.md`](plans/escala-dry-pos-b197-impl.md). + **Recently resolved (2026-08-11):** **C116** (Issue #655) — `/campanha/pessoas` desktop vira **edit-where-you-see**: toda célula (exceto Ações) é um input permanente sem destaque — salva no blur/Enter, Esc descarta, vazio mostra "—" apagado. **Nome** mantém o valor como link para a ficha (`/campanha/liderancas/[id]`) com o mecanismo travado no gate: input invisível (`text-transparent`, z-0) sobre o link (z-10, `pointer-events-auto`, `w-auto` — cobre só o texto; o resto da célula é a área clicável do input), draft renderizado **no texto do link** (o valor real do input nunca é o display), clique no link navega, teclado/área fora do texto edita. **Células de municípios** (Assessora, Lidera, Aliada em) e **Assessorado** usam chips internos com: grupo novo **"Salvador (19)"** (`buildMunicipalityPortfolioChips` ganha kind `city`, checado antes do território — senão as 19 ZEs colapsariam como "Metropolitano de Salvador"), **chip batch clicável expande in loco** (estado de apresentação do wrapper `PeopleMunicipalityCell` — clique expande, mouse-leave colapsa se todos os membros seguem atribuídos; X num membro remove e impede o recolapso), **"+X"** no toggle de overflow do B170, `quiet` (sem tint de hover/foco; indicador de foco discreto só no input), commit por **match exato** no Enter/espaço (digitar "salvador-ze-2"+Enter adiciona a ZE certa, não a pre-selecionada — regra da intenção). Escrita: `updatePersonContactRecord` (escopo "edita o que vê" — assessor só com entidade da pessoa na carteira; `contactFieldUpdateSchema` ganhou variante `city`, convivendo com `phones` do C112), `setPersonAssessoraMembershipRecord` (unrestricted-only, single-account — multi-conta nega com mensagem segura e célula read-only; toggle extraído para `toggleMunicipalityAdvisorMembership` em `municipality.ts`, reusado pelo record B27) e `setPersonAdvisorMembershipRecord` (union person-centric: delta de assessor nas DUAS entidades quando ambas existem). Matriz por papel na página: assessor edita Lidera/Aliada com `addableIds`=carteira e **read-only** em Assessora/Assessorado (regras das collections donas); tooltips de label (WhatsApp/Convidar/Apagar) via `CampaignHoverTooltip`; `CampaignListSheetProvider` na tabela (guard miss #52 — wrapper de composição registrado no `sharedSheetHostConventions`). Mobile intacto. Sem migration. Testes: unit (grupo Salvador + expand + match exato; guard do sheet host), int novo `campaignPersonCellEditing` (11 — escopo por papel, assessora single/multi/sem-conta, union nas duas entidades), e2e `campaignPeople` 4/4. Intenção [`pessoas-edicao-inplace-lista.md`](plans/pessoas-edicao-inplace-lista.md); impl [`pessoas-edicao-inplace-lista-impl.md`](plans/pessoas-edicao-inplace-lista-impl.md). **Recently resolved (2026-08-11):** **B198** (Issue #660) — o drawer mobile do Sollinha fecha ao navegar por link interno: tocar num link `/campanha…` da resposta fecha o drawer **no toque** (antes de a página carregar) e a navegação segue no mesmo tab; desktop inalterado (painel fica aberto); link externo (nova aba) não fecha o drawer da aba de origem; reload não reabre (o close persiste `open: false`). **Engrenagem:** a decisão pura mora no owner `src/lib/ai/markdownLinks.ts` — regex `^\/campanha(?:\/|$)` promovido a `isCampaignInternalLink` (era `APP_INTERNAL_LINK` no renderer) + `shouldCloseDrawerOnLinkClick(href, isMobile, event)` (fecha ⇔ interno && mobile && clique simples — ignora ctrl/meta/shift/alt, middle-click e `defaultPrevented`, pois abrem nova aba e a origem mantém o chat); o `markdownComponents` estático do `CampaignAIChat` virou `useMemo` no corpo (acesso ao `ctx.isMobile`/`setOpen`; identidade estável, recomputa só no crossing de breakpoint). Sessão/restauração intactas (fechar com `requestOpen(false)` marca `openBy:'user'` com `open:false` — inerte, o restore só reabre com `open:true`). Testes: unit (12 — interno/externo, viewport, modifiers, middle, prevented) + e2e no `campaignSollinhaContext` (interno fecha+navega sem `load`+reload não reabre; externo mantém drawer e abre popup interceptado). Nota: dev-mode local flakeou no prewarm/compile cold — e2e rodado no modo CI (`E2E_PROD=1` com `NEXT_DIST_DIR=.next/e2e`, 7/7). **Débito registrado no gate (B199/#672, `depends` #660):** race pré-existente do persist effect (só grava com `status==='ready'`) — fechar o drawer mid-stream e recarregar antes do settle reabre o drawer "sozinho" (classe OPS22); o tap-no-link do B198 amplia a superfície. Intenção [`sollinha-drawer-fecha-link-mobile.md`](plans/sollinha-drawer-fecha-link-mobile.md); impl [`sollinha-drawer-fecha-link-mobile-impl.md`](plans/sollinha-drawer-fecha-link-mobile-impl.md). diff --git a/docs/plans/c115-google-calendar-edicao-bidirecional-impl.md b/docs/plans/c115-google-calendar-edicao-bidirecional-impl.md new file mode 100644 index 00000000..c596f242 --- /dev/null +++ b/docs/plans/c115-google-calendar-edicao-bidirecional-impl.md @@ -0,0 +1,145 @@ +# Impl: C115 — Google Calendar: edição pela agenda pessoal volta para Teqo (bidirecional) + +Status: aprovado +Atualizado em: 2026-08-11 +Issue: #636 +Intenção: docs/plans/c115-google-calendar-edicao-bidirecional.md +Appetite restante: ~2–2,5 dias eng (herdado; corte explícito: criação no Google fora de v1; apenas título/horário/cancelamento voltam) + +## Leitura da intenção + +- **Outcome:** candidato (e autorizados) edita/remarca/cancela um compromisso da Agenda da Campanha no Google Calendar e a mudança volta para o Teqo — a atividade é atualizada, o registro fica auditável e o espelho propaga para quem segue (mecanismo do C114). +- **O que NÃO negociar:** sem criação de eventos pelo Google em v1; conflito = regra automática (mais recente vence) com registro, nunca tela; acessos do Teqo valem para o que vem do Google (leader lockdown intocado); Teqo permanece SoT do domínio — o Google é superfície de edição (horário/título/cancelamento) e o Teqo reescreve o evento a partir do próprio estado; Teqo funciona sem Google. +- **O que reavaliar:** a intenção aponta "webhook do Google + sync incremental" — confirmado, com duas correções de engenharia: (1) a notificação do Google NÃO diz qual evento mudou ("bare ping", doc oficial) — o "sync incremental" da intenção vira uma passada completa de reconciliação (o motor C114 já lista a janela inteira; não há custo marginal relevante); (2) o canal de push exige renovação periódica e **não há cron no Hobby** — renovação lazy em cada trigger do motor (aceite "se renova sozinho" = sem ação manual, com a limitação de silêncio de 30 dias documentada). A intenção assume "edição mais recente vence" — o forward do C114 hoje sobrescreve QUALQUER diferença de conteúdo; o motor precisa virar bidirecional com regra de relógio, senão o forward clobbera a edição do Google (contradição com o aceite). + +## Abordagem recomendada + +```mermaid +flowchart LR + G[Google Calendar
usuário edita/remarca/cancela] -->|notificação push| W[webhook público
campanha/agenda/google-webhook/[secret]] + W -->|valida X-Goog-* + token
200 imediato| R[passada bidirecional
googleCalendarSync.ts] + A[trigger local:
hook activity / view agenda /
Sincronizar agora] --> R + R --> D[diff por id determinístico + relógio:
Google mais novo → aplica no Teqo
Teqo mais novo → re-asserta no Google
status cancelled → cancela atividade] + D --> T[(atividade atualizada
+ registro no updates feed)] + D --> C[ensurePushChannel
watch/renova/stop — best-effort] + C --> S[(estado do canal
googleCalendarSync)] +``` + +**Opções consideradas:** D1–D8 abaixo. +**Recomendação:** um **motor único bidirecional** (regra de relógio decide a direção por evento), **webhook público com validação fail-closed** (URL secret + `X-Goog-Channel-ID` + `X-Goog-Resource-ID` + `X-Goog-Channel-Token`, comparação constant-time), **canal de push lazy** (ensure em toda passada; TTL 30 dias; renovação = watch com UUID novo + `channels.stop` do antigo), **cancelamento detectado por `showDeleted=true`** (status `cancelled` = usuário cancelou → cancela a atividade) **+ snapshot `lastSeenEventIds`** (remoção permanente ≠ nunca criado), **registro no `updates` feed** da atividade com prefixo "Google Calendar:" (sem schema novo de updates). + +### Decisões de engenharia + +**D1 — Detecção Google → Teqo.** +Opções: A) **push channel** (`events.watch`, webhook `web_hook`) + passada completa ao receber | B) polling com cron | C) `syncToken` incremental. +Recomendação: **A** — latência de segundos (aceite "minutos"), sem cron no Hobby; a notificação é um ping sem payload ("nothing about the change itself", doc oficial), então o handler roda a mesma passada completa do motor — que já lista a janela inteira (D3 C114), sem custo marginal real (centenas de eventos). +Rejeitadas: B (sem cron no Hobby; cadência de horas não entrega o aceite); C (syncToken expira em ~30d, adiciona estado e não economiza nada — a passada já é full-list; o ping → passada completa é o fluxo documentado do Google). + +**D2 — Um motor bidirecional (não dois caminhos).** +Opções: A) **regra de relógio dentro do `runSyncPass` atual**: para cada evento nosso, conteúdo difere? → quem é mais novo aplica (Google → update na atividade; Teqo → update no evento) | B) passada reversa separada rodando antes do forward | C) só forward + reverter edições do Google no próximo ciclo. +Recomendação: **A** — um único caminho de código (uma superfície de teste), e é o único jeito de a regra "mais recente vence" valer em TODOS os triggers: sem A, o forward (disparado por qualquer escrita no Teqo) sobrescreveria a edição do Google antes de ela ser aplicada. "Edit the owner": o dono da reconciliação é o motor C114 — estende, não cria irmão. +Rejeitadas: B (duas passadas = chamadas duplicadas + orquestração; a decisão de direção É o relógio, um único diff resolve); C (viola o aceite — a edição do Google seria revertida na passada seguinte). + +**D3 — Regra de conflito (relógio).** +Opções: A) **vence o mais novo**: `remote.updated > activity.updatedAt + tolerância (2s)` → aplica edição do Google; senão Teqo re-asserta (forward) | B) Teqo sempre vence | C) pausa o evento. +Recomendação: **A** — decisão travada da intenção; content-compare roda ANTES do relógio (passadas convergem sem tocar em nada, D3 C114); a tolerância de 2s absorve skew NTP entre Google e o banco (ambos NTP); quando NOSSA escrita gera notificação, conteúdo é igual → no-op (sem loop). O relógio só decide quando há diferença real de conteúdo. +Rejeitadas: B (trai o sentido de "editar pelo Google"); C (vira a tela de conflito cortada na intenção). + +**D4 — Cancelamento pelo Google.** +Opções: A) **`showDeleted=true` no list + snapshot `lastSeenEventIds`**: evento `status: 'cancelled'` (lixeira do Google) com atividade `confirmado` → cancela a atividade; evento sumiu por completo com id no snapshot da passada anterior → usuário removeu permanentemente → cancela; id fora do snapshot → nunca criado (calendário novo) → cria | B) todo "sumiu" = cancelar | C) todo "sumiu" = recriar. +Recomendação: **A** — a lixeira é o sinal direto de cancelamento (o UI padrão do Google trashes, não remove); a remoção permanente só se distingue de "nunca criado" com o snapshot (a passada anterior viu o id). Snapshot = JSONB `lastSeenEventIds` na collection de sync (estado transitório de reconciliação, NÃO duplicação do mapeamento — o id determinístico D2/C114 continua sendo a identidade). Só grava em passada BEM-SUCEDIDA: um create que falhou não entra no snapshot → próxima passada cria (não cancela). Cancelação só quando `activity.status === 'confirmado'` (compromissos vivos): `realizado` é histórico protegido (no-op; o evento trashed fica invisível na lixeira do usuário). Após cancelar, o forward da passada seguinte apaga o trashed permanentemente (convergência; o C114 já exclui eventos de atividades não vivas). +Rejeitadas: B (quebraria a primeira sincronização: calendário novo → todas as atividades seriam canceladas); C (ressuscita remoção deliberada do usuário e é a semântica atual do C114 que o C115 precisa substituir). + +**D5 — Canal de push: criação e renovação lazy (sem cron).** +Opções: A) **ensure na passada do motor**: sem canal → `events.watch` (UUID novo, `token` = segredo da URL, TTL 30 dias via `params.ttl`); expira em <48h → watch com **UUID novo** (doc oficial: "you must use a unique value for the id property of the new channel") + `channels.stop` do antigo; falha → `pushChannelError` (state), **nunca** `paused` | B) cron de renovação | C) renovar com o mesmo id. +Recomendação: **A** — todo trigger existente do C114 (hook de activity, view da agenda, "Sincronizar agora", config-change) vira também renovador; TTL máximo (~30d, limite interno do Google) minimiza renovações; a falha do canal NUNCA pausa o sync (o reverso continua funcionando pelos triggers locais — toda passada é bidirecional, o canal só dá imediatismo). Address = `getCampaignInviteBaseURL()` + `/campanha/agenda/google-webhook/` — **C98 lesson**: `NEXT_PUBLIC_SITE_URL` obrigatória em prod (sem ela, ensure falha com `pushChannelError` legível, não quebra nada). +Rejeitadas: B (sem cron no Hobby); C (doc oficial exige id único por canal; re-watch com mesmo id tem comportamento indefinido). +Limitação documentada no runbook: com 30 dias de silêncio total (nenhuma escrita no Teqo, nenhuma view, nenhuma notificação) o canal expira e o reverso passa a depender do próximo trigger local — dentro do "renova sozinho" (nunca ação manual), com a lacuna de silêncio declarada. + +**D6 — Webhook público (superfície nova, fail-closed).** +Opções: A) **rota `POST /campanha/agenda/google-webhook/[secret]/route.ts` fora de `(app)`** (precedente `agenda/ical/[secret]`): segredo na URL (≥32 chars) + `X-Goog-Channel-ID` == `pushChannelId` + `X-Goog-Resource-ID` == `pushChannelResourceId` + `X-Goog-Channel-Token` == token — todas comparações constant-time; falha → 404 (precedente iCal: não revela existência) | B) assinatura de corpo | C) rodar a passada em background pós-response. +Recomendação: **A** — 200 imediato após validação; passada inline (`export const maxDuration = 60` — Hobby permite até 60s; uma passada típica é 1 list + N updates, segundos); erros da passada NÃO viram não-200 (o Google re-tentaria e replicaria trabalho; o auto-retry local já cobre); `X-Goog-Resource-State: sync` (notificação de criação de canal) → ignora (passada já roda nos triggers). `not_exists` (recurso apagado) → estado de erro no sync ("calendário não existe mais"). +Rejeitadas: B (o corpo do push do Calendar é vazio por contrato — a autenticidade É o token + ids, que o Google documenta para isso); C (serverless congela após o response; trabalho perdido + Google re-tenta — pior que inline). + +**D7 — Estado do canal e snapshot (collection `googleCalendarSync` + migration).** +Opções: A) **campos novos na collection existente** (system-write via `canSetGoogleCalendarSyncSystemField`): `pushChannelId`, `pushChannelResourceId`, `pushChannelExpiresAt`, `pushChannelSecret`, `pushChannelError` + `lastSeenEventIds` (json) | B) collection separada de canais | C) tudo em env. +Recomendação: **A** — "edit the owner": a collection É o recurso de sync (C114 D5); estado do canal vive junto do estado do sync; `pushChannelSecret` segue o precedente `calendarFeed.secretSlug` (credencial de link em DB, não em env — env exigiria redeploy para rotacionar); o config hook (`shouldSyncConfigChange`) só olha `calendarId`/`disabledAt` → escritas de estado nunca re-disparam (guard existente, sem loop). `calendarId` trocado → canal antigo é stopado na ensure seguinte e o snapshot é re-derivado por passada (o novo calendário lista vazio → cria tudo de novo — D7 C114 preservado). +Rejeitadas: B (mais uma collection/access para um estado de 5 campos); C (calendarId/channel rotacionariam por redeploy). + +**D8 — Registro da edição ("com registro").** +Opções: A) **entrada no `updates` feed da atividade** com body prefixado `Google Calendar: …` e `author: null`; o card mostra "Google Calendar" como autor quando o body tem o prefixo (fallback do `ActivityUpdateFeed`, mudança contida) | B) log no `googleCalendarSync` | C) notification do Teqo. +Recomendação: **A** — o registro é visível no contexto da atividade (a equipe vê "remarcada de X para Y pelo Google Calendar" na aba Atualizações), sem schema novo (o array `updates` e a derivação do `deriveActivityFields` já existem; `author: null` passa pelo passthrough); a notificação Teqo fica de fora (o aceite manda "mesmo mecanismo do C114" = aviso do próprio Google aos seguidores). +Rejeitadas: B (invisível para a equipe no contexto do compromisso); C (novo tipo de notification para um caso que o feed já conta). + +**D9 — Campos reversos editáveis (v1).** +Opções: A) **título + horário**: `summary` → `title` (strip de `[] ` apenas quando o prefixo bate com o município da atividade — desfazemos só a nossa própria prefixação; resto vira título inteiro); `start`/`end` do evento → `startAt`/`endAt`/`allDay` (presença de `date` vs `dateTime` decide all-day; converte com `activityAllDay`); somente atividades `status: 'confirmado'` | B) incluir location/description | C) permitir em qualquer status. +Recomendação: **A** — o aceite lista data/hora/título/cancelamento; locality/description/location/tags são campos do Teqo (a regra estrutural da intenção: Google é espelho para o resto — o forward re-asserta). `confirmado`-only protege `realizado` (histórico) e `cancelado` (Teqo SoT). A validação local (`validateActivitySchedule`) roda na aplicação: valor remoto malformado → o update falha → o Teqo mantém o estado e o forward re-asserta (fail-safe embutido). +Rejeitadas: B (descrição é rica em campos do Teqo; parse de volta = fragile e fora do aceite); C (editar realizado via Google corrompe histórico; cancelado no Teqo já é gerenciado). + +### Componentes / mudanças + +- **`src/lib/googleCalendarReverseEdit.ts`** (novo, puro, unit-testável): `googleTitleFromSummary(summary, municipalityName)` (strip condicional do prefixo), `googleScheduleToActivityFields(event)` → `{ startAt, endAt, allDay }` ou `null` (malformado), `buildGoogleReverseUpdateBody(kind, antes→depois)` (pt-BR, prefixo `Google Calendar: `), `GOOGLE_REVERSE_EDIT_BODY_PREFIX` (compartilhado com o feed UI), `googleEditIsNewer(remoteUpdated, activityUpdatedAt, toleranceMs)` (regra do relógio pura). +- **`src/lib/googleCalendarEventMapping.ts`** (editar): `GoogleRemoteEvent` ganha `status?: string` e `updated?: string` (o list passa a devolver lixeira). +- **`src/utilities/googleCalendarClient.ts`** (editar): `listEvents` passa `showDeleted: true` (sem mudança de assinatura — o stub não é afetado); novos métodos `watchEvents(calendarId, { id, address, token, ttlSeconds })` → `{ id, resourceId, expiration }` e `stopChannel(id, resourceId)` (`POST /channels/stop`); `GoogleCalendarClient` (e stub de teste) crescem junto. +- **`src/utilities/googleCalendarSync.ts`** (editar — dono do motor): `runSyncPass` vira **bidirecional** (D2/D3/D4): por evento nosso — `status cancelled` → cancela atividade (`confirmado`); conteúdo difere → relógio decide (reverse via `payload.update` com `updates` + body prefixado, `overrideAccess: true` — sem usuário, precedente dos hooks; ou forward `updateEvent`); conteúdo igual → no-op; atividade querida sem evento → snapshot decide (cria vs cancela); snapshot `lastSeenEventIds` gravado no fim de cada passada bem-sucedida; `ensureGoogleCalendarPushChannel(payload, config, client)` (D5) chamado no início (best-effort; falha → `pushChannelError`, nunca `paused`); estados `not_exists` → `lastError` explicativo. `deriveGoogleCalendarSyncStatus` ganha a leitura do canal só para a UI (não muda a matriz — canal nunca pausa). +- **`src/collections/GoogleCalendarSync.ts`** (editar): campos novos D7 (system-write, `admin.readOnly`); `pushChannelExpiresAt` aparece nos defaultColumns. +- **Migration:** `migrate:create add_google_calendar_push_channel` (6 colunas: 4 text + 1 date + 1 json). +- **Rota pública** `src/app/(campaign)/campanha/agenda/google-webhook/[secret]/route.ts` (novo): `POST` (e `GET` → 404) fora de `(app)`, precedente `agenda/ical/[secret]`; validação D6; `export const dynamic = 'force-dynamic'`, `maxDuration = 60`; responde 200 e roda a passada; `not_exists` → estado de erro. +- **`src/components/campaign/activity/ActivityUpdateFeed.tsx`** (editar): fallback de autor — body com prefixo → "Google Calendar"; senão mantém "Autor removido". +- **`src/components/campaign/activity/GoogleCalendarSyncDialog.tsx`** (editar, Impeccable B — shape→craft→critique→polish): quando `synced`, seção "Edições pelo Google" com copy (candidato/autores editam no Google e volta para o Teqo) + estado do canal (ativa até quando o canal existe; mensagem de `pushChannelError` quando presente). Nada novo de ação — o toggle/retry existentes cobrem. +- **Server actions** (sem mudança): `runGoogleCalendarSyncNow` e a view da agenda já chamam o motor — agora bidirecional, o mesmo caminho traz o reverso. +- **`docs/CHANGELOG-AGENTS.md`** (editar): UMA entrada curta C115. +- **Access / Consent:** sem chave de Consent (dados internos da campanha, precedente C114); sem PII nova; o webhook é fail-closed (nunca processa sem canal/token válidos); a escrita reversa respeita os guards de hook do Activity (o guard de leader não se aplica — sem `req.user`); `overrideAccess` apenas onde o C114 já usa (engine), nunca em paths de usuário. + +### Dados → forma (se aplicável) + +N/A — não há apresentação de dados nova no Teqo; o único dado novo visível é o registro no `updates` feed (forma já existente) e o estado do canal no dialog (linha de texto derivada, sem forma nova). + +## Fases verificáveis + +1. **Tracer / schema+server** (dia 1): migration + collection fields + `generate:types`; client (`showDeleted`, `watchEvents`, `stopChannel`, `status`/`updated` no tipo); `googleCalendarReverseEdit` + unit tests; motor bidirecional + ensure de canal + int tests com stub (edição do Google mais nova → aplica; Teqo mais nova → re-asserta; `cancelled` → cancela; remoção permanente via snapshot → cancela; calendário novo → cria tudo; create falhou → cria na próxima, não cancela; canal: cria/renova/stop/falha não pausa; loop de re-entrada: passada após reverse é no-op); rota webhook + validação (unit: headers falsos → 404; token errado → 404); `migrate` local + `migrate:status`. +2. **UI** (dia 1–2): dialog (seção reverso + estado do canal), fallback do feed; e2e: webhook com segredo inválido → 404 (determinístico, sem Google), dialog mostra a seção quando sincronizado; Impeccable shape→craft. +3. **Gates** (dia 2): `pnpm gate:fast`; `pnpm format:check`; `pnpm exec knip`; `pnpm check:cycles`; `pnpm test` (unit+int); `pnpm test:e2e`; `pnpm build`; Aikido nos arquivos novos; `pnpm push` com CI green. + +## Rabbit holes / Não escopo (engenharia) + +- **Verificação de domínio do callback no Google Cloud** — se o Google exigir (alguns serviços pedem domínio verificado no console), é ops one-time (pt.jorgesolla.com.br); não bloqueia o código (falha → `pushChannelError` legível). +- **`syncToken` incremental** — D1; a passada full-list já cobre. +- **Participantes/attendees** — corte herdado do C114 (P1). +- **Criação pelo Google** — anti-goal da intenção (sem município não entra). +- **Recorrências/todos-os-dias complexos** — mapa de campos do espelho (C114), fora do aceite. +- **Notificação Teqo (sino) para edições reversas** — o feed é o registro; aviso aos seguidores é do Google. +- **Editar locality/description/location pelo Google** — D9; o forward re-asserta. +- **Lock distribuído da passada** — corridas convergem por conteúdo (herdado D3 C114); canal duplicado em renovação = notificações duplicadas, idempotentes. + +## Riscos e mitigação + +- **Semântica do push/`showDeleted` desconhecida na prática** — verificar no doc oficial durante o impl (source-driven-development); os int tests com stub travam NOSSO contrato, não o do Google. +- **Loop de re-entrada** (reverse aplica → hook roda passada) — conteúdo igual após aplicar → no-op; termina na segunda passada; verificado em int test. +- **Skew de relógio** Google × banco — tolerância 2s (D3); ambos NTP. +- **Canal morto sem trigger (30d de silêncio)** — limitação documentada no runbook; todo trigger local renova; a falha fica visível no dialog (`pushChannelError`/expiração). +- **maxDuration no webhook** — passada típica em segundos; `maxDuration = 60`; em pico o Google re-tenta (não-200) e o auto-retry local cobre. +- **Valores remotos malformados** — `validateActivitySchedule` rejeita → Teqo mantém estado e re-asserta (fail-safe). +- **Ressurreição por restore do Google** — usuário restaura evento cancelado → atividade já cancelada no Teqo → forward apaga de novo (Teqo SoT, documentado). +- **E2E com Google real** — webhook e2e só cobre fail-closed sem canal (404); motor testado em int com stub (precedente C114). + +## Aceite de engenharia + +- [ ] Aceite de produto da intenção coberto: edição de título/horário e cancelamento feitos no Google refletem na atividade do Teqo (com registro no feed) e o espelho propaga; criação não existe em v1; conflito = relógio, sem tela; leader lockdown intocado (sem superfície e sem escrita reversa para líder — `confirmado`-only, engine sem usuário); Teqo funciona sem Google (canal é best-effort; falha → estado, nunca quebra escrita). +- [ ] Regra de conflito documentada e testada: mais recente vence com tolerância; Teqo re-asserta campos estruturais; cancelamento só para `confirmado`. +- [ ] Webhook fail-closed: rota pública valida secret + channel id + resource id + token em tempo constante; sem canal configurado → 404; nunca processa corpo não validado. +- [ ] Invariantes AGENTS/engineering-standards: identificadores em inglês, copy pt-BR; escrita multi-coleção onde houver usa transação (aqui a escrita reversa é 1 doc — sem transação necessária, sem `req.transactionID`); sem PII nova no Google; segredo de URL em DB segue precedente `calendarFeed`; migration commitada; sem migration retroativa. +- [ ] Testes de domínio previstos: unit (reverse edit mapping, relógio, prefixo do summary, validação do webhook), int (motor bidirecional com stub: todas as direções de D3/D4/D5 + re-entrada + snapshot), e2e (webhook 404 fail-closed, dialog). +- [ ] Self-score decision-quality: 5/5 (decisões caras com rejeitadas; cabe no appetite; rabbit holes nomeados; depth check reusa motor C114, client, collection, ical route, `activityAllDay`, shells do dialog; intenção preservada). + +## Decisões em aberto (produto — para o gate humano) + +- Nenhuma nova: as questões abertas da intenção (B: candidato + coordenador editam; A: mais recente vence; A: estrutural não propaga) foram assumidas na própria intenção. Confirmação do gate = impl segue com elas. + +## Referências + +- Intenção: `docs/plans/c115-google-calendar-edicao-bidirecional.md` (gate de produto) +- Base obrigatória: impl C114 `docs/plans/c114-google-calendar-push-agenda-oficial-impl.md` (D1–D7 herdados) + código em `src/utilities/googleCalendarSync.ts` (494 linhas), `googleCalendarClient.ts`, `googleCalendarSyncHooks.ts`, `src/collections/GoogleCalendarSync.ts` +- Precedentes: `src/app/(campaign)/campanha/agenda/ical/[secret]/route.ts` (rota pública com segredo), `src/lib/activityAllDay.ts` (conversões all-day), `src/utilities/campaignInviteOrigin.ts` (`getCampaignInviteBaseURL` — C98), `src/collections/Activity.ts` (guards + updates), `ActivityUpdateFeed.tsx`/`GoogleCalendarSyncDialog.tsx` +- Docs oficiais consultados: [Events: watch](https://developers.google.com/workspace/calendar/api/v3/reference/events/watch), [Push notifications](https://developers.google.com/workspace/calendar/api/guides/push) (headers, token, renovação com id único, TTL default 604800s) +- Testes existentes: `tests/int/googleCalendarSync.int.spec.ts`, `tests/unit/googleCalendarSync*.spec.ts`, `tests/e2e/campaignAgendaGoogleSync.e2e.spec.ts` diff --git a/src/app/(campaign)/campanha/actions/googleCalendarSync.ts b/src/app/(campaign)/campanha/actions/googleCalendarSync.ts index 1cee7d83..9e468fb1 100644 --- a/src/app/(campaign)/campanha/actions/googleCalendarSync.ts +++ b/src/app/(campaign)/campanha/actions/googleCalendarSync.ts @@ -36,6 +36,8 @@ const failure = (message: string): GoogleCalendarSyncActionResult => ({ lastSuccessAt: null, lastErrorAt: null, lastError: null, + pushChannelExpiresAt: null, + pushChannelError: null, addLink: null, }) diff --git a/src/app/(campaign)/campanha/agenda/google-webhook/[secret]/route.ts b/src/app/(campaign)/campanha/agenda/google-webhook/[secret]/route.ts new file mode 100644 index 00000000..084ca974 --- /dev/null +++ b/src/app/(campaign)/campanha/agenda/google-webhook/[secret]/route.ts @@ -0,0 +1,86 @@ +import config from '@payload-config' +import { getPayload } from 'payload' + +import { isGooglePushNotificationValid } from '@/lib/googleCalendarPushNotification' +import { + loadGoogleCalendarSyncConfig, + recordGoogleCalendarSyncError, + runCampaignCalendarSync, +} from '@/utilities/googleCalendarSync' + +type RouteContext = { + params: Promise<{ secret: string }> +} + +// C115: the push channel is validated against the live config on every +// delivery — an explicit marker per repo convention (dynamic campaign routes +// declare it) so a cached handler can never accept a stale channel. +export const dynamic = 'force-dynamic' + +/** Google re-delivers failed notifications — a lean pass needs the extra headroom. */ +export const maxDuration = 60 + +const notFoundResponse = () => + new Response('Não encontrado.', { + status: 404, + headers: { + 'Content-Type': 'text/plain; charset=utf-8', + 'Cache-Control': 'no-store', + }, + }) + +export const GET = async (): Promise => notFoundResponse() + +/** + * C115 — Google Calendar push notifications (events.watch). Google POSTs a + * bare "something changed" ping with channel headers and NO event data — the + * handler validates the origin (URL secret + channel id + resource id + + * channel token, all constant-time) and then runs the same bidirectional + * reconciliation every other trigger runs. A valid ping answers 200 even if + * the pass fails (the failure lands in the `paused` state and the local + * auto-retry paths recover) — retries would only replicate work. + */ +export const POST = async (request: Request, context: RouteContext): Promise => { + const { secret } = await context.params + + const payload = await getPayload({ config }) + + // Intentional admin bypass: the endpoint is unauthenticated by design + // (Google delivers by URL); the secret + channel identity are the + // credential, validated below — fail-closed. + const doc = await loadGoogleCalendarSyncConfig(payload) + if ( + !isGooglePushNotificationValid({ + secret, + channelId: request.headers.get('x-goog-channel-id'), + resourceId: request.headers.get('x-goog-resource-id'), + channelToken: request.headers.get('x-goog-channel-token'), + config: { + pushChannelSecret: doc?.pushChannelSecret ?? null, + pushChannelId: doc?.pushChannelId ?? null, + pushChannelResourceId: doc?.pushChannelResourceId ?? null, + }, + }) + ) { + return notFoundResponse() + } + + const resourceState = request.headers.get('x-goog-resource-state') + + // `sync` is the channel-creation ping — nothing to reconcile yet. + // `not_exists` means the watched calendar itself is gone — record it so + // the staff sees why the sync stopped, instead of a silent no-op. + if (resourceState === 'not_exists') { + await recordGoogleCalendarSyncError( + payload, + 'O calendário configurado não existe mais no Google.', + ) + return new Response('OK', { status: 200 }) + } + if (resourceState === 'sync') { + return new Response('OK', { status: 200 }) + } + + await runCampaignCalendarSync(payload, { reason: 'webhook' }) + return new Response('OK', { status: 200 }) +} diff --git a/src/collections/Activity.ts b/src/collections/Activity.ts index 8812bfd2..6af8345f 100644 --- a/src/collections/Activity.ts +++ b/src/collections/Activity.ts @@ -72,12 +72,20 @@ const setCanonicalActivitySlug: CollectionBeforeValidateHook = ({ }) => { if (isActivityMutationShortcut(context)) return data if (!data) return data + const isGoogleCalendarWrite = context?.mutationKind === 'googleCalendarSync' const title = trimmedText(data.title ?? originalDoc?.title) const slug = slugify(title) if (!slug) { throw new APIError('Informe um título com letras ou números.', 400) } - if (operation === 'update' && data.title !== undefined && title !== originalDoc?.title) { + // C115 — the Google direction edits titles by product decision (D9); the + // canonical slug stays frozen so public URLs never break. + if ( + operation === 'update' && + !isGoogleCalendarWrite && + data.title !== undefined && + title !== originalDoc?.title + ) { throw new APIError('O título da atividade não pode ser alterado após a criação.', 409) } data.title = title diff --git a/src/collections/GoogleCalendarSync.ts b/src/collections/GoogleCalendarSync.ts index b3ca252e..a7da2bee 100644 --- a/src/collections/GoogleCalendarSync.ts +++ b/src/collections/GoogleCalendarSync.ts @@ -107,5 +107,65 @@ export const GoogleCalendarSync: CollectionConfig = { update: canSetGoogleCalendarSyncSystemField, }, }, + { + name: 'pushChannelId', + type: 'text', + label: 'ID do canal de notificação (Google)', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, + { + name: 'pushChannelResourceId', + type: 'text', + label: 'Resource ID do canal (Google)', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, + { + name: 'pushChannelExpiresAt', + type: 'date', + label: 'Canal de notificação expira em', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, + { + name: 'pushChannelSecret', + type: 'text', + label: 'Segredo do webhook (URL)', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, + { + name: 'pushChannelError', + type: 'textarea', + label: 'Erro do canal de notificação', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, + { + name: 'lastSeenEventIds', + type: 'json', + label: 'Eventos vistos na última sincronização', + admin: { readOnly: true }, + access: { + create: canSetGoogleCalendarSyncSystemField, + update: canSetGoogleCalendarSyncSystemField, + }, + }, ], } diff --git a/src/components/campaign/activity/ActivityUpdateFeed.tsx b/src/components/campaign/activity/ActivityUpdateFeed.tsx index 9416b8ad..f2b631e0 100644 --- a/src/components/campaign/activity/ActivityUpdateFeed.tsx +++ b/src/components/campaign/activity/ActivityUpdateFeed.tsx @@ -3,23 +3,31 @@ import { MessageSquareTextIcon } from 'lucide-react' import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card' import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@/components/ui/Empty' import { formatBahiaDateTimeLabel } from '@/lib/campaignTime' +import { GOOGLE_REVERSE_EDIT_BODY_PREFIX } from '@/lib/googleCalendarReverseEdit' import type { ActivityUpdateViewModel } from '@/utilities/activityViewModels' -const UpdateCard = ({ update }: { update: ActivityUpdateViewModel }) => ( -
- - - {update.authorName ?? 'Autor removido'} -

- {update.createdAt ? formatBahiaDateTimeLabel(update.createdAt) : ''} -

- - -

{update.body}

- - -
-) +const UpdateCard = ({ update }: { update: ActivityUpdateViewModel }) => { + // C115 — reverse-direction records carry no campaign author; the body + // prefix attributes the entry to Google Calendar. + const googleRecord = update.body.startsWith(GOOGLE_REVERSE_EDIT_BODY_PREFIX) + return ( +
+ + + + {update.authorName ?? (googleRecord ? 'Google Calendar' : 'Autor removido')} + +

+ {update.createdAt ? formatBahiaDateTimeLabel(update.createdAt) : ''} +

+ + +

{update.body}

+ + +
+ ) +} export const ActivityUpdateFeed = ({ updates }: { updates: ActivityUpdateViewModel[] }) => { if (!updates.length) { diff --git a/src/components/campaign/activity/GoogleCalendarSyncDialog.tsx b/src/components/campaign/activity/GoogleCalendarSyncDialog.tsx index fb5ad864..6bc55479 100644 --- a/src/components/campaign/activity/GoogleCalendarSyncDialog.tsx +++ b/src/components/campaign/activity/GoogleCalendarSyncDialog.tsx @@ -152,6 +152,30 @@ export const GoogleCalendarSyncDialog = ({ ) + const reverseEditBlock = ( +
+

Edições pelo Google

+

+ Quem tem permissão de edição no calendário pode remarcar, renomear ou cancelar o compromisso + direto no Google — a mudança volta para a atividade do Teqo automaticamente e fica + registrada nas atualizações. Título e horário seguem editáveis por lá; os demais campos só + mudam pelo Teqo. +

+ {state.pushChannelExpiresAt ? ( +

+ Notificações ativas até {formatBahiaDateTimeLabel(state.pushChannelExpiresAt)} — renovadas + automaticamente. +

+ ) : null} + {state.pushChannelError ? ( +

+ Notificações de mudanças feitas no Google indisponíveis: {state.pushChannelError}. O Teqo + continua detectando as mudanças ao sincronizar. +

+ ) : null} +
+ ) + const syncButton = (