semantics update

backend/src/core/superset_client.py

@@ -2,10 +2,12 @@
 #
 # @COMPLEXITY: 3
 # @SEMANTICS: superset, api, client, rest, http, dashboard, dataset, import, export
-# @PURPOSE:   Предоставляет высокоуровневый клиент для взаимодействия с Superset REST API, инкапсулируя логику запросов, обработку ошибок и пагинацию.
-# @LAYER:     Core
-# @RELATION: DEPENDS_ON -> [ConfigModels]
-# @RELATION: DEPENDS_ON -> [ConnectionContracts]
+# @PURPOSE: Предоставляет высокоуровневый клиент для взаимодействия с Superset REST API, инкапсулируя логику запросов, обработку ошибок и пагинацию.
+# @LAYER: Core
+# @RELATION: [DEPENDS_ON] ->[ConfigModels]
+# @RELATION: [DEPENDS_ON] ->[APIClient]
+# @RELATION: [DEPENDS_ON] ->[SupersetAPIError]
+# @RELATION: [DEPENDS_ON] ->[get_filename_from_headers]
 #
 # @INVARIANT: All network operations must use the internal APIClient instance.
 # @PUBLIC_API: SupersetClient
@@ -31,8 +33,9 @@ app_logger = cast(Any, app_logger)
 # [DEF:SupersetClient:Class]
 # @COMPLEXITY: 3
 # @PURPOSE: Класс-обёртка над Superset REST API, предоставляющий методы для работы с дашбордами и датасетами.
-# @RELATION: DEPENDS_ON -> [ConfigModels]
-# @RELATION: DEPENDS_ON -> [ConnectionContracts]
+# @RELATION: [DEPENDS_ON] ->[ConfigModels]
+# @RELATION: [DEPENDS_ON] ->[APIClient]
+# @RELATION: [DEPENDS_ON] ->[SupersetAPIError]
 class SupersetClient:
     # [DEF:SupersetClientInit:Function]
     # @COMPLEXITY: 3
@@ -40,13 +43,13 @@ class SupersetClient:
     # @PRE:  `env` должен быть валидным объектом Environment.
     # @POST: Атрибуты `env` и `network` созданы и готовы к работе.
     # @DATA_CONTRACT: Input[Environment] -> self.network[APIClient]
-    # @RELATION: DEPENDS_ON -> [Environment]
-    # @RELATION: DEPENDS_ON -> [ConnectionContracts]
+    # @RELATION: [DEPENDS_ON] ->[Environment]
+    # @RELATION: [DEPENDS_ON] ->[APIClient]
     def __init__(self, env: Environment):
-        with belief_scope("__init__"):
-            app_logger.info(
-                "[SupersetClient.__init__][Enter] Initializing SupersetClient for env %s.",
-                env.name,
+        with belief_scope("SupersetClientInit"):
+            app_logger.reason(
+                "Initializing Superset client for environment",
+                extra={"environment": getattr(env, "id", None), "name": env.name},
             )
         self.env = env
         # Construct auth payload expected by Superset API
@@ -62,7 +65,10 @@ class SupersetClient:
             timeout=env.timeout,
         )
         self.delete_before_reimport: bool = False
-        app_logger.info("[SupersetClient.__init__][Exit] SupersetClient initialized.")
+        app_logger.reflect(
+            "Superset client initialized",
+            extra={"environment": getattr(self.env, "id", None)},
+        )
 
     # [/DEF:SupersetClientInit:Function]
 
@@ -72,11 +78,22 @@ class SupersetClient:
     # @PRE: self.network must be initialized with valid auth configuration.
     # @POST: Client is authenticated and tokens are stored.
     # @DATA_CONTRACT: None -> Output[Dict[str, str]]
-    # @RELATION: CALLS -> [ConnectionContracts]
+    # @RELATION: [CALLS] ->[APIClient]
     def authenticate(self) -> Dict[str, str]:
-        with belief_scope("SupersetClient.authenticate"):
-            return self.network.authenticate()
-
+        with belief_scope("SupersetClientAuthenticate"):
+            app_logger.reason(
+                "Authenticating Superset client",
+                extra={"environment": getattr(self.env, "id", None)},
+            )
+            tokens = self.network.authenticate()
+            app_logger.reflect(
+                "Superset client authentication completed",
+                extra={
+                    "environment": getattr(self.env, "id", None),
+                    "token_keys": sorted(tokens.keys()),
+                },
+            )
+            return tokens
     # [/DEF:SupersetClientAuthenticate:Function]
 
     @property
@@ -1545,7 +1562,7 @@ class SupersetClient:
     # @PRE: dataset_record should come from Superset dataset detail when possible.
     # @POST: Returns one serialized-ready form_data structure preserving native filter clauses in legacy transport fields.
     # @DATA_CONTRACT: Input[dataset_id:int,dataset_record:Dict,template_params:Dict,effective_filters:List[Dict]] -> Output[Dict[str, Any]]
-    # @RELATION: CALLS -> [SupersetClientBuildDatasetPreviewQueryContext]
+    # @RELATION: [CALLS] ->[SupersetClientBuildDatasetPreviewQueryContext]
     # @SIDE_EFFECT: Emits reasoning diagnostics describing the inferred legacy payload shape.
     def build_dataset_preview_legacy_form_data(
         self,
@@ -1630,9 +1647,11 @@ class SupersetClient:
         template_params: Dict[str, Any],
         effective_filters: List[Dict[str, Any]],
     ) -> Dict[str, Any]:
-        with belief_scope(
-            "SupersetClient.build_dataset_preview_query_context", f"id={dataset_id}"
-        ):
+        with belief_scope("SupersetClientBuildDatasetPreviewQueryContext"):
+            app_logger.reason(
+                "Building Superset dataset preview query context",
+                extra={"dataset_id": dataset_id, "filter_count": len(effective_filters or [])},
+            )
             normalized_template_params = deepcopy(template_params or {})
             normalized_filter_payload = (
                 self._normalize_effective_filters_for_query_context(
@@ -1749,7 +1768,7 @@ class SupersetClient:
     # @PURPOSE: Convert execution mappings into Superset chart-data filter objects.
     # @PRE: effective_filters may contain mapping metadata and arbitrary scalar/list values.
     # @POST: Returns only valid filter dictionaries suitable for the chart-data query payload.
-    # @RELATION: DEPENDS_ON -> [CoreContracts]
+    # @RELATION: [DEPENDS_ON] ->[SupersetClient]
     def _normalize_effective_filters_for_query_context(
         self,
         effective_filters: List[Dict[str, Any]],