# Impl: Sync por filtro + link de import (Google Calendar)

Status: aprovado
Atualizado em: 2026-08-08
Issue: #392
Intenção: docs/plans/sync-teqo-google-calendar.md
Appetite restante: ~1,5–2 dias eng (herdado)

## Leitura da intenção

- **Outcome:** Com um filtro ativo na agenda, o usuário obtém um link de import e o Google Calendar passa a refletir esse recorte. Teqo permanece SoT.
- **O que NÃO negociar:** Leader lockdown (sem acesso); fail-closed no access do feed (não vaza municípios fora do escopo do criador); link com credencial revogável; sem sync bidirecional; sem PII desnecessária no feed.
- **O que reavaliar:** A hipótese de "token/HMAC" da intenção — para revogação real, collection é mais simples que stateless+blocklist.

## Abordagem recomendada

```mermaid
flowchart LR
  F[filtros na agenda] --> G[server action: createCalendarFeed]
  G --> DB[(calendarFeed collection)]
  DB --> R[GET /campanha/agenda/ical/secret]
  R --> ICS[ical response]
  ICS --> GC[Google Calendar assina URL]
```

**Opções consideradas:**

- **A) Token HMAC stateless** (como supporterImportToken): codifica filtro+actorID no token. Problema: sem revogação real sem blocklist (= collection disfarçada).
- **B) Collection `calendarFeed`** com secret slug: feed URL usa o slug como credencial. Revogação = delete/soft-revoke do documento. Listing natural ("meus feeds").
- **C) Híbrido HMAC + collection:** over-engineered para o escopo.

**Recomendação: B** — collection `calendarFeed`. Revogação nativa, listing, access scoping no create e no read. O secret slug é a credencial (como um invite token, mas para leitura de feed).

**Rejeitadas:** A porque revogação exige estado de qualquer forma; C porque adiciona complexidade sem ganho.

### Decisões de engenharia

#### 1. Collection `calendarFeed` vs stateless

**Opções:** A) stateless HMAC | B) collection Payload
**Recomendação: B** — porque revogação é requisito de produto ("credencial revogável"), e uma collection dá listing, auditoria (`createdBy`), e access scoping nativo via Payload hooks.
**Rejeitadas: A** porque sem revogação real; blocklist seria uma collection disfarçada.

#### 2. Formato iCal: hand-roll vs library

**Opções:** A) `ical-generator` (npm) | B) hand-roll RFC 5545
**Recomendação: B** — o formato VCALENDAR/VEVENT é texto simples; os campos da Activity mapeiam diretamente (title→SUMMARY, startAt→DTSTART, etc.). Zero dependências novas, zero risk de supply-chain. Escaping de texto iCal é trivial (newline→`\n`, comma→`\,`, semicolon→`\;`).
**Rejeitadas: A** porque adiciona dependência para ~80 linhas de código.

#### 3. Feed endpoint: dentro ou fora de `(app)`

**Opções:** A) dentro de `(app)` (exige cookie campaign-token) | B) fora de `(app)`, sem auth cookie
**Recomendação: B** — Google Calendar não envia cookies. O secret slug É a credencial. O endpoint fica em `src/app/(campaign)/campanha/agenda/ical/[secret]/route.ts` (fora do `(app)` group, assim como os routes WebAuthn).
**Rejeitadas: A** porque Google Calendar "From URL" é um GET anônimo.

#### 4. Access scoping no feed read

**Opções:** A) snapshot no create (feed congela o escopo) | B) re-avaliar escopo do criador a cada read
**Recomendação: B** — se o advisor perde acesso a um município, o feed para de incluir atividades daquele município. Fail-closed: se o criador for desativado/deletado, o feed para de servir.
**Rejeitadas: A** porque violaria o invariante "não vaza municípios fora do ator".

#### 5. Atividades canceladas no feed

**Opções:** A) excluídas | B) incluídas com STATUS:CANCELLED
**Recomendação: A** — alinhado com a recomendação da intenção ("some do calendário importado").
**Rejeitadas: B** porque polui o calendário do consumidor sem valor.

#### 6. Janela temporal do feed

**Opções:** A) todas as atividades (passado + futuro) | B) janela deslizante (ex: 6 meses passado + 12 meses futuro)
**Recomendação: B** — janela de 90 dias passados + 365 dias futuros. Feed muito grande degrada a sync do Google Calendar. A janela é generosa para o uso real.
**Rejeitadas: A** porque histórico completo cresce indefinidamente.

### Componentes / mudanças

