rf4-spotter/docs/ux-contract.md

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

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

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

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

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

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

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

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

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

Источники координат относятся к вторичному provenance: в activity-карточке и detail точки они раскрываются отдельным доступным блоком внутри evidence-паспорта. Основная точность координат остаётся видимой сразу.

Многокомпонентный комплект снастей в списке уловов также раскрывается по запросу: базовые сведения и источник остаются видимыми, а canonical-компоненты сохраняют свои переходы в каталог.

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

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

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-сценариев

Сквозной task journey дополнительно проверяет путь home → spot → что взять → plan на mobile и сохранение query-контекста после возврата.

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-тестами.