UX X1: Score explanation breakdown + verbal explain (per-factor) #47

New issue

Closed

opened 2026-05-11 20:17:49 +00:00 by lekss361 · 0 comments

lekss361 commented

2026-05-11 20:17:49 +00:00

(Migrated from github.com)

Эшелон: 🟣 Explainability / UX — доверие к скорингу

Контекст / проблема

Сейчас score: 12.3 / 40 · среднее — это число без объяснения. Девелопер не понимает что повлияло, почему именно 12. Это главный блокер для встреч — на втором демо человек спросит «а почему?», и без ответа продукт мёртв.

Что сделать

Backend — расширенный analyze response

Новое поле score_breakdown_detailed: list[FactorContribution]:

class FactorContribution(BaseModel):
    factor: str            # "school_in_400m"
    category: str          # "social_infra"
    value: float           # raw value, e.g. distance_m=400
    weight: float          # 1.5
    contribution: float    # weight * decay = 0.9
    contribution_pct: float  # % of total positive score
    verbal: str            # "Школа №125 в 400м — +0.9 баллов"

Verbal explain templates per category — генерируются на backend
score_top_3_positives и score_top_3_negatives — для UI summary

Frontend

Новый компонент ScoreBreakdownPanel.tsx — раскрывающийся под ScoreCard:
- Stacked bar показывает % contribution каждой категории
- Toggle «детали» → раскрывает list of FactorContribution с verbal
- Top-3 positive / Top-3 negative в кратком виде
Tooltip on hover каждого POI marker'а на карте показывает его contribution

Acceptance

Каждый POI в score_breakdown_detailed имеет verbal explanation
Sum of contributions = final score (sanity check)
UI прячет панель если score детально не требуется (mobile)

Owner

backend-engineer (breakdown structure + verbal templates) + frontend-engineer (UI panel)

Effort

1.5–2 дня

Dependencies

— (можно делать сразу)

Why critical

Это killer feature для встреч — каждый девелопер первым делом спросит «почему именно столько». Без X1 продукт «чёрный ящик».

**Эшелон:** 🟣 Explainability / UX — доверие к скорингу ## Контекст / проблема Сейчас `score: 12.3 / 40 · среднее` — это число без объяснения. Девелопер не понимает что повлияло, почему именно 12. Это **главный блокер для встреч** — на втором демо человек спросит «а почему?», и без ответа продукт мёртв. ## Что сделать ### Backend — расширенный analyze response 1. Новое поле `score_breakdown_detailed: list[FactorContribution]`: ```python class FactorContribution(BaseModel): factor: str # "school_in_400m" category: str # "social_infra" value: float # raw value, e.g. distance_m=400 weight: float # 1.5 contribution: float # weight * decay = 0.9 contribution_pct: float # % of total positive score verbal: str # "Школа №125 в 400м — +0.9 баллов" ``` 2. Verbal explain templates per category — генерируются на backend 3. `score_top_3_positives` и `score_top_3_negatives` — для UI summary ### Frontend 1. Новый компонент `ScoreBreakdownPanel.tsx` — раскрывающийся под ScoreCard: - Stacked bar показывает % contribution каждой категории - Toggle «детали» → раскрывает list of FactorContribution с verbal - Top-3 positive / Top-3 negative в кратком виде 2. Tooltip on hover каждого POI marker'а на карте показывает его `contribution` ## Acceptance - [ ] Каждый POI в score_breakdown_detailed имеет verbal explanation - [ ] Sum of contributions = final score (sanity check) - [ ] UI прячет панель если score детально не требуется (mobile) ## Owner `backend-engineer` (breakdown structure + verbal templates) + `frontend-engineer` (UI panel) ## Effort 1.5–2 дня ## Dependencies — (можно делать сразу) ## Why critical Это killer feature для встреч — каждый девелопер первым делом спросит «почему именно столько». Без X1 продукт «чёрный ящик».