feat: Enhance audit_calendar_sync tool with comprehensive management features
- Add detailed documentation in README.md for all 10 audit commands - Fix Advoware API parameter from 'frNr' to 'frnr' for proper filtering - Fix subject field mapping from 'betreff' to 'text' in API responses - Add verify-sync command for bidirectional sync verification - Add query-frnr and query-event commands for individual record lookup - Add management commands: find-duplicates, delete-duplicates, find-orphaned, cleanup-orphaned - Improve error handling and output formatting - Remove temporary test script
This commit is contained in:
root
@@ -177,13 +177,254 @@ Cron-Step läuft täglich.
|
||||
- Recurring-Events: Begrenzte Unterstützung.
|
||||
- Performance: Bei vielen Terminen Paginierung prüfen.
|
||||
|
||||
## Letzte Änderungen
|
||||
## Audit und Management Tool (`audit_calendar_sync.py`)
|
||||
|
||||
- Refaktorierung zu event-driven Design ohne PostgreSQL Hub.
|
||||
- Fixes für mehrtägige Termine: Korrekte Verwendung von `datumBis`.
|
||||
- Entfernung 24h-Limit; Google Calendar unterstützt lange Events.
|
||||
- Per-Employee Locking mit Redis.
|
||||
- Logging via context.logger für Workbench.
|
||||
- Neue Schritte: calendar_sync_all_step.py, calendar_sync_cron_step.py.
|
||||
- Workbench-Gruppierung: "advoware-calendar-sync".
|
||||
Das `audit_calendar_sync.py` Tool bietet umfassende Audit-, Management- und Debugging-Funktionen für die Calendar-Synchronisation. Es ermöglicht die Überprüfung der Sync-Integrität, das Aufräumen von Duplikaten und verwaisten Einträgen sowie detaillierte Abfragen einzelner Termine.
|
||||
|
||||
### Verwendung
|
||||
|
||||
```bash
|
||||
cd /opt/motia-app/bitbylaw
|
||||
source python_modules/bin/activate
|
||||
python steps/advoware_cal_sync/audit_calendar_sync.py <command> [options]
|
||||
```
|
||||
|
||||
### Befehle
|
||||
|
||||
#### `audit <employee_kuerzel> <google|advoware> [--delete-orphaned-google]`
|
||||
|
||||
Auditiert Sync-Einträge für einen spezifischen Mitarbeiter und prüft deren Existenz in beiden Systemen.
|
||||
|
||||
**Parameter:**
|
||||
- `employee_kuerzel`: Mitarbeiter-Kürzel (z.B. "SB", "UR")
|
||||
- `google|advoware`: System, das auditiert werden soll
|
||||
- `--delete-orphaned-google`: Optional, löscht Google-Events die in Google existieren aber nicht in der DB
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
# Audit Google Calendar für Mitarbeiter SB
|
||||
python audit_calendar_sync.py audit SB google
|
||||
|
||||
# Audit Advoware für Mitarbeiter UR mit Löschung verwaister Google-Events
|
||||
python audit_calendar_sync.py audit UR google --delete-orphaned-google
|
||||
```
|
||||
|
||||
**Ausgabe:**
|
||||
- Anzahl der DB-Einträge
|
||||
- Anzahl der Events im Zielsystem
|
||||
- Anzahl existierender/verwaiste Einträge
|
||||
- Details zu verwaisten Einträgen
|
||||
|
||||
#### `delete-calendar <employee_kuerzel>`
|
||||
|
||||
Löscht den Google Calendar für einen spezifischen Mitarbeiter (falls vorhanden).
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py delete-calendar SB
|
||||
```
|
||||
|
||||
#### `list-all`
|
||||
|
||||
Listet alle Google Calendars auf, einschließlich Name, ID, Primary-Status und Access-Role.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py list-all
|
||||
```
|
||||
|
||||
**Ausgabe:**
|
||||
```
|
||||
=== All Google Calendars (27) ===
|
||||
AW-SB (ID: abc123@group.calendar.google.com, Primary: False, Access: owner)
|
||||
AW-UR (ID: def456@group.calendar.google.com, Primary: False, Access: owner)
|
||||
...
|
||||
```
|
||||
|
||||
#### `find-duplicates`
|
||||
|
||||
Findet duplizierte Google Calendars nach Namen.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py find-duplicates
|
||||
```
|
||||
|
||||
**Ausgabe:**
|
||||
```
|
||||
=== Duplicate Calendars Found (2 unique names with duplicates) ===
|
||||
Total duplicate calendars: 3
|
||||
|
||||
Calendar Name: 'AW-SB' - 2 instances
|
||||
ID: abc123@group.calendar.google.com, Primary: False, Access Role: owner
|
||||
ID: xyz789@group.calendar.google.com, Primary: False, Access Role: owner
|
||||
```
|
||||
|
||||
#### `delete-duplicates`
|
||||
|
||||
Findet und löscht duplizierte Calendars (behält jeweils einen pro Namen).
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py delete-duplicates
|
||||
```
|
||||
|
||||
#### `find-orphaned`
|
||||
|
||||
Findet AW-* Calendars ohne entsprechende Mitarbeiter in der Datenbank.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py find-orphaned
|
||||
```
|
||||
|
||||
#### `cleanup-orphaned`
|
||||
|
||||
Findet und löscht verwaiste AW-* Calendars.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py cleanup-orphaned
|
||||
```
|
||||
|
||||
#### `query-frnr <frnr>`
|
||||
|
||||
Zeigt alle Sync-Informationen für eine spezifische Advoware frNr.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py query-frnr 79291
|
||||
```
|
||||
|
||||
**Ausgabe:**
|
||||
```
|
||||
=== Sync Information for frNr: 79291 ===
|
||||
Found 1 sync entry
|
||||
|
||||
Sync ID: 6ee9ba95-8aff-4868-9171-c10a8789427c
|
||||
Employee: UR
|
||||
Advoware frNr: 79291
|
||||
Google Event ID: jao7r00j26lt1i0chk454bi9as
|
||||
Source System: advoware
|
||||
Sync Strategy: source_system_wins
|
||||
Sync Status: synced
|
||||
Last Sync: 2025-10-24 23:30:17.692668+00:00
|
||||
Created: 2025-10-24 07:22:41.729295+00:00
|
||||
Updated: 2025-10-24 07:22:41.729295+00:00
|
||||
```
|
||||
|
||||
#### `query-event <event_id>`
|
||||
|
||||
Zeigt Sync-Informationen für eine spezifische Google Event ID.
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py query-event jao7r00j26lt1i0chk454bi9as
|
||||
```
|
||||
|
||||
#### `verify-sync <frnr>`
|
||||
|
||||
Vollständige Sync-Verifikation: Prüft einen Termin in beiden Systemen (Advoware und Google Calendar).
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
python audit_calendar_sync.py verify-sync 79291
|
||||
```
|
||||
|
||||
**Ausgabe:**
|
||||
```
|
||||
=== Sync Verification for frNr: 79291 ===
|
||||
Employee: UR
|
||||
Sync Status: synced
|
||||
Last Sync: 2025-10-24 23:30:17.692668+00:00
|
||||
|
||||
--- Checking Advoware ---
|
||||
✅ Found in Advoware:
|
||||
Subject: Jour fixe iS Neomi - Teilnahme im Einzelfall
|
||||
Date: 2024-06-04T17:00:00
|
||||
Time: N/A
|
||||
End Time: 19:00:00
|
||||
End Date: 2026-02-03T00:00:00
|
||||
Last Modified: 2025-09-29T11:55:43.624
|
||||
frNr: 79291
|
||||
|
||||
--- Checking Google Calendar ---
|
||||
✅ Found in Google Calendar:
|
||||
Summary: Advoware (frNr: 79291)
|
||||
Start: 2024-06-04T17:00:00+02:00
|
||||
End: 2024-06-04T19:00:00+02:00
|
||||
|
||||
--- Sync Status Summary ---
|
||||
✅ Synchronized: Exists in both systems
|
||||
```
|
||||
|
||||
### Technische Details
|
||||
|
||||
#### Datenbank-Integration
|
||||
- Verwendet PostgreSQL-Verbindung aus `config.py`
|
||||
- Tabelle: `calendar_sync`
|
||||
- Felder: `sync_id`, `employee_kuerzel`, `advoware_frnr`, `google_event_id`, etc.
|
||||
|
||||
#### API-Integration
|
||||
- **Google Calendar API**: `calendarList().list()` mit Paginierung (maxResults=250)
|
||||
- **Advoware API**: `GET /api/v1/advonet/Termine` mit `frnr` Filter
|
||||
- Automatische Token-Verwaltung und Fehlerbehandlung
|
||||
|
||||
#### Sicherheit
|
||||
- Verwendet bestehende Service-Account und API-Credentials
|
||||
- Keine zusätzlichen Berechtigungen erforderlich
|
||||
|
||||
### Häufige Anwendungsfälle
|
||||
|
||||
#### 1. Nach der Erstinstallation
|
||||
```bash
|
||||
# Alle Calendars auflisten
|
||||
python audit_calendar_sync.py list-all
|
||||
|
||||
# Duplikate finden und entfernen
|
||||
python audit_calendar_sync.py find-duplicates
|
||||
python audit_calendar_sync.py delete-duplicates
|
||||
|
||||
# Verwaiste Calendars entfernen
|
||||
python audit_calendar_sync.py find-orphaned
|
||||
python audit_calendar_sync.py cleanup-orphaned
|
||||
```
|
||||
|
||||
#### 2. Bei Sync-Problemen
|
||||
```bash
|
||||
# Sync-Status für einen Mitarbeiter prüfen
|
||||
python audit_calendar_sync.py audit SB google
|
||||
|
||||
# Einzelnen Termin verifizieren
|
||||
python audit_calendar_sync.py verify-sync 79291
|
||||
|
||||
# Sync-Informationen abfragen
|
||||
python audit_calendar_sync.py query-frnr 79291
|
||||
```
|
||||
|
||||
#### 3. Regelmäßige Wartung
|
||||
```bash
|
||||
# Wöchentliche Überprüfung auf Duplikate
|
||||
python audit_calendar_sync.py find-duplicates
|
||||
|
||||
# Monatliche Bereinigung verwaister Einträge
|
||||
python audit_calendar_sync.py cleanup-orphaned
|
||||
```
|
||||
|
||||
### Fehlerbehandlung
|
||||
|
||||
- **API-Fehler**: Automatische Retry-Logik mit Backoff
|
||||
- **Berechtigungsfehler**: Klare Fehlermeldungen mit Lösungsvorschlägen
|
||||
- **Netzwerkprobleme**: Timeout-Handling und Wiederholungen
|
||||
- **Dateninkonsistenzen**: Detaillierte Logging für Debugging
|
||||
|
||||
### Performance
|
||||
|
||||
- **Paginierung**: Automatische Handhabung großer Resultsets
|
||||
- **Batch-Verarbeitung**: Effiziente API-Calls mit minimalen Requests
|
||||
- **Caching**: Wiederverwendung von API-Verbindungen wo möglich
|
||||
|
||||
### Logging
|
||||
|
||||
Alle Operationen werden über `context.logger` geloggt und sind in der Motia Workbench sichtbar. Zusätzliche Debug-Informationen werden auf der Konsole ausgegeben.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user