feat(dashboard): add PR by distance and race comparison table

Made-with: Cursor

.gitignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 .env
 *.log
+*plan*
+*PLAN*

PLAN.md

@@ -69,6 +69,8 @@ flowchart LR
   API -->|"DB_* connection"| DB
 ```
 
+
+
 ### 4.2 Вне рантайма (разово)
 
 **Seed-скрипт** (запуск вручную при развёртывании/обновлении стартового набора):
@@ -88,20 +90,22 @@ flowchart LR
 
 Один набор полей — в таблице, в JSON тел запросов/ответов API и в опциональном файле для seed. Согласовать **camelCase в API** и **snake_case в SQL** в `docs/backend.md`.
 
-| Поле | Обяз. | Примечание |
+
-| ------ | ------- | ------------ |
+| Поле              | Обяз. | Примечание                                           |
-| `id` | да | Стабильный ключ, напр. `2026-05-03-kazan-marathon` |
+| ----------------- | ----- | ---------------------------------------------------- |
-| `date` | да | День старта `YYYY-MM-DD` |
+| `id`              | да    | Стабильный ключ, напр. `2026-05-03-kazan-marathon`   |
-| `title` | да | Название |
+| `date`            | да    | День старта `YYYY-MM-DD`                             |
-| `distanceKm` | да | Число км |
+| `title`           | да    | Название                                             |
-| `status` | нет | `planned` / `completed`; иначе можно вывести из даты |
+| `distanceKm`      | да    | Число км                                             |
-| `officialUrl` | нет | Ссылка на организатора |
+| `status`          | нет   | `planned` / `completed`; иначе можно вывести из даты |
-| `startTime` | нет | Напр. `09:30` |
+| `officialUrl`     | нет   | Ссылка на организатора                               |
-| `clusterSchedule` | нет | Многострочный текст |
+| `startTime`       | нет   | Напр. `09:30`                                        |
-| `bibPickup` | нет | Выдача номеров |
+| `clusterSchedule` | нет   | Многострочный текст                                  |
-| `bibNumber` | нет | Стартовый номер |
+| `bibPickup`       | нет   | Выдача номеров                                       |
-| `finishTime` | нет | Время H:MM:SS / HH:MM:SS; для PR — перевод в секунды |
+| `bibNumber`       | нет   | Стартовый номер                                      |
-| `notes` | нет | Заметки |
+| `finishTime`      | нет   | Время H:MM:SS / HH:MM:SS; для PR — перевод в секунды |
+| `notes`           | нет   | Заметки                                              |
+
 
 Опционально в миграциях: `created_at`, `updated_at`.
 
@@ -115,12 +119,12 @@ flowchart LR
 - Если дата **строго до сегодня** (локальная дата пользователя) — показать **результат** и **стартовый номер** (необязательны при первом сохранении).
 - Если дата в будущем — поля результата скрыты.
 - Опционально: чекбокс «Уже прошёл» для случая **сегодняшней** даты, чтобы открыть поля результата.
-- Сохранение: **`POST`** на API → запись в БД.
+- Сохранение: `**POST`** на API → запись в БД.
 
 ### 6.2 Страница забега
 
 - Все поля модели; для прошедших — акцент на результат и номер.
-- Редактирование результата и номера **в любой момент**: **`PATCH`** на API, затем обновление состояния на клиенте (refetch / инвалидация кэша).
+- Редактирование результата и номера **в любой момент**: `**PATCH`** на API, затем обновление состояния на клиенте (refetch / инвалидация кэша).
 
 ### 6.3 Личные рекорды
 
@@ -139,19 +143,21 @@ flowchart LR
 
 ## 7. Документация
 
-Создать каталог **`docs/`**:
+Создать каталог `**docs/`**:
 
-| Файл | Назначение |
-| ------ | ------------ |
-| `docs/backend.md` | Docker, `DB_*`, миграции, seed, REST API, CORS |
-| `docs/frontend.md` | Структура `frontend/`, `VITE_*`, сборка, контракт с API |
-| `docs/ux-spa.md` | Сценарии, экраны, BEM, кратко про a11y |
 
-Корневой **`README.md`**: описание проекта, быстрый старт, **ссылки на три файла выше**.
+| Файл               | Назначение                                              |
+| ------------------ | ------------------------------------------------------- |
+| `docs/backend.md`  | Docker, `DB`_*, миграции, seed, REST API, CORS          |
+| `docs/frontend.md` | Структура `frontend/`, `VITE`_*, сборка, контракт с API |
+| `docs/ux-spa.md`   | Сценарии, экраны, BEM, кратко про a11y                  |
+
+
+Корневой `**README.md`**: описание проекта, быстрый старт, **ссылки на три файла выше**.
 
 ## 8. Риски и ограничения
 
-- **`DB_*` и пароли** — только в окружении сервера API; в git — только `.env.example` без реальных секретов.
+- `**DB`_* и пароли** — только в окружении сервера API; в git — только `.env.example` без реальных секретов.
 - Актуальные данные после работы в UI — в **БД**; файлы в git не синхронизируются с правками автоматически. Надёжный бэкап — **резервное копирование PostgreSQL**.
 - Деплой: Postgres + процесс API с env + статическая раздача фронта (или иная схема хостинга — описать в README).
 - Данные организаторов (расписание стартов) — **вручную** + ссылка; без парсинга чужих сайтов в объёме первой версии.
@@ -171,7 +177,7 @@ flowchart LR
 ## 10. Чеклист задач (implementation todos)
 
 1. Монорепо: `frontend/` + `backend/`, BEM, токены, роутер.
-2. Postgres в docker-compose, миграции таблицы `races`, бэкенд читает `DB_*`.
+2. Postgres в docker-compose, миграции таблицы `races`, бэкенд читает `DB`_*.
 3. REST CRUD + разовый seed (CSV и/или JSON) → БД.
 4. Клиент API на фронте, типы, загрузка данных для экранов и PR.
 5. Экраны месяц и год, модалка по дате.

README.md

@@ -0,0 +1,24 @@
+# Calendar Run
+
+Calendar Run is a races calendar project with a backend API for storing and querying race events.
+
+## Quick Start
+
+1. Install dependencies:
+  - `cd backend`
+  - `npm install`
+2. Configure environment variables in `backend/.env`:
+  - `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+  - Optional API port: `PORT` (priority) or `API_PORT`
+  - **No PostgreSQL (CI / local smoke):** set `CALENDAR_RUN_MOCK_DB=1` (or `true`). Real `DB_`* values are not required; the API uses in-memory stubs for SQL used by the HTTP routes. Do not use mock mode for `npm run db:migrate` or `npm run seed`.
+3. Build and run backend:
+  - `npm run build`
+  - `npm run dev`
+
+By default, the API listens on port `3001` if `PORT` and `API_PORT` are not set.
+
+## Backend And API Docs
+
+- [Backend API for Frontend](docs/backend-api-for-frontend.md)
+- [Backend Agent Instruction](docs/agent-backend-instruction.md)
+- [Backend Sync Fix Instruction](docs/agent-fix-backend-sync-instruction.md)

agent-frontend-ui-instructions.md

@@ -0,0 +1,336 @@
+Ниже — инструкция для дизайн-агента, которая задаёт стиль, структуру и принципы интерфейса для твоего SPA. Она ориентирована на **минимализм, читаемость данных и удовольствие от использования**, а не на “перегруженный фитнес-дэшборд”.
+
+# 🎯 Общая задача
+
+Создать **чистый, современный, минималистичный интерфейс** для SPA-приложения бегуна, где пользователь:
+
+- отслеживает свои старты (прошлые и будущие),
+- видит прогресс и личные рекорды,
+- сравнивает результаты,
+- получает ощущение “контроля над своей беговой историей”.
+
+---
+
+# 🧭 Общая философия дизайна
+
+### 1. “Спокойная сила”, а не “спортивная агрессия”
+
+Не:
+
+- кислотные цвета,
+- перегруженные графики,
+- “фитнес-клуб стиль 2015”.
+
+Да:
+
+- чистый интерфейс,
+- воздух,
+- акцент на данных,
+- ощущение премиальности.
+
+---
+
+### 2. Минимум визуального шума
+
+Каждый экран должен отвечать на вопрос:
+
+> “Что здесь главное?”
+
+Если не ясно — убрать лишнее.
+
+---
+
+### 3. Данные — главный герой
+
+Интерфейс не про “украшения”, а про:
+
+- результаты,
+- прогресс,
+- сравнение,
+- числа.
+
+---
+
+# 🎨 Визуальный стиль
+
+## Цвета
+
+### Основа:
+
+- фон: светлый (#F7F8FA или близко)
+- карточки: белые
+- текст:
+  - основной: почти чёрный (#111)
+  - вторичный: серый (#666)
+
+### Акцент:
+
+- 1 основной цвет:
+  - глубокий синий или изумрудный (например #2F6BFF или #1FA37A)
+
+### Дополнительно:
+
+- PR / успех: мягкий зелёный
+- предупреждения: нейтральный жёлтый
+- ошибки: мягкий красный
+
+❗ Никаких “радуг”.
+
+---
+
+## Типографика
+
+- современный sans-serif (Inter / SF Pro / аналог)
+- крупные числа:
+  - результаты (время) — большие, жирные
+- иерархия:
+  - H1 — экран
+  - H2 — блок
+  - body — данные
+  - caption — мета
+
+---
+
+## Отступы и сетка
+
+- много воздуха
+- карточки с padding 16–24px
+- равномерная вертикальная ритмика
+- закругления: 12–16px
+
+---
+
+# 🧱 Основные экраны
+
+## 1. Главный экран (Dashboard)
+
+### Цель:
+
+дать быстрый ответ:
+
+- что впереди
+- где я сейчас
+- какой прогресс
+
+### Блоки:
+
+#### 🔹 Ближайший старт
+
+- название
+- дата
+- дистанция
+- countdown (“через 12 дней”)
+
+#### 🔹 Последний результат
+
+- время
+- дистанция
+- место
+- дата
+
+#### 🔹 Личный рекорд
+
+- по ключевой дистанции
+- выделен визуально
+
+#### 🔹 Сезон
+
+- количество стартов
+- лучший результат
+- краткая статистика
+
+---
+
+## 2. Календарь стартов
+
+### Два раздела:
+
+- будущие
+- прошедшие
+
+### Карточка старта:
+
+- название
+- дата
+- дистанция
+- статус:
+  - планирую
+  - зарегистрирован
+  - пробежал
+
+Минимум кликов.
+
+---
+
+## 3. Карточка старта
+
+- название
+- дата
+- дистанция
+- время
+- темп
+- место (если есть)
+- заметки (опционально)
+
+---
+
+## 4. Личные рекорды (PR)
+
+- список дистанций:
+  - 5K
+  - 10K
+  - 21.1
+  - 42.2
+
+Для каждой:
+
+- лучшее время
+- дата
+- старт
+
+---
+
+## 5. Сравнение стартов (ВАЖНО)
+
+Это ключевая фича.
+
+### UI:
+
+таблица или карточки:
+
+
+| Год | Время | Темп | Место |
+| --- | ----- | ---- | ----- |
+
+
+Можно добавить:
+
+- стрелки (лучше/хуже)
+- визуальный прогресс
+
+---
+
+# 📊 Графики
+
+Минимально и аккуратно:
+
+- линия прогресса по дистанции
+- без перегруза
+- без 10 линий сразу
+
+---
+
+# 🧩 Компоненты
+
+- карточки
+- таблицы (очень аккуратно)
+- фильтры
+- переключатели (tabs)
+- кнопки (primary / secondary)
+
+---
+
+# 🧠 UX принципы
+
+### 1. Минимум кликов
+
+Любая частая задача:  
+→ максимум 2–3 клика
+
+---
+
+### 2. Быстрое считывание
+
+Пользователь должен за 2 секунды понять:
+
+- что это
+- где он
+- что делать
+
+---
+
+### 3. Консистентность
+
+- одинаковые карточки
+- одинаковые статусы
+- одинаковые действия
+
+---
+
+# 🧪 Для аналитики (важно)
+
+Заложить:
+
+- зоны кликов
+- понятные CTA
+- отсутствие “пустых зон”
+
+---
+
+# 🖼️ Использование изображений
+
+## Когда использовать:
+
+- пустые состояния
+- onboarding
+- вдохновение
+
+## Когда НЕ использовать:
+
+- в данных
+- в списках стартов
+- в результатах
+
+---
+
+## Если генерировать изображения
+
+Стиль:
+
+- минимализм
+- спорт без пафоса
+- одиночный бегун
+- город / парк
+- мягкий свет
+- утро / вечер
+
+### Пример prompt:
+
+> “minimalist photo of a runner jogging alone in a city park at sunrise, soft light, calm mood, no crowd, modern aesthetic”
+
+---
+
+# 🚫 Чего избегать
+
+- перегруженных дашбордов
+- 100 метрик сразу
+- ярких кислотных цветов
+- сложных графиков
+- таблиц как в Excel
+- лишних иконок
+- “геймификации ради геймификации”
+
+---
+
+# 💡 Вдохновение (по духу)
+
+Если бы нужно было описать стиль:
+
+- как Notion, но для бегунов
+- как Apple Fitness, но менее ярко
+- как Strava, но более спокойно и чисто
+
+---
+
+# 🧭 Финальный ориентир
+
+Интерфейс должен вызывать ощущение:
+
+> “Я контролирую свою беговую историю и прогресс”
+
+а не:
+
+> “Я заполняю таблицу результатов”
+
+---
+

backend/src/config.ts

@@ -11,14 +11,27 @@ function requireEnv(name: string): string {
   return value;
 }
 
+const useMockDb =
+  process.env.CALENDAR_RUN_MOCK_DB === "1" ||
+  process.env.CALENDAR_RUN_MOCK_DB?.toLowerCase() === "true";
+
 export const config = {
-  db: {
+  useMockDb,
-    host: requireEnv("DB_HOST"),
+  db: useMockDb
-    port: parseInt(requireEnv("DB_PORT"), 10),
+    ? {
-    database: requireEnv("DB_NAME"),
+        host: "mock",
-    user: requireEnv("DB_USER"),
+        port: 5432,
-    password: requireEnv("DB_PASSWORD"),
+        database: "mock",
-  },
+        user: "mock",
-  apiPort: parseInt(process.env.API_PORT || "3001", 10),
+        password: "mock",
+      }
+    : {
+        host: requireEnv("DB_HOST"),
+        port: parseInt(requireEnv("DB_PORT"), 10),
+        database: requireEnv("DB_NAME"),
+        user: requireEnv("DB_USER"),
+        password: requireEnv("DB_PASSWORD"),
+      },
+  apiPort: parseInt(process.env.PORT || process.env.API_PORT || "3001", 10),
   corsOrigin: process.env.CORS_ORIGIN || "http://localhost:5173",
 };

backend/src/db.ts

@@ -1,5 +1,6 @@
-import { Pool, PoolConfig } from "pg";
+import { Pool, PoolConfig, QueryResult, QueryResultRow } from "pg";
 import { config } from "./config";
+import type { RaceRow } from "./mappers/race";
 
 const poolConfig: PoolConfig = {
   host: config.db.host,
@@ -12,13 +13,119 @@ const poolConfig: PoolConfig = {
   connectionTimeoutMillis: 5_000,
 };
 
-export const pool = new Pool(poolConfig);
+function mockRowFromInsert(sql: string, params: unknown[]): RaceRow {
+  const match = sql.match(/INSERT INTO races\s*\(([^)]+)\)\s*VALUES/i);
+  const now = new Date().toISOString();
+  if (!match) {
+    return {
+      id: String(params[0] ?? ""),
+      race_date: "",
+      title: "",
+      distance_km: "0",
+      status: null,
+      official_url: null,
+      start_time: null,
+      cluster_schedule: null,
+      bib_pickup: null,
+      bib_number: null,
+      finish_time: null,
+      notes: null,
+      created_at: now,
+      updated_at: null,
+    };
+  }
+  const cols = match[1].split(",").map((c) => c.trim());
+  const row: Record<string, unknown> = {};
+  cols.forEach((col, i) => {
+    row[col] = params[i];
+  });
+  return {
+    id: String(row.id ?? ""),
+    race_date: String(row.race_date ?? ""),
+    title: String(row.title ?? ""),
+    distance_km: String(row.distance_km ?? "0"),
+    status: row.status != null ? String(row.status) : null,
+    official_url: row.official_url != null ? String(row.official_url) : null,
+    start_time: row.start_time != null ? String(row.start_time) : null,
+    cluster_schedule: row.cluster_schedule != null ? String(row.cluster_schedule) : null,
+    bib_pickup: row.bib_pickup != null ? String(row.bib_pickup) : null,
+    bib_number: row.bib_number != null ? String(row.bib_number) : null,
+    finish_time: row.finish_time != null ? String(row.finish_time) : null,
+    notes: row.notes != null ? String(row.notes) : null,
+    created_at: now,
+    updated_at: null,
+  };
+}
 
-pool.on("error", (err) => {
+function createMockPool(): Pool {
-  console.error("[db] Unexpected pool error:", err.message);
+  const emptyResult = <T extends QueryResultRow>(): QueryResult<T> =>
-});
+    ({
+      rows: [],
+      rowCount: 0,
+      command: "",
+      oid: 0,
+      fields: [],
+    }) as QueryResult<T>;
+
+  const mockQuery = async <T extends QueryResultRow>(
+    text: string,
+    params?: unknown[],
+  ): Promise<QueryResult<T>> => {
+    const sql = text.replace(/\s+/g, " ").trim();
+    const p = params ?? [];
+
+    if (sql.includes("DELETE FROM races")) {
+      return emptyResult();
+    }
+    if (sql.includes("INSERT INTO races") && sql.includes("RETURNING")) {
+      const row = mockRowFromInsert(text, p);
+      return {
+        rows: [row as unknown as T],
+        rowCount: 1,
+        command: "INSERT",
+        oid: 0,
+        fields: [],
+      } as QueryResult<T>;
+    }
+    if (sql.includes("UPDATE races") && sql.includes("RETURNING")) {
+      return emptyResult();
+    }
+    if (sql.includes("SELECT * FROM races")) {
+      return emptyResult();
+    }
+    return emptyResult();
+  };
+
+  const mockPool = {
+    query: mockQuery,
+    connect: async () => {
+      throw new Error(
+        "CALENDAR_RUN_MOCK_DB is enabled: migrate/seed require a real database; unset CALENDAR_RUN_MOCK_DB and configure DB_*.",
+      );
+    },
+    end: async () => {},
+    on() {
+      return mockPool;
+    },
+  };
+
+  return mockPool as unknown as Pool;
+}
+
+export const pool = config.useMockDb ? createMockPool() : new Pool(poolConfig);
+
+if (!config.useMockDb) {
+  pool.on("error", (err) => {
+    console.error("[db] Unexpected pool error:", err.message);
+  });
+} else {
+  console.warn("[db] Mock database enabled (CALENDAR_RUN_MOCK_DB); no PostgreSQL connection is used.");
+}
 
 export async function checkDbConnection(): Promise<boolean> {
+  if (config.useMockDb) {
+    return true;
+  }
   try {
     const client = await pool.connect();
     client.release();

backend/src/routes/races.ts

@@ -4,26 +4,77 @@ import { rowToDto, bodyToColumns, RaceRow } from "../mappers/race";
 
 const router = Router();
 
+type ValidationErrorBody = {
+  error: "validation_error";
+  details: string[];
+};
+
 function dbError(res: Response) {
   res.status(503).json({ error: "database_unavailable" });
 }
 
+function validationError(res: Response, details: string[]) {
+  const body: ValidationErrorBody = { error: "validation_error", details };
+  res.status(400).json(body);
+}
+
+function parseOptionalIntegerQuery(
+  value: unknown,
+  fieldName: string,
+  min?: number,
+  max?: number,
+): { value?: number; error?: string } {
+  if (value == null) {
+    return {};
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    return { error: `${fieldName} must be an integer` };
+  }
+
+  const normalized = value.trim();
+  if (!/^-?\d+$/.test(normalized)) {
+    return { error: `${fieldName} must be an integer` };
+  }
+
+  const parsed = Number(normalized);
+  if (!Number.isInteger(parsed)) {
+    return { error: `${fieldName} must be an integer` };
+  }
+
+  if (min != null && parsed < min) {
+    return { error: `${fieldName} must be between ${min} and ${max}` };
+  }
+  if (max != null && parsed > max) {
+    return { error: `${fieldName} must be between ${min} and ${max}` };
+  }
+
+  return { value: parsed };
+}
+
 /* ─── GET /races ──────────────────────────────────────────── */
 
 router.get("/races", async (req: Request, res: Response) => {
+  const yearResult = parseOptionalIntegerQuery(req.query.year, "year");
+  const monthResult = parseOptionalIntegerQuery(req.query.month, "month", 1, 12);
+  const details = [yearResult.error, monthResult.error].filter(Boolean) as string[];
+
+  if (details.length > 0) {
+    validationError(res, details);
+    return;
+  }
+
   try {
-    const { year, month } = req.query;
     const conditions: string[] = [];
     const params: unknown[] = [];
     let idx = 1;
 
-    if (year) {
+    if (yearResult.value != null) {
       conditions.push(`EXTRACT(YEAR FROM race_date) = $${idx++}`);
-      params.push(Number(year));
+      params.push(yearResult.value);
     }
-    if (month) {
+    if (monthResult.value != null) {
       conditions.push(`EXTRACT(MONTH FROM race_date) = $${idx++}`);
-      params.push(Number(month));
+      params.push(monthResult.value);
     }
 
     const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
@@ -46,7 +97,7 @@ router.get("/races/:id", async (req: Request, res: Response) => {
       [req.params.id],
     );
     if (rows.length === 0) {
-      res.status(404).json({ error: "not_found" });
+      res.status(404).json({ error: "not_found", details: ["Race not found"] });
       return;
     }
     res.json(rowToDto(rows[0]));
@@ -62,10 +113,7 @@ router.post("/races", async (req: Request, res: Response) => {
   const body = req.body;
 
   if (!body.id || !body.date || !body.title || body.distanceKm == null) {
-    res.status(400).json({
+    validationError(res, ["Fields id, date, title, distanceKm are required"]);
-      error: "validation_error",
-      details: ["Fields id, date, title, distanceKm are required"],
-    });
     return;
   }
 
@@ -81,7 +129,10 @@ router.post("/races", async (req: Request, res: Response) => {
     res.status(201).json(rowToDto(rows[0]));
   } catch (err: any) {
     if (err.code === "23505") {
-      res.status(409).json({ error: "conflict", details: ["Race with this id already exists"] });
+      res.status(409).json({
+        error: "conflict",
+        details: ["Race with this id already exists"],
+      });
       return;
     }
     console.error("[POST /races]", err);
@@ -95,10 +146,7 @@ router.patch("/races/:id", async (req: Request, res: Response) => {
   const { columns, values } = bodyToColumns(req.body);
 
   if (columns.length === 0) {
-    res.status(400).json({
+    validationError(res, ["No updatable fields provided"]);
-      error: "validation_error",
-      details: ["No updatable fields provided"],
-    });
     return;
   }
 
@@ -110,7 +158,7 @@ router.patch("/races/:id", async (req: Request, res: Response) => {
   try {
     const { rows } = await pool.query<RaceRow>(sql, values);
     if (rows.length === 0) {
-      res.status(404).json({ error: "not_found" });
+      res.status(404).json({ error: "not_found", details: ["Race not found"] });
       return;
     }
     res.json(rowToDto(rows[0]));
@@ -129,7 +177,7 @@ router.delete("/races/:id", async (req: Request, res: Response) => {
       [req.params.id],
     );
     if (rowCount === 0) {
-      res.status(404).json({ error: "not_found" });
+      res.status(404).json({ error: "not_found", details: ["Race not found"] });
       return;
     }
     res.status(204).end();

docs/agent-fix-backend-sync-instruction.md

@@ -0,0 +1,77 @@
+# Инструкция агенту: устранение рассинхронизации backend с планом/контрактом
+
+Документ описывает, как выполнить план исправлений **только через изменения кода** (без правок существующей документации в `docs/`).
+
+## 1) Ветка и границы задачи
+
+- Создать отдельную ветку по best practice, например: `fix/backend-api-validation-and-runtime-sync`.
+- Не менять существующие файлы документации в `docs/` как способ "починить" замечания.
+- Исправления вносятся в runtime-код и обязательные артефакты репозитория.
+
+## 2) Обязательные изменения в коде
+
+### A. Строгая валидация `GET /races`
+
+Файл: `backend/src/routes/races.ts`
+
+- Добавить явную проверку `year`:
+  - целое число;
+  - при невалидном значении вернуть `400`:
+    - `{"error":"validation_error","details":[...]}`
+- Добавить явную проверку `month`:
+  - целое число в диапазоне `1..12`;
+  - при невалидном значении вернуть `400` в том же формате.
+- Исключить передачу `NaN`/некорректных значений в SQL-параметры.
+
+### B. Разделение ошибок валидации и ошибок БД
+
+Файл: `backend/src/routes/races.ts`
+
+- `400` использовать только для ошибок входа (query/body/params).
+- `503 {"error":"database_unavailable"}` использовать только для технической недоступности БД.
+- Сохранить единый JSON-формат ошибок во всех CRUD-маршрутах.
+
+### C. Выравнивание конфигурации порта
+
+Файл: `backend/src/config.ts`
+
+- Поддержать оба env-подхода:
+  - приоритет `PORT`,
+  - затем `API_PORT`,
+  - затем fallback `3001`.
+
+### D. Обязательный root-артефакт
+
+Файл: `README.md` (в корне)
+
+- Создать базовый `README.md` с:
+  - кратким описанием проекта,
+  - минимальным quick start,
+  - ссылками на текущие документы backend/API.
+
+## 3) Допустимая реорганизация кода
+
+- Можно добавить небольшие локальные helper-функции в `backend/src/routes/races.ts`.
+- При необходимости можно вынести общие mapper/validator-хелперы в `backend/src/mappers/race.ts`, если это уменьшает дублирование.
+- Не усложнять архитектуру: только то, что нужно для контракта и устойчивого поведения API.
+
+## 4) Проверка результата
+
+Минимум выполнить:
+
+1. `npm run build` в `backend/` (типизация/сборка).
+2. Проверка диагностики/линтов по измененным backend-файлам.
+3. Smoke-сценарии API:
+   - `GET /health` -> `200`,
+   - `GET /ready` -> `200` при доступной БД или `503` при недоступной,
+   - `GET /races?year=bad` -> `400`,
+   - `GET /races?month=13` -> `400`,
+   - `GET /races?year=2026&month=5` -> корректный `200` и данные/пустой массив.
+
+## 5) Критерии готовности (Definition of Done)
+
+- Контракт валидации `GET /races` соблюден в runtime.
+- Валидационные ошибки не маскируются под `database_unavailable`.
+- Конфиг порта поддерживает `PORT` и `API_PORT` с правильным приоритетом.
+- В репозитории есть корневой `README.md`.
+- Никакие существующие документы в `docs/` не менялись для "закрытия" замечаний.

frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Calendar Run</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "calendar-run-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "@types/react": "^18.3.8",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.2",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.8"
+  }
+}

frontend/src/api/errors.ts

@@ -0,0 +1,75 @@
+export type ApiErrorCode =
+  | "validation_error"
+  | "not_found"
+  | "database_unavailable"
+  | "conflict"
+  | "network_error"
+  | "unknown_error";
+
+export interface ApiErrorPayload {
+  error?: string;
+  details?: string[];
+}
+
+export class ApiError extends Error {
+  public readonly code: ApiErrorCode;
+  public readonly status: number | null;
+  public readonly details: string[];
+
+  constructor(params: {
+    code: ApiErrorCode;
+    message: string;
+    status?: number | null;
+    details?: string[];
+  }) {
+    super(params.message);
+    this.name = "ApiError";
+    this.code = params.code;
+    this.status = params.status ?? null;
+    this.details = params.details ?? [];
+  }
+}
+
+function normalizeApiCode(value: string | undefined): ApiErrorCode {
+  if (
+    value === "validation_error" ||
+    value === "not_found" ||
+    value === "database_unavailable" ||
+    value === "conflict"
+  ) {
+    return value;
+  }
+  return "unknown_error";
+}
+
+export function toApiError(status: number, payload: unknown): ApiError {
+  const maybePayload = payload as ApiErrorPayload;
+  const code = normalizeApiCode(maybePayload?.error);
+  const details = Array.isArray(maybePayload?.details)
+    ? maybePayload.details.filter((item): item is string => typeof item === "string")
+    : [];
+
+  return new ApiError({
+    code,
+    status,
+    message: getApiErrorMessage(code),
+    details,
+  });
+}
+
+export function getApiErrorMessage(code: ApiErrorCode): string {
+  switch (code) {
+    case "validation_error":
+      return "Проверьте введённые данные и попробуйте снова.";
+    case "not_found":
+      return "Запись не найдена.";
+    case "database_unavailable":
+      return "Сервис временно недоступен. Попробуйте позже.";
+    case "conflict":
+      return "Запись с таким идентификатором уже существует.";
+    case "network_error":
+      return "Не удалось связаться с сервером.";
+    default:
+      return "Произошла неизвестная ошибка.";
+  }
+}

frontend/src/api/http.ts

@@ -0,0 +1,55 @@
+import { ApiError, toApiError } from "./errors";
+
+const API_BASE_URL = (import.meta.env.VITE_API_BASE_URL as string | undefined)?.trim() || "http://localhost:3001";
+
+function buildUrl(path: string): string {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${API_BASE_URL}${normalizedPath}`;
+}
+
+async function parseResponseBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    return null;
+  }
+
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+export async function requestJson<T>(path: string, init?: RequestInit): Promise<T> {
+  try {
+    const response = await fetch(buildUrl(path), {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        ...(init?.headers ?? {}),
+      },
+    });
+
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    const payload = await parseResponseBody(response);
+
+    if (!response.ok) {
+      throw toApiError(response.status, payload);
+    }
+
+    return payload as T;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+
+    throw new ApiError({
+      code: "network_error",
+      status: null,
+      message: "Не удалось связаться с сервером.",
+    });
+  }
+}

frontend/src/api/index.ts

@@ -0,0 +1,3 @@
+export type { CreateRacePayload, Race, RacesQuery, RaceStatus, UpdateRacePayload } from "./types";
+export { ApiError, getApiErrorMessage } from "./errors";
+export { getRaceById, getRaces, createRace, updateRace, deleteRace } from "./races";

frontend/src/api/races.ts

@@ -0,0 +1,112 @@
+import { ApiError } from "./errors";
+import { requestJson } from "./http";
+import type { CreateRacePayload, Race, RacesQuery, UpdateRacePayload } from "./types";
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function normalizeRace(input: unknown): Race {
+  const race = input as Partial<Race>;
+
+  const isValid =
+    isString(race?.id) &&
+    isString(race?.date) &&
+    isString(race?.title) &&
+    typeof race?.distanceKm === "number" &&
+    (race?.status === null || race?.status === "planned" || race?.status === "completed") &&
+    isNullableString(race?.officialUrl) &&
+    isNullableString(race?.startTime) &&
+    isNullableString(race?.clusterSchedule) &&
+    isNullableString(race?.bibPickup) &&
+    isNullableString(race?.bibNumber) &&
+    isNullableString(race?.finishTime) &&
+    isNullableString(race?.notes) &&
+    isString(race?.createdAt) &&
+    (race?.updatedAt === null || isString(race?.updatedAt));
+
+  if (!isValid) {
+    throw new ApiError({
+      code: "unknown_error",
+      status: null,
+      message: "Некорректный формат данных от API.",
+    });
+  }
+
+  return {
+    id: race.id,
+    date: race.date,
+    title: race.title,
+    distanceKm: race.distanceKm,
+    status: race.status,
+    officialUrl: race.officialUrl,
+    startTime: race.startTime,
+    clusterSchedule: race.clusterSchedule,
+    bibPickup: race.bibPickup,
+    bibNumber: race.bibNumber,
+    finishTime: race.finishTime,
+    notes: race.notes,
+    createdAt: race.createdAt,
+    updatedAt: race.updatedAt,
+  };
+}
+
+function buildRacesQuery(query?: RacesQuery): string {
+  if (!query) {
+    return "";
+  }
+
+  const params = new URLSearchParams();
+  if (typeof query.year === "number") {
+    params.set("year", String(query.year));
+  }
+  if (typeof query.month === "number") {
+    params.set("month", String(query.month));
+  }
+
+  const serialized = params.toString();
+  return serialized ? `?${serialized}` : "";
+}
+
+export async function getRaces(query?: RacesQuery): Promise<Race[]> {
+  const response = await requestJson<unknown[]>(`/races${buildRacesQuery(query)}`);
+  if (!Array.isArray(response)) {
+    throw new ApiError({
+      code: "unknown_error",
+      status: null,
+      message: "Некорректный формат списка забегов от API.",
+    });
+  }
+
+  return response.map(normalizeRace);
+}
+
+export async function getRaceById(id: string): Promise<Race> {
+  return normalizeRace(await requestJson<unknown>(`/races/${id}`));
+}
+
+export async function createRace(payload: CreateRacePayload): Promise<Race> {
+  return normalizeRace(
+    await requestJson<unknown>("/races", {
+      method: "POST",
+      body: JSON.stringify(payload),
+    }),
+  );
+}
+
+export async function updateRace(id: string, payload: UpdateRacePayload): Promise<Race> {
+  return normalizeRace(
+    await requestJson<unknown>(`/races/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify(payload),
+    }),
+  );
+}
+
+export async function deleteRace(id: string): Promise<void> {
+  await requestJson<void>(`/races/${id}`, { method: "DELETE" });
+}

frontend/src/api/types.ts

@@ -0,0 +1,40 @@
+export type RaceStatus = "planned" | "completed";
+
+export interface Race {
+  id: string;
+  date: string;
+  title: string;
+  distanceKm: number;
+  status: RaceStatus | null;
+  officialUrl: string | null;
+  startTime: string | null;
+  clusterSchedule: string | null;
+  bibPickup: string | null;
+  bibNumber: string | null;
+  finishTime: string | null;
+  notes: string | null;
+  createdAt: string;
+  updatedAt: string | null;
+}
+
+export interface RacesQuery {
+  year?: number;
+  month?: number;
+}
+
+export interface CreateRacePayload {
+  id: string;
+  date: string;
+  title: string;
+  distanceKm: number;
+  status?: RaceStatus | null;
+  officialUrl?: string | null;
+  startTime?: string | null;
+  clusterSchedule?: string | null;
+  bibPickup?: string | null;
+  bibNumber?: string | null;
+  finishTime?: string | null;
+  notes?: string | null;
+}
+
+export type UpdateRacePayload = Partial<Omit<CreateRacePayload, "id">>;

frontend/src/app/layouts/AppLayout.tsx

@@ -0,0 +1,33 @@
+import { NavLink, Outlet } from "react-router-dom";
+
+export function AppLayout(): JSX.Element {
+  return (
+    <div className="app-shell">
+      <header className="app-shell__header">
+        <div className="app-shell__brand">Calendar Run</div>
+        <nav className="app-shell__nav" aria-label="Primary navigation">
+          <NavLink
+            to="/"
+            end
+            className={({ isActive }) =>
+              isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+            }
+          >
+            Dashboard
+          </NavLink>
+          <NavLink
+            to="/races"
+            className={({ isActive }) =>
+              isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+            }
+          >
+            Races
+          </NavLink>
+        </nav>
+      </header>
+      <main className="app-shell__main">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

frontend/src/app/router.tsx

@@ -0,0 +1,17 @@
+import { createBrowserRouter } from "react-router-dom";
+import { AppLayout } from "./layouts/AppLayout";
+import { DashboardPage } from "../pages/DashboardPage";
+import { RacesPage } from "../pages/RacesPage";
+import { RaceDetailsPage } from "../pages/RaceDetailsPage";
+
+export const appRouter = createBrowserRouter([
+  {
+    path: "/",
+    element: <AppLayout />,
+    children: [
+      { index: true, element: <DashboardPage /> },
+      { path: "races", element: <RacesPage /> },
+      { path: "races/:raceId", element: <RaceDetailsPage /> },
+    ],
+  },
+]);

frontend/src/components/index.ts

@@ -0,0 +1 @@
+export {};

frontend/src/features/index.ts

@@ -0,0 +1 @@
+export {};

frontend/src/lib/index.ts

@@ -0,0 +1,11 @@
+export {
+  formatDistance,
+  formatRaceDate,
+  getPaceLabel,
+  getRaceCountdownLabel,
+  getRaceStatusLabel,
+  parseFinishTimeToSeconds,
+  sortByDateAsc,
+  sortByDateDesc,
+  splitRacesByDate,
+} from "./raceMetrics";

frontend/src/lib/raceMetrics.ts

@@ -0,0 +1,110 @@
+import type { Race } from "../api";
+
+const MS_IN_DAY = 24 * 60 * 60 * 1000;
+
+function parseRaceDate(date: string): Date {
+  return new Date(`${date}T00:00:00`);
+}
+
+export function parseFinishTimeToSeconds(value: string | null): number | null {
+  if (!value) {
+    return null;
+  }
+
+  const parts = value.split(":").map((part) => Number(part));
+  if (parts.some((part) => Number.isNaN(part) || part < 0)) {
+    return null;
+  }
+
+  if (parts.length === 2) {
+    const [minutes, seconds] = parts;
+    return minutes * 60 + seconds;
+  }
+
+  if (parts.length === 3) {
+    const [hours, minutes, seconds] = parts;
+    return hours * 3600 + minutes * 60 + seconds;
+  }
+
+  return null;
+}
+
+export function formatDistance(distanceKm: number): string {
+  return `${distanceKm.toLocaleString("ru-RU", { maximumFractionDigits: 1 })} км`;
+}
+
+export function formatRaceDate(date: string): string {
+  return parseRaceDate(date).toLocaleDateString("ru-RU", {
+    day: "2-digit",
+    month: "long",
+    year: "numeric",
+  });
+}
+
+export function sortByDateAsc(races: Race[]): Race[] {
+  return [...races].sort((left, right) => parseRaceDate(left.date).getTime() - parseRaceDate(right.date).getTime());
+}
+
+export function sortByDateDesc(races: Race[]): Race[] {
+  return [...races].sort((left, right) => parseRaceDate(right.date).getTime() - parseRaceDate(left.date).getTime());
+}
+
+export function splitRacesByDate(races: Race[], now: Date = new Date()): { upcoming: Race[]; past: Race[] } {
+  const today = new Date(now);
+  today.setHours(0, 0, 0, 0);
+
+  const upcoming: Race[] = [];
+  const past: Race[] = [];
+
+  for (const race of races) {
+    if (parseRaceDate(race.date).getTime() >= today.getTime()) {
+      upcoming.push(race);
+    } else {
+      past.push(race);
+    }
+  }
+
+  return {
+    upcoming: sortByDateAsc(upcoming),
+    past: sortByDateDesc(past),
+  };
+}
+
+export function getRaceCountdownLabel(date: string, now: Date = new Date()): string {
+  const today = new Date(now);
+  today.setHours(0, 0, 0, 0);
+
+  const target = parseRaceDate(date);
+  const days = Math.ceil((target.getTime() - today.getTime()) / MS_IN_DAY);
+
+  if (days <= 0) {
+    return "сегодня";
+  }
+  if (days === 1) {
+    return "через 1 день";
+  }
+  if (days < 5) {
+    return `через ${days} дня`;
+  }
+  return `через ${days} дней`;
+}
+
+export function getPaceLabel(finishTime: string | null, distanceKm: number): string | null {
+  const totalSeconds = parseFinishTimeToSeconds(finishTime);
+  if (!totalSeconds || distanceKm <= 0) {
+    return null;
+  }
+
+  const paceSeconds = Math.round(totalSeconds / distanceKm);
+  const paceMinutes = Math.floor(paceSeconds / 60);
+  const paceRemainder = paceSeconds % 60;
+
+  return `${String(paceMinutes).padStart(2, "0")}:${String(paceRemainder).padStart(2, "0")} /км`;
+}
+
+export function getRaceStatusLabel(status: Race["status"]): string {
+  if (status === "completed") {
+    return "пробежал";
+  }
+  return "планирую";
+}

frontend/src/main.tsx

@@ -0,0 +1,12 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { RouterProvider } from "react-router-dom";
+import { appRouter } from "./app/router";
+import "./styles/tokens.css";
+import "./styles/global.css";
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <RouterProvider router={appRouter} />
+  </React.StrictMode>
+);

frontend/src/pages/DashboardPage.tsx

@@ -0,0 +1,276 @@
+import { useEffect, useMemo, useState } from "react";
+import type { Race } from "../api";
+import { ApiError, getRaces } from "../api";
+import {
+  formatDistance,
+  formatRaceDate,
+  getRaceCountdownLabel,
+  getPaceLabel,
+  parseFinishTimeToSeconds,
+  splitRacesByDate,
+} from "../lib";
+
+const PR_DISTANCES = [5, 10, 21.1, 42.2] as const;
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить данные dashboard.";
+}
+
+function isSameDistance(left: number, right: number): boolean {
+  return Math.abs(left - right) < 0.05;
+}
+
+export function DashboardPage(): JSX.Element {
+  const [races, setRaces] = useState<Race[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    async function loadDashboardData(): Promise<void> {
+      try {
+        const items = await getRaces();
+        if (!isMounted) {
+          return;
+        }
+        setRaces(items);
+        setErrorMessage(null);
+      } catch (error) {
+        if (!isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadDashboardData();
+    return () => {
+      isMounted = false;
+    };
+  }, []);
+
+  const dashboardMetrics = useMemo(() => {
+    const { upcoming, past } = splitRacesByDate(races);
+    const completed = races.filter((race) => race.status === "completed");
+
+    const nextRace = upcoming[0] ?? null;
+    const lastResult = past.find((race) => race.status === "completed") ?? null;
+
+    let personalRecord: Race | null = null;
+    let personalRecordSeconds = Number.POSITIVE_INFINITY;
+
+    for (const race of completed) {
+      const finishSeconds = parseFinishTimeToSeconds(race.finishTime);
+      if (!finishSeconds) {
+        continue;
+      }
+
+      const candidate = finishSeconds / race.distanceKm;
+      if (candidate < personalRecordSeconds) {
+        personalRecordSeconds = candidate;
+        personalRecord = race;
+      }
+    }
+
+    const currentYear = new Date().getFullYear();
+    const seasonRaces = races.filter((race) => new Date(`${race.date}T00:00:00`).getFullYear() === currentYear);
+    const seasonCompleted = seasonRaces.filter((race) => race.status === "completed");
+
+    return {
+      nextRace,
+      lastResult,
+      personalRecord,
+      seasonTotal: seasonRaces.length,
+      seasonCompletedCount: seasonCompleted.length,
+    };
+  }, [races]);
+
+  const personalRecordsByDistance = useMemo(() => {
+    return PR_DISTANCES.map((distanceKm) => {
+      const candidates = races.filter((race) => {
+        return (
+          race.status === "completed" &&
+          isSameDistance(race.distanceKm, distanceKm) &&
+          Boolean(parseFinishTimeToSeconds(race.finishTime))
+        );
+      });
+
+      let bestRace: Race | null = null;
+      let bestPace = Number.POSITIVE_INFINITY;
+
+      for (const race of candidates) {
+        const totalSeconds = parseFinishTimeToSeconds(race.finishTime);
+        if (!totalSeconds) {
+          continue;
+        }
+
+        const paceSeconds = totalSeconds / race.distanceKm;
+        if (paceSeconds < bestPace) {
+          bestPace = paceSeconds;
+          bestRace = race;
+        }
+      }
+
+      return {
+        distanceKm,
+        bestRace,
+      };
+    });
+  }, [races]);
+
+  const comparisonRows = useMemo(() => {
+    return races
+      .filter((race) => race.status === "completed")
+      .map((race) => ({
+        id: race.id,
+        year: new Date(`${race.date}T00:00:00`).getFullYear(),
+        title: race.title,
+        distance: formatDistance(race.distanceKm),
+        finishTime: race.finishTime ?? "время не указано",
+        pace: getPaceLabel(race.finishTime, race.distanceKm) ?? "не удалось вычислить",
+        place: "нет данных",
+      }))
+      .sort((left, right) => right.year - left.year || left.title.localeCompare(right.title, "ru-RU"));
+  }, [races]);
+
+  if (isLoading) {
+    return (
+      <section className="page page--dashboard" aria-busy="true">
+        <h1 className="page__title">Dashboard</h1>
+        <p className="page__subtitle">Загружаем ваши старты...</p>
+      </section>
+    );
+  }
+
+  if (errorMessage) {
+    return (
+      <section className="page page--dashboard" role="alert">
+        <h1 className="page__title">Dashboard</h1>
+        <p className="page__subtitle page__subtitle--error">{errorMessage}</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="page page--dashboard">
+      <h1 className="page__title">Dashboard</h1>
+      <p className="page__subtitle">Ключевые метрики по вашему календарю стартов.</p>
+
+      <div className="dashboard-grid" aria-label="Ключевые метрики">
+        <article className="dashboard-card">
+          <h2 className="dashboard-card__title">Ближайший старт</h2>
+          {dashboardMetrics.nextRace ? (
+            <>
+              <p className="dashboard-card__value">{dashboardMetrics.nextRace.title}</p>
+              <p className="dashboard-card__meta">
+                {formatRaceDate(dashboardMetrics.nextRace.date)} · {formatDistance(dashboardMetrics.nextRace.distanceKm)}
+              </p>
+              <p className="dashboard-card__hint">{getRaceCountdownLabel(dashboardMetrics.nextRace.date)}</p>
+            </>
+          ) : (
+            <p className="dashboard-card__empty">Нет запланированных стартов.</p>
+          )}
+        </article>
+
+        <article className="dashboard-card">
+          <h2 className="dashboard-card__title">Последний результат</h2>
+          {dashboardMetrics.lastResult ? (
+            <>
+              <p className="dashboard-card__value">{dashboardMetrics.lastResult.finishTime ?? "время не указано"}</p>
+              <p className="dashboard-card__meta">
+                {dashboardMetrics.lastResult.title} · {formatDistance(dashboardMetrics.lastResult.distanceKm)}
+              </p>
+              <p className="dashboard-card__hint">{formatRaceDate(dashboardMetrics.lastResult.date)}</p>
+            </>
+          ) : (
+            <p className="dashboard-card__empty">Пока нет завершённых стартов.</p>
+          )}
+        </article>
+
+        <article className="dashboard-card">
+          <h2 className="dashboard-card__title">Личный рекорд</h2>
+          {dashboardMetrics.personalRecord ? (
+            <>
+              <p className="dashboard-card__value">{dashboardMetrics.personalRecord.finishTime ?? "время не указано"}</p>
+              <p className="dashboard-card__meta">
+                {dashboardMetrics.personalRecord.title} · {formatDistance(dashboardMetrics.personalRecord.distanceKm)}
+              </p>
+              <p className="dashboard-card__hint">Лучший темп среди завершённых стартов.</p>
+            </>
+          ) : (
+            <p className="dashboard-card__empty">Недостаточно данных для PR.</p>
+          )}
+        </article>
+
+        <article className="dashboard-card">
+          <h2 className="dashboard-card__title">Сезон</h2>
+          <p className="dashboard-card__value">{dashboardMetrics.seasonTotal}</p>
+          <p className="dashboard-card__meta">стартов в этом году</p>
+          <p className="dashboard-card__hint">Завершено: {dashboardMetrics.seasonCompletedCount}</p>
+        </article>
+      </div>
+
+      <section className="dashboard-section" aria-label="Личные рекорды по дистанциям">
+        <h2 className="dashboard-section__title">PR по дистанциям</h2>
+        <div className="dashboard-grid dashboard-grid--pr">
+          {personalRecordsByDistance.map((item) => (
+            <article key={item.distanceKm} className="dashboard-card">
+              <h3 className="dashboard-card__title">{formatDistance(item.distanceKm)}</h3>
+              {item.bestRace ? (
+                <>
+                  <p className="dashboard-card__value">{item.bestRace.finishTime ?? "время не указано"}</p>
+                  <p className="dashboard-card__meta">{item.bestRace.title}</p>
+                  <p className="dashboard-card__hint">{formatRaceDate(item.bestRace.date)}</p>
+                </>
+              ) : (
+                <p className="dashboard-card__empty">Нет завершённых стартов для этой дистанции.</p>
+              )}
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <section className="dashboard-section" aria-label="Сравнение завершённых стартов">
+        <h2 className="dashboard-section__title">Сравнение стартов</h2>
+        {comparisonRows.length > 0 ? (
+          <div className="comparison-table-wrapper">
+            <table className="comparison-table">
+              <thead>
+                <tr>
+                  <th>Год</th>
+                  <th>Старт</th>
+                  <th>Дистанция</th>
+                  <th>Время</th>
+                  <th>Темп</th>
+                  <th>Место</th>
+                </tr>
+              </thead>
+              <tbody>
+                {comparisonRows.map((row) => (
+                  <tr key={row.id}>
+                    <td>{row.year}</td>
+                    <td>{row.title}</td>
+                    <td>{row.distance}</td>
+                    <td>{row.finishTime}</td>
+                    <td>{row.pace}</td>
+                    <td>{row.place}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        ) : (
+          <p className="dashboard-card__empty">Нет completed-стартов для сравнения.</p>
+        )}
+      </section>
+    </section>
+  );
+}

frontend/src/pages/RaceDetailsPage.tsx

@@ -0,0 +1,159 @@
+import { useEffect, useMemo, useState } from "react";
+import { Link, useParams } from "react-router-dom";
+import { ApiError, getRaceById } from "../api";
+import { formatDistance, formatRaceDate, getPaceLabel, getRaceStatusLabel } from "../lib";
+import type { Race } from "../api";
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить карточку старта.";
+}
+
+export function RaceDetailsPage(): JSX.Element {
+  const { raceId } = useParams<{ raceId: string }>();
+  const [race, setRace] = useState<Race | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    async function loadRace(): Promise<void> {
+      if (!raceId) {
+        setErrorMessage("Не найден идентификатор старта.");
+        setIsLoading(false);
+        return;
+      }
+
+      try {
+        const item = await getRaceById(raceId);
+        if (!isMounted) {
+          return;
+        }
+        setRace(item);
+        setErrorMessage(null);
+      } catch (error) {
+        if (!isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadRace();
+    return () => {
+      isMounted = false;
+    };
+  }, [raceId]);
+
+  const paceLabel = useMemo(() => {
+    if (!race || race.status !== "completed") {
+      return null;
+    }
+    return getPaceLabel(race.finishTime, race.distanceKm);
+  }, [race]);
+
+  if (isLoading) {
+    return (
+      <section className="page page--race-details" aria-busy="true">
+        <h1 className="page__title">Карточка старта</h1>
+        <p className="page__subtitle">Загружаем данные старта...</p>
+      </section>
+    );
+  }
+
+  if (errorMessage || !race) {
+    return (
+      <section className="page page--race-details" role="alert">
+        <h1 className="page__title">Карточка старта</h1>
+        <p className="page__subtitle page__subtitle--error">{errorMessage ?? "Старт не найден."}</p>
+        <Link className="page-link" to="/races">
+          Вернуться к списку стартов
+        </Link>
+      </section>
+    );
+  }
+
+  const isCompleted = race.status === "completed";
+
+  return (
+    <section className="page page--race-details">
+      <div className="race-details-header">
+        <div className="race-details-header__main">
+          <h1 className="page__title">{race.title}</h1>
+          <p className="page__subtitle">
+            {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
+          </p>
+        </div>
+        <span
+          className={
+            isCompleted
+              ? "race-card__status race-card__status--completed"
+              : "race-card__status race-card__status--planned"
+          }
+        >
+          {getRaceStatusLabel(race.status)}
+        </span>
+      </div>
+
+      <div className="race-details-grid">
+        <article className="race-details-card">
+          <h2 className="race-details-card__title">Основная информация</h2>
+          <dl className="race-details-meta">
+            <div className="race-details-meta__item">
+              <dt className="race-details-meta__key">Дата</dt>
+              <dd className="race-details-meta__value">{formatRaceDate(race.date)}</dd>
+            </div>
+            <div className="race-details-meta__item">
+              <dt className="race-details-meta__key">Дистанция</dt>
+              <dd className="race-details-meta__value">{formatDistance(race.distanceKm)}</dd>
+            </div>
+            <div className="race-details-meta__item">
+              <dt className="race-details-meta__key">Статус</dt>
+              <dd className="race-details-meta__value">{getRaceStatusLabel(race.status)}</dd>
+            </div>
+          </dl>
+        </article>
+
+        <article className="race-details-card">
+          <h2 className="race-details-card__title">Completed-метрики</h2>
+          {isCompleted ? (
+            <dl className="race-details-meta">
+              <div className="race-details-meta__item">
+                <dt className="race-details-meta__key">Время</dt>
+                <dd className="race-details-meta__value">{race.finishTime ?? "время не указано"}</dd>
+              </div>
+              <div className="race-details-meta__item">
+                <dt className="race-details-meta__key">Темп</dt>
+                <dd className="race-details-meta__value">{paceLabel ?? "не удалось вычислить"}</dd>
+              </div>
+              <div className="race-details-meta__item">
+                <dt className="race-details-meta__key">Стартовый номер</dt>
+                <dd className="race-details-meta__value">{race.bibNumber ?? "не указан"}</dd>
+              </div>
+            </dl>
+          ) : (
+            <p className="race-details-card__empty">
+              Метрики появятся после завершения старта и ввода результата.
+            </p>
+          )}
+        </article>
+      </div>
+
+      <article className="race-details-card race-details-card--notes">
+        <h2 className="race-details-card__title">Заметки</h2>
+        <p className="race-details-card__notes">{race.notes?.trim() ? race.notes : "Заметок пока нет."}</p>
+      </article>
+
+      <Link className="page-link" to="/races">
+        Назад к календарю стартов
+      </Link>
+    </section>
+  );
+}

frontend/src/pages/RacesPage.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useMemo, useState } from "react";
+import { Link } from "react-router-dom";
+import type { Race } from "../api";
+import { ApiError, getRaces } from "../api";
+import { formatDistance, formatRaceDate, getRaceStatusLabel, splitRacesByDate } from "../lib";
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить календарь стартов.";
+}
+
+function RaceList(props: { title: string; races: Race[] }): JSX.Element {
+  const { title, races } = props;
+
+  return (
+    <section className="race-list" aria-label={title}>
+      <h2 className="race-list__title">{title}</h2>
+      {races.length > 0 ? (
+        <ul className="race-list__items">
+          {races.map((race) => (
+            <li key={race.id} className="race-card">
+              <div className="race-card__main">
+                <p className="race-card__title">
+                  <Link className="race-card__link" to={`/races/${race.id}`}>
+                    {race.title}
+                  </Link>
+                </p>
+                <p className="race-card__meta">
+                  {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
+                </p>
+              </div>
+              <span
+                className={
+                  race.status === "completed"
+                    ? "race-card__status race-card__status--completed"
+                    : "race-card__status race-card__status--planned"
+                }
+              >
+                {getRaceStatusLabel(race.status)}
+              </span>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p className="race-list__empty">Пока нет данных в этом разделе.</p>
+      )}
+    </section>
+  );
+}
+
+export function RacesPage(): JSX.Element {
+  const [races, setRaces] = useState<Race[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    async function loadRaces(): Promise<void> {
+      try {
+        const items = await getRaces();
+        if (!isMounted) {
+          return;
+        }
+        setRaces(items);
+        setErrorMessage(null);
+      } catch (error) {
+        if (!isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadRaces();
+    return () => {
+      isMounted = false;
+    };
+  }, []);
+
+  const { upcoming, past } = useMemo(() => splitRacesByDate(races), [races]);
+
+  if (isLoading) {
+    return (
+      <section className="page page--races" aria-busy="true">
+        <h1 className="page__title">Календарь стартов</h1>
+        <p className="page__subtitle">Загружаем данные...</p>
+      </section>
+    );
+  }
+
+  if (errorMessage) {
+    return (
+      <section className="page page--races" role="alert">
+        <h1 className="page__title">Календарь стартов</h1>
+        <p className="page__subtitle page__subtitle--error">{errorMessage}</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="page page--races">
+      <h1 className="page__title">Календарь стартов</h1>
+      <p className="page__subtitle">Будущие и прошедшие старты в одном месте.</p>
+
+      <div className="race-lists">
+        <RaceList title="Будущие" races={upcoming} />
+        <RaceList title="Прошедшие" races={past} />
+      </div>
+    </section>
+  );
+}

frontend/src/styles/global.css

@@ -0,0 +1,343 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: var(--font-family-base);
+  font-size: var(--font-size-body);
+  line-height: var(--line-height-base);
+  background: var(--color-bg);
+  color: var(--color-text);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.app-shell {
+  min-height: 100vh;
+  display: grid;
+  grid-template-rows: auto 1fr;
+}
+
+.app-shell__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+  padding: var(--space-4) var(--space-6);
+  background: var(--color-surface);
+  border-bottom: 1px solid var(--color-border);
+}
+
+.app-shell__brand {
+  font-size: var(--font-size-h2);
+  font-weight: 700;
+}
+
+.app-shell__nav {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.app-shell__link {
+  padding: var(--space-2) var(--space-3);
+  border-radius: var(--radius-sm);
+  color: var(--color-text-muted);
+}
+
+.app-shell__link:hover,
+.app-shell__link:focus-visible {
+  color: var(--color-text);
+  background: #eef2f6;
+  outline: none;
+}
+
+.app-shell__link--active {
+  color: var(--color-surface);
+  background: var(--color-accent);
+}
+
+.app-shell__main {
+  width: min(1080px, 100%);
+  margin: 0 auto;
+  padding: var(--space-6);
+}
+
+.page {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-6);
+}
+
+.page__title {
+  margin: 0 0 var(--space-2);
+  font-size: var(--font-size-h1);
+}
+
+.page__subtitle {
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.page__subtitle--error {
+  color: var(--color-error);
+}
+
+.dashboard-grid {
+  margin-top: var(--space-6);
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-4);
+}
+
+.dashboard-card {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  background: #fcfdff;
+}
+
+.dashboard-card__title {
+  margin: 0 0 var(--space-3);
+  font-size: var(--font-size-body);
+  color: var(--color-text-muted);
+}
+
+.dashboard-card__value {
+  margin: 0;
+  font-size: var(--font-size-h2);
+  font-weight: 700;
+  color: var(--color-text);
+}
+
+.dashboard-card__meta {
+  margin: var(--space-2) 0 0;
+  color: var(--color-text);
+}
+
+.dashboard-card__hint,
+.dashboard-card__empty {
+  margin: var(--space-2) 0 0;
+  color: var(--color-text-muted);
+  font-size: var(--font-size-caption);
+}
+
+.dashboard-section {
+  margin-top: var(--space-6);
+}
+
+.dashboard-section__title {
+  margin: 0 0 var(--space-4);
+  font-size: var(--font-size-h2);
+}
+
+.dashboard-grid--pr {
+  margin-top: 0;
+}
+
+.comparison-table-wrapper {
+  overflow-x: auto;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: #fcfdff;
+}
+
+.comparison-table {
+  width: 100%;
+  border-collapse: collapse;
+  min-width: 720px;
+}
+
+.comparison-table th,
+.comparison-table td {
+  padding: var(--space-3);
+  text-align: left;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.comparison-table th {
+  color: var(--color-text-muted);
+  font-size: var(--font-size-caption);
+  font-weight: 600;
+}
+
+.comparison-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.race-lists {
+  margin-top: var(--space-6);
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-4);
+}
+
+.race-list {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  background: #fcfdff;
+}
+
+.race-list__title {
+  margin: 0 0 var(--space-4);
+  font-size: var(--font-size-h2);
+}
+
+.race-list__items {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: grid;
+  gap: var(--space-3);
+}
+
+.race-list__empty {
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.race-card {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  padding: var(--space-3);
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-3);
+  background: var(--color-surface);
+}
+
+.race-card__title {
+  margin: 0;
+  font-weight: 600;
+}
+
+.race-card__link:hover,
+.race-card__link:focus-visible {
+  text-decoration: underline;
+  outline: none;
+}
+
+.race-card__meta {
+  margin: var(--space-2) 0 0;
+  color: var(--color-text-muted);
+  font-size: var(--font-size-caption);
+}
+
+.race-card__status {
+  display: inline-flex;
+  align-items: center;
+  white-space: nowrap;
+  border-radius: 999px;
+  padding: 0.2rem 0.5rem;
+  font-size: var(--font-size-caption);
+  font-weight: 600;
+}
+
+.race-card__status--planned {
+  background: #edf3ff;
+  color: var(--color-accent);
+}
+
+.race-card__status--completed {
+  background: #ecf8f1;
+  color: var(--color-success);
+}
+
+.page-link {
+  margin-top: var(--space-4);
+  display: inline-flex;
+  color: var(--color-accent);
+  font-weight: 600;
+}
+
+.page-link:hover,
+.page-link:focus-visible {
+  text-decoration: underline;
+  outline: none;
+}
+
+.race-details-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-4);
+}
+
+.race-details-grid {
+  margin-top: var(--space-6);
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-4);
+}
+
+.race-details-card {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  background: #fcfdff;
+}
+
+.race-details-card--notes {
+  margin-top: var(--space-4);
+}
+
+.race-details-card__title {
+  margin: 0 0 var(--space-3);
+  font-size: var(--font-size-body);
+  color: var(--color-text-muted);
+}
+
+.race-details-card__empty,
+.race-details-card__notes {
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.race-details-meta {
+  margin: 0;
+  display: grid;
+  gap: var(--space-3);
+}
+
+.race-details-meta__item {
+  display: grid;
+  gap: var(--space-1);
+}
+
+.race-details-meta__key {
+  color: var(--color-text-muted);
+  font-size: var(--font-size-caption);
+}
+
+.race-details-meta__value {
+  margin: 0;
+  font-weight: 600;
+  color: var(--color-text);
+}
+
+@media (max-width: 900px) {
+  .dashboard-grid,
+  .race-lists,
+  .race-details-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .race-details-header {
+    flex-direction: column;
+  }
+}

frontend/src/styles/tokens.css

@@ -0,0 +1,29 @@
+:root {
+  --color-bg: #f3f5f7;
+  --color-surface: #ffffff;
+  --color-text: #13202b;
+  --color-text-muted: #5d6b77;
+  --color-accent: #1f7ae0;
+  --color-border: #dce2e8;
+  --color-success: #2f9e63;
+  --color-warning: #c0821f;
+  --color-error: #cc3a3a;
+
+  --font-family-base: "Inter", "Segoe UI", Arial, sans-serif;
+  --font-size-h1: 2rem;
+  --font-size-h2: 1.5rem;
+  --font-size-body: 1rem;
+  --font-size-caption: 0.875rem;
+  --line-height-base: 1.5;
+
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.25rem;
+  --space-6: 1.5rem;
+  --space-8: 2rem;
+
+  --radius-sm: 0.375rem;
+  --radius-md: 0.75rem;
+  --radius-lg: 1rem;
+}

frontend/tsconfig.app.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.app.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/main.tsx","./src/api/index.ts","./src/app/router.tsx","./src/app/layouts/applayout.tsx","./src/components/index.ts","./src/features/index.ts","./src/lib/index.ts","./src/pages/dashboardpage.tsx","./src/pages/racespage.tsx"],"version":"5.9.3"}

frontend/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

frontend/tsconfig.node.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowSyntheticDefaultImports": true,
+    "types": ["node"],
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

frontend/vite.config.js

@@ -0,0 +1,5 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+export default defineConfig({
+    plugins: [react()]
+});

frontend/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()]
+});