Neuer Advoware Calendar Sync implementiert

- steps/advoware_cal_sync/advoware_calendar_sync_step.py: Bidirektionale Sync zwischen Advoware und Google Calendar
- Automatische Kalender-Erstellung für jeden Mitarbeiter (AW-{Kuerzel})
- Konfigurierbare Sync-Optionen (volle Details vs. nur 'blocked')
- Google Calendar API Integration mit OAuth
- Mitarbeiter- und Termin-API Integration
- Umfassende Fehlerbehandlung und Logging
- steps/advoware_cal_sync/README.md: Detaillierte Dokumentation
- requirements.txt: Google API Dependencies hinzugefügt
- motia-workbench.json: Neuer advoware_cal_sync Flow

bitbylaw/steps/advoware_cal_sync/README.md

@@ -0,0 +1,161 @@
+# 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