Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16a.md
T
2026-07-08 16:15:37 +02:00

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 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

  • 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.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:

  • Connection pro User + Leak-Schutz (DoD 3) — calendar.prisma per-User, availability.ts exponiert 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 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.