docs: add standardized comments to all services (Python, Go, Bash)

- Add docs/commenting-standard.md defining per-language comment standards
  (Go godoc, Python PEP-257, C Doxygen, Bash header blocks, SQL banners)

- services/dashboard: 100% docstring coverage (100/100 functions)
  - All FastAPI route handlers, helpers, classes, and models documented
  - Language: French (project convention)

- services/bot-detector: 100% docstring coverage (53/53 symbols)
  - bot_detector.py: 14 functions + module docstring
  - anubis/fetch_rules.py: 9 functions

- shared/python/ja4_common: full docstrings on ClickHouseClient (7 methods)
  and ClickHouseSettings class

- services/correlator: 24 godoc comments added across 6 Go files
  - correlation_service.go: 10 private helpers
  - unixsocket/source.go: 6 parsing/socket helpers
  - correlated_log.go: 4 field extraction helpers
  - orchestrator.go, logger.go, main.go: 4 comments

- services/correlator/scripts/audit-architecture.sh: standardized header block

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

services/dashboard/backend/routes/__init__.py

@@ -1 +1 @@
-# Routes package
+"""Package des routes FastAPI de l'API bot-detector."""

services/dashboard/backend/routes/analysis.py

@@ -374,6 +374,7 @@ async def analyze_user_agents(ip: str):
         
         # Classification des UAs
         def classify_ua(ua: str) -> str:
+            """Classe un User-Agent en 'bot', 'script', 'browser' ou 'unknown'."""
             ua_lower = ua.lower()
             if any(bot in ua_lower for bot in ['bot', 'crawler', 'spider', 'curl', 'wget', 'python', 'requests', 'scrapy']):
                 return 'bot'

services/dashboard/backend/routes/botnets.py

@@ -10,6 +10,7 @@ router = APIRouter(prefix="/api/botnets", tags=["botnets"])
 
 
 def _botnet_class(unique_countries: int) -> str:
+    """Classifie un JA4 selon sa dispersion géographique."""
     if unique_countries > 100:
         return "global_botnet"
     if unique_countries > 20:

services/dashboard/backend/routes/clustering.py

@@ -222,6 +222,7 @@ def _run_clustering_job(k: int, hours: int, sensitivity: float = 1.0) -> None:
                 continue
 
             def avg_f(key: str, crows: list[dict] = cluster_rows[j]) -> float:
+                """Calcule la moyenne flottante d'un champ numérique sur les lignes du cluster."""
                 return float(np.mean([float(r.get(key) or 0) for r in crows]))
 
             mean_ttl   = avg_f("ttl")
@@ -245,6 +246,7 @@ def _run_clustering_job(k: int, hours: int, sensitivity: float = 1.0) -> None:
             orgs      = [str(r.get("asn_org") or "") for r in cluster_rows[j] if r.get("asn_org")]
 
             def topk(lst: list[str], n: int = 5) -> list[str]:
+                """Retourne les n valeurs les plus fréquentes d'une liste (valeurs vides exclues)."""
                 return [v for v, _ in Counter(lst).most_common(n) if v]
 
             radar = [

services/dashboard/backend/routes/fingerprints.py

@@ -489,6 +489,7 @@ async def get_ua_analysis(
 
 
 def _build_ua_risk_flags(ua: str, ua_type: str, unique_ja4s: int, ip_count: int) -> list:
+    """Construit la liste des indicateurs de risque pour un User-Agent."""
     flags = []
     if ua_type == "bot":
         flags.append("ua_bot_signature")

services/dashboard/backend/routes/metrics.py

@@ -144,6 +144,7 @@ async def get_metrics_baseline():
         row = r.result_rows[0] if r.result_rows else None
 
         def pct_change(today: int, yesterday: int) -> float:
+            """Calcule la variation en pourcentage entre aujourd'hui et hier. Retourne 100 si hier=0 et aujourd'hui>0."""
             if yesterday == 0:
                 return 100.0 if today > 0 else 0.0
             return round((today - yesterday) / yesterday * 100, 1)

services/dashboard/backend/routes/ml_features.py

@@ -11,6 +11,7 @@ router = APIRouter(prefix="/api/ml", tags=["ml_features"])
 
 def _attack_type(fuzzing_index: float, hit_velocity: float,
                  is_fake_nav: int, ua_ch_mismatch: int) -> str:
+    """Déduit le type d'attaque depuis les métriques comportementales."""
     if fuzzing_index > 50:
         return "brute_force"
     if hit_velocity > 1.0:
@@ -113,6 +114,7 @@ async def get_ip_radar(ip: str):
         row = result.result_rows[0]
 
         def _f(v) -> float:
+            """Convertit une valeur nullable en float (None ou falsy → 0.0)."""
             return float(v or 0)
 
         return {