docs(tradein): clarify n_analogs vs analogs[] top-10 cap (#698) (#737)

Co-authored-by: bot-backend <bot-backend@gendsgn.local>
Co-committed-by: bot-backend <bot-backend@gendsgn.local>

tradein-mvp/backend/app/schemas/trade_in.py

@@ -131,6 +131,8 @@ class AggregatedEstimate(BaseModel):
     median_price_per_m2: int
     confidence: Literal["low", "medium", "high"]
     confidence_explanation: str | None = None  # «Найдено 15 аналогов, разброс ±7%»
+    # #698: ПОЛНОЕ число найденных аналогов — НЕ равно len(analogs) (тот обрезан до
+    # top-10, см. поле `analogs` ниже). Консьюмер должен брать счёт отсюда, а не из len().
     n_analogs: int
 
     @computed_field  # type: ignore[prop-decorator]
@@ -145,7 +147,9 @@ class AggregatedEstimate(BaseModel):
         return self.median_price_rub <= 0
 
     period_months: int  # 24
-    analogs: list[AnalogLot]  # top 5-10 listings
+    # #698: показываемый top-10 (обрезано в estimator.py:2026/2028) — НЕ полный список.
+    # Полное число аналогов — в n_analogs (len(analogs) ≤ 10 < n_analogs при большой выборке).
+    analogs: list[AnalogLot]
     actual_deals: list[AnalogLot]  # реальные продажи last 12 mo
     expires_at: datetime
     # ── Дополнительные метаданные ──