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