refactor: decompose 6 monolithic modules (>1000 LOC) into domain packages

Decompose 6 large modules into packages with <400-line modules to satisfy INV_7:

- superset_client.py (2145->0) -> superset_client/ package (12 modules)
- assistant.py (2683->0) -> assistant/ package (12 modules)
- git_service.py (2101->11 shim) -> services/git/ package (9 modules)
- git.py (1757->0) -> routes/git/ package (11 modules)
- dashboards.py (1619->0) -> routes/dashboards/ package (8 modules)
- translate.py (1587->0) -> routes/translate/ package (11 modules)
- superset_context_extractor.py (1397->0) -> utils/superset_context_extractor/ (7 modules)

All modules <400 lines (INV_7). All 80 tests pass.
All external imports preserved via __init__.py re-exports or shim.
Semantic [DEF] contracts with @LAYER/@SEMANTICS added to all Module types.

backend/src/api/routes/dashboards/_helpers.py

@@ -0,0 +1,187 @@
+# [DEF:DashboardHelpers:Module]
+# @COMPLEXITY: 2
+# @SEMANTICS: api, dashboards, helpers, resolution
+# @PURPOSE: Basic helper functions for dashboard route handlers — slug resolution, filter normalization.
+# @LAYER: Infra
+# @RELATION: DEPENDS_ON -> [SupersetClient]
+# @RELATION: DEPENDS_ON -> [AsyncSupersetClient]
+
+from typing import List, Optional, Dict, Any
+from fastapi import HTTPException
+from src.core.superset_client import SupersetClient
+from src.core.async_superset_client import AsyncSupersetClient
+from src.core.logger import logger
+
+
+# [DEF:_find_dashboard_id_by_slug:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Resolve dashboard numeric ID by slug using Superset list endpoint.
+# @PRE: `dashboard_slug` is non-empty.
+# @POST: Returns dashboard ID when found, otherwise None.
+def _find_dashboard_id_by_slug(
+    client: SupersetClient,
+    dashboard_slug: str,
+) -> Optional[int]:
+    query_variants = [
+        {
+            "filters": [{"col": "slug", "opr": "eq", "value": dashboard_slug}],
+            "page": 0,
+            "page_size": 1,
+        },
+        {
+            "filters": [{"col": "slug", "op": "eq", "value": dashboard_slug}],
+            "page": 0,
+            "page_size": 1,
+        },
+    ]
+
+    for query in query_variants:
+        try:
+            _count, dashboards = client.get_dashboards_page(query=query)
+            if dashboards:
+                resolved_id = dashboards[0].get("id")
+                if resolved_id is not None:
+                    return int(resolved_id)
+        except Exception:
+            continue
+
+    return None
+
+
+# [/DEF:_find_dashboard_id_by_slug:Function]
+
+
+# [DEF:_resolve_dashboard_id_from_ref:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Resolve dashboard ID from slug-first reference with numeric fallback.
+# @PRE: `dashboard_ref` is provided in route path.
+# @POST: Returns a valid dashboard ID or raises HTTPException(404).
+def _resolve_dashboard_id_from_ref(
+    dashboard_ref: str,
+    client: SupersetClient,
+) -> int:
+    normalized_ref = str(dashboard_ref or "").strip()
+    if not normalized_ref:
+        raise HTTPException(status_code=404, detail="Dashboard not found")
+
+    # Slug-first: even if ref looks numeric, try slug first.
+    slug_match_id = _find_dashboard_id_by_slug(client, normalized_ref)
+    if slug_match_id is not None:
+        return slug_match_id
+
+    if normalized_ref.isdigit():
+        return int(normalized_ref)
+
+    raise HTTPException(status_code=404, detail="Dashboard not found")
+
+
+# [/DEF:_resolve_dashboard_id_from_ref:Function]
+
+
+# [DEF:_find_dashboard_id_by_slug_async:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Resolve dashboard numeric ID by slug using async Superset list endpoint.
+# @PRE: dashboard_slug is non-empty.
+# @POST: Returns dashboard ID when found, otherwise None.
+async def _find_dashboard_id_by_slug_async(
+    client: AsyncSupersetClient,
+    dashboard_slug: str,
+) -> Optional[int]:
+    query_variants = [
+        {
+            "filters": [{"col": "slug", "opr": "eq", "value": dashboard_slug}],
+            "page": 0,
+            "page_size": 1,
+        },
+        {
+            "filters": [{"col": "slug", "op": "eq", "value": dashboard_slug}],
+            "page": 0,
+            "page_size": 1,
+        },
+    ]
+
+    for query in query_variants:
+        try:
+            _count, dashboards = await client.get_dashboards_page_async(query=query)
+            if dashboards:
+                resolved_id = dashboards[0].get("id")
+                if resolved_id is not None:
+                    return int(resolved_id)
+        except Exception:
+            continue
+
+    return None
+
+
+# [/DEF:_find_dashboard_id_by_slug_async:Function]
+
+
+# [DEF:_resolve_dashboard_id_from_ref_async:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Resolve dashboard ID from slug-first reference using async Superset client.
+# @PRE: dashboard_ref is provided in route path.
+# @POST: Returns valid dashboard ID or raises HTTPException(404).
+async def _resolve_dashboard_id_from_ref_async(
+    dashboard_ref: str,
+    client: AsyncSupersetClient,
+) -> int:
+    normalized_ref = str(dashboard_ref or "").strip()
+    if not normalized_ref:
+        raise HTTPException(status_code=404, detail="Dashboard not found")
+
+    slug_match_id = await _find_dashboard_id_by_slug_async(client, normalized_ref)
+    if slug_match_id is not None:
+        return slug_match_id
+
+    if normalized_ref.isdigit():
+        return int(normalized_ref)
+
+    raise HTTPException(status_code=404, detail="Dashboard not found")
+
+
+# [/DEF:_resolve_dashboard_id_from_ref_async:Function]
+
+
+# [DEF:_normalize_filter_values:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Normalize query filter values to lower-cased non-empty tokens.
+# @PRE: values may be None or list of strings.
+# @POST: Returns trimmed normalized list preserving input order.
+def _normalize_filter_values(values: Optional[List[str]]) -> List[str]:
+    if not values:
+        return []
+    normalized: List[str] = []
+    for value in values:
+        token = str(value or "").strip().lower()
+        if token:
+            normalized.append(token)
+    return normalized
+
+
+# [/DEF:_normalize_filter_values:Function]
+
+
+# [DEF:_dashboard_git_filter_value:Function]
+# @COMPLEXITY: 2
+# @PURPOSE: Build comparable git status token for dashboards filtering.
+# @PRE: dashboard payload may contain git_status or None.
+# @POST: Returns one of ok|diff|no_repo|error|pending.
+def _dashboard_git_filter_value(dashboard: Dict[str, Any]) -> str:
+    git_status = dashboard.get("git_status") or {}
+    sync_status = str(git_status.get("sync_status") or "").strip().upper()
+    has_repo = git_status.get("has_repo")
+    if has_repo is False or sync_status == "NO_REPO":
+        return "no_repo"
+    if sync_status == "DIFF":
+        return "diff"
+    if sync_status == "OK":
+        return "ok"
+    if sync_status == "ERROR":
+        return "error"
+    return "pending"
+
+
+# [/DEF:_dashboard_git_filter_value:Function]
+
+
+# [/DEF:DashboardHelpers:Module]