9.0 KiB
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 alsDataConnection) - 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.prismanur 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
- Bidirektionaler Google-Sync (CalendarAdapter, Auto-Token-Refresh, Webhook-Subscriptions); Outlook → v2 (Interface provider-agnostisch)
- HiveGrid-Termine (Booking/Projekt/Plantafel) gehen extern, externe Events kommen read-only für Verfügbarkeit
- Connection pro User; externe Event-Inhalte nie an andere User leaken (nur „belegt von X bis Y")
- Last-Write-Wins-Konflikt mit Klartext-Notification + Konflikt-Log (letzte 50)
- Kalender-Ansicht mit Quell-Markern (HiveGrid + extern)
- 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.prismanur lesend (DataConnection-Bezug, AD-21). - Kalender = Apps-Engine-Adapter (R-P5): OAuth/Health vom Framework; hier der provider-agnostische
CalendarAdaptermit 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_dataauf 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-P16aaktualisiert
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:
- Connection pro User + Leak-Schutz (DoD 3) —
calendar.prismaper-User,availability.tsexponiert nur Busy-Intervalle (getestet), Owner-Check im Guard. - 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 lokalesCalendarEvent(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 → DavidD-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.