13 – Integrationen (Google / Microsoft) + Storage + Geo

Reifegrad: 🟡 funktional, Teile Beta · Schicht: src/lib/google/*, src/lib/microsoft/*, src/lib/calendar/*, src/lib/geo/*, @work7/storage, src/app/api/{google,microsoft,calendar,geo,places}/*

Zweck

Anbindung externer Plattformen: Kalender- und Mail-Sync mit Google Workspace und Microsoft 365, Adress-/Geo-Daten über Google Places sowie mandantenspezifischer Dokumentenspeicher.

Google Workspace

• Auth: src/lib/google/auth.ts, request-auth.ts, config.ts, clients.ts, company-connection.ts. Unterstützt Domain-Wide Delegation (DWD) (Service-Account impersoniert Tenant-User) – Setup-Doku in src/dwd_setup1.png/dwd_setup2.png, Test-Skripte scripts/test-google-dwd.ts, scripts/send-google-dwd-test-mails.ts, scripts/list-google-tenant-users.ts.
• Kalender (/api/google/calendar/*): calendars, events (+ [eventId]), Watch-Channels watch/{start,status,stop,webhook} (Push-Notifications).
• Gmail (/api/google/gmail/*): messages (+ [id]), send.
• Verwaltung: /api/google/setup, connection-test, health, users, users/suggestions.
• Bootstrap eingeladener Nutzer: src/lib/google/invite-user-bootstrap.ts.

Microsoft 365 (Graph)

• Spiegelbildlich: src/lib/microsoft/* (auth, clients, company-connection, config, errors).
• Kalender (/api/microsoft/calendar/*): calendars, events (+ [eventId]), watch/{start,status,stop,webhook}.
• Mail (/api/microsoft/mail/*): messages (+ [id]), send.
• Verwaltung: /api/microsoft/setup, connection-test, users, users/suggestions.

Kalender-Sync-Engine (src/lib/calendar/*)

Provider-neutrale Sync-Schicht über den Termin-Tabellen (Migration 016):

• sync-service.ts – enqueueOutboundAppointmentSync, Outbound-Queue.
• mirror-sync.ts / provider-inbound.ts – Inbound: Provider-Eventzeiten auf verknüpfte appointments (inkl. Abwesenheit/leave_requests/user_absences); Löschungen canceln.
• google-watch.ts / microsoft-watch.ts – Push-Channel-Lifecycle.
• outbound-push.ts – interne Termine → Provider (pushAppointmentToActiveProviders).
• unified-events.ts – gemeinsames Event-Modell beider Provider.
• ics.ts – ICS/iCalendar-Generierung. browser-cache.ts – clientseitiger Cache.
• Verbindungs-/Sync-State: sync_connections, external_event_links, sync_events, sync_runs; status/conflict_strategy-Lifecycle (Migration 018). API: /api/calendar/connect/[provider]/{start,callback}, /api/calendar/connections[/id], /api/calendar/sync/[provider]/{delta,webhook}.

Geo / Places (src/lib/geo/*)

• google-places.ts + company-bias.ts – Adress-Autocomplete mit Bias auf den Firmenstandort.
• API: /api/geo/address-autocomplete, /api/geo/place-details, /api/places/*.
• Nutzung in Kontakt-/Projekt-/Firmen-Adressfeldern (siehe 03-kontakte-crm).

Mandanten-Storage (@work7/storage)

Zusammenfassung (Detail in 02-mandanten-company-settings): Default Azure Blob, optional SharePoint/Google Drive/Dropbox/Nextcloud via PKCE-OAuth. Tabellen tenant_storage_settings, tenant_storage_oauth_credentials (verschlüsselte Tokens), document_storage_mappings. APIs unter /api/settings/storage/*. WhatsApp-Medien des Agents landen im selben Tenant-Storage (work7-media).

Ordnerstruktur (alle Provider)

Pfad-Helpers in packages/storage/src/workspace.ts. Alles unter {company_id}/work7-app/:

{company_id}/work7-app/
├── customers/{kontakt-slug}/projects/{projekt-slug}/
│   ├── files | contracts | images | notes
│   ├── bautagebuch | aufmass | acceptance
├── anfragen/{anfrage_number}/          # Fallback: id-{n}
│   ├── files | images | mail
├── system/
│   ├── agent-media/                    # WhatsApp/Voice Staging
│   └── leave/
└── import-migration/inbox[/material]

Domäne	Ablage
Anfrage (Upload)	anfragen/…/files oder …/images
Mail-Anhang nach Sync	anfragen/…/mail
Mail vor Anfrage	kein Tenant-Pfad (Provider)
Projekt / WhatsApp-Final	customers/…/projects/…/images
Abnahme	Projekt-acceptance/ (ohne Projekt: system/agent-media)
Agent Staging	system/agent-media
Logo / E-Rechnung	DB, nicht Tenant-Storage

resolveUploadFolder legt relative Pfade immer unter den Tenant-Root. Parent-Ordner werden lazy beim Upload (putTenantObject) sichergestellt. Bestehende Blob-Pfade bleiben gültig (keine Pflicht-Migration).

Realtime-Kopplung

Eingehende Kalender-Webhooks emittieren calendar:google / calendar:microsoft über die Realtime-Bridge (siehe 15-notifications-realtime), sodass UI-Plantafeln live aktualisieren.

Bekannte Befunde / offene Punkte

• Sync ist Beta: Webhook-Erneuerung, Delta-Token-Recovery und Konfliktstrategien (internal_wins/provider_wins/manual_review) sind angelegt, brauchen aber Monitoring (sync_runs) im Dauerbetrieb.
• DWD setzt korrekte Google-Workspace-Admin-Konfiguration voraus (Scopes, Service-Account).
• Callback-/Webhook-URLs sind an die App-Subdomain gebunden (app.work7.net) – bei Domain-Wechsel nachziehen (siehe adr-0001-landing-app-domain-split).

Verwandte Notes

• 06-termine-kalender-plantafel · 02-mandanten-company-settings · 15-notifications-realtime
• 03-kontakte-crm