From 709456301c4fbe3e664e0c6c68109fc3addd098d Mon Sep 17 00:00:00 2001
From: bitbylaw <info@bitbylaw.com>
Date: Sat, 7 Feb 2026 22:38:53 +0000
Subject: [PATCH] feat: Optimize initial sync logic and remove redundant rowId
 updates in sync process

---
 bitbylaw/docs/BETEILIGTE_SYNC_ANALYSIS.md     | 458 ++++++++++++++++++
 bitbylaw/services/beteiligte_sync_utils.py    |   7 +-
 .../steps/vmh/beteiligte_sync_event_step.py   |  39 +-
 3 files changed, 466 insertions(+), 38 deletions(-)
 create mode 100644 bitbylaw/docs/BETEILIGTE_SYNC_ANALYSIS.md

diff --git a/bitbylaw/docs/BETEILIGTE_SYNC_ANALYSIS.md b/bitbylaw/docs/BETEILIGTE_SYNC_ANALYSIS.md
new file mode 100644
index 00000000..6048b922
--- /dev/null
+++ b/bitbylaw/docs/BETEILIGTE_SYNC_ANALYSIS.md
@@ -0,0 +1,458 @@
+# Beteiligte Sync - Architektur-Analyse
+
+**Stand:** 7. Februar 2026  
+**Analysiert:** Bidirektionale EspoCRM ↔ Advoware Beteiligte-Synchronisation
+
+---
+
+## 🏗️ ARCHITEKTUR-ÜBERSICHT
+
+### Komponenten
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        EspoCRM (Master)                          │
+│                     Webhooks → Motia                             │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   WEBHOOK HANDLER (3 Endpoints)                  │
+│  • beteiligte_create_api_step.py                                │
+│  • beteiligte_update_api_step.py  ← Loop-Prevention entfernt    │
+│  • beteiligte_delete_api_step.py                                │
+└────────────────────────────┬────────────────────────────────────┘
+                             │ emits events
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              CENTRAL SYNC HANDLER (Event-Based)                  │
+│            beteiligte_sync_event_step.py (~329 lines)            │
+│                                                                   │
+│  Subscribes: vmh.beteiligte.{create,update,delete,sync_check}   │
+│                                                                   │
+│  Flow:                                                            │
+│  1. Distributed Lock (Redis + syncStatus)                        │
+│  2. Fetch EspoCRM Entity                                         │
+│  3. Route: CREATE, UPDATE/CHECK, DELETE                          │
+│  4. Release Lock + Update Status                                 │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                   ┌─────────┴─────────┐
+                   ▼                   ▼
+        ┌──────────────────┐  ┌──────────────────┐
+        │  handle_create   │  │  handle_update   │
+        │                  │  │                  │
+        │  • Map to Advo   │  │  • Fetch Advo    │
+        │  • POST          │  │  • Compare       │
+        │  • GET rowId     │  │  • Sync/Skip     │
+        │  • Write back    │  │  • Update rowId  │
+        └──────────────────┘  └──────────────────┘
+                   │                   │
+                   └─────────┬─────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      SUPPORT SERVICES                            │
+│                                                                   │
+│  • BeteiligteSync (sync_utils)       (~524 lines)               │
+│    - Locking, Compare, Merge, Conflict Resolution               │
+│                                                                   │
+│  • BeteiligteMapper                  (~200 lines)               │
+│    - EspoCRM ↔ Advoware transformations                         │
+│    - None-value filtering                                        │
+│    - Date format conversion                                      │
+│                                                                   │
+│  • AdvowareAPI / EspoCRMAPI                                      │
+│    - HTTP clients mit Token-Caching                              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✅ STÄRKEN (Was funktioniert gut)
+
+### 1. **Robustheit durch Distributed Locking**
+```python
+# 2-stufiges Locking verhindert Race Conditions:
+# 1. Redis Lock (atomic, TTL 15min)
+# 2. syncStatus Update (UI visibility)
+lock_key = f"sync_lock:cbeteiligte:{entity_id}"
+acquired = self.redis.set(lock_key, "locked", nx=True, ex=LOCK_TTL_SECONDS)
+```
+✅ **Gut:** Verhindert parallele Syncs derselben Entity  
+✅ **Gut:** TTL verhindert Deadlocks bei Crashes  
+✅ **Gut:** UI-Sichtbarkeit via syncStatus
+
+### 2. **Primäre Change Detection: rowId**
+```python
+# rowId ändert sich bei JEDEM Advoware PUT → sehr zuverlässig
+if espo_rowid and advo_rowid:
+    advo_changed = (espo_rowid != advo_rowid)
+    espo_changed = (espo_modified > last_sync)
+```
+✅ **Sehr gut:** rowId ist Base64, ändert sich immer, keine NULLs  
+✅ **Gut:** Timestamp als Fallback vorhanden  
+✅ **Gut:** Konfliktlogik (beide geändert) implementiert
+
+### 3. **API-Call-Optimierung (50% Reduktion)**
+```python
+# VORHER: PUT + GET (2 Calls)
+# NACHHER: PUT Response enthält neue rowId (1 Call)
+put_result = await advoware.api_call(...)
+new_rowid = put_result[0].get('rowId')  # direkt aus Response!
+```
+✅ **Exzellent:** Keine extra GETs nach PUT nötig  
+✅ **Gut:** Funktioniert für CREATE, UPDATE, Conflict Resolution
+
+### 4. **Loop-Prevention auf EspoCRM-Seite**
+```python
+# ENTFERNT: should_skip_update() Filterung
+# NEU: EspoCRM triggert keine Webhooks für rowId-Updates
+```
+✅ **Gut:** Vereinfacht Code erheblich  
+✅ **Gut:** Keine komplexe Filterlogik mehr nötig  
+✅ **Gut:** Vertraut auf EspoCRM-Konfiguration
+
+### 5. **Mapper mit Validierung**
+```python
+# None-Filtering verhindert EspoCRM Validation Errors
+espo_data = {k: v for k, v in espo_data.items() if v is not None}
+
+# Datumsformat-Konversion
+dateOfBirth = geburtsdatum.split('T')[0]  # '2001-01-05T00:00:00' → '2001-01-05'
+```
+✅ **Gut:** Robuste Fehlerbehandlung  
+✅ **Gut:** Dokumentiert welche Felder funktionieren (nur 8 von 14)
+
+### 6. **Error Handling mit Retry-Logik**
+```python
+MAX_SYNC_RETRIES = 5
+if new_retry >= MAX_SYNC_RETRIES:
+    update_data['syncStatus'] = 'permanently_failed'
+    await self.send_notification(...)
+```
+✅ **Gut:** Verhindert Endlos-Retries  
+✅ **Gut:** Notification an User bei dauerhaftem Fehler
+
+---
+
+## 🔴 SCHWÄCHEN & VERBESSERUNGSPOTENZIALE
+
+### 1. **CREATE-Flow ineffizient (Extra GET nach POST)**
+
+**Problem:**
+```python
+# Nach POST: Extra GET nur für rowId
+result = await advoware.api_call(..., method='POST', data=advo_data)
+new_betnr = result.get('betNr')
+
+# Extra GET!
+created_entity = await advoware.api_call(f'.../{new_betnr}', method='GET')
+new_rowid = created_entity.get('rowId')
+```
+
+**Lösung:**
+```python
+# POST Response sollte rowId bereits enthalten (prüfen!)
+# Falls ja: Extrahiere direkt wie bei PUT
+if isinstance(result, dict):
+    new_rowid = result.get('rowId')
+elif isinstance(result, list):
+    new_rowid = result[0].get('rowId')
+```
+⚠️ **TODO:** Teste ob Advoware POST auch rowId zurückgibt (wie PUT)
+
+---
+
+### 2. **Doppeltes rowId-Update nach EspoCRM→Advoware**
+
+**Problem:**
+```python
+# 1. Update via release_sync_lock extra_fields
+await sync_utils.release_sync_lock(entity_id, 'clean', 
+    extra_fields={'advowareRowId': new_rowid})
+
+# 2. Aber VORHER bereits direktes Update!
+if new_rowid:
+    await espocrm.update_entity('CBeteiligte', entity_id, {
+        'advowareRowId': new_rowid
+    })
+```
+
+**Lösung:** Entweder/oder - nicht beides!
+```python
+# OPTION A: Nur release_lock (weniger Code, eleganter)
+await sync_utils.release_sync_lock(
+    entity_id, 'clean',
+    extra_fields={'advowareRowId': new_rowid}
+)
+
+# OPTION B: Direktes Update + release ohne extra_fields
+await espocrm.update_entity('CBeteiligte', entity_id, {
+    'advowareRowId': new_rowid,
+    'syncStatus': 'clean',
+    'advowareLastSync': now()
+})
+await self.redis.delete(lock_key)
+```
+⚠️ **Recommendation:** Option A ist eleganter (1 API Call statt 2)
+
+---
+
+### 3. **Initial Sync Special Case nicht nötig?**
+
+**Problem:**
+```python
+# Separate Logik für "kein lastSync"
+if not espo_entity.get('advowareLastSync'):
+    context.logger.info(f"📤 Initial Sync → ...")
+    # ... exakt derselbe Code wie bei espocrm_newer!
+```
+
+**Lösung:** compare_entities sollte das automatisch erkennen
+```python
+# In compare_entities:
+if not last_sync:
+    # Kein lastSync → EspoCRM neuer (always sync on first run)
+    return 'espocrm_newer'
+```
+✅ **Eliminiert:** ~30 Zeilen Duplikat-Code in event_step.py
+
+---
+
+### 4. **Conflict Resolution immer EspoCRM Wins**
+
+**Problem:**
+```python
+# Hardcoded: EspoCRM gewinnt immer
+elif comparison == 'conflict':
+    context.logger.warn(f"⚠️  KONFLIKT erkannt → EspoCRM WINS")
+    # ... force update zu Advoware
+```
+
+**Überlegungen:**
+- Für **STAMMDATEN** ist das sinnvoll (EspoCRM ist Master)
+- Für **Kontaktdaten** könnte Advoware Master sein
+- Für **Adresse** sollte vielleicht Merge stattfinden
+
+✅ **Status:** OK für aktuelle Scope (nur Stammdaten)  
+📝 **Später:** Konfigurierbare Conflict Strategy pro Feld-Gruppe
+
+---
+
+### 5. **Timestamp-Fallback verwendet geaendertAm (deprecated?)**
+
+**Code:**
+```python
+return self.compare_timestamps(
+    espo_entity.get('modifiedAt'),
+    advo_entity.get('geaendertAm'),  # ← Swagger deprecated?
+    espo_entity.get('advowareLastSync')
+)
+```
+
+⚠️ **TODO:** Prüfe ob `geaendertAm` zuverlässig ist oder ob Advoware ein anderes Feld hat
+
+---
+
+### 6. **Keine Batch-Verarbeitung für Webhooks**
+
+**Problem:**
+```python
+# Webhook-Handler: Emittiert Event pro Entity
+for entity_id in entity_ids:
+    await context.emit({...})  # N Events
+```
+
+**Resultat:** Bei 100 Updates → 100 separate Event-Handler-Invocations
+
+**Lösung (Optional):**
+```python
+# Batch-Event mit allen IDs
+await context.emit({
+    'topic': 'vmh.beteiligte.update_batch',
+    'data': {
+        'entity_ids': list(entity_ids),  # Alle auf einmal
+        'source': 'webhook'
+    }
+})
+
+# Handler verarbeitet in Parallel (mit Limit)
+async def handler_batch(event_data, context):
+    entity_ids = event_data['entity_ids']
+    
+    # Process max 10 parallel
+    semaphore = asyncio.Semaphore(10)
+    tasks = [sync_with_semaphore(id, semaphore) for id in entity_ids]
+    await asyncio.gather(*tasks)
+```
+📝 **Entscheidung:** Aktuell OK (Lock verhindert Probleme), aber bei >50 gleichzeitigen Updates könnte Batch helfen
+
+---
+
+### 7. **Fehlende Metriken/Monitoring**
+
+**Was fehlt:**
+- Durchschnittliche Sync-Dauer pro Entity
+- Anzahl Konflikte pro Tag
+- API-Call-Count (EspoCRM vs Advoware)
+- Failed Sync Ratio
+
+**Lösung:**
+```python
+# In sync_utils oder neues monitoring_utils.py
+class SyncMetrics:
+    async def record_sync(self, entity_id, duration, result, comparison):
+        await redis.hincrby('metrics:sync:daily', 'total', 1)
+        await redis.hincrby('metrics:sync:daily', f'result_{result}', 1)
+        await redis.lpush('metrics:sync:durations', duration)
+```
+
+---
+
+## 🎯 VERBESSERUNGS-EMPFEHLUNGEN
+
+### Priorität 1: SOFORT (Effizienz)
+
+1. **✅ Eliminiere doppeltes rowId-Update**
+   ```python
+   # NUR in release_sync_lock, nicht vorher extra Update
+   ```
+   Impact: -1 API Call pro EspoCRM→Advoware Update (ca. 50% weniger EspoCRM calls)
+
+2. **✅ Teste POST Response für rowId**
+   ```python
+   # Falls POST auch rowId enthält: Extra GET entfernen
+   ```
+   Impact: -1 API Call pro CREATE (50% weniger bei Neuanlagen)
+
+### Priorität 2: MITTELFRISTIG (Eleganz)
+
+3. **📝 Merge Initial Sync in compare_entities**
+   ```python
+   # Eliminiert Special Case, -30 Zeilen
+   ```
+   Impact: Cleaner Code, leichter wartbar
+
+4. **📝 Prüfe geaendertAm Timestamp**
+   ```python
+   # Stelle sicher dass Fallback funktioniert
+   ```
+   Impact: Robustheit falls rowId mal fehlt
+
+### Priorität 3: OPTIONAL (Features)
+
+5. **💡 Batch-Processing für Webhooks**
+   - Bei >50 gleichzeitigen Updates könnte Performance leiden
+   - Aktuell nicht kritisch (Lock verhindert Probleme)
+
+6. **💡 Metriken/Dashboard**
+   - Sync-Statistiken für Monitoring
+   - Nicht kritisch aber nützlich für Ops
+
+---
+
+## 📊 PERFORMANCE-SCHÄTZUNG
+
+### Aktueller Stand (pro Entity)
+
+**CREATE:**
+- 1× EspoCRM GET (Entity laden)
+- 1× Advoware POST
+- 1× Advoware GET (rowId holen) ← **OPTIMIERBAR**
+- 1× EspoCRM PUT (betNr + rowId schreiben) ← **OPTIMIERBAR** 
+- 1× EspoCRM PUT (syncStatus + lastSync) ← Teil von Lock-Release
+
+**Total: 5 API Calls** → Mit Optimierung: **3 API Calls (-40%)**
+
+**UPDATE (EspoCRM→Advoware):**
+- 1× EspoCRM GET (Entity laden)
+- 1× Advoware GET (Vergleich)
+- 1× Advoware PUT
+- 1× EspoCRM PUT (rowId update) ← **DOPPELT**
+- 1× EspoCRM PUT (Lock-Release mit rowId) ← **DOPPELT**
+
+**Total: 5 API Calls** → Mit Optimierung: **4 API Calls (-20%)**
+
+**UPDATE (Advoware→EspoCRM):**
+- 1× EspoCRM GET
+- 1× Advoware GET
+- 1× EspoCRM PUT (Daten)
+- 1× EspoCRM PUT (Lock-Release)
+
+**Total: 4 API Calls** → Bereits optimal
+
+---
+
+## 🎨 ARCHITEKTUR-BEWERTUNG
+
+### ✅ Was ist ROBUST?
+
+1. **Distributed Locking** - Verhindert Race Conditions
+2. **rowId Change Detection** - Sehr zuverlässig
+3. **Retry Logic** - Graceful Degradation
+4. **Error Handling** - Try-catch auf allen Ebenen
+5. **TTL auf Locks** - Keine Deadlocks
+
+### ✅ Was ist EFFIZIENT?
+
+1. **PUT Response Parsing** - Spart GET nach Updates
+2. **None-Filtering** - Verhindert unnötige Validierungsfehler  
+3. **Early Returns** - "no_change" skipped sofort
+4. **Redis Token Caching** - Nicht bei jedem Call neu authentifizieren
+
+### ✅ Was ist ELEGANT?
+
+1. **Event-Driven Architecture** - Entkoppelt Webhook von Sync-Logik
+2. **Mapper Pattern** - Transformationen zentral
+3. **Utility Class** - Wiederverwendbare Funktionen
+4. **Descriptive Logging** - Mit Emojis, sehr lesbar
+
+### ⚠️ Was könnte ELEGANTER sein?
+
+1. **Doppelte rowId-Updates** - Redundant
+2. **Initial Sync Special Case** - Unnötige Duplikation
+3. **Keine Config für Conflict Strategy** - Hardcoded
+4. **Fehlende Metriken** - Monitoring schwierig
+
+---
+
+## 🏆 GESAMTBEWERTUNG
+
+| Kategorie | Bewertung | Note |
+|-----------|-----------|------|
+| Robustheit | ⭐⭐⭐⭐⭐ | 9/10 - Sehr stabil durch Locking + Retry |
+| Effizienz | ⭐⭐⭐⭐☆ | 7/10 - Gut, aber 2 klare Optimierungen möglich |
+| Eleganz | ⭐⭐⭐⭐☆ | 8/10 - Sauber strukturiert, kleine Code-Duplikate |
+| Wartbarkeit | ⭐⭐⭐⭐⭐ | 9/10 - Gut dokumentiert, klare Struktur |
+| Erweiterbarkeit | ⭐⭐⭐⭐☆ | 8/10 - Event-Driven macht Extensions einfach |
+
+**Gesamt: 8.2/10 - SEHR GUT**
+
+---
+
+## 🚀 EMPFOHLENE NÄCHSTE SCHRITTE
+
+### Sofort (1-2h Aufwand):
+1. ✅ Eliminiere doppeltes rowId-Update (5min)
+2. ✅ Teste Advoware POST Response auf rowId (15min)
+3. ✅ Falls ja: Entferne GET nach CREATE (5min)
+
+### Mittelfristig (2-4h):
+4. 📝 Merge Initial Sync in compare_entities (30min)
+5. 📝 Add Metrics Collection (1-2h)
+
+### Optional:
+6. 💡 Batch-Processing (nur wenn Performance-Problem)
+7. 💡 Configurable Conflict Strategy (bei neuen Requirements)
+
+---
+
+## 📝 FAZIT
+
+**Das System ist produktionsreif und robust.**
+
+- **Stärken:** Exzellentes Locking, zuverlässige Change Detection, gutes Error Handling
+- **Optimierungen:** 2-3 kleine Fixes können 20-40% API Calls sparen
+- **Architektur:** Sauber, wartbar, erweiterbar
+
+**Recommendation:** Ship it mit den 2 Quick-Fixes (doppeltes Update + POST rowId-Check).
diff --git a/bitbylaw/services/beteiligte_sync_utils.py b/bitbylaw/services/beteiligte_sync_utils.py
index 6e5f699c..b8b3578c 100644
--- a/bitbylaw/services/beteiligte_sync_utils.py
+++ b/bitbylaw/services/beteiligte_sync_utils.py
@@ -244,7 +244,12 @@ class BeteiligteSync:
         last_sync = espo_entity.get('advowareLastSync')
         espo_modified = espo_entity.get('modifiedAt')
         
-        if espo_rowid and advo_rowid and last_sync:
+        # SPECIAL CASE: Kein lastSync → Initial Sync (EspoCRM→Advoware)
+        if not last_sync:
+            self._log(f"Initial Sync (kein lastSync) → EspoCRM neuer")
+            return 'espocrm_newer'
+        
+        if espo_rowid and advo_rowid:
             # Prüfe ob Advoware geändert wurde (rowId)
             advo_changed = (espo_rowid != advo_rowid)
             
diff --git a/bitbylaw/steps/vmh/beteiligte_sync_event_step.py b/bitbylaw/steps/vmh/beteiligte_sync_event_step.py
index c45ca4fc..6c857f47 100644
--- a/bitbylaw/steps/vmh/beteiligte_sync_event_step.py
+++ b/bitbylaw/steps/vmh/beteiligte_sync_event_step.py
@@ -204,35 +204,6 @@ async def handle_update(entity_id, betnr, espo_entity, espocrm, advoware, sync_u
         
         context.logger.info(f"⏱️  Vergleich: {comparison}")
         
-        # SPECIAL: Wenn LastSync null → immer von EspoCRM syncen (initial sync)
-        if not espo_entity.get('advowareLastSync'):
-            context.logger.info(f"📤 Initial Sync → EspoCRM STAMMDATEN zu Advoware")
-            
-            # OPTIMIERT: Use merge utility (reduces code duplication)
-            merged_data = sync_utils.merge_for_advoware_put(advo_entity, espo_entity, mapper)
-            
-            put_result = await advoware.api_call(
-                f'api/v1/advonet/Beteiligte/{betnr}',
-                method='PUT',
-                data=merged_data
-            )
-            
-            # Extrahiere neue rowId aus PUT Response (spart extra GET!)
-            new_rowid = None
-            if isinstance(put_result, list) and len(put_result) > 0:
-                new_rowid = put_result[0].get('rowId')
-            elif isinstance(put_result, dict):
-                new_rowid = put_result.get('rowId')
-            
-            # Speichere neue rowId für zukünftige Vergleiche
-            await sync_utils.release_sync_lock(
-                entity_id, 
-                'clean',
-                extra_fields={'advowareRowId': new_rowid}
-            )
-            context.logger.info(f"✅ Advoware aktualisiert (initial sync), neue rowId: {new_rowid[:20] if new_rowid else 'N/A'}...")
-            return
-        
         # KEIN SYNC NÖTIG
         if comparison == 'no_change':
             context.logger.info(f"✅ Keine Änderungen, Sync übersprungen")
@@ -259,19 +230,13 @@ async def handle_update(entity_id, betnr, espo_entity, espocrm, advoware, sync_u
             elif isinstance(put_result, dict):
                 new_rowid = put_result.get('rowId')
             
-            # Schreibe neue rowId zurück nach EspoCRM
-            if new_rowid:
-                await espocrm.update_entity('CBeteiligte', entity_id, {
-                    'advowareRowId': new_rowid
-                })
-                context.logger.info(f"📝 rowId in EspoCRM aktualisiert: {new_rowid[:20]}...")
-            
+            # Release Lock + Update rowId in einem Call (effizienter!)
             await sync_utils.release_sync_lock(
                 entity_id, 
                 'clean',
                 extra_fields={'advowareRowId': new_rowid}
             )
-            context.logger.info(f"✅ Advoware aktualisiert, neue rowId: {new_rowid[:20] if new_rowid else 'N/A'}...")
+            context.logger.info(f"✅ Advoware aktualisiert, rowId in EspoCRM geschrieben: {new_rowid[:20] if new_rowid else 'N/A'}...")
         
         # ADVOWARE NEUER → Update EspoCRM
         elif comparison == 'advoware_newer':