- **`calendarFeed` collection** (`src/collections/CalendarFeed.ts`): secretSlug (unique, indexed, auto-generated), label, filterMunicipality (optional rel→municipality), filterDeputyPresent (checkbox), filterTag (optional text), createdBy (rel→campaignUser), revokedAt (optional date). Admin group `Campanha`. Access: staff create/read own; coordinator/candidate read all; leader none.
- **Migration:** `add_calendar_feed` — cria a tabela `calendar_feeds`.
- **`src/utilities/calendarFeed.ts`**: `buildCalendarFeedWhere(state, rangeStart, rangeEnd)` (reusa `buildActivityAgendaWhere` com janela fixa), `generateICalFeed(events, feedLabel)` (hand-roll RFC 5545), `resolveFeedSecret(secret)` (lookup + access check).
- **`src/app/(campaign)/campanha/actions/calendarFeed.ts`**: server action `createCalendarFeedLink(state)` — valida filtro, gera secretSlug (randomUUID), salva no DB, retorna URL completa.
- **`src/app/(campaign)/campanha/agenda/ical/[secret]/route.ts`**: GET route (fora `(app)`). Lookup feed → access check do criador → query activities → generate iCal → response `text/calendar; charset=utf-8`.
- **UI: `CalendarFeedButton`** (`src/components/campaign/activity/CalendarFeedButton.tsx`): botão na barra de filtros da agenda. Habilitado quando há filtros ativos. Ao clicar: chama server action → dialog com URL + copy-to-clipboard + instruções Google Calendar.
- **UI: `CalendarFeedList`** (`src/components/campaign/activity/CalendarFeedList.tsx`): seção na página da agenda (ou modal) listando feeds ativos do usuário com opção de revogar.

### Access / Consent

- **Sem Consent** — feed não captura PII novo; é leitura de dados existentes com access já controlado.
- **Access no create:** `isCampaignStaff` (coordinator, advisor, candidate). Advisor só pode criar feed com filtros dentro do próprio escopo de municípios.
- **Access no read (feed endpoint):** re-carrega o criador, re-avalia escopo de municípios, aplica restrição ao where. Se criador inativo/deletado → 404.
- **Leader lockdown:** sem acesso a create/read/list.

## Fases verificáveis

1. **Schema + server** (~50% do appetite)
   - Collection `calendarFeed` + migration
   - Utility `generateICalFeed` + `resolveFeedSecret`
   - GET route `/campanha/agenda/ical/[secret]`
   - Server action `createCalendarFeedLink`
   - Unit tests: iCal generation, access scoping, feed resolution
   - Gate: `pnpm gate:fast`

2. **UI** (~30% do appetite)
   - `CalendarFeedButton` na barra de filtros da agenda
   - Dialog com URL + copy + instruções
   - `CalendarFeedList` (meus feeds + revogar)
   - Server action `revokeCalendarFeed`

3. **Gates** (~20% do appetite)
   - `pnpm gate:fast` (tsc + lint + format + test)
   - `pnpm build` (com DB local)
   - `pnpm test` (unit + int)

## Rabbit holes / Não escopo (engenharia)

- **Webhook/push para Google:** fora. O Google puxa (poll) o feed periodicamente.
- **OAuth push:** fora. Link de import cobre o job.
- **Feed público sem segredo:** fora. Fail-closed.
- **Múltiplos formatos (CalDAV, etc.):** fora. Só iCal (RFC 5545).
- **Rate limiting no feed endpoint:** fora de v1. O slug é imprevisível (UUID) e o endpoint é read-only.
- **Cache HTTP no feed:** fora de v1. Google Calendar respeita `Cache-Control` mas a sync já é periódica (~12-24h). Podemos adicionar `max-age` depois.

## Riscos e mitigação

- **Secret slug vazado = leitura do recorte.** Mitigação: UUID (imprevisível), revogação disponível, access re-avaliado a cada read.
- **Feed endpoint sem auth cookie = surface nova.** Mitigação: slug é a credencial; fail-closed se slug inválido/revogado/criador inativo; sem PII sensível no output (só título + município + datas).
- **iCal mal-formado rejeitado pelo Google.** Mitigação: seguir RFC 5545 estritamente; testar com validador iCal; unit tests cobrindo escaping e edge cases.

## Aceite de engenharia

- [ ] Aceite de produto da intenção ainda coberto
- [ ] Invariantes AGENTS/engineering-standards
- [ ] Testes de domínio previstos (unit/int) onde access/write paths mudam
- [ ] Leader lockdown preservado
- [ ] Feed fail-closed (slug inválido → 404; criador inativo → 404)