5.6 KiB
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-задачи
npm --prefix apps/web run checkпроходит без diagnostics.- Адресный Playwright-тест покрывает новый journey и empty/error-state.
- Visual matrix проверяет 320/390/768/1280 px и light/dark/system.
- Не остаётся горизонтального overflow, ложных координат или статуса, различимого только цветом.
- Для скорости production нужны реальные Lighthouse/Web Vitals; локальный build подтверждает только лабораторный baseline.
Текущий документ фиксирует контракт и критерии. Фактический completion rate, INP и production p95 появятся только после пилота и не должны подменяться headless-тестами.