184 lines
14 KiB
Markdown
184 lines
14 KiB
Markdown
# 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** | Done (2026-07-11, PR #75; Interim-UI AD-28; finale Optik = design-nachzug) · Audit 2026-07-17: Reachability-Lücke B.6 gefixt, RLS seit Cutover 14.07. live → 7/7 DoD; offen nur Live-OAuth-Smoke (EXT-15) |
|
||
|
||
**🎨 design-nachzug: offen** (seit 2026-07-11) — Interim-UI aus `~/ui` steht; finale Subframe-Optik aus `D-P16`/`D-BOOK` ausstehend.
|
||
|
||
## 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)
|
||
- [x] Kalender-Ansicht mit Quell-Markern (HiveGrid + extern) — *Interim-Monats-/Wochen-Grid aus `~/ui` (AD-28); finale Subframe-Optik = design-nachzug*
|
||
- [x] Konnektor `tenantHasModule('calendar')`; RLS auf allen Tenant-Tabellen; OAuth verschlüsselt (AD-8, via Apps-Engine) · *RLS ist seit `20260713190000_appwide_rls_cutover` (14.07.) LIVE — der frühere „deferred cutover"-Vermerk ist damit erledigt*
|
||
- [x] **Reachability Verbindungsseite (fehlender DoD-Punkt, Audit 2026-07-17):** `/settings/integrations/calendar` ist aus dem Integrations-Katalog erreichbar — die „Kalender"-Karte und die generische `google-calendar`-Detailseite leiten auf die Kalender-Verbindungen um (Aircall-Muster; vorher nur per Direkt-URL/OAuth-Redirect erreichbar, DoD B.6)
|
||
|
||
## 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 · Milestones: (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)
|
||
|
||
## Dev-Nachzug (nach Davids `D-BOOK`/`D-P16`-Delta)
|
||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
||
- [ ] Plane-Ticket `AK-P16a` aktualisiert
|
||
|
||
**Interim-UI (Vorschau, Stand 2026-07-11):** Screens aus `~/ui` gebaut —
|
||
`apps/web/app/components/screens/calendar/CalendarViewPage.tsx` (Monats-/Wochen-Grid mit
|
||
Quell-Marker-Legende, GET-Navigation `?view=&anchor=`),
|
||
`CalendarConnectionsPage.tsx` (A6: Connect-CTA, Not-Configured-/Re-Connect-Banner, Status-Tabelle),
|
||
`CalendarConnectionDetailPage.tsx` (A6+A2: Kalender-Liste, Konfliktprotokoll-Tabelle, Disconnect
|
||
als XS-420-Dialog). Routen unverändert (Loader/Action), injizieren nur VM+csrf. Proof:
|
||
`subframe-layout-boundary.test.ts` (Guard, alle 3 Screens registriert), Calendar-Modultests 24 grün,
|
||
`tests/e2e/calendar.spec.ts`-Marker (`ui.calendar.list`) erhalten. Visual-Baseline/Hot-Swap: für
|
||
diese Bereiche existiert (wie bei den Automations-/Forms-Nachzügen) noch keine Infra — beim
|
||
D-P16-Nachzug mit Re-Baseline aufsetzen. Refactor-Nachzug offen: finale Subframe-Optik aus
|
||
`D-P16`/`D-BOOK` (Plane-Label `design-nachzug`).
|
||
|
||
## 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.
|
||
|
||
## Umsetzungs-Notiz (2026-07-11, Akeshan) — Interim-UI (AD-28), 6/6 DoD selbst machbar
|
||
|
||
Branch `akeshan/ak-p16ab-interim-ui` (von `origin/main`), gemeinsamer Interim-UI-PR
|
||
mit AK-P16b. Neu: `CalendarViewPage` (bespoke Monats-/Wochen-Grid aus `~/ui`,
|
||
Quell-Marker-Legende + farbige Event-Chips, Heute/Prev/Next/Toggle als
|
||
GET-Navigation, Loader lädt das Event-Fenster passend zum Grid, Tage werden
|
||
Berlin-lokal gebucketed — pure `calendar-grid.ts` in `@hivegrid/view-models`
|
||
mit 7 Unit-Tests), `CalendarConnectionsPage` und `CalendarConnectionDetailPage`
|
||
ersetzen die Baseline-Routen-JSX; Disconnect läuft als echter Dialog.
|
||
|
||
**DoD-Stand: 6/6 = 100 % selbst machbar** — DoD 5 (Kalender-Ansicht Quell-Marker)
|
||
per Interim-UI erfüllt; finale Subframe-Optik = getrackter design-nachzug
|
||
(Tag oben). Weiter env-blockiert (unverändert): Staging-`db push`, RLS-Live-Check,
|
||
Live-OAuth (EXT-15); Visual-Baseline/Hot-Swap-Infra für Calendar fehlt repo-weit
|
||
und wird beim D-P16-Nachzug mit aufgesetzt.
|
||
|
||
**Proof:** `@hivegrid/{view-models,web}` typecheck 0 Fehler; `verify:i18n` +
|
||
`verify:sidebar-routes` Exit 0; Vitest gezielt grün: view-models 26,
|
||
Calendar-Modul 24, `subframe-layout-boundary.test.ts` (3 neue Calendar-Screens
|
||
registriert); e2e-Marker `ui.calendar.list` unverändert.
|
||
|
||
**Nachtrag Demo-Seed (2026-07-11):** Für das Interim-Kalender-Grid liefert der Demo-Seed
|
||
jetzt 6 Kalender-Events mit Quell-Vielfalt (3 interne Booking-Spiegelungen, externer
|
||
Material-/Privat-Termin, zweitägige ganztägige Messe) — Details/Proof im
|
||
AK-P16b-Seed-Nachtrag; `docs/ops/local-demo-seed.md` aktualisiert.
|
||
|
||
## Umsetzungs-Notiz (2026-07-17, Akeshan) — Stand-Audit + Restarbeiten
|
||
|
||
Audit-Befund (Code auf `main` pro DoD-Punkt geprüft): DoD 1–6 real erfüllt, aber
|
||
eine **Reachability-Lücke** (DoD B.6, oben als nachgetragener DoD-Punkt): die
|
||
„Kalender"-Katalog-Karte führte auf die generische `DataConnection`-Detailseite
|
||
(zeigt für Kalender immer 0 Verbindungen, Connect-Wizard hätte den OAuth-Flow
|
||
umgangen); `/settings/integrations/calendar` war nur per Direkt-URL erreichbar.
|
||
**Fix** (Branch `fix/ak-p16-audit-restwork`): Katalog-Karte + Loader/Action der
|
||
generischen Detailseite leiten nach Aircall-Muster auf `calendarConnectionsPath`
|
||
um; Routing-Kontrakt-Test `integrations.calendar-routing.test.ts` (6 Tests grün).
|
||
|
||
**Drift korrigiert:** Die RLS ist seit dem appwide Cutover
|
||
(`20260713190000_appwide_rls_cutover`, ENABLE+FORCE auf allen 6 Calendar-Tabellen)
|
||
live — die als „env-blockiert offen" geführten Staging-RLS-Vermerke sind damit
|
||
gegenstandslos; `calendar.prisma`-Header-Kommentar entsprechend nachgezogen.
|
||
Offen extern bleibt nur der Live-OAuth-Smoke (EXT-15, Google-App-Verifizierung).
|
||
|
||
Kleinbefund (kein DoD-Bruch, notiert): der Worker-Write-Pfad mappt Provider-412
|
||
hart auf `external_won` statt den pure `resolveConflict`-Resolver zu nutzen —
|
||
funktional Last-Write-Wins-konform; Umbau nur als Vorschlag außerhalb Scope.
|