Merge pull request 'docs(site-finder): analyze confidence by-design distinct from §15 (#1668)' (#1671) from fix/1668-analyze-confidence into main

backend/app/api/v1/parcels.py

@@ -814,11 +814,20 @@ def _compute_confidence(
     market_trend: dict[str, Any] | None,
     zoning: dict[str, Any],
 ) -> dict[str, Any]:
-    """X2 (#48) — composite confidence score 0..1 + caveats.
+    """X2 (#48) — composite confidence score 0..1 + caveats для site-finder analyze.
 
-    Stub-версия (до реализации G1/G2/D1/D2): использует сигналы которые уже
-    доступны на main. Композитный балл = avg of subscore'ов; caveats — list
-    конкретных проблем для UI ("Нет данных N, score K ненадёжен").
+    Это НАДЁЖНОСТЬ САМОГО SITE-FINDER СКОРИНГА (coverage/свежесть входных
+    сигналов: POI, район, рынок, конкуренты, источник геометрии) — отдельная
+    by-design метрика, НЕ форсайтный §15 `forecasting.confidence_engine`
+    (`compute_report_confidence`). §15 оценивает надёжность ПРОГНОЗА
+    спроса/цены и работает над форсайт-входами (coverage/confounded/
+    special_indices/sales_series), которых в analyze hot-path нет — поэтому
+    analyze намеренно держит свою лёгкую coverage-метрику, а не зовёт §15.
+
+    Композитный балл = avg of subscore'ов; caveats — list конкретных проблем
+    для UI ("Нет данных N, score K ненадёжен"). См. #1668 (решение: оставить
+    раздельно by-design; «stub до G1/G2/D1/D2» — устаревшая формулировка,
+    те эшелоны уже отгружены, их confidence сюда не вплетается намеренно).
     """
     caveats: list[str] = []
     subscores: dict[str, float] = {}