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,496 @@
---
module: 25
title: Calendar-Sync (Google + Microsoft)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 25 — Calendar-Sync
> **Detail-Spec gemäß LP-9.** OAuth2-Connect von Google Calendar und Microsoft Outlook/365-Calendar **pro User** (nicht pro Tenant). Bidirektionale Synchronisation: HiveGrid-Termine (Booking, Projekt, Plantafel) gehen nach extern; externe Termine kommen read-only ins HiveGrid für Verfügbarkeits-Berechnung im Booking. Adapter-Pattern (LP-11): Google + MS implementieren gemeinsames `CalendarAdapter`-Interface.
## Themenblöcke
```
A. Datenmodell (CalendarConnection, CalendarEvent, CalendarEventMapping, CalendarSyncCursor, CalendarWebhookEvent)
B. Menü-Struktur und Routes
C. OAuth2-Connect-Flow (Google + Microsoft)
D. Sync-Richtungen und Mappings
E. Webhook-Sync (kein Polling)
F. Konflikt-Handling (Last-Write-Wins mit Hinweis)
G. Adapter-Pattern (CalendarAdapter-Interface)
H. Verfügbarkeits-Berechnung (Integration mit Booking, Modul 6)
I. Permissions-Anwendung
J. Klartext-Hinweise
K. Phase 2
```
---
## Block A — Datenmodell
### CalendarConnection
Pro User pro Provider eine Verbindung. Tenant-scoped (User kann pro Tenant unterschiedliche Konten verbinden), RLS-aktiv.
- `id`, `tenant_id`, `user_id`, `created_at`, `updated_at`
- `provider` (Enum: `google | microsoft`)
- `external_account_email` (z.B. `noah@geerkens.de` — User-sichtbar zur Kontrolle)
- `external_account_id` (Provider-interne Account-ID)
- `oauth_refresh_token` (verschlüsselt at-rest)
- `oauth_access_token` (verschlüsselt; kurzer Lebenszyklus)
- `oauth_access_token_expires_at`
- `oauth_scopes[]` (gewährte Scopes; bei Reduktion durch User → Klartext-Hinweis und Re-Connect)
- `webhook_subscription_id` (Provider-interne Subscription-ID; bei Google: `channel.id`, bei MS: `subscription.id`)
- `webhook_subscription_expires_at` (Provider-Limits: Google ~1 Woche, MS ~3 Tage; Auto-Renewal-Job nötig)
- `selected_calendars[]` (JSONB — User wählt welche externen Kalender synchronisiert werden; Default: Primary-Calendar)
- `sync_direction` (Enum: `bidirectional | hivegrid_to_external_only | external_to_hivegrid_only`; Default `bidirectional`)
- `status` (Enum: `active | paused | error | revoked`)
- `last_sync_at`
- `last_error_text` (Klartext, falls `status = error`)
**Constraints:** `(tenant_id, user_id, provider, external_account_id)` unique.
### CalendarEvent
Cache externer Events + interne Events (über Mappings verknüpft). Tenant-scoped, RLS-aktiv.
- `id`, `tenant_id`, `user_id`, `created_at`, `updated_at`
- `source` (Enum: `hivegrid_internal | external_synced`)
- `provider` (NULL bei `hivegrid_internal`, sonst `google | microsoft`)
- `external_event_id` (Provider-Event-ID, NULL bei rein internen Events ohne externe Spiegelung)
- `external_calendar_id` (welcher externer Kalender; NULL bei internen)
- `title`
- `description`
- `location`
- `starts_at`, `ends_at`, `is_all_day`
- `time_zone`
- `recurrence_rule` (RRULE-String, optional)
- `attendees` (JSONB — Liste mit Email + Status)
- `etag` / `version_token` (Provider-spezifisch — für Konflikt-Erkennung)
- `last_modified_external` (Provider-Modify-Timestamp)
- `is_busy_for_availability` (Boolean — fließt in Verfügbarkeits-Berechnung; bei externen Events Default true außer „Free"-Status)
- `internal_entity_link` (JSONB optional — z.B. `{ "type": "booking", "id": "uuid" }` oder `{ "type": "project", "id": "uuid" }` oder `{ "type": "plantafel_entry", "id": "uuid" }`)
- `archived_at` (Soft-Delete für gelöschte externe Events behalten wir kurz, dann purge)
**Indizes:**
- `(tenant_id, user_id, starts_at)` für Verfügbarkeits-Queries
- `(tenant_id, user_id, provider, external_event_id)` unique (für Update-Lookup)
- `(tenant_id, user_id, last_modified_external DESC)` für Sync-Cursor-Queries
### CalendarEventMapping
Verknüpft HiveGrid-interne Events mit externen Spiegel-Events.
- `id`, `tenant_id`, `created_at`, `updated_at`
- `internal_event_id` (FK auf `CalendarEvent` mit `source = hivegrid_internal`)
- `external_event_id` (Provider-Event-ID)
- `provider`
- `external_calendar_id`
- `connection_id` (FK auf `CalendarConnection`)
- `last_synced_at`
- `last_known_external_etag`
- `last_known_internal_version_token`
**Constraints:** ein `internal_event_id` kann mehrere Mappings haben (z.B. wenn User Google + MS gleichzeitig verbunden) — also `(internal_event_id, provider, external_calendar_id)` unique.
### CalendarSyncCursor
Pro Connection und Kalender ein Sync-Cursor (Provider-spezifisch).
- `id`, `tenant_id`, `connection_id`, `external_calendar_id`, `created_at`, `updated_at`
- `cursor_token` (Google: `syncToken`; MS: `deltaLink`)
- `last_full_sync_at`
**Constraints:** `(connection_id, external_calendar_id)` unique.
### CalendarWebhookEvent
Eingehende Webhook-Notifications werden persistiert (für Idempotenz und Retry).
- `id`, `tenant_id`, `connection_id`, `received_at`
- `provider`
- `notification_payload` (JSONB)
- `processing_status` (Enum: `pending | processing | completed | failed | skipped`)
- `processing_error_text` (Klartext)
- `processed_at`
- `external_resource_state` (Provider-spezifisch — z.B. Google's `X-Goog-Resource-State`)
**Indizes:** `(tenant_id, processing_status, received_at)` für Worker-Pickup.
---
## Block B — Menü-Struktur und Routes
**Sidebar-Hauptpunkt:** keiner direkt — Settings-Bereich.
**Routen:**
```
/{tenant}/settings/integrations/calendar/ → Übersicht Verbindungen + Connect-Buttons
/{tenant}/settings/integrations/calendar/google/connect → OAuth-Initiate Google
/{tenant}/settings/integrations/calendar/google/callback → OAuth-Callback Google
/{tenant}/settings/integrations/calendar/microsoft/connect → OAuth-Initiate Microsoft
/{tenant}/settings/integrations/calendar/microsoft/callback→ OAuth-Callback Microsoft
/{tenant}/settings/integrations/calendar/:connection_id → Detail-View einer Verbindung (Kalender-Auswahl, Sync-Status, Logs)
```
**Embedded-Anwendung:**
- Verfügbarkeits-Berechnung im Booking (Modul 6) liest `CalendarEvent` mit `is_busy_for_availability = true`
- Plantafel (Modul 4) zeigt externe Events des zugewiesenen Mitarbeiters als „belegt"
- Termine im Customer-Portal (Modul 15) werden nicht direkt angezeigt, aber Booking-Slots berücksichtigen sie
---
## Block C — OAuth2-Connect-Flow
### Google (Provider 1)
**Scopes (Phase 1):**
- `https://www.googleapis.com/auth/calendar` (Read/Write)
- `https://www.googleapis.com/auth/calendar.events` (Events Read/Write)
- `openid email profile` (für `external_account_email`)
**Flow-Schritte:**
1. User klickt „Google Calendar verbinden" auf Settings-View
2. App leitet zu Google-Consent-Screen mit `state`-Token (CSRF-Schutz, mit `tenant_id + user_id` signiert)
3. User autorisiert, Google leitet zurück zu `/google/callback?code=...&state=...`
4. Server validiert `state`, tauscht `code` gegen Tokens via Google-Token-Endpoint
5. Server holt User-Info (`external_account_email`, `external_account_id`)
6. `CalendarConnection` wird angelegt (oder bei Re-Connect aktualisiert)
7. Initial-Discovery: Liste aller Kalender → User wählt welche synchronisiert werden (Default: Primary)
8. Initial-Sync (Full-Pull der gewählten Kalender; siehe Block D)
9. Webhook-Subscription (Google Calendar Push Notifications) wird angelegt
10. UI zeigt: *„Verbunden mit {email}. Letzte Synchronisation: gerade eben."*
### Microsoft (Provider 2)
**Scopes (Phase 1):**
- `Calendars.ReadWrite`
- `User.Read` (für Email + Profile)
- `offline_access` (für Refresh-Tokens)
**Flow-Schritte:** analog Google, gegen Microsoft-Identity-Platform (`login.microsoftonline.com`).
**Tenant-Setup:** App muss als Multi-Tenant-App in Azure AD registriert sein. Klartext-Hinweis falls User-Org-Admin Consent nicht gegeben hat: *„Dein IT-Admin muss diese Verbindung zuerst genehmigen. [Link zur Admin-Consent-URL]"*
### Disconnect
- User klickt „Verbindung trennen" → Server widerruft Tokens beim Provider, löscht Webhook-Subscription, setzt `CalendarConnection.status = revoked`
- Optional: alle synchronisierten externen Events aus HiveGrid entfernen (User-Wahl mit Klartext-Erklärung)
- Mappings (für interne Events mit externer Spiegelung) werden gelöscht; interne Events bleiben in HiveGrid
### Re-Connect
- Bei `status = error` (z.B. Token revoked, Scope reduziert): Klartext-Banner mit „Erneut verbinden"-Funktion
- Token-Refresh läuft automatisch im Hintergrund; bei Fehler → `status = error` + Email-Notification an User
### Token-Storage
- Refresh-Tokens verschlüsselt at-rest (envelope encryption mit Tenant-spezifischem Schlüssel via KMS)
- Access-Tokens nur kurz gehalten, Re-Fetch bei Bedarf
- Logging niemals den Token-Klartext
---
## Block D — Sync-Richtungen und Mappings
### Richtung 1: HiveGrid → externer Kalender (bidirektional, Schreib-Pfad)
**Welche HiveGrid-Events werden gespiegelt:**
- **Booking-Termine** (Modul 6): wenn ein Booking gegen einen User mit aktiver `CalendarConnection` gebucht wird, wird automatisch ein Spiegel-Event im externen Kalender erstellt
- **Projekt-Termine** (Modul 4): User-konfigurierbar pro Projekt-Termin („In meinen Kalender eintragen" Toggle)
- **Plantafel-Einträge** (Modul 4): wenn User Plantafel-Einträge zugewiesen bekommt, automatisch oder per User-Setting
- **Tasks mit Fälligkeit** (Modul 26): optional als All-Day-Event; User-Setting Default aus
**Operationen:**
- **Create** in HiveGrid → API-Call zum Provider (Google/MS Insert), `external_event_id` und `etag` werden gespeichert
- **Update** in HiveGrid → Provider-Update-Call mit `If-Match`-Header (Optimistic Locking via etag)
- **Delete** in HiveGrid → Provider-Delete-Call
**Mehrfach-Provider:** wenn User Google + MS gleichzeitig verbunden hat → Spiegel-Event in BEIDEN Kalendern (zwei Mappings pro internem Event)
**Welche User-Felder werden synchronisiert:**
- `title` — von HiveGrid-Event-Titel (z.B. „Kundentermin Schmidt", „Projekt Heizung Schmidt — Montage Tag 2")
- `description` — Kontext-Info + Link zurück zu HiveGrid-Entity (z.B. „Geöffnet in HiveGrid: {url}")
- `location` — Adresse aus Projekt/Kunde
- `starts_at` / `ends_at` / `time_zone`
- `attendees` — bei Booking: Endkunde wird als Attendee eingeladen (mit Provider-eigener Einladungs-Mail; konfigurierbar per Booking-Page-Setting)
### Richtung 2: externer Kalender → HiveGrid (read-only)
**Zweck:** Verfügbarkeits-Berechnung für Booking + Plantafel. **Kein** Schreib-Zugriff auf externe Events außer für die von HiveGrid selbst erstellten (Mappings).
**Operationen:**
- **Initial-Sync:** Full-List der nächsten 60 Tage + vergangenen 7 Tage; danach inkrementeller Sync via Sync-Token
- **Inkrementeller Sync:** über `syncToken` (Google) bzw. `deltaLink` (MS) — Provider liefert nur Änderungen seit letztem Cursor
- **Webhook-getriggert** (siehe Block E): Notification → Worker holt Delta-Liste und aktualisiert `CalendarEvent`-Cache
**Welche externen Events werden gespiegelt:**
- Alle Events der vom User ausgewählten Kalender im Sync-Fenster (rolling window: -7 Tage bis +60 Tage; Phase 2: konfigurierbar)
- Private Events des Users (mit `private`-Markierung) werden gespiegelt aber `title` wird auf „Privat" reduziert; `is_busy_for_availability` bleibt true
**Welche externen Events werden NICHT gespiegelt:**
- Events mit Status „Free" beim Provider (haben `is_busy_for_availability = false`)
- Abgesagte Events
- Events außerhalb des Sync-Fensters
### Sicherheit & Privacy
- Externe Event-Inhalte sind sichtbar **nur** für den User selbst und Tenant-Admin (mit `calendar.admin`); nicht für andere Tenant-User
- Im Booking/Plantafel-Kontext werden externe Events nur als „belegt zwischen X und Y" angezeigt — kein Titel/Inhalt-Leak
- DSGVO: bei Account-Löschung des Users werden alle externen Event-Cache-Einträge hart gelöscht; bei Disconnect optional
---
## Block E — Webhook-Sync (kein Polling)
### Anforderungen
- **Kein Polling** — Provider pushen Notifications via Webhook
- **Google Calendar Push Notifications:** Channel-basiert, eine Subscription pro Kalender, Renewal vor Ablauf
- **Microsoft Graph Subscriptions:** ähnlich, Renewal alle 3 Tage
- **Renewal-Job:** Cron läuft alle 6h, erneuert Subscriptions die in den nächsten 24h ablaufen
- Webhook-Endpoints sind öffentlich erreichbar (keine Auth aus Provider-Sicht), aber:
- Provider-Signature-Verifikation (Google: `X-Goog-Channel-Token`, MS: `clientState`)
- Eindeutige Channel-IDs werden mit `connection_id` gemappt
### Webhook-Verarbeitung
1. Provider sendet POST an `/webhooks/calendar/{provider}` mit Notification
2. Server validiert Signature, schlägt `connection_id` über Channel-/Subscription-ID nach
3. Eintrag in `CalendarWebhookEvent` mit `processing_status = pending`
4. Sofortige 200-OK-Antwort an Provider (Provider-Limit auf <10s Response)
5. Async-Worker holt `pending`-Events und verarbeitet:
- Inkrementeller Sync via Cursor-Token
- Updates auf `CalendarEvent` schreiben
- Bei Updates an Events mit Mapping → Konflikt-Check (siehe Block F)
6. Status-Update auf `completed` oder `failed`
### Idempotenz
- Provider können Notifications duplizieren — Worker prüft `last_modified_external` und skippt wenn bereits verarbeitet
- Bei Cursor-Invalidierung (z.B. nach langem Offline-Sein) → Full-Resync (Provider liefert 410-Gone, App reagiert mit Full-List-Pull)
---
## Block F — Konflikt-Handling
### Last-Write-Wins (LP-7-konform; einfach für Phase 1)
**Szenarien:**
1. **HiveGrid-Update + externes Update zwischen den Syncs:**
- User editiert Termin in HiveGrid → App pusht zu Provider mit `If-Match: etag`
- Falls Provider-etag inzwischen geändert (paralleler Edit im Google Calendar UI) → Provider antwortet 412 Precondition Failed
- App löst Konflikt mit **„externer Stand gewinnt"** als Default (HiveGrid-Edit wird verworfen) UND zeigt Klartext-Notification an User: *„Dein Termin ‚{titel}' wurde gleichzeitig in {provider} geändert — die externe Version wurde übernommen. Du kannst die Änderung manuell wieder einarbeiten. [Original-HiveGrid-Stand anzeigen]"*
- User hat dann via In-App-Notification die Möglichkeit, manuell nachzuziehen
2. **Externer Termin gelöscht, HiveGrid hat noch Mapping:**
- Mapping wird entfernt, internes Event bleibt unverändert (z.B. Booking-Termin existiert weiter, externer Spiegel ist weg) — Klartext: *„Der Termin wurde im externen Kalender gelöscht. In HiveGrid bleibt er bestehen. [Im externen Kalender wieder anlegen]"*
3. **HiveGrid-Termin gelöscht:**
- App pusht Delete an alle gemappten externen Events
- Falls externe Events bereits geändert/gelöscht → still ignorieren
### Konflikt-Sichtbarkeit im UI
- In `CalendarConnection`-Detail-View: Liste der letzten 50 Konflikte mit Klartext-Beschreibung und Resolution
- In Notifications (Modul 22): bei wichtigen Konflikten Push/Email an User
### Optimistic Locking auf HiveGrid-Seite
- Interne Events haben `version_token` (Increment bei jedem Update)
- Mapping speichert `last_known_internal_version_token` — Worker prüft, dass Webhook-Updates nicht inzwischen veraltete Stände schreiben
---
## Block G — Adapter-Pattern (CalendarAdapter-Interface)
### Anforderungen (LP-11, AV #2)
Gemeinsames Interface für Google + Microsoft (und ggf. Phase-2-Provider wie Apple/iCloud, FastMail):
- `initiateOAuth(redirect_url) → authorizationUrl`
- `handleOAuthCallback(code, state) → { access_token, refresh_token, account_id, account_email, scopes }`
- `refreshAccessToken(connection) → { access_token, expires_at }`
- `listCalendars(connection) → Calendar[]`
- `subscribeWebhook(connection, calendar_id) → { subscription_id, expires_at }`
- `unsubscribeWebhook(connection, subscription_id) → void`
- `renewWebhook(connection, subscription_id) → { new_subscription_id, expires_at }`
- `fetchEventsInitial(connection, calendar_id, time_window) → { events[], cursor_token }`
- `fetchEventsDelta(connection, calendar_id, cursor_token) → { events[], next_cursor_token, full_resync_required }`
- `createEvent(connection, calendar_id, event_data) → { external_event_id, etag }`
- `updateEvent(connection, calendar_id, external_event_id, event_data, if_match_etag) → { etag }` (412 wirft `ConflictError`)
- `deleteEvent(connection, calendar_id, external_event_id, if_match_etag) → void`
- `verifyWebhookSignature(headers, body) → boolean`
### Klartext-Diagnostik pro Adapter (LP-10)
Adapter müssen Provider-spezifische Fehler in einheitliche Klartext-Codes übersetzen:
- `auth_token_expired` → *„Verbindung zu {provider} ist abgelaufen. Bitte neu verbinden."*
- `auth_scope_missing` → *„Berechtigung im {provider}-Konto wurde reduziert. Bitte neu verbinden."*
- `rate_limit_exceeded` → *„{provider} bremst gerade unsere Anfragen — wir versuchen es automatisch nochmal in {minutes} Minuten."*
- `calendar_not_found` → *„Der ausgewählte Kalender existiert nicht mehr im externen Konto."*
- `webhook_subscription_failed` → *„Push-Benachrichtigungen von {provider} sind gerade gestört. Synchronisation läuft mit Verzögerung."*
- `provider_outage` → *„{provider} ist gerade nicht erreichbar — Synchronisation pausiert."*
---
## Block H — Verfügbarkeits-Berechnung (Booking-Integration)
### Anforderungen
- Booking-Page (Modul 6) zeigt verfügbare Slots eines Users basierend auf:
- Working-Hours des Users (Modul 6 Settings)
- HiveGrid-eigene Termine des Users (`source = hivegrid_internal`)
- Externe Events mit `is_busy_for_availability = true`
- Plantafel-Einträge (Modul 4)
- Verfügbarkeits-Query: gegeben User + Zeitraum + Slot-Dauer → Liste freier Slots
- Performance: Slots werden für die nächsten 30 Tage gecacht; Cache-Invalidierung bei jedem CalendarEvent-Update
### Anti-Doppel-Buchung
- Wenn ein externer Termin während eines reservierten Booking-Slots erscheint (Sync-Verzögerung): Klartext-Notification an Booker mit Re-Booking-Vorschlag
- Realistisch nur bei Sync-Latenz > Booking-Duration; Phase-1-Toleranz akzeptabel
### Slot-Filterung
- Booking-Page lädt nicht direkt aus `CalendarEvent` (DSGVO/Privacy), sondern erhält nur `boolean is_available`-Antwort pro Slot
- Endkunde sieht nie Titel/Inhalt externer Events
---
## Block I — Permissions-Anwendung
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `calendar.connect_own` | Eigenen Kalender verbinden, eigene Connection verwalten |
| `calendar.admin` | Alle Connections im Tenant sehen, gestörte Verbindungen anzeigen, Auto-Disconnect bei User-Offboarding |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `calendar.none` | (keine — Calendar-Sync nicht verfügbar) |
| `calendar.connect_own` | `calendar.connect_own` |
| `calendar.admin` | `calendar.connect_own` + `calendar.admin` |
**Default:** `calendar.connect_own` für alle Tenant-User. Calendar-Sync ist user-spezifisch — keine Tenant-weite Zentral-Connection in Phase 1.
### Anwendung in Routes
- `/{tenant}/settings/integrations/calendar/` → `calendar.connect_own`
- `/{tenant}/settings/integrations/calendar/:connection_id` → `calendar.connect_own` (Owner-Check: `connection.user_id = self`) ODER `calendar.admin`
- `/{tenant}/admin/integrations/calendar/` (Phase 2 Tenant-Übersicht) → `calendar.admin`
- Webhook-Endpoints `/webhooks/calendar/{provider}` → keine User-Auth (Provider-Signature-Verifikation)
### Anwendung in Action-Funktionen
- Connect / Disconnect: nur eigene Connections (`calendar.connect_own`); Tenant-Admin kann fremde Connections bei User-Offboarding zwangs-trennen (`calendar.admin`)
- Sync-Settings ändern (Direction, ausgewählte Kalender): `calendar.connect_own` mit Owner-Check
- Sync-Logs einsehen: nur eigene; Tenant-Admin sieht aggregierte Statistiken (kein Event-Inhalt-Zugriff)
### Off-Boarding (Modul 27, D.2)
- Bei User-Deaktivierung → automatisch alle `CalendarConnection` des Users auf `paused`, Webhooks abgemeldet
- Bei User-Hard-Delete → Connections und alle externen Event-Caches hart löschen
---
## Block J — Klartext-Hinweise / Fehler-Cases (LP-10)
- **Verbindung abgelaufen:** *„Verbindung zu {provider} ist abgelaufen. Bitte neu verbinden, damit deine Termine weiter synchronisiert werden. [Neu verbinden]"*
- **Scope reduziert:** *„Du hast HiveGrid die Kalender-Berechtigung im {provider}-Konto entzogen. Synchronisation pausiert. [Neu verbinden]"*
- **Provider-Outage:** *„{provider} ist gerade nicht erreichbar — wir holen die letzten Termine sobald die Verbindung wieder steht. Letzte erfolgreiche Synchronisation: {time}."*
- **Rate-Limit:** *„{provider} bremst unsere Anfragen — Synchronisation läuft langsamer. Termine erscheinen mit etwas Verzögerung."*
- **Mehrfach-Account-Hinweis:** falls User dasselbe Provider-Konto bereits verbunden hat: *„{email} ist bereits verbunden. Stattdessen die existierende Verbindung anpassen?"*
- **Konflikt:** *„Termin ‚{titel}' wurde gleichzeitig in {provider} geändert — die externe Version wurde übernommen. [Original-Stand anzeigen]"*
- **Webhook gestört:** *„Push-Benachrichtigungen von {provider} sind gerade nicht aktiv. Synchronisation läuft alle 30 Minuten als Fallback."* (kein automatisches Polling normal — nur als kurzfristiger Fallback)
- **MS-Admin-Consent fehlt:** *„Dein IT-Admin muss diese Verbindung im {provider}-Tenant zuerst genehmigen. [Admin-Consent-Link kopieren]"*
- **Disconnect-Bestätigung:** *„Verbindung zu {email} wird getrennt. {n} synchronisierte Termine bleiben in HiveGrid. Auch in {provider} entfernen? [Nur trennen] [Trennen + extern entfernen]"*
- **Initial-Sync läuft:** *„Synchronisation läuft — kann beim ersten Mal ein paar Minuten dauern."*
---
## Activity-Stream-Integration
Calendar-Sync erzeugt selektiv Activities (Modul 1, Block E):
- `calendar_connected` (subject = User)
- `calendar_disconnected` (subject = User)
- `calendar_sync_error` (subject = User; bei wiederholten Fehlern)
- `appointment_synced_external` (subject = Booking/Project; metadata: `provider`, `external_calendar`)
**Bewusst NICHT** als Activity: jedes einzelne externe Event-Update (Spam-Vermeidung).
---
## Phase 2 / spätere Features
- **iCal-Feed** (read-only Feed-URL für Kalender-Apps, die keine OAuth-Anbindung haben)
- **Resource-Calendar** (Kran, Werkstatt-Heber, Pool-Fahrzeuge als buchbare Resource — eigener Kalender-Typ)
- **Tenant-Zentral-Connection** für Resource-Kalender (statt User-spezifisch)
- **Apple/iCloud-Calendar** (CalDAV-Adapter) — Trade-off Aufwand vs. Nachfrage
- **FastMail** (CalDAV)
- **Konfigurierbares Sync-Fenster** (statt fest -7/+60 Tage)
- **Multi-Calendar pro User** (User wählt mehrere externe Kalender pro Verbindung — Phase 1 erlaubt nur Default-Setup, Phase 2 macht pro-Calendar-Settings sichtbar)
- **Calendar-Color-Sync**
- **Smart-Conflict-Resolution mit KI-Vorschlag** (statt nur Last-Write-Wins)
- **Time-Zone-Awareness erweitert** (User in unterschiedlichen Zeitzonen)
- **Recurring-Event-Edits** (Edit nur dieser einen Instanz vs. Edit der Serie) — Komplex; Phase 2 ausgereifter
---
## Architektur-Vorschriften (Querschnitt)
- **LP-7:** Calendar-Sync löst teilweise Google Calendar Standalone-Nutzung ab — Geerkens-Kontext
- **LP-9, AV #1:** Klartext-Diagnostik pro Provider-Fehler (Block J)
- **LP-11, AV #2:** Adapter-Pattern für Google + Microsoft (Block G)
- **LP-13, AV #12:** EU-Stack — Tokens und Caches in EU-Region; Provider-APIs sind extern (Google/MS), das ist akzeptiert (DSGVO-konforme DPAs liegen vor)
- **AV #5:** Permissions-aware-Default — externe Event-Inhalte nie an andere User leaken
- **AV #6:** Audit-Trail-Default für Connect/Disconnect/Konflikte
- **AV #15:** Optimistic Locking + Last-Write-Wins-mit-Sichtbarkeit für Sync-Konflikte (Block F)
- **LP-1:** User-Connection mit `tenant_id` für Trennung; OAuth-State signiert mit Tenant-Kontext
---
## Abhängige Module
- **Modul 6 (Booking):** liest Verfügbarkeit aus `CalendarEvent`; pusht neue Bookings als interne Events
- **Modul 4 (Projekt-/Plantafel):** pusht Plantafel-Einträge in externen Kalender (User-Setting)
- **Modul 26 (Tasks):** optionale Synchronisation (User-Setting)
- **Modul 22 (Notifications):** zeigt Konflikte und Verbindungsfehler
- **Modul 27 (Auth):** Off-Boarding-Hook (Pause/Trennung bei User-Deaktivierung)
- **Modul 33a (Apps Engine):** stellt Adapter-Pattern-Infrastruktur bereit (LP-11)
- **Modul 21 (Audit-Log):** Connect/Disconnect/Konflikte werden geloggt
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 25. **Vor Bau:** Verifizierung mit Noah und Abgleich mit Modul 6 (Booking-Verfügbarkeits-Spec) und Modul 33a (Apps-Engine-Adapter-Pattern).
**Offene Detail-Punkte (nicht-blockierend):**
- Konkrete Sync-Fenster-Defaults (-7/+60 Tage) mit Geerkens-Workflow validieren
- Mehrfach-Verbindung pro User (Geschäftlich + Privat?) — Default-Verhalten
- Recurring-Event-Updates: Edit-Single-Instance vs. Edit-Series — minimaler Phase-1-Scope
- All-Day-Events Behandlung über Zeitzonen
- Konkretes Webhook-Renewal-Timing (Google: max 1 Woche; MS: max ~3 Tage) — Cron-Frequenz
- Microsoft-Multi-Tenant-App-Setup mit Azure AD (Admin-Consent-Flow im Detail)
- Klartext-Wording-Review für Konflikt-Notifications mit Noah/Sandra (Verständlichkeit für Endkunden-Bezug)
- Encryption-Strategie für Refresh-Tokens (KMS-Provider, Tenant-Schlüssel-Setup)