Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16a.md
T

184 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.