motia/bitbylaw/scripts/calendar_sync/README.md

Calendar Sync Utility Scripts

---

title: Calendar Sync Utilities description: Helper-Scripts für Google Calendar Synchronisation - Wartung, Debugging und Cleanup date: 2026-02-07 category: utilities

Übersicht

Dieses Verzeichnis enthält Utility-Scripts für Wartung und Debugging der Calendar-Sync-Funktionalität.

---

Scripts

delete_all_calendars.py

Zweck: Löscht alle (nicht-primären) Kalender aus dem Google Calendar Service Account.

Use Case:

• Reset bei fehlerhafter Synchronisation
• Cleanup nach Tests
• Bereinigung von Duplikaten

Ausführung:

cd /opt/motia-app/bitbylaw
python3 scripts/calendar_sync/delete_all_calendars.py

Funktionsweise:

1. Authentifizierung mit Google Service Account
2. Abruf aller Kalender via calendarList().list()
3. Iteration durch alle Kalender
4. Überspringen des Primary Calendar (Schutz)
5. Löschen aller anderen Kalender via calendars().delete()

Sicherheit:

• ⚠️ WARNUNG: Löscht unwiderruflich alle Kalender!
• Primary Calendar wird automatisch übersprungen
• Manuelle Bestätigung erforderlich (TODO: Confirmation Prompt)

Abhängigkeiten:

• steps.advoware_cal_sync.calendar_sync_event_step.get_google_service
• Google Calendar API Access
• Service Account Credentials

Output-Beispiel:

Fetching calendar list...
Found 15 calendars to delete:
  - Max Mustermann (ID: max@example.com, Primary: False)
    ✓ Deleted calendar: Max Mustermann
  - Primary (ID: service@project.iam.gserviceaccount.com, Primary: True)
    Skipping primary calendar: Primary
  ...
All non-primary calendars have been deleted.

---

delete_employee_locks.py

Zweck: Löscht alle Employee-Locks aus Redis für Calendar Sync.

Use Case:

• Cleanup nach abgestürztem Sync-Prozess
• Manueller Reset bei "hanging" Locks
• Debugging von Lock-Problemen

Ausführung:

cd /opt/motia-app/bitbylaw
python3 scripts/calendar_sync/delete_employee_locks.py

Funktionsweise:

1. Verbindung zu Redis DB 2 (REDIS_DB_CALENDAR_SYNC)
2. Suche nach allen Keys mit Pattern calendar_sync_lock_*
3. Löschen aller gefundenen Lock-Keys

Redis Key Pattern:

calendar_sync_lock_{employee_id}

Sicherheit:

• ⚠️ Kann zu Race Conditions führen, wenn Sync läuft
• Empfehlung: Nur ausführen, wenn kein Sync-Prozess aktiv ist

Abhängigkeiten:

• config.Config (Redis-Konfiguration)
• Redis DB 2 (Calendar Sync State)

Output-Beispiel:

Deleted 12 employee lock keys.

Oder bei leerer DB:

No employee lock keys found.

---

Workflow: Kompletter Reset

Bei schwerwiegenden Sync-Problemen:

cd /opt/motia-app/bitbylaw

# 1. Stoppe Motia Service (verhindert neue Syncs)
sudo systemctl stop motia

# 2. Lösche alle Redis Locks
python3 scripts/calendar_sync/delete_employee_locks.py

# 3. Lösche alle Google Kalender (optional, nur bei Bedarf!)
python3 scripts/calendar_sync/delete_all_calendars.py

# 4. Starte Motia Service neu
sudo systemctl start motia

# 5. Triggere Full-Sync
curl -X POST http://localhost:3000/api/calendar/sync/all

---

Best Practices

Vor Ausführung

1. Backup prüfen: Sicherstellen, dass Advoware-Daten konsistent sind
2. Service Status: systemctl status motia prüfen
3. Redis Dump: redis-cli -n 2 BGSAVE (optional)

Nach Ausführung

1. Logs prüfen: journalctl -u motia -n 100 --no-pager
2. Sync triggern: Via API oder Cron
3. Verifizierung: Google Calendar auf korrekte Kalender prüfen

---

Zukünftige Scripts (TODO)

audit_calendar_sync.py

Zweck: Vergleicht Advoware-Termine mit Google Calendar

Features:

• Diff-Anzeige zwischen Advoware und Google
• Erkennung von Orphaned Calendars
• Report-Generierung

repair_calendar_sync.py

Zweck: Automatische Reparatur bei Inkonsistenzen

Features:

• Auto-Sync bei fehlenden Terminen
• Löschen von Duplikaten
• Lock-Cleanup mit Safety-Checks

---

Siehe auch

• Calendar Sync Architecture
• Calendar Sync Cron Step
• Troubleshooting Guide