runners-calendar/FRONTEND_PLAN.md

name: Frontend implementation plan overview: Собрать минималистичный frontend для календаря забегов по UI-инструкции, строго в рамках текущего API-контракта. todos: - id: frontend-structure content: Подготовить структуру frontend, роутинг, базовые layout-компоненты и дизайн-токены на CSS variables + BEM status: completed - id: api-contract-layer content: Реализовать типизированный API-клиент и слой нормализации/обработки ошибок по контракту backend-api-for-frontend.md status: completed - id: dashboard-and-calendar content: Собрать Dashboard, списки будущих/прошедших стартов и базовые карточки по минималистичному UI-гайду status: completed - id: race-details-and-metrics content: Реализовать экран карточки старта, вычисление темпа на фронте и отображение completed-метрик status: completed - id: pr-and-comparison content: Сделать блок PR и сравнение стартов с fallback для отсутствующего поля place status: completed - id: backend-dependency-task content: "Расширение API полем finishPlace: миграция 002, маппер, DTO, фронтенд-интеграция — выполнено" status: completed isProject: false

План frontend части Calendar Run

Исходные опоры

• UI и UX принципы: минимализм, воздух, акцент на данных, спокойная палитра, быстрые сценарии (дизайн-токены в frontend/src/styles/tokens.css).
• Продуктовые ограничения и структура экранов сверяем с d:\vaka.pro\calendar_run\PLAN.md.
• Интеграционный контракт берём из d:\vaka.pro\calendar_run\docs\backend-api-for-frontend.md.
• Общий контекст запуска/окружения — d:\vaka.pro\calendar_run\README.md и d:\vaka.pro\calendar_run\docs\backend.md.

Границы версии (V1)

• Только frontend + интеграция с текущим API.
• Статус зарегистрирован трактуется как UI-вариант planned (без изменения backend-контракта).
• Для completed-забегов обязательно показываем темп; считаем на фронте из finishTime и distanceKm.
• Для completed-забегов поле место (finishPlace) доступно в API (миграция 002, маппер, DTO); фронтенд отображает его в карточке и таблице сравнения.

Архитектура frontend

• Базовая структура: frontend/src/app, frontend/src/pages, frontend/src/components, frontend/src/api, frontend/src/features, frontend/src/lib, frontend/src/styles.
• Дизайн-система на CSS variables: токены цвета/типографики/отступов/радиусов, единые состояния (success, warning, error).
• БЭМ для всех UI-блоков и модификаторов (block, block__element, block--modifier).
• Единый слой API-клиента:
  • GET /races, GET /races/:id, POST /races, PATCH /races/:id, DELETE /races/:id (если используется UI-сценарием).
  • Типы Race, RaceStatus, DTO для POST/PATCH.
  • Централизованный маппинг ошибок API (validation_error, not_found, database_unavailable, conflict) в UX-сообщения.

Экранная модель и сценарии

• Dashboard:
  • Ближайший старт, Последний результат, Личный рекорд, Сезон.
  • CTA к календарю и добавлению старта.
• Календарь стартов:
  • Переключение Будущие / Прошедшие.
  • Карточка старта: title, date, distanceKm, статус-лейбл.
• Карточка старта:
  • Базовые поля + finishTime, вычисляемый pace, finishPlace, notes.
• PR блок:
  • Дистанции: 5K, 10K, 21.1, 42.2 (согласно UI-инструкции).
  • Расчёт по completed-забегам с валидным finishTime.
• Сравнение стартов (ключевая фича):
  • Таблица/карточки по годам с time, pace, finishPlace.
  • Если finishPlace не заполнено — graceful-degradation: колонка в состоянии «нет данных».

UX и визуальные требования

• Визуальная система: светлый фон, белые карточки, один акцентный цвет, без кислотных сочетаний.
• Иерархия типографики: H1/H2/body/caption, крупные числовые метрики.
• Минимум визуального шума, 2–3 клика на частые действия.
• Консистентные состояния загрузки/ошибок/пустых данных.
• A11y-базис: фокус-стили, клавиатурная навигация, контраст, корректная разметка интерактивных элементов.

Зависимая задача (выполнена)

• Поле finishPlace добавлено в модель Race: миграция 002_finish_place_and_registered_status.sql, маппер race.ts, DTO, API-документация.
• Frontend-типы, карточка и блок сравнения используют finishPlace.

Порядок реализации

1. Подготовить каркас frontend и дизайн-токены (BEM + CSS variables).
2. Реализовать API-клиент и типы данных с обработкой ошибок.
3. Собрать Dashboard и календарные списки (будущие/прошедшие).
4. Реализовать карточку старта с вычислением pace на клиенте.
5. Реализовать PR и блок сравнения стартов с fallback для place.
6. Добавить состояния пустых данных/ошибок/загрузки и а11y-полировку.

Definition of Done для frontend

• Все ключевые экраны из UI-инструкции доступны и консистентны визуально.
• API-интеграция работает по текущему контракту без локальных обходов хранилища.
• pace считается корректно для completed-забегов.
• registered не ломает модель: визуально интерпретируется в рамках planned.
• finishPlace интегрирован; при отсутствии значения — безопасный fallback в UI.