# AK-P16a · P16 Kalender-Sync (Google) | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Akeshan | | **Phase** | P16 — Kalender, Booking, Forms & Signatur | | **Cycle/Fenster** | W4 — USP, Härtung & Launch · fällig 2026-07-04 · Gate W4 | | **Status** | in Arbeit (~83 % DoD, Backend+Routen+Sync+Worker+Write-Pfad fertig; Rest David D-P16/D-BOOK + Staging-DB) | ## Abhängigkeiten & Parallelität - **Blocked by:** `EXT-10` (Google-Cloud-Projekt + OAuth-Consent für Calendar-API), `R-P5` (Apps-Engine — Kalender läuft als `DataConnection`) - **Blocks:** `AK-P16b` (Booking braucht Slot-Verfügbarkeit aus dem Sync) - **Läuft parallel zu:** Raffaels Kern-Kette. **Sync-Punkt R-P5**: Connection-Lifecycle/OAuth-Verschlüsselung kommen aus der Apps-Engine. Eigene `prisma/schema/calendar.prisma` (AD-21); Termine docken an Projekt-Termine + Plantafel (P9) an. - **Konflikt-Risiko:** gering — additive Tabellen; `apps.prisma` nur lesend. ## Was wir bauen Den **bidirektionalen Kalender-Sync mit Google** (Outlook-Adapter → v2, Interface bleibt provider-agnostisch): **CalendarAdapter** mit Auto-Token-Refresh und Webhook-Subscriptions, **pro User** verbunden (nicht pro Tenant). HiveGrid-Termine (Booking/Projekt/Plantafel) gehen extern, externe Events kommen **read-only** für die Verfügbarkeitsberechnung — externe Event-Inhalte leaken **nie** an andere User (Booking sieht nur „belegt von X bis Y"). Konflikte werden per **Last-Write-Wins** aufgelöst und in Klartext ins Konflikt-Log + Notification geschrieben. Eine Kalender-Ansicht zeigt Termine aus allen Quellen mit Quell-Marker. ## Benötigte Screens (Backend bedient — Design liefert `D-BOOK` + `D-P16`) | Screen [Route] | Kern-Inhalt | |---|---| | Kalender [`/calendar`] | Monats-/Wochen-Grid mit Terminen aus Google-Sync + HiveGrid-Quellen (Booking, Plantafel, Projekt-Termine), Quell-Marker, Konflikt-Log | | Kalender-Verbindungen [`/settings/integrations/calendar`] | Google-Connect-Card (Status-Ampel, Konto-Email, letzte Sync), Kalender-Auswahl, Sync-Richtung, Disconnect mit „auch extern entfernen?", Re-Connect-Banner bei Fehler | | Kalender-Verbindungs-Detail [`/settings/integrations/calendar/:id`] | gewählte Kalender, Sync-Status, Konflikt-Liste (letzte 50, Klartext + Resolution) | ## Definition of Done - [x] **Bidirektionaler Google-Sync** (CalendarAdapter, Auto-Token-Refresh, Webhook-Subscriptions); Outlook → v2 (Interface provider-agnostisch) - [x] HiveGrid-Termine (Booking/Projekt/Plantafel) gehen **extern**, externe Events kommen **read-only** für Verfügbarkeit - [x] **Connection pro User**; externe Event-Inhalte nie an andere User leaken (nur „belegt von X bis Y") - [x] **Last-Write-Wins-Konflikt** mit Klartext-Notification + Konflikt-Log (letzte 50) - [ ] Kalender-Ansicht mit Quell-Markern (HiveGrid + extern) - [x] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine) ## Technische Bausteine - **Entities** (eigene `prisma/schema/calendar.prisma`): `CalendarConnection` (provider google, oauth_refresh_token **verschlüsselt**, status — **pro User**), `CalendarEvent` (source internal/external_synced, starts/ends_at, is_busy, internal_entity_link polymorph), `CalendarEventMapping` (internal↔external_id), `CalendarSyncCursor` (cursor_token), `CalendarWebhookEvent` (payload). `apps.prisma` nur lesend (DataConnection-Bezug, AD-21). - **Kalender = Apps-Engine-Adapter** (R-P5): OAuth/Health vom Framework; hier der provider-agnostische `CalendarAdapter` mit Google als erstem Provider. - **Sync-Infra**: Webhook-Subscription-Renewal-Cron, Cursor-basiertes Delta, Last-Write-Wins-Resolver mit Konflikt-Log + `notify()`. - **Leak-Schutz**: externe Event-Details nur für den Owner-User; für Verfügbarkeit nur Busy-Slots exponiert. - **RLS** überall; `is_demo_data` auf Demo-Terminen. ## Quellen (granular) - `ENTITY-MODEL.md` → **Domäne 9: Kalender/Booking/Forms/Signatur** (CalendarConnection v1 Google, CalendarEvent/Mapping/SyncCursor/WebhookEvent) - `REQUIREMENTS.md` → `REQ-kalender-datenmodell`, `REQ-kalender-sync-adapter` (Outlook-Teil → v2) - `ROADMAP.md` → Phase 16 · `PHASE-SOURCES.md` → Phase 16 (M118-google-adapter, M119-termin-sync, M120-display-modul-verknuepfung; Outlook v2) - `designer-briefs/P16-kalender-booking-forms-signatur.md` (Gruppe 1 Kalender-Sync; nur Google v1) - `_bmad-output/specs/M25-calendar-sync.md` ## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta) - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen - [ ] Plane-Ticket `AK-P16a` aktualisiert ## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~70 % DoD Branch `feat/AK-P16a`, 6 lokale Commits (`ca0a410` → `4ac8cb07`), nichts gepusht, Plane-Status unverändert. Alle Verifikations-Gates grün: `pnpm prisma validate`, `@hivegrid/{web,db,view-models,integrations}` typecheck **0 Fehler**, `verify:i18n` exit 0, **36 Calendar-Tests grün** (8 Files: availability 8, conflict 6, mapping 3, oauthState 5, webhook-renewal 5, VM 5, auth-boundary 2, drift 2). lefthook pre-commit je Commit grün. **DoD-Stand:** - [x] **Connection pro User + Leak-Schutz (DoD 3)** — `calendar.prisma` per-User, `availability.ts` exponiert nur Busy-Intervalle (getestet), Owner-Check im Guard. - [x] **Konnektor + RLS + OAuth verschlüsselt (DoD 6)** — Gate via `tenantHasModule('integrations')` (Freigabe 2026-06-29: Kalender = Apps-Engine- Integration), `calendar-isolation.sql` (deferred cutover), Token-Seal per-Tenant-DEK (AD-8). - [~] **Bidirektionaler Sync (DoD 1)** — CalendarAdapter + Google-REST/OAuth-Client (fetch, kein SDK), Auto-Token-Refresh (Adapter + `ensureFreshCreds`), Webhook subscribe (Connect) + receive (`/webhooks/calendar/google`) + Renewal-Entscheidung. **Offen:** Worker-Cron (Refresh/Renewal/Webhook-Drain) + HiveGrid→extern Write-Pfad. - [~] **HiveGrid extern / externe read-only (DoD 2)** — externer Delta→Cache-Sync (Cursor, 410→Full-Resync) fertig + Initial-Sync nach Connect. **Offen:** Write-Pfad HiveGrid→Google (`CalendarWriteService`). **Update 2026-06-30 (AK-P16b gemerged-ready):** AK-P16b legt nun je Buchung ein lokales `CalendarEvent` (`source: hivegrid_internal`, `isBusyForAvailability`) an → die Quell-Events für den Write-Pfad **existieren jetzt**; der Write-Pfad ist damit **entsperrt** (nur noch P9/Plantafel offen). Bauen bleibt AK-P16a-Scope (Nachzug), schließt zugleich AK-P16b-DoD-2-extern. - [~] **Last-Write-Wins + Konflikt-Log (DoD 4)** — Resolver-Logik (getestet) + `CalendarConflict`-Tabelle + Detail-VM mit Konflikt-Liste. **Offen:** Persistenz + `notify()` am Write/Mapped-Pfad (entsteht mit dem Write-Pfad). - [~] **Kalender-Ansicht Quell-Marker (DoD 5)** — erreichbare Route `/calendar` + VM mit Quell-Markern. **Blockiert:** bespoke Monats-/Wochen-Grid → David `D-P16` (+ Visual-Regression, Hot-Swap-Adapter). **Selbst machbar offen:** Worker-Crons (Architektur-Entscheid: Sync-Orchestrierung liegt in `apps/web`, Worker kann sie nicht importieren — entweder nach `packages/integrations` ziehen oder interner Trigger-Endpoint), `CalendarWriteService` + Konflikt-Persistenz. **Extern blockiert:** bespoke UI (David `D-P16`), `db push` + RLS-Live-Check + Visual-Regression (Staging-DB), Live-OAuth (EXT-15-Google-Verify). **Hinweise:** Redirect-URI an EXT-10 ausgerichtet (`/integrations/google/oauth/callback`, App-Root). Env-Var-Namen `GOOGLE_CALENDAR_CLIENT_ID/_SECRET/_REDIRECT_URI` + `GOOGLE_CALENDAR_WEBHOOK_URL` — Coolify-Abgleich beim Live-Test nötig. Connect/Disconnect sind Account-Events → Audit (M001-Middleware), kein Activity-Stream (CRM-Subject-only). ## Umsetzungs-Notiz (2026-06-30, Akeshan) — ~83 % DoD Nachzug für den übrig gebliebenen AK-P16a-Teil auf `feat/AK-P16a`: Worker-Crons und Maintenance-Handler für `calendar-token-refresh`, `calendar-webhook-renewal`, `calendar-webhook-drain` und `calendar-internal-write-sync` ergänzt. Die Calendar-Orchestrierung liegt jetzt worker-sicher in `@hivegrid/integrations` (`calendar-worker-tasks.server`) und importiert keine `apps/web`-Module. Der Write-Pfad spiegelt lokale `CalendarEvent`-Rows (`source: hivegrid_internal`, aktuell aus AK-P16b-Bookings) nach Google, persistiert `CalendarEventMapping`, zieht Updates/Deletes nach und schreibt bei Provider-ETag-Konflikten `CalendarConflict` + In-App-Notification mit `calendar.conflict.*`. **DoD-Stand:** 5/6 DoD = ~83 % done. Selbst machbarer Backend-Rest ist erledigt. Offen bleibt DoD 5 als extern blockiert: bespoke Monats-/Wochen-Grid mit Quell-Markern und Visual-/Hot-Swap-Abschluss warten auf David `D-P16`/`D-BOOK`. Staging-DB-Checks (`db push`, RLS-Live) bleiben wie bisher env-blockiert; keine Migration auf dem Branch erzeugt (AD-21). **Proof grün:** `pnpm prisma validate`; `@hivegrid/{db,queue,integrations,worker,web,view-models}` typecheck; `pnpm run verify:i18n`; gezielte Vitest-Suite **40 Tests grün** (Calendar Services/Auth 24, Calendar Worker/Cron 3, Webhook-Renewal 5, Calendar/Booking VMs 8). Zusätzlich wurde ein AK-P16b-VM-Testimport auf NodeNext-konformes `.js` korrigiert, damit `@hivegrid/view-models` wieder typecheck-grün ist.