# Universal Kalender Integration Setup

## Übersicht

Die Universal Kalender Integration unterstützt verschiedene E-Mail-Provider und Kalender-Dienste:

- **Microsoft Outlook** (Outlook.com, Office 365, Exchange)
- **Google Calendar** (Gmail, Google Workspace)
- **CalDAV** (Yahoo, iCloud, Nextcloud, etc.)
- **iCal Export** (für manuellen Import)

## 1. Microsoft Outlook Integration

### Setup
Siehe `OUTLOOK_SETUP.md` für detaillierte Anweisungen.

### Umgebungsvariablen
```bash
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_TENANT_ID=your_tenant_id
MICROSOFT_REDIRECT_URI=https://yourdomain.com/admin/outlook/callback
```

## 2. Google Calendar Integration

### Google Cloud Console Setup

1. **Projekt erstellen**:
   - Gehen Sie zu [Google Cloud Console](https://console.cloud.google.com/)
   - Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes

2. **Calendar API aktivieren**:
   - Navigieren Sie zu "APIs & Services" > "Library"
   - Suchen Sie nach "Google Calendar API"
   - Klicken Sie auf "Enable"

3. **OAuth2-Anmeldedaten erstellen**:
   - Gehen Sie zu "APIs & Services" > "Credentials"
   - Klicken Sie auf "Create Credentials" > "OAuth 2.0 Client IDs"
   - Wählen Sie "Web application"
   - Fügen Sie Redirect URIs hinzu:
     - Entwicklung: `http://localhost:8000/admin/calendar/google/callback`
     - Produktion: `https://yourdomain.com/admin/calendar/google/callback`

4. **Service Account (optional)**:
   - Für Server-zu-Server-Kommunikation
   - Erstellen Sie einen Service Account
   - Laden Sie die JSON-Datei herunter

### Umgebungsvariablen
```bash
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://yourdomain.com/admin/calendar/google/callback
GOOGLE_CREDENTIALS_PATH=/path/to/service-account.json
```

## 3. CalDAV Integration

### Unterstützte Provider

#### Yahoo Calendar
- **CalDAV-URL**: `https://caldav.calendar.yahoo.com/`
- **Principal**: `/dav/[email]/Calendar/`
- **Authentifizierung**: App-spezifisches Passwort erforderlich

#### iCloud Calendar
- **CalDAV-URL**: `https://caldav.icloud.com/`
- **Principal**: `/[icloud_id]/calendars/`
- **Authentifizierung**: App-spezifisches Passwort erforderlich

#### Nextcloud/ownCloud
- **CalDAV-URL**: `https://your-nextcloud.com/remote.php/dav/`
- **Principal**: `/calendars/[username]/`
- **Authentifizierung**: Benutzername und Passwort

#### Generic CalDAV
- **CalDAV-URL**: Vom Provider bereitgestellt
- **Principal**: Vom Provider bereitgestellt
- **Authentifizierung**: Benutzername und Passwort

### Setup-Schritte

1. **App-spezifisches Passwort erstellen** (für Yahoo/iCloud):
   - Yahoo: Account-Einstellungen > Sicherheit > App-Passwörter
   - iCloud: Apple ID > Anmelden und Sicherheit > App-spezifische Passwörter

2. **CalDAV-URL ermitteln**:
   - Oft in den Konto-Einstellungen des Providers zu finden
   - Oder über Autodiscovery: `https://[domain]/.well-known/caldav`

3. **Kalender-Pfad finden**:
   - Meist `/calendar/` oder `/calendars/[username]/`
   - Kann über CalDAV-Client-Tools ermittelt werden

## 4. iCal Export

### Funktionsweise
- Generiert `.ics`-Dateien für jeden Kurs
- Kann in jeden Kalender importiert werden
- Keine Authentifizierung erforderlich
- Einmalige Synchronisation (keine automatischen Updates)

### Unterstützte Kalender-Apps
- Apple Calendar (macOS/iOS)
- Google Calendar (Import-Funktion)
- Outlook (Import-Funktion)
- Thunderbird Lightning
- Alle anderen iCal-kompatiblen Apps

## 5. Verwendung

### Schritt-für-Schritt-Anleitung

1. **Provider auswählen**:
   - Navigieren Sie zu `/admin/calendar`
   - Klicken Sie auf den gewünschten Provider

2. **Anmeldedaten eingeben**:
   - Füllen Sie das Formular aus
   - Testen Sie die Verbindung
   - Speichern Sie die Verbindung (optional)

3. **Kurse synchronisieren**:
   - Wählen Sie einzelne Kurse oder alle
   - Klicken Sie auf "Synchronisieren"
   - Überwachen Sie den Fortschritt

4. **iCal exportieren**:
   - Klicken Sie auf "iCal exportieren"
   - Laden Sie die Datei herunter
   - Importieren Sie sie in Ihren Kalender

## 6. Konfiguration

### Provider-spezifische Einstellungen

#### Microsoft Outlook
```yaml
# config/packages/outlook_calendar.yaml
parameters:
    outlook_calendar:
        sync_enabled: true
        default_calendar_name: 'Kursverwaltung'
```

#### Google Calendar
```yaml
# config/packages/google_calendar.yaml
parameters:
    google_calendar:
        application_name: 'Kursverwaltung'
        default_calendar_id: 'primary'
```

#### CalDAV
```yaml
# config/packages/caldav.yaml
parameters:
    caldav:
        timeout: 30
        user_agent: 'Kursverwaltung CalDAV Client'
```

### Event-Mapping anpassen
```yaml
# config/packages/calendar_mapping.yaml
parameters:
    calendar_mapping:
        course_prefix: '[KURS]'
        event_prefix: '[EVENT]'
        location_format: '{location.name} - {location.address}'
```

## 7. Sicherheit

### Credentials-Speicherung
- **Entwicklung**: Session-basiert (temporär)
- **Produktion**: Verschlüsselt in Datenbank
- **Empfehlung**: Verwenden Sie Symfony Secrets für sensible Daten

### OAuth2-Token
- Access-Token werden sicher gespeichert
- Refresh-Token für automatische Erneuerung
- Token-Ablauf wird überwacht

### CalDAV-Passwörter
- Verwenden Sie App-spezifische Passwörter
- Niemals Haupt-Passwörter verwenden
- Regelmäßige Rotation empfohlen

## 8. Troubleshooting

### Häufige Fehler

#### Microsoft Outlook
- **Invalid redirect_uri**: Überprüfen Sie die Azure-Konfiguration
- **Insufficient privileges**: Admin-Zustimmung erforderlich
- **Token expired**: Refresh-Token verwenden

#### Google Calendar
- **API not enabled**: Calendar API in Google Cloud Console aktivieren
- **Invalid credentials**: OAuth2-Setup überprüfen
- **Quota exceeded**: API-Limits beachten

#### CalDAV
- **Authentication failed**: App-spezifisches Passwort verwenden
- **URL not found**: CalDAV-URL überprüfen
- **SSL errors**: Zertifikate validieren

#### iCal Export
- **File not found**: Temporäre Dateien werden automatisch gelöscht
- **Invalid format**: Event-Daten überprüfen

### Debug-Modus
```bash
# Logs anzeigen
tail -f var/log/dev.log | grep -i calendar

# Spezifische Provider-Logs
tail -f var/log/dev.log | grep -i outlook
tail -f var/log/dev.log | grep -i google
tail -f var/log/dev.log | grep -i caldav
```

### Test-Verbindungen
```bash
# Symfony-Konsole für Tests
php bin/console app:test-calendar-connection microsoft user@outlook.com
php bin/console app:test-calendar-connection google user@gmail.com
php bin/console app:test-calendar-connection caldav https://caldav.example.com/
```

## 9. Erweiterte Features

### Automatische Synchronisation
- Webhook-basierte Updates (geplant)
- Cron-Job für regelmäßige Synchronisation
- Event-basierte Synchronisation bei Kurs-Änderungen

### Bulk-Operationen
- Mehrere Provider gleichzeitig
- Batch-Export für große Kursmengen
- Fortschrittsanzeige für lange Operationen

### Kalender-Management
- Mehrere Kalender pro Provider
- Kalender-spezifische Einstellungen
- Automatische Kalender-Erstellung

## 10. API-Referenz

### REST-Endpoints

```bash
# Provider auflisten
GET /admin/calendar/providers

# Kurs synchronisieren
POST /admin/calendar/sync/{id}
{
    "provider": "google",
    "credentials": {...}
}

# Bulk-Synchronisation
POST /admin/calendar/sync-bulk
{
    "provider": "microsoft",
    "credentials": {...},
    "course_ids": [1, 2, 3]
}

# iCal exportieren
GET /admin/calendar/export-ical/{id}

# Verbindung testen
POST /admin/calendar/test-connection
{
    "provider": "caldav",
    "credentials": {...}
}
```

### Service-Methoden

```php
// Universal Calendar Service verwenden
$result = $calendarService->syncCourse($course, 'google', $credentials);

// Unterstützte Provider abrufen
$providers = $calendarService->getSupportedProviders();

// iCal-Datei generieren
$result = $calendarService->syncCourse($course, 'ical', []);
```