69 lines
5.6 KiB
Markdown
69 lines
5.6 KiB
Markdown
# 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-тестами.
|