From a157d3fa1d97bc54cec85c3016ef422f255a4c60 Mon Sep 17 00:00:00 2001
From: bitbylaw <info@bitbylaw.com>
Date: Sun, 8 Feb 2026 23:03:44 +0000
Subject: [PATCH] feat(docs): Update documentation for Kommunikation Sync and
 VMH Sync steps, marking legacy files and enhancing clarity

---
 .../services/KOMMUNIKATION_SYNC_README.md     | 21 ++++++++++--
 bitbylaw/steps/vmh/README.md                  | 34 ++++++++++---------
 bitbylaw/steps/vmh/README_SYNC.md             |  4 +++
 .../steps/vmh/beteiligte_sync_event_step.md   | 15 ++++----
 4 files changed, 50 insertions(+), 24 deletions(-)

diff --git a/bitbylaw/services/KOMMUNIKATION_SYNC_README.md b/bitbylaw/services/KOMMUNIKATION_SYNC_README.md
index 58bacead..22fb0240 100644
--- a/bitbylaw/services/KOMMUNIKATION_SYNC_README.md
+++ b/bitbylaw/services/KOMMUNIKATION_SYNC_README.md
@@ -1,8 +1,25 @@
 # Kommunikation Sync Implementation
 
-## Overview
+> **⚠️ Diese Datei ist veraltet und wird nicht mehr gepflegt.**  
+> **Aktuelle Dokumentation**: [../docs/SYNC_OVERVIEW.md](../docs/SYNC_OVERVIEW.md)
 
-Bidirektionale Synchronisation von Email- und Telefon-Daten zwischen Advoware und EspoCRM.
+## Quick Reference
+
+Für die vollständige und aktuelle Dokumentation siehe [SYNC_OVERVIEW.md](../docs/SYNC_OVERVIEW.md#kommunikation-sync).
+
+**Implementiert in**: `services/kommunikation_sync_utils.py`
+
+### Kern-Features
+
+1. **Base64-Marker** in Advoware `bemerkung`: `[ESPOCRM:base64_value:kommKz]`
+2. **Hash-basierte Change Detection**: MD5 von allen Kommunikation-rowIds
+3. **6 Sync-Varianten**: Var1-6 für alle Szenarien (neu, gelöscht, geändert)
+4. **Empty Slots**: Workaround für DELETE 403
+5. **Konflikt-Handling**: EspoCRM wins, direction='to_advoware'
+
+---
+
+# Legacy Documentation (Reference Only)
 
 ## Architektur-Übersicht
 
diff --git a/bitbylaw/steps/vmh/README.md b/bitbylaw/steps/vmh/README.md
index 9344d25d..95b47b43 100644
--- a/bitbylaw/steps/vmh/README.md
+++ b/bitbylaw/steps/vmh/README.md
@@ -1,5 +1,7 @@
 # VMH Webhook & Sync Steps
 
+> **📚 Vollständige Sync-Dokumentation**: [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)
+
 Dieser Ordner enthält die Webhook-Receiver für EspoCRM und den Event-basierten Synchronisations-Handler für Beteiligte-Entitäten.
 
 ## Übersicht
@@ -8,7 +10,7 @@ Die VMH-Steps implementieren eine vollständige Webhook-Pipeline:
 1. **Webhook Receiver** empfangen Events von EspoCRM
 2. **Redis Deduplication** verhindert Mehrfachverarbeitung
 3. **Event Emission** triggert die Synchronisation
-4. **Sync Handler** verarbeitet die Änderungen (aktuell Placeholder)
+4. **Sync Handler** verarbeitet die Änderungen (✅ **Production Ready**)
 
 ## Webhook Receiver Steps
 
@@ -91,28 +93,28 @@ Die VMH-Steps implementieren eine vollständige Webhook-Pipeline:
 
 **Zweck:** Zentraler Event-Handler für die Synchronisation von Beteiligte-Änderungen.
 
+**Status:** ✅ **Production Ready** - Vollständig implementiert
+
 **Konfiguration:**
 - **Type:** event
 - **Name:** VMH Beteiligte Sync
-- **Subscribes:** `vmh.beteiligte.create`, `vmh.beteiligte.update`, `vmh.beteiligte.delete`
+- **Subscribes:** 
+  - `vmh.beteiligte.create` - Neue Entities
+  - `vmh.beteiligte.update` - Änderungen
+  - `vmh.beteiligte.delete` - Löschungen
+  - `vmh.beteiligte.sync_check` - Cron-Checks (alle 15min)
 - **Flows:** vmh
-- **Emits:** (none)
 
 **Funktionalität:**
-- Empfängt Events von allen Webhook-Receivern
-- Aktuell Placeholder-Implementierung (nur Logging)
-- Entfernt verarbeitete IDs aus Redis-Pending-Queues
-- Bereit für Integration mit EspoCRM-API
+- ✅ Empfängt Events von allen Webhook-Receivern + Cron
+- ✅ Redis Distributed Lock (verhindert Race Conditions)
+- ✅ Beteiligte Sync (Stammdaten): rowId-basierte Change Detection
+- ✅ Kommunikation Sync (Phone/Email/Fax): Hash-basierte Change Detection
+- ✅ Konflikt-Handling: EspoCRM wins mit Notification
+- ✅ Retry-Logic: Exponential Backoff (1min, 5min, 15min, 1h, 4h)
+- ✅ Auto-Reset nach 24h bei permanently_failed
 
-**Event Data Format:**
-```json
-{
-  "entity_id": "entity-123",
-  "action": "create",
-  "source": "webhook",
-  "timestamp": "2025-01-20T10:00:00Z"
-}
-```
+**Dokumentation:** Siehe [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)
 
 ## Redis Deduplication
 
diff --git a/bitbylaw/steps/vmh/README_SYNC.md b/bitbylaw/steps/vmh/README_SYNC.md
index 6b42bfb4..1d3f862a 100644
--- a/bitbylaw/steps/vmh/README_SYNC.md
+++ b/bitbylaw/steps/vmh/README_SYNC.md
@@ -1,7 +1,11 @@
 # Beteiligte Sync - Event Handler
 
+> **📚 Vollständige Dokumentation**: [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)
+
 Event-driven sync handler für bidirektionale Synchronisation von Beteiligten (Stammdaten).
 
+**Implementiert in**: `steps/vmh/beteiligte_sync_event_step.py`
+
 ## Subscribes
 
 - `vmh.beteiligte.create` - Neuer Beteiligter in EspoCRM
diff --git a/bitbylaw/steps/vmh/beteiligte_sync_event_step.md b/bitbylaw/steps/vmh/beteiligte_sync_event_step.md
index caaae736..bad4ed6d 100644
--- a/bitbylaw/steps/vmh/beteiligte_sync_event_step.md
+++ b/bitbylaw/steps/vmh/beteiligte_sync_event_step.md
@@ -2,18 +2,21 @@
 type: step
 category: event
 name: VMH Beteiligte Sync
-version: 1.0.0
-status: placeholder
-tags: [sync, vmh, beteiligte, event, todo]
-dependencies: []
+version: 2.0.0
+status: active
+tags: [sync, vmh, beteiligte, event, production]
+dependencies: [redis, espocrm, advoware]
 emits: []
-subscribes: [vmh.beteiligte.create, vmh.beteiligte.update, vmh.beteiligte.delete]
+subscribes: [vmh.beteiligte.create, vmh.beteiligte.update, vmh.beteiligte.delete, vmh.beteiligte.sync_check]
 ---
 
 # VMH Beteiligte Sync Event Step
 
+> **⚠️ Diese Datei ist veraltet.**  
+> **Aktuelle Dokumentation**: [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)
+
 ## Status
-⚠️ **PLACEHOLDER** - Implementierung noch ausstehend
+✅ **PRODUCTION** - Vollständig implementiert und in Betrieb
 
 ## Zweck
 Verarbeitet Create/Update/Delete-Events für Beteiligte-Entitäten und synchronisiert zwischen EspoCRM und Zielsystem.