feat(sync): Implement auto-reset for permanently_failed entities and add retry backoff logic

- Added logic to reset permanently_failed entities that have reached their auto-reset threshold in `beteiligte_sync_cron_step.py`.
- Enhanced event handling in `beteiligte_sync_event_step.py` to skip retries if the next retry time has not been reached.
- Introduced validation checks after sync operations to ensure data consistency and integrity.
- Created detailed documentation outlining the fixes and their impacts on the sync process.
- Added scripts for analyzing sync issues and comparing entities to facilitate debugging and validation.

bitbylaw/steps/vmh/beteiligte_sync_cron_step.py

@@ -55,6 +55,38 @@ async def handler(context):
         
         context.logger.info(f"📊 Gefunden: {len(unclean_entities)} Entities mit Status pending/dirty/failed")
         
+        # FIX #12: QUERY 1b: permanently_failed Entities die Auto-Reset erreicht haben
+        permanently_failed_filter = {
+            'where': [
+                {
+                    'type': 'and',
+                    'value': [
+                        {'type': 'equals', 'attribute': 'syncStatus', 'value': 'permanently_failed'},
+                        {'type': 'isNotNull', 'attribute': 'syncAutoResetAt'},
+                        {'type': 'before', 'attribute': 'syncAutoResetAt', 'value': threshold_str}
+                    ]
+                }
+            ]
+        }
+        
+        reset_result = await espocrm.search_entities('CBeteiligte', permanently_failed_filter, max_size=50)
+        reset_entities = reset_result.get('list', [])
+        
+        # Reset permanently_failed entities
+        for entity in reset_entities:
+            entity_id = entity['id']
+            context.logger.info(f"🔄 Auto-Reset für permanently_failed Entity {entity_id}")
+            
+            # Reset Status und Retry-Count
+            await espocrm.update_entity('CBeteiligte', entity_id, {
+                'syncStatus': 'failed',  # Zurück zu 'failed' für normalen Retry
+                'syncRetryCount': 0,
+                'syncAutoResetAt': None,
+                'syncErrorMessage': f"Auto-Reset nach 24h - vorheriger Fehler: {entity.get('syncErrorMessage', 'N/A')}"
+            })
+        
+        context.logger.info(f"📊 Auto-Reset: {len(reset_entities)} permanently_failed Entities")
+        
         # QUERY 2: Clean Entities die > 24h nicht gesynct wurden
         stale_filter = {
             'where': [
@@ -80,8 +112,8 @@ async def handler(context):
         
         context.logger.info(f"📊 Gefunden: {len(stale_entities)} Entities mit veraltetem Sync (> 24h)")
         
-        # KOMBINIERE ALLE
-        all_entities = unclean_entities + stale_entities
+        # KOMBINIERE ALLE (inkl. reset_entities)
+        all_entities = unclean_entities + stale_entities + reset_entities
         entity_ids = list(set([e['id'] for e in all_entities]))  # Dedupliziere
         
         context.logger.info(f"🎯 Total: {len(entity_ids)} eindeutige Entities zum Sync")