docs: define ux contract and scorecard

docs/ROADMAP.md

@@ -92,13 +92,13 @@
 
 Результаты сравнительного аудита и ссылки сохранены в [ux-competitive-audit.md](ux-competitive-audit.md). Целевой критерий проекта: RF4 Spotter должен быстрее и честнее отвечать на вопрос «куда идти, на что ловить и почему этому можно доверять», чем каталог или лента community-постов.
 
-- [ ] **U01 · UX-контракт и scorecard.** Зафиксировать task-based навигацию, смысловой порядок ответа, словарь статусов (`fresh`, `stale`, `insufficient_data`, `blocked`, `temporary_error`) и единый scorecard: time-to-first-useful-answer, filter-to-result steps, completion rate, overflow, axe и keyboard regression. Сверить каждый публичный маршрут с контрактом; не добавлять фичи, которые не улучшают решение игрока.
+- [ ] **U01 · UX-контракт и scorecard.** Контракт маршрутов, смысловой порядок ответа, словарь статусов и целевые метрики зафиксированы в [ux-contract.md](ux-contract.md); для home, spot, waterbody, plan и tackle описаны первый ответ и обязательное объяснение. Осталось провести ручной task-based review и собрать completion rate на пилоте.
 - [ ] **U02 · Главный сценарий «рыба → водоём → точка → снасть».** Главная уже сохраняет рыбу, водоём, период и сортировку в shareable URL и после поиска явно показывает контекст запроса, включая мобильный режим; empty-state предлагает вернуться к полному набору данных. Осталось показать 3–5 вариантов с понятным CTA и добавить режим map. Acceptance: первый полезный вариант виден без регистрации, back/refresh сохраняют контекст, mobile не теряет фильтры.
 - [ ] **U03 · Evidence/trust card.** Общий evidence-контракт используется на activity-карточках, detail точки, водоёма и карточках снастей: freshness, completeness, confidence/статус, source badges и доступные доменные поля; targeted E2E проверяет публичные пути. Осталось добавить период выборки, конфликт источников и правило минимальной выборки для любых рекомендаций. Нельзя показывать «лучшую точку» или AI-like рекомендацию без объяснения и минимальной выборки.
 - [ ] **U04 · List/map и progressive disclosure.** List остаётся честным базовым режимом: фильтры, сортировка, URL-состояние и evidence-карточки уже работают без имитации координатной карты. Следующий шаг — единый list/map-контракт после подтверждения геометрии; на mobile карта должна открываться отдельным действием. Вторичные raw/provenance-поля не исчезают и раскрываются по запросу.
 - [ ] **U05 · Mobile-first и сохранённый план рыбалки.** `/plan` поддерживает список до 5 локальных вариантов, удаление, очистку, переход к точке, print/PDF и восстановление из shareable URL; кнопка «Поделиться планом» использует native share или clipboard fallback. Detail-кнопка сохраняет данные с `aria-pressed` и восстанавливается после reload. Осталось сделать отдельную проверку print на 320/390 px и расширить сравнение полями метода/риска.
 - [ ] **U06 · Контентная и визуальная иерархия.** Для detail точки действие «Что взять» выделено отдельным заголовком, а provenance и качество собраны в общем паспорте данных; статусы дополнительно передаются текстом, не только цветом. Осталось сократить конкурирующие цифры на карточках и провести ручной review на 5 ключевых маршрутах.
-- [ ] **U07 · UX-приёмка и измерения.** Добавить Playwright-контракты для полного journey, list/map, evidence states, saved plan, stale/blocked/insufficient data и share/print. Зафиксировать baseline Lighthouse/axe/CLS/INP и time-to-first-useful-answer; закрывать U01–U06 только по evidence, screenshots и обратной связи пилота.
+- [ ] **U07 · UX-приёмка и измерения.** Playwright-контракты уже покрывают query journey, evidence states, saved plan, share/print, accessibility и visual matrix; их критерии собраны в [ux-contract.md](ux-contract.md). Осталось добавить отдельные stale/blocked/insufficient-data fixtures, сохранить reference screenshots и получить production Lighthouse/CLS/INP/time-to-first-useful-answer после пилота.
 
 - [ ] **Q01 · Документы источников — реестр готов, нужны первичные подтверждения.** Создан единый production-gate с атрибуцией, общим лимитом 30 минут, хранением и процедурой отзыва для RF4DB, RF4-STAT, RF4MAP, RF4 Posts и официального RF4. До открытой публикации приложить устойчивые ссылки/копии первичных разрешений, контакты, даты и отдельно подтвердить право на изображения; пустое поле блокирует соответствующий источник.
 - [x] **Q02 · Управляемое удаление источника.** Изменение ранее опубликованной записи возвращает её в staging, сбрасывает сопоставление и переводит связанный улов в pending с новой версией решения. Результат проверки хранится как `available`, `missing`, `temporary_error` или `blocked`: только подтверждённый `missing` отзывает публикацию, временная ошибка и блокировка остаются диагностикой. Повторное появление требует ручного подтверждения. Withdrawn-записи исключены из публичной активности, а статус и время проверки доступны в admin provenance и журнале решений. Отдельного сетевого обхода нет: Q03 подключит эту реакцию к разрешённому плановому запросу.

docs/ux-contract.md

@@ -0,0 +1,68 @@
+# 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-тестами.