# Google Service Account Setup für Advoware Calendar Sync

## Übersicht
Dieser Calendar Sync verwendet **ausschließlich Google Service Accounts** für die Authentifizierung. Kein OAuth, kein Browser-Interaktion - perfekt für Server-Umgebungen!

## Voraussetzungen
- Google Cloud Console Zugang
- Berechtigung zum Erstellen von Service Accounts
- (Optional) Google Workspace Admin Zugang für Domain-wide Delegation

## Schritt 1: Google Cloud Console aufrufen
1. Gehen Sie zu: https://console.cloud.google.com/
2. Melden Sie sich mit Ihrem Google-Konto an
3. Wählen Sie ein bestehendes Projekt aus oder erstellen Sie ein neues

## Schritt 2: Google Calendar API aktivieren
1. Klicken Sie auf "APIs & Dienste" → "Bibliothek"
2. Suchen Sie nach "Google Calendar API"
3. Klicken Sie auf "Google Calendar API" → "Aktivieren"

## Schritt 3: Service Account erstellen
1. Gehen Sie zu "IAM & Verwaltung" → "Service-Konten"
2. Klicken Sie auf "+ Service-Konto erstellen"
3. Grundlegende Informationen:
   - **Service-Kontoname**: `advoware-calendar-sync`
   - **Beschreibung**: `Service Account für Advoware-Google Calendar Synchronisation`
   - **E-Mail**: wird automatisch generiert
4. Klicken Sie auf "Erstellen und fortfahren"

## Schritt 4: Berechtigungen zuweisen
1. **Rolle zuweisen**: Wählen Sie eine der folgenden Optionen:
   - Für volle Zugriffe: `Editor`
   - Für eingeschränkte Zugriffe: `Calendar API Admin` (falls verfügbar)
2. Klicken Sie auf "Fertig"

## Schritt 5: JSON-Schlüssel erstellen und installieren
1. Klicken Sie auf das neu erstellte Service-Konto
2. Gehen Sie zum Tab "Schlüssel"
3. Klicken Sie auf "Schlüssel hinzufügen" → "Neuen Schlüssel erstellen"
4. Wählen Sie "JSON" als Schlüsseltyp
5. Klicken Sie auf "Erstellen"
6. Die JSON-Datei wird automatisch heruntergeladen
7. **Benennen Sie die Datei um zu: `service-account.json`**
8. **Kopieren Sie die Datei nach: `/opt/motia-app/service-account.json`**
9. **Stellen Sie sichere Berechtigungen ein:**
   ```bash
   chmod 600 /opt/motia-app/service-account.json
   ```

## Schritt 6: Domain-wide Delegation (nur für Google Workspace)
Falls Sie Google Workspace verwenden und auf Kalender anderer Benutzer zugreifen möchten:

1. Gehen Sie zurück zum Service-Konto
2. Aktivieren Sie "Google Workspace Domain-wide Delegation"
3. Notieren Sie sich die "Unique ID" des Service-Kontos
4. Gehen Sie zu Google Admin Console: https://admin.google.com/
5. "Sicherheit" → "API-Berechtigungen"
6. "Domain-wide Delegation" → "API-Clienten verwalten"
7. Fügen Sie die Unique ID hinzu
8. Berechtigungen: `https://www.googleapis.com/auth/calendar`

## Schritt 7: Testen
Nach dem Setup können Sie den Calendar Sync testen:

```bash
# Vollständige Termindetails synchronisieren
curl -X POST http://localhost:3000/api/flows/advoware_cal_sync \
  -H "Content-Type: application/json" \
  -d '{"full_content": true}'

# Nur "blocked" Termine synchronisieren (weniger Details)
curl -X POST http://localhost:3000/api/flows/advoware_cal_sync \
  -H "Content-Type: application/json" \
  -d '{"full_content": false}'
```

## Wichtige Hinweise
- ✅ **Kein Browser nötig** - läuft komplett server-seitig
- ✅ **Automatisch** - einmal setup, läuft für immer
- ✅ **Sicher** - Service Accounts haben granulare Berechtigungen
- ✅ **Skalierbar** - perfekt für Produktionsumgebungen

## Fehlerbehebung
- **"service-account.json nicht gefunden"**: Überprüfen Sie den Pfad `/opt/motia-app/service-account.json`
- **"Access denied"**: Überprüfen Sie die Berechtigungen des Service Accounts
- **"API not enabled"**: Stellen Sie sicher, dass Calendar API aktiviert ist
- **"Invalid credentials"**: Überprüfen Sie die service-account.json Datei

## Sicherheit
- Halten Sie die `service-account.json` Datei sicher und versionieren Sie sie nicht
- Verwenden Sie IAM-Rollen in GCP-Umgebungen statt JSON-Keys
- Rotiere Service Account Keys regelmäßig