# Advoware Calendar Sync

Dieser Abschnitt implementiert die bidirektionale Synchronisation zwischen Advoware-Terminen und Google Calendar. Für jeden Mitarbeiter in Advoware wird automatisch ein entsprechender Google Calendar erstellt und gepflegt.

## Übersicht

Das System synchronisiert Termine zwischen:
- **Advoware**: Zentrale Terminverwaltung mit detaillierten Informationen
- **Google Calendar**: Benutzerfreundliche Kalenderansicht für jeden Mitarbeiter

## Funktionalität

### Automatische Kalender-Erstellung
- Für jeden Advoware-Mitarbeiter wird ein Google Calendar mit dem Namen `AW-{Kuerzel}` erstellt
- Beispiel: Mitarbeiter mit Kürzel "SB" → Calendar "AW-SB"

### Bidirektionale Synchronisation

#### Advoware → Google Calendar
- Alle Termine eines Mitarbeiters werden aus Advoware abgerufen
- Neue Termine werden in den entsprechenden Google Calendar eingetragen
- Die Advoware-Termin-ID (`frNr`) wird als Metadaten gespeichert

#### Google Calendar → Advoware
- Termine aus Google Calendar ohne `frNr` werden als neue Termine in Advoware erstellt
- Die generierte `frNr` wird zurück in den Google Calendar geschrieben

### Konfigurationsoptionen
- **Vollständige Termindetails**: Titel, Beschreibung, Ort werden synchronisiert
- **Nur "Blocked"**: Termine werden nur als "beschäftigt" markiert (keine Details)

## API-Endpunkte

### Advoware
- `GET /api/v1/advonet/Mitarbeiter` - Liste aller Mitarbeiter
- `GET /api/v1/advonet/Termine?kuerzel={kuerzel}&from={date}&to={date}` - Termine eines Mitarbeiters

### Google Calendar API
- Kalender-Management (erstellen, auflisten)
- Event-Management (erstellen, aktualisieren, löschen)

## Step-Konfiguration

### advoware_calendar_sync_step.py
- **Type:** api
- **Path:** `/advoware/calendar/sync`
- **Method:** POST
- **Flows:** advoware

**Request Body:**
```json
{
  "full_content": true  // oder false für nur "blocked"
}
```

## Setup

### Google API Credentials
1. Google Cloud Console Projekt erstellen
2. Google Calendar API aktivieren
3. OAuth 2.0 Credentials erstellen
4. `token.pickle` Datei im Projektverzeichnis bereitstellen

### Umgebungsvariablen
```env
GOOGLE_CALENDAR_CREDENTIALS_PATH=token.pickle
```

## Verwendung

### Manueller Sync
```bash
curl -X POST "http://localhost:3000/advoware/calendar/sync" \
  -H "Content-Type: application/json" \
  -d '{"full_content": true}'
```

### Automatischer Sync
Der Step kann über Cron-Jobs oder Events regelmäßig ausgeführt werden.

## Datenmapping

### Advoware → Google Calendar
```javascript
{
  "summary": appointment.text || "Advoware Termin",
  "description": `Advoware Termin\nNotiz: ${appointment.notiz}\nOrt: ${appointment.ort}`,
  "location": appointment.ort,
  "start": {
    "dateTime": `${appointment.datum}T${appointment.uhrzeitBis || '00:00:00'}`,
    "timeZone": "Europe/Berlin"
  },
  "end": {
    "dateTime": `${appointment.datumBis || appointment.datum}T${appointment.uhrzeitBis || '23:59:59'}`,
    "timeZone": "Europe/Berlin"
  },
  "extendedProperties": {
    "private": {
      "advoware_frnr": appointment.frNr
    }
  }
}
```

### Google Calendar → Advoware
```javascript
{
  "text": event.summary,
  "notiz": event.description,
  "ort": event.location,
  "datum": event.start.dateTime.substring(0, 10),
  "uhrzeitBis": event.start.dateTime.substring(11, 19),
  "datumBis": event.end.dateTime.substring(0, 10),
  "sb": employee_kuerzel,
  "anwalt": employee_kuerzel
}
```

## Fehlerbehandlung

- **Google API Fehler:** Automatische Token-Refresh, Fallback bei Authentifizierungsfehlern
- **Advoware API Fehler:** Retry-Logic, detaillierte Logging
- **Netzwerkfehler:** Timeout-Handling, Wiederholungsversuche
- **Dateninkonsistenzen:** Validierung vor Sync, Konfliktlösung

## Monitoring

### Logs
- Erfolgreiche Synchronisationen
- Fehlerhafte Termine
- Kalender-Erstellungen
- Performance-Metriken

### Metriken
- Anzahl synchronisierter Termine
- Verarbeitete Mitarbeiter
- Fehlerquoten
- Sync-Dauer

## Sicherheit

- OAuth 2.0 für Google API Zugriff
- Token-Speicherung in verschlüsselten Dateien
- Scoped API Permissions (nur Calendar-Zugriff)
- Audit-Logs für alle Änderungen

## Erweiterungen

### Geplante Features
- Inkrementelle Syncs (nur geänderte Termine)
- Konfliktlösungsstrategien (Advoware gewinnt, Google gewinnt, Manuell)
- Batch-Verarbeitung für Performance
- Webhook-Integration für Echtzeit-Syncs
- Mehrere Google-Accounts unterstützen

### Integration mit anderen Systemen
- Outlook Calendar
- Apple Calendar
- Mobile Apps
- Notification-Systeme