# UX-контракт и scorecard RF4 Spotter

Версия: 20 сентября 2026 года. Документ задаёт проверяемый смысловой
контракт публичного интерфейса. Он не заменяет ручной visual review и
production-метрики.

## Главная задача игрока

Ответ должен вести по цепочке:

`рыба → водоём → точка → что взять → почему доверять`

Первый полезный ответ — первая видимая карточка, в которой одновременно
есть точка, координаты или их честнее отсутствие, действие/снасть и evidence
свежести, выборки, доверия и источника. Регистрация и внешний поиск не нужны.

## Контракт маршрутов

| Маршрут | Первый смысловой блок | Основное действие | Обязательное объяснение |
|---|---|---|---|
| `/` | контекст запроса и горячие точки | открыть точку | период, сортировка, freshness и evidence |
| `/spots/:id` | координаты и точность | сохранить/скопировать точку | активность, выборка, доверие и источник |
| `/waterbodies/:slug` | водоём и подтверждённые сведения | выбрать рыбу | источник справочника и свежесть |
| `/plan` | сохранённые варианты | открыть, удалить, поделиться или печатать | локальность данных и лимит 5 |
| `/tackle` | подтверждённый каталог | выбрать снасть | источник, полнота и отсутствие догадок |

Вторичные provenance-поля могут быть ниже первого ответа, но не должны
исчезать, заменяться декоративным рейтингом или становиться единственным
способом понять статус.

## Словарь состояний

| Код | Текст для игрока | Поведение |
|---|---|---|
| `fresh` | Свежие данные | Можно использовать как текущий сигнал, но не как гарантию улова |
| `stale` | Данные устарели | Показывать возраст и снижать доверие; не называть точку горячей без оговорки |
| `insufficient_data` | Недостаточно данных | Показывать размер выборки и не выдавать рекомендацию как уверенную |
| `blocked` | Источник временно ограничен | Сохранить старые подтверждённые данные, показать ограничение и не делать новый импорт |
| `temporary_error` | Данные временно недоступны | Не заменять последнюю дату свежей; дать понятный retry/следующий шаг |
| `verified` | Учтено | Есть разрешённый источник и достаточный контекст |
| `incomplete` | Неполные данные | Перечислить отсутствующие поля, а не скрывать карточку за цветом |

## Scorecard

| Метрика | Как измеряем | Цель альфы |
|---|---|---:|
| Time-to-first-useful-answer | от загрузки главной до первой видимой полной activity-карточки | ≤ 2 высот экрана на 390 px |
| Filter-to-result steps | число действий от выбора фильтра до результата | ≤ 4 действия |
| Query completion | доля участников, получивших точку без подсказки | ≥ 80% |
| Context retention | back/reload сохраняют query или plan | 100% regression-сценариев |
| Viewport integrity | `scrollWidth ≤ clientWidth` | 100% матрицы 320/390/768/1280 |
| Accessibility | axe serious/critical, landmarks, labels, keyboard focus | 0 serious/critical |
| Evidence completeness | источник, freshness, status и доменные поля доступны текстом | 100% публичных рекомендаций |
| Print/share | plan печатается и открывается по ссылке | 100% smoke-сценариев |

## Gates перед закрытием UI-задачи

1. `npm --prefix apps/web run check` проходит без diagnostics.
2. Адресный Playwright-тест покрывает новый journey и empty/error-state.
3. Visual matrix проверяет 320/390/768/1280 px и light/dark/system.
4. Не остаётся горизонтального overflow, ложных координат или статуса,
   различимого только цветом.
5. Для скорости production нужны реальные Lighthouse/Web Vitals; локальный
   build подтверждает только лабораторный baseline.

Текущий документ фиксирует контракт и критерии. Фактический completion rate,
INP и production p95 появятся только после пилота и не должны подменяться
headless-тестами.