refactor(logging): standardize logging approach across services and steps

services/logging_utils.py

@@ -5,6 +5,59 @@ Vereinheitlicht Logging über:
 - Standard Python Logger
 - Motia FlowContext Logger
 - Structured Logging
+
+Usage Guidelines:
+=================
+
+FOR SERVICES: Use get_service_logger('service_name', context)
+-----------------------------------------------------------------
+Example: 
+    from services.logging_utils import get_service_logger
+    
+    class XAIService:
+        def __init__(self, ctx=None):
+            self.logger = get_service_logger('xai', ctx)
+            
+        def upload(self):
+            self.logger.info("Uploading file...")
+
+FOR STEPS: Use ctx.logger directly (preferred)
+-----------------------------------------------------------------
+Steps already have ctx.logger available - use it directly:
+    async def handler(event_data, ctx: FlowContext):
+        ctx.logger.info("Processing event")
+        
+Alternative: Use get_step_logger() for additional loggers:
+    step_logger = get_step_logger('beteiligte_sync', ctx)
+
+FOR SYNC UTILS: Inherit from BaseSyncUtils (provides self.logger)
+-----------------------------------------------------------------
+    from services.sync_utils_base import BaseSyncUtils
+    
+    class MySync(BaseSyncUtils):
+        def __init__(self, espocrm, redis, context):
+            super().__init__(espocrm, redis, context)
+            # self.logger is now available
+            
+        def sync(self):
+            self._log("Syncing...", level='info')
+
+FOR STANDALONE UTILITIES: Use get_logger()
+-----------------------------------------------------------------
+    from services.logging_utils import get_logger
+    
+    logger = get_logger('my_module', context)
+    logger.info("Processing...")
+
+CONSISTENCY RULES:
+==================
+✅ Services: get_service_logger('service_name', ctx)
+✅ Steps: ctx.logger (direct) or get_step_logger('step_name', ctx)
+✅ Sync Utils: Inherit from BaseSyncUtils → use self._log() or self.logger
+✅ Standalone: get_logger('module_name', ctx)
+
+❌ DO NOT: Use module-level logging.getLogger(__name__)
+❌ DO NOT: Mix get_logger() and get_service_logger() in same module
 """
 
 import logging