Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,116 @@
# Boilerplate-Abgleich — Modul M25 (Calendar-Sync)
**Modul-ID:** M25 (Block 5 / Pflichtenheft 25.x)
**Name:** Calendar-Sync (Google + Microsoft, bidirektional)
**Milestones:** M118 (Google+MS via Apps-Engine), M119 (Termin-Sync + Konflikt), M120 (Display + Modul-Verknüpfung + Activity-Stream)
**Block:** block5.md §§ 25.1–25.7 (+ Phase-2 25.8)
**Reuse-Level:** **low**
> Begründung Reuse-Level: Es gibt in der Boilerplate **keinen** Calendar-, OAuth2-Connect-, Google-Calendar- oder Microsoft-Graph-Code und **kein** zugehöriges Datenmodell. Die fünf fachlichen Kern-Entitäten (`CalendarConnection`, `CalendarEvent`, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent`), das `CalendarAdapter`-Interface, der bidirektionale Sync, das Webhook-Push-Subsystem und die Verfügbarkeits-Berechnung müssen komplett neu gebaut werden. Was vorhanden ist, ist **Querschnitt-Fundament** (Token-Verschlüsselung, SSRF-Schutz, Outbox/Queue/Cron, Notifications, Audit, Adapter-Registry, Webhook-HMAC-Verify, EU-Provider-Pattern) — solide, aber nur Bausteine, kein fertiges Modul. Damit klar über „none", aber nicht „medium".
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
|---|---|---|
| `packages/foundation/src/adapters.ts` | `defineAdapter()` / `getAdapter()` + `AdapterStatus` (`not_configured`/`configured`/`healthy`/`degraded`/`unavailable`) | als-vorlage — Registry-Muster für das `CalendarAdapter`-Interface (Block G). Das vorhandene `AdapterDefinition` ist generisch (`key`/`status`/`adapter`); die calendar-spezifische Methoden-Signatur (`initiateOAuth`/`fetchEventsDelta`/`createEvent`…) ist neu zu definieren. Status-Enum 1:1 nutzbar für Connection-Health. |
| `apps/web/app/utils/api/.server/CryptoApi.ts` | AES-256-GCM `encrypt`/`decrypt` (versionierter Payload `version:iv:tag:ciphertext`), Key via Hash | anpassen — direktes Vorbild für `oauth_refresh_token`/`oauth_access_token` at-rest (Block C, Token-Storage). Spec verlangt envelope-encryption mit tenant-spezifischem KMS-Schlüssel — CryptoApi ist single-key; für Tenant-Key/KMS erweitern. |
| `apps/web/app/utils/leads/marketingIntegrations.db.server.ts` | `encryptSensitive`/`decryptSensitive` über `SENSITIVE_KEYS` + `CRYPTO_TAG`-Präfix; „Admin-UI zeigt entschlüsselte Secrets nie erneut" | als-vorlage — exakt das Pattern für selektiv verschlüsselte Token-Felder in `CalendarConnection` + Never-Redisplay-Regel (Block C: „Logging niemals Token-Klartext"). |
| `packages/foundation/src/outbound-http.ts` (Subpath `@toolctrl/foundation/outbound-http`) | `fetchOutboundHttpWithRedirects`, `validateOutboundHttpUrl`, SSRF-Block (private/internal IPv4+IPv6, DNS-Resolve, Redirect-Limit, Timeout, Response-Size-Limit) | 1:1 — für jeden ausgehenden Provider-Call (Google/MS Token-Endpoint, Calendar-API, Webhook-Subscribe). Pflicht-Querschnitt. |
| `packages/api-client-ts/src/webhooks.ts` + `apps/api/src/webhooks/mailersend-signature.ts` | HMAC-SHA256-Verify mit `timingSafeEqual`, Timestamp-Toleranz, Header-Parsing (`webhook-signature`), typisierte Failure-Codes | als-vorlage — Vorbild für `verifyWebhookSignature(headers, body)` (Block G/E). Provider-spezifisch anzupassen (Google `X-Goog-Channel-Token`, MS `clientState`) — nicht HMAC, aber Verify-Struktur (constant-time, fail-closed, Failure-Codes) übernehmbar. |
| `packages/db/src/outbox.ts` + `prisma/schema/outbox.prisma` (`OutboxEvent`) | `publishOutboxEvent(tx, args)` in `$transaction`, `dispatchKey @unique` (Idempotenz), `eventType`-Pattern `<domain>.<entity>.<verb>` | 1:1 — Webhook-Empfang → DB-Write → async Verarbeitung (Block E, Schritt 3-5). `CalendarWebhookEvent` kann eigenständig sein ODER über Outbox laufen; Outbox-Idempotenz (`dispatchKey`) deckt „Provider duplizieren Notifications" (Block E Idempotenz) ab. |
| `apps/worker/src/outbox/event-router.ts` (`DEFAULT_OUTBOX_ROUTING`) | Prefix→Queue-Routing (longest-prefix-wins) | anpassen — neuen Prefix `calendar.` (z.B. `calendar.sync.*`) ergänzen, auf eine Worker-Queue routen. |
| `packages/queue` (`enqueueJob`, `buildIdempotentJobId`, Prioritäten) + `apps/worker` (Handler-Registry, Cron-Scheduler `*-cron.ts`, Gruppen/Concurrency) | BullMQ-Wrapper + single-instance Cron-Scheduler-Muster (`dsgvo-grace-cron.ts`, `lead-stale-trigger.ts`, `ai-cost-*-cron.ts`) | als-vorlage — (a) Sync-Worker (Webhook-Delta-Pull), (b) **Webhook-Subscription-Renewal-Cron** (Block E: alle 6h, Subscriptions die in 24h ablaufen). Cron-Job-Skelett + Idempotenz direkt übernehmbar. |
| `packages/foundation/src/notifications.ts` (`notify`, `bundleNotifications`, `assertI18nKey`, `NotificationPreferenceChannel` IN_APP/EMAIL) + `prisma/schema/notifications.prisma` | Tenant-pflichtige Notifications mit Preference-Check, Upsert per `sourceKey`, Bündelung | 1:1 — Konflikt-Notifications (Block F), Verbindungsfehler-Mails (Block C Re-Connect), „externe Version gewinnt"-Hinweis. INTEGRATION-CONTRACTS §7 verlangt ohnehin `notify()` statt Direkt-Mail. |
| `packages/foundation/src/audit.ts` (`auditEvent`, `withAuditMiddleware`) + `prisma/schema/core.prisma` (`AuditEvent`, Hash-Chain) | Audit-Trail mit Tamper-Evidence | 1:1 — Connect/Disconnect/Konflikte (AV #6, Spec „Audit-Trail-Default"). Da OAuth-Connect/Webhook-Calls außerhalb Prisma laufen, **manuelles** `auditEvent` nötig (INTEGRATION-CONTRACTS §6 Ausnahme). |
| `packages/foundation/src/permissions.ts` (`withTenantScope`, `withPermission`, `withOwnerCheck`, `requirePermission`; 404-statt-403) | Tenant-Scope + Permission- + Owner-Gating | 1:1 — `calendar.connect_own` (Owner-Check `connection.user_id = self`) + `calendar.admin` (Block I). Permission-Denied → 404 deckt Bauprinzip A.5.3 / DoD ab. |
| `prisma/schema/permissions.prisma` (`Role`/`Permission`/`RolePermission`/`UserRole`) | RBAC-Fundament | als-vorlage — die zwei atomaren Permissions + Bundles (Block I) sind neu zu seeden; das Modell trägt sie. HiveGrid-seitig `packages/entitlements/src/permissions.ts` (INTEGRATION-CONTRACTS §10). |
| `packages/foundation/src/idempotency.ts` (`withIdempotency`) + `prisma/schema/core.prisma` (`IdempotencyKey`) | Replay-sichere Mutationen, In-Process-Lock, Fingerprint-Hash | anpassen — für Webhook-Verarbeitung + Create/Update-Push (Optimistic-Locking-Ergänzung, Block F). |
| `packages/feature-flags` (`evaluateFlag`, Targeting, React-Hooks) + `prisma/schema/featureFlags.prisma` | Feature-Flag-Engine | 1:1 — DoD verlangt „Modul ohne Deploy abschaltbar". Connect-Button + Routes hinter `calendar`-Flag. |
| `packages/i18n` (Namespaces/Locales, `formatDate`/`formatRelativeTime`, `assertI18nKey`) | i18n + locale-explizite Datums-Formatierung | 1:1 — alle Klartext-Hinweise (Block J), Termin-Zeiten in Detail-View. DoD: alle UI-Texte als i18n-Keys. |
| `packages/view-models/src/index.ts` (`VMState`, `ActionCallbacks`, `RegistryGate`, `SidebarRegistryItem`, `ready`/`empty`) | VM-State-Maschine + Shell-Registry-Typen | 1:1 — Loader baut VM, UI empfängt nur VM+Actions (DoD Code-Layer + INTEGRATION-CONTRACTS §11). Loading-/Empty-/Error-State (Klartext-DoD). |
| `packages/foundation/src/errors.ts` (`CatalogError`, `foundationErrors`, `toPinoLogObject`) | Strukturierte Klartext-Fehler (`code`/`status`/`i18nKey`) | als-vorlage — Adapter-Klartext-Codes (Block G: `auth_token_expired`, `rate_limit_exceeded`, `provider_outage` …). Catalog-Einträge sind HiveGrid-spezifisch neu zu registrieren. |
| `packages/logger` (`createLogger` mit Redaction von `token`/`secret`/`apiKey`/`authorization`) | Pino-Logger mit Secret-Redaction | 1:1 — Block C „Logging niemals Token-Klartext" wird durch die eingebauten Redact-Paths abgedeckt. |
| `prisma/schema/notifications.prisma` (`DeviceToken`) + `apps/worker/src/jobs/push-notification.ts` | Push-Token + Push-Versand | 1:1 — Termin-Erinnerungen / Konflikt-Push (Pflichtenheft 22.7.4). Über `notify()` (Kanal-Entscheidung im Notification-Service). |
| `prisma/schema/entityBuilder.prisma` (`EntityView.layout` kennt `"calendar"`) | EntityView-Calendar-Layout-Enum (No-Code-Builder) | als-vorlage (schwach) — nur ein Layout-String, **keine** fertige Calendar-View-Component. Für M120 (Tag/Woche/Monat-Display) liefert die BP keinen Renderer; Component ist neu (Subframe-Design + ui-hivegrid). |
| `apps/api` (Hono-App, `route-access-inventory.ts`, `webhook-signature`-Route-Klasse, `error-envelope`, `request-id`, `body-limit`) | Public-API-Runtime mit Auth-Klassen-Matrix inkl. `webhook-signature` | als-vorlage — die öffentlichen Webhook-Endpoints `/webhooks/calendar/{provider}` (Block E, keine User-Auth, Provider-Signature) passen in die bestehende `webhook-signature`-Route-Klasse + Middleware-Kette. |
| `prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) | Data-Sync-„Apps-Engine": App-Installation pro Tenant, **`DataConnection.config` = „Encrypted JSON credentials"**, Sync-Run mit `executionMode` manual/scheduled/webhook + Metriken (`itemsProcessed/Created/Updated/Failed`) + Rollback (`AppSyncItem.rolledBackData`) | als-vorlage — **wichtigstes Boilerplate-Modell für M118** (Milestone-Titel: „via Apps-Engine"). `DataConnection` kann die OAuth2-Verbindung tragen ODER als Muster für `CalendarConnection` dienen. `AppSyncRun`/`AppSyncRunLog` ist ein fertiges Sync-Lauf-/Log-Modell (Sync-Status, Konflikt-Logs Block F „letzte 50 Konflikte"). **Aber:** keine Provider-Logik, kein Cursor/Webhook-Modell, kein Event-Cache — nur Hülle. Entscheidung nötig: `appsEngine`-Modelle wiederverwenden vs. dedizierte `Calendar*`-Modelle in `app.prisma`. |
---
## Vorhandene Daten-Modelle (konkrete Prisma-Modelle mit Pfad)
Es gibt **kein** Calendar-spezifisches Prisma-Modell. Nutzbare/angrenzende Modelle:
- `prisma/schema/appsEngine.prisma` — `App`, `DataConnection` (verschlüsselte Credentials), `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`. **Am nächsten** an „Connection + Sync-Lauf + Konflikt-Log". Deckt aber `CalendarEvent`-Cache, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent` **nicht** ab.
- `prisma/schema/outbox.prisma` — `OutboxEvent` (`dispatchKey @unique`, Idempotenz, `priority`, `lockedUntil`). Für Webhook→Worker-Entkopplung + Dedup.
- `prisma/schema/notifications.prisma` — `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken`. Konflikt-/Fehler-Notifications + Push.
- `prisma/schema/core.prisma` — `AuditEvent` (Connect/Disconnect/Konflikt-Audit), `IdempotencyKey`, `Credential` (globaler Secret-Store, `value Json`).
- `prisma/schema/accounts.prisma` — `User`, `Tenant`, `TenantUser` (User-/Tenant-Anker; pro-User-Connection-Scoping). `WorkspaceAuthProvider` (inbound SSO/OIDC — **nicht** outbound OAuth-Connect, nur als Feld-Vorbild `authorizationUrl`/`tokenUrl`/`clientId`).
- `prisma/schema/permissions.prisma` — `Permission`/`Role`/`UserRole` für `calendar.connect_own` / `calendar.admin`.
- `prisma/schema/featureFlags.prisma` — `FeatureFlag` (Modul-Abschaltung).
- `prisma/schema/app.prisma` — **leerer Platzhalter** (`// custom database models`): vorgesehener Ort für die neuen `Calendar*`-Modelle.
**Neu zu erstellende Modelle (alle, gemäß Spec Block A):** `CalendarConnection`, `CalendarEvent`, `CalendarEventMapping`, `CalendarSyncCursor`, `CalendarWebhookEvent` — in `prisma/schema/app.prisma` (oder eigene `calendar.prisma`). Pflicht: tenant-scoped + RLS, FK auf `User`/`Tenant`, Eintrag in `packages/db/src/dsgvo/user-fk-map.ts` (CI-Gate bricht sonst — DSGVO Block, Spec „Account-Löschung → harte Löschung der Event-Caches").
---
## Lücken / komplett neu zu bauen
**Datenmodell**
- Alle fünf `Calendar*`-Modelle inkl. Indizes/Constraints (Block A) — nicht vorhanden.
- `user-fk-map.ts`-Einträge für die neuen User-FK-Modelle (DSGVO, Pflicht-Gate).
**Provider-Integration (Kern, fehlt vollständig)**
- `CalendarAdapter`-Interface mit allen Methoden (Block G): `initiateOAuth`, `handleOAuthCallback`, `refreshAccessToken`, `listCalendars`, `subscribeWebhook`/`unsubscribeWebhook`/`renewWebhook`, `fetchEventsInitial`/`fetchEventsDelta`, `createEvent`/`updateEvent`/`deleteEvent`, `verifyWebhookSignature`.
- **Google-Adapter** (Calendar API v3, Push-Notification-Channels, `syncToken`, `If-Match`/etag) — neu.
- **Microsoft-Adapter** (Graph Calendar, Subscriptions/`deltaLink`, `clientState`, Azure-AD-Multi-Tenant-App + Admin-Consent-Flow) — neu.
- OAuth2-Connect-Flow Ende-zu-Ende (state-Token signiert mit `tenant_id+user_id`, code↔token-Exchange, User-Info-Fetch) — **kein** outbound-OAuth-Connect existiert (nur inbound SSO/OIDC + ein GitHub-Service `apps/web/app/utils/integrations/githubService.ts`, das als loses Vorbild taugt).
**Sync-Engine (fehlt)**
- Bidirektionaler Sync (Block D): Schreib-Pfad HiveGrid→extern (Booking/Projekt/Plantafel/Tasks-Spiegelung, Mehrfach-Provider-Mappings), Lese-Pfad extern→HiveGrid (Initial-Full-Pull -7/+60, inkrementell via Cursor, „Free"-Filter, Private→„Privat"-Titel-Reduktion).
- Konflikt-Handling Last-Write-Wins-mit-Sichtbarkeit (Block F): 412-Precondition-Failed-Behandlung, „externe Version gewinnt" + Restore-Option, Mapping-Cleanup bei extern gelöschten Events, `last_known_internal_version_token`-Check.
**Webhook-Subsystem (fehlt fachlich)**
- Provider-Webhook-Empfangs-Endpoints `/webhooks/calendar/{provider}` mit Provider-spezifischer Signature-Verifikation (Google `X-Goog-Channel-Token`, MS `clientState`) — generisches HMAC-Verify-Muster vorhanden, aber Provider-Logik neu.
- **Subscription-Renewal-Cron** (Google ~1 Woche, MS ~3 Tage; alle 6h, Renewal in 24h-Fenster) — Cron-Skelett vorhanden, Logik neu.
- 410-Gone → Full-Resync.
**Verfügbarkeits-Berechnung (fehlt, Block H)**
- Slot-Engine: Working-Hours + interne Events + externe Busy-Events + Plantafel → freie Slots; 30-Tage-Slot-Cache mit Invalidierung bei `CalendarEvent`-Update; DSGVO-Filterung (Booking erhält nur `is_available`-Boolean, nie Event-Inhalt). Hängt an Modul 6/M126.
**Querschnitt-Wiring (HiveGrid-seitig neu zu verdrahten)**
- Sidebar-Eintrag „Termine" (Gruppe ARBEITEN, M120) + Settings-Eintrag „Integrationen → Kalender" in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts`.
- Routes (Block B / INTEGRATION-CONTRACTS §3): `settings/integrationen/calendar/...` + Connect/Callback + `:connection_id`-Detail.
- Calendar-Display-Component (Tag/Woche/Monat) für M120 — kein BP-Renderer vorhanden (Subframe-Design Pflicht, siehe Memory `feedback_subframe_mandatory`).
- Activity-Stream-Hooks (`logActivity`): `calendar_connected`/`_disconnected`/`_sync_error`/`appointment_synced_external` — bewusst NICHT pro Event-Update (M120 / INTEGRATION-CONTRACTS §5).
- Off-Boarding-Hook (Block I / Modul 27): User-Deaktivierung → Connections `paused`, Webhooks abmelden; Hard-Delete → Caches hart löschen.
- Tenant-spezifische KMS/Envelope-Encryption für Refresh-Tokens (Spec verlangt Tenant-Key; CryptoApi ist single-key — Erweiterung nötig).
**Anti-Liste (Phase 2, NICHT bauen):** iCal-Feed, Resource-Calendar, Tenant-Zentral-Connection, Apple/iCloud-CalDAV, FastMail, konfigurierbares Sync-Fenster, Multi-Calendar-Settings-UI, Color-Sync, KI-Konflikt-Resolution, erweiterte Zeitzonen, Recurring-Event-Single-Instance-Edits.
---
## Empfohlenes Vorgehen
1. **Querschnitt zuerst aus BP verdrahten (1:1):** `withTenantScope`/`withPermission`/`withOwnerCheck` (Permissions), `notify`/`auditEvent` (Konflikt/Connect-Audit), `VMState`/`ActionCallbacks` (VM-Layer), `i18n`-Keys + `formatDate`, `feature-flags` (Modul-Abschaltung), `outbound-http` (SSRF für alle Provider-Calls), `logger` (Token-Redaction). Permissions `calendar.connect_own`/`calendar.admin` in `packages/entitlements/src/permissions.ts` + seed.
2. **Datenmodell (M118):** Die fünf `Calendar*`-Modelle in `app.prisma`/`calendar.prisma` anlegen (Block A, inkl. Indizes/Unique-Constraints), `user-fk-map.ts` ergänzen, Forward-Only-Migration mit Inverse-SQL-Kommentar (DoD). **Vorab entscheiden:** `appsEngine`-Modelle (`DataConnection`/`AppSyncRun`/`AppSyncRunLog`) wiederverwenden für Connection+Sync-Lauf+Konflikt-Log, oder dedizierte Modelle — `appsEngine` ist die nächste Vorlage, deckt aber Cache/Cursor/Webhook nicht und vermischt zwei „Apps-Engine"-Bedeutungen (siehe Inventur integrations-ki §4.4).
3. **Token-Storage (M118):** `CryptoApi`/`marketingIntegrations`-Verschlüsselungs-Pattern als Vorlage; auf Tenant-Key/KMS-Envelope erweitern (Spec/AV #13). Never-Redisplay-Regel übernehmen.
4. **Adapter-Pattern (M118):** `CalendarAdapter`-Interface (Block G) definieren; Google- und MS-Adapter neu implementieren; Klartext-Fehler-Codes als `CatalogError`-Katalog (Block G/J) registrieren. OAuth-Connect/Callback-Routes über `apps/api`-Webhook/Auth-Klassen-Muster + `outbound-http`.
5. **Webhook + Sync-Worker (M118→M119):** Public Webhook-Endpoints (Provider-Signature-Verify nach `mailersend-signature`-Muster) → `CalendarWebhookEvent`/Outbox (`dispatchKey`-Idempotenz) → BullMQ-Sync-Worker (Cursor-Delta-Pull). `calendar.`-Prefix in `event-router.ts`. Renewal-Cron nach `*-cron.ts`-Muster.
6. **Bidirektionaler Sync + Konflikt (M119):** Schreib-Pfad (Spiegelung Booking/Projekt/Plantafel, Mehrfach-Provider-Mappings), Lese-Pfad (Privacy-Reduktion), Last-Write-Wins-mit-Restore-Option via `notify`.
7. **Verfügbarkeit + Display (M119/M120):** Slot-Engine + Cache (an Modul 6/M126 koppeln); Calendar-View-Component via Subframe neu (kein BP-Renderer); Activity-Stream-Hooks; Sidebar/Route/Breadcrumb-Wiring; Off-Boarding-Hook.
8. **DoD-Schluss je Milestone:** Smoke-Test je Route, Hot-Swap-Drill gegen `ui-mock`, Visual-Snapshot, Permission-Denied→404, Feature-Flag, Customer-Portal-Sichtbarkeit explizit (default NICHT sichtbar).
---
### Quellen-Hinweis
Alle Aussagen direkt in `/Users/raffaelsheikh/Documents/GitHub/boilerplate` verifiziert (Greps auf `calendar|ical|google.?calendar|microsoft.?graph|oauth2|encrypt`, gelesene Dateien: `foundation/src/adapters.ts`, `CryptoApi.ts`, `marketingIntegrations.db.server.ts`, `api-client-ts/src/webhooks.ts`, `mailersend-signature.ts`, `appsEngine.prisma`, `entityBuilder.prisma`, `outbox/event-router.ts`). **Kein** Calendar-/OAuth-Connect-/Provider-Code gefunden.