Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M25-calendar-sync.md
T

497 lines
25 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.
---
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)