From 6647a9a8c108100186e6d3cee5f1918efcab4457 Mon Sep 17 00:00:00 2001
From: bot-backend <bot-backend@gendsgn.local>
Date: Sat, 30 May 2026 17:58:11 +0300
Subject: [PATCH] docs(tradein): clarify n_analogs vs analogs[] top-10 cap
 (#698)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

n_analogs is the FULL count; analogs is capped to top-10 (estimator.py
:2026/2028). Consumers reading len(analogs) under-count. Make the cap explicit
in both field comments, each referencing the other. Comments only — no field
or signature changes.

Refs #698
---
 tradein-mvp/backend/app/schemas/trade_in.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tradein-mvp/backend/app/schemas/trade_in.py b/tradein-mvp/backend/app/schemas/trade_in.py
index 8caef7c6..e883551f 100644
--- a/tradein-mvp/backend/app/schemas/trade_in.py
+++ b/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
     # ── Дополнительные метаданные ──