Merge pull request 'feature/registration-auth' (#37) from feature/registration-auth into main

Reviewed-on: #37

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+**/node_modules
+**/dist
+.env
+.env.*
+!.env.example
+**/*.md
+.cursor
+*.log

.env.example

@@ -1,18 +1,66 @@
-# ─── PostgreSQL ───────────────────────────────────────────────
+# =============================================================================
+# Корневой шаблон окружения: локальная разработка, docker-compose.yml (Postgres)
+# и docker-compose.stack.yml (backend + frontend в общей сети с Postgres).
+# Скопируйте в .env и подставьте значения. Файл .env не коммитьте.
+# =============================================================================
+
+# ─── Подключение бэкенда к PostgreSQL ──────────────────────────
+# Локально + docker-compose из этого репо: DB_HOST=localhost, DB_PORT=5432
+# Backend в Docker рядом с Postgres: DB_HOST = имя контейнера/сервиса в той же
+# docker-сети (например postgres_budget), DB_PORT=5432 (внутренний порт Postgres).
 DB_HOST=localhost
 DB_PORT=5432
 DB_NAME=calendar_run
 DB_USER=calendar_user
-DB_PASSWORD=calendar_pass
+DB_PASSWORD=replace_with_strong_secret
 
-# ─── Backend API ──────────────────────────────────────────────
-# Port the API server listens on
+# ─── Backend API ───────────────────────────────────────────────
+# Порт процесса: сначала PORT, иначе API_PORT, иначе 3001.
+# В docker-compose.stack.yml для контейнера задаётся PORT=3000 (см. compose).
+# PORT=3000
 API_PORT=3001
 
-# ─── CORS ─────────────────────────────────────────────────────
-# Allowed origin for the frontend (Vite dev server default)
+# ─── Режим без БД (только тесты / smoke API, не для migrate/seed) ─
+# CALENDAR_RUN_MOCK_DB=1
+
+# ─── CORS ────────────────────────────────────────────────────
+# Должен совпадать с origin в браузере (схема + хост + порт, без пути), иначе API «молчит».
+# Локальный Vite: http://localhost:5173
+# Стек с фронтом на 3033: http://localhost:3033
+# Прод: https://ваш-домен  — несколько origin через запятую: https://a.ru,https://www.a.ru
 CORS_ORIGIN=http://localhost:5173
 
-# ─── Frontend (Vite) ─────────────────────────────────────────
-# Public URL of the API, used in SPA code via import.meta.env
-VITE_API_BASE_URL=http://localhost:3001
+# ─── Auth / sessions ─────────────────────────────────────────
+# APP_BASE_URL is the only source for verify/reset email links.
+APP_BASE_URL=http://localhost:5173
+SESSION_SECRET=replace_with_32plus_char_random_secret
+# Production defaults to __Host-sid + Secure cookies. Local dev can stay insecure over http.
+# SESSION_COOKIE_NAME=__Host-sid
+# SESSION_COOKIE_SECURE=true
+# SESSION_TTL_DAYS=30
+# AUTH_CLEANUP_INTERVAL_HOURS=24
+
+# ─── Cloudflare Turnstile ────────────────────────────────────
+TURNSTILE_SECRET_KEY=replace_with_turnstile_secret
+# Local tests/dev only, rejected in production:
+# TURNSTILE_BYPASS_TOKEN=mock-turnstile-token
+
+# ─── SMTP email ──────────────────────────────────────────────
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=replace_with_smtp_user
+SMTP_PASSWORD=replace_with_smtp_password
+SMTP_FROM=Calendar Run <no-reply@example.com>
+
+# ─── Seed after auth ─────────────────────────────────────────
+# Required once users exist, so seed never creates ownerless races or overwrites user edits.
+# SEED_OWNER_USER_ID=
+# SEED_OWNER_EMAIL=
+
+# ─── Версия API (опционально) ─────────────────────────────────
+# Если в образе не удаётся прочитать package.json, подставьте вручную (видно в GET /health).
+# APP_VERSION=1.0.0
+
+# ─── Frontend (Vite, локально из каталога frontend/) ─────────
+# Браузер всегда ходит на относительный /api; в dev это проксирует Vite.

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: |
+            backend/package-lock.json
+            frontend/package-lock.json
+
+      - name: Backend — install, build, test
+        working-directory: backend
+        env:
+          CALENDAR_RUN_MOCK_DB: "1"
+        run: |
+          npm ci
+          npm run build
+          npm test
+
+      - name: Frontend — install, build
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 .env
 *.log
+.DS_Store

Dockerfile.backend

@@ -0,0 +1,22 @@
+# Сборка из корня монорепо: docker build -f Dockerfile.backend .
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY backend/package.json backend/package-lock.json ./
+RUN npm ci
+
+FROM deps AS build
+COPY backend/tsconfig.json ./
+COPY backend/src ./src
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY backend/package.json backend/package-lock.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+COPY backend/migrations ./migrations
+COPY import ./import
+EXPOSE 3000
+ENV PORT=3000
+CMD ["node", "dist/index.js"]

Dockerfile.frontend

@@ -0,0 +1,13 @@
+# Сборка из корня монорепо: docker build -f Dockerfile.frontend .
+# SPA дергает API по префиксу /api (nginx проксирует на сервис runners-calendar-backend:3000).
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+COPY docker/nginx.frontend.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80

PLAN.md

@@ -1,196 +0,0 @@
-# План: календарь забегов (SPA + API + PostgreSQL)
-
-Консолидированный план реализации с актуальными решениями. После инициализации git — работать в отдельной ветке (например `feature/race-calendar-app`).
-
-## 1. Цели продукта
-
-1. **Расписание по месяцу** — выбор месяца/года, список забегов.
-2. **Расписание на год** — календарная сетка года, отметки на датах со стартами; по клику на дату — модалка/панель со списком забегов и переход на карточку.
-3. Добавлять забеги **запланированные** и **уже прошедшие**.
-4. Для **прошедших** — ввод/редактирование **результата** и **стартового номера**; поля можно дописать позже.
-5. **Личные рекорды** на главной по дистанциям: 1 км, 5 км, 10 км, 15 км, 21.1 км, 42.2 км — обновляются, если в забеге указан более быстрый результат на «подходящей» дистанции.
-6. **Старты (организатор):** дата и время старта, расписание кластеров, выдача номеров — **ручной ввод**; обязательна возможность указать **официальную ссылку** на страницу организатора (автопарсинг сайтов не входит в объём).
-7. **Авторизация не требуется.**
-
-## 2. Исходные данные в репозитории
-
-- Файл `import/races_2026_calendar.csv` — колонки `date`, `month`, `day`, `event`, `distance_km`.
-- Назначение CSV: **один раз** — как вход для **seed-скрипта**, который пишет строки в PostgreSQL.
-- **В рантайме** ни фронт, ни API этот CSV **не читают**. После успешного seed файл может оставаться в репо только как архив/референс.
-
-## 3. Стек и структура репозитория
-
-- **Монорепозиторий:** `frontend/` (Vite + React 18 + TypeScript + react-router-dom) и `backend/` (Node.js + Fastify или Express).
-- **БД:** PostgreSQL; схема — SQL-миграции в `backend/` (или согласованный каталог миграций).
-- **Локально:** `docker-compose.yml` с сервисом Postgres.
-- **Стили:** CSS + **BEM** + CSS variables (минимальная дизайн-система: цвета, отступы, типографика).
-- **Даты/время:** `date-fns` или `Intl`, русская локаль там, где нужно.
-
-### 3.1 Переменные окружения
-
-**Только на сервере API (никогда не во фронт-бандле):**
-
-```env
-DB_HOST=
-DB_PORT=
-DB_NAME=
-DB_USER=
-DB_PASSWORD=
-```
-
-Дополнительно по необходимости: `PORT` или `API_PORT`, `NODE_ENV`, `CORS_ORIGIN`.
-
-**Фронтенд (Vite):** только публичный адрес API, например:
-
-```env
-VITE_API_BASE_URL=http://localhost:3001
-```
-
-В коде: `import.meta.env.VITE_API_BASE_URL`.
-
-Шаблон без секретов — корневой `.env.example`; описание — в `docs/frontend.md` и `docs/backend.md`.
-
-## 4. Источник правды и поток данных
-
-### 4.1 Рантайм
-
-Единственный источник правды для календаря и карточек в работающем приложении — **PostgreSQL**. SPA общается **только с HTTP API**.
-
-**localStorage не используется** для хранения забегов или «дельт».
-
-```mermaid
-flowchart LR
-  User[User]
-  SPA[React SPA]
-  API[Node API]
-  DB[(PostgreSQL)]
-  User --> SPA
-  SPA -->|"fetch VITE_API_BASE_URL"| API
-  API -->|"DB_* connection"| DB
-```
-
-### 4.2 Вне рантайма (разово)
-
-**Seed-скрипт** (запуск вручную при развёртывании/обновлении стартового набора):
-
-- Читает `import/*.csv` и/или опционально `public/data/races.json`.
-- Выполняет `INSERT` / upsert в таблицу `races`.
-- Не вызывается из SPA и не выполняется на каждом HTTP-запросе.
-
-Промежуточная ступень **CSV → races.json для работы SPA не обязательна**: seed может писать в БД напрямую из CSV и/или из JSON.
-
-### 4.3 Разовый перенос CSV → БД
-
-- Парсинг: заголовок; кавычки в `event`; `distance_km` — число; `date` — `YYYY-MM-DD`.
-- После переноса приложение в обычном режиме **не использует** `import/races_2026_calendar.csv`. Новые старты — через UI/API (или отдельная админ-фича импорта, если появится позже).
-
-## 5. Модель данных (БД и API)
-
-Один набор полей — в таблице, в JSON тел запросов/ответов API и в опциональном файле для seed. Согласовать **camelCase в API** и **snake_case в SQL** в `docs/backend.md`.
-
-| Поле | Обяз. | Примечание |
-| ------ | ------- | ------------ |
-| `id` | да | Стабильный ключ, напр. `2026-05-03-kazan-marathon` |
-| `date` | да | День старта `YYYY-MM-DD` |
-| `title` | да | Название |
-| `distanceKm` | да | Число км |
-| `status` | нет | `planned` / `completed`; иначе можно вывести из даты |
-| `officialUrl` | нет | Ссылка на организатора |
-| `startTime` | нет | Напр. `09:30` |
-| `clusterSchedule` | нет | Многострочный текст |
-| `bibPickup` | нет | Выдача номеров |
-| `bibNumber` | нет | Стартовый номер |
-| `finishTime` | нет | Время H:MM:SS / HH:MM:SS; для PR — перевод в секунды |
-| `notes` | нет | Заметки |
-
-Опционально в миграциях: `created_at`, `updated_at`.
-
-**Операции:** `GET` список/фильтры по году-месяцу при необходимости, `GET :id`, `POST`, `PATCH :id`, при необходимости `DELETE` — зафиксировать в `docs/backend.md`.
-
-## 6. Поведение SPA
-
-### 6.1 Форма «Добавить забег»
-
-- Обязательно: дата, название, дистанция.
-- Если дата **строго до сегодня** (локальная дата пользователя) — показать **результат** и **стартовый номер** (необязательны при первом сохранении).
-- Если дата в будущем — поля результата скрыты.
-- Опционально: чекбокс «Уже прошёл» для случая **сегодняшней** даты, чтобы открыть поля результата.
-- Сохранение: **`POST`** на API → запись в БД.
-
-### 6.2 Страница забега
-
-- Все поля модели; для прошедших — акцент на результат и номер.
-- Редактирование результата и номера **в любой момент**: **`PATCH`** на API, затем обновление состояния на клиенте (refetch / инвалидация кэша).
-
-### 6.3 Личные рекорды
-
-- Дистанции: 1, 5, 10, 15, 21.1, 42.2 км.
-- Учитывать забеги с заполненным `finishTime` и дистанцией в пределах допуска к целевой (напр. 21.0975 → 21.1, 42.195 → 42.2).
-- «Чужие» дистанции (2 км, 6 км, 30 км…) в таблицу PR по умолчанию **не** включаются.
-- Расчёт на клиенте по данным, полученным с API.
-
-### 6.4 Экраны
-
-1. Главная — PR, навигация «Месяц» / «Год», ближайшие старты.
-2. Месяц — селектор, список.
-3. Год — сетка, маркеры, клик по дате → модалка со списком → карточка.
-4. Карточка забега, форма добавления.
-5. Доступность модалки: фокус, Esc, контраст.
-
-## 7. Документация
-
-Создать каталог **`docs/`**:
-
-| Файл | Назначение |
-| ------ | ------------ |
-| `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` без реальных секретов.
-- Актуальные данные после работы в UI — в **БД**; файлы в git не синхронизируются с правками автоматически. Надёжный бэкап — **резервное копирование PostgreSQL**.
-- Деплой: Postgres + процесс API с env + статическая раздача фронта (или иная схема хостинга — описать в README).
-- Данные организаторов (расписание стартов) — **вручную** + ссылка; без парсинга чужих сайтов в объёме первой версии.
-
-## 9. Ключевые пути после реализации
-
-- `docker-compose.yml`, `.env.example`
-- `backend/` — сервер, миграции, роуты
-- `scripts/` или `backend/scripts/` — **разовый** seed из CSV/JSON
-- `import/races_2026_calendar.csv` — только вход seed (не рантайм)
-- `public/data/races.json` — опциональный вход seed
-- `frontend/src/api/` — клиент API
-- `frontend/src/pages/`, `frontend/src/components/` — UI (BEM)
-- `frontend/src/lib/distances.ts` — PR
-- `docs/*.md`, `README.md`
-
-## 10. Чеклист задач (implementation todos)
-
-1. Монорепо: `frontend/` + `backend/`, BEM, токены, роутер.
-2. Postgres в docker-compose, миграции таблицы `races`, бэкенд читает `DB_*`.
-3. REST CRUD + разовый seed (CSV и/или JSON) → БД.
-4. Клиент API на фронте, типы, загрузка данных для экранов и PR.
-5. Экраны месяц и год, модалка по дате.
-6. Форма добавления с условными полями; карточка с PATCH результата/номера.
-7. Поля организатора на карточке.
-8. A11y модалки, мобильная вёрстка, смоук-сценарии.
-9. `docs/` + README + `.env.example`.
-
-## 11. Идеи на будущее (тематика бега)
-
-- Недельный объём / простой план подготовки.
-- Импорт/экспорт JSON для бэкапа через API.
-- Фильтры (город, дистанция), погода по дню старта.
-- График динамики PR.
-- Загрузка GPX / тренировки.
-- Браузерные напоминания за N дней до старта.
-- Сравнение результатов одной дистанции по годам.
-- PWA для офлайн-просмотра (read-only кэш не заменяет БД без продуманной синхронизации).
-
----
-
-*Документ создан как единый актуальный план в корне репозитория. При расхождениях с черновиками в IDE приоритет у этого файла.*

README.md

@@ -0,0 +1,49 @@
+# Calendar Run
+
+Монорепозиторий: **backend** (Express + PostgreSQL) и **frontend** (React + Vite) — календарь забегов.
+
+## Переменные окружения
+
+Один шаблон для локальной разработки и для Docker-стека: `**[.env.example](.env.example)`** → скопируйте в `**.env**` в корне репозитория.
+
+Там же перечислены `**DB_HOST**`, `**DB_PORT**`, `**DB_NAME**`, `**DB_USER**`, `**DB_PASSWORD**` (подключение бэкенда к БД), `**PORT**` / `**API_PORT**`, опционально `**CALENDAR_RUN_MOCK_DB**` и `**CORS_ORIGIN**`.
+
+## Backend — локально
+
+1. `cd backend && npm install`
+2. Корень: `cp .env.example .env`, задайте `DB_*` (и при необходимости `CORS_ORIGIN`).
+3. Postgres: из корня `docker compose up -d` (см. `[docker-compose.yml](docker-compose.yml)`) — в compose используются те же `DB_NAME`, `DB_USER`, `DB_PASSWORD` из `.env`.
+4. `cd backend && npm run db:migrate && npm run seed`
+5. Dev-режим: `npm run dev`
+6. Или production: `npm run build && npm start`
+
+Без PostgreSQL (только smoke API): в `.env` задайте `CALENDAR_RUN_MOCK_DB=1`; `**db:migrate` и `seed` с mock не использовать**.
+
+## Frontend — локально
+
+```bash
+cd frontend
+cp .env.example .env
+npm install
+npm run dev
+```
+
+Фронт всегда отправляет запросы на относительный префикс `**/api**`. В dev это проксирует Vite на `http://localhost:3001`, в Docker/проде — nginx фронта проксирует на `runners-calendar-backend:3000`. У бэкенда `CORS_ORIGIN` должен совпадать с origin приложения (например `http://localhost:5173`).
+
+## Docker: backend + frontend рядом с Postgres
+
+Используйте `[docker-compose.stack.yml](docker-compose.stack.yml)`: общая **внешняя** сеть с контейнером Postgres (как в вашей инфраструктуре). В корне должен быть `**.env`** (из `.env.example`): `DB_HOST` — имя сервиса/контейнера Postgres в этой сети, `DB_PORT=5432`, плюс остальные `DB_*` и `**CORS_ORIGIN=http://localhost:3033**`, если заходите на фронт с хоста на порту 3033.
+
+```bash
+docker compose -f docker-compose.stack.yml up -d --build
+docker compose -f docker-compose.stack.yml exec runners-calendar-backend node dist/migrate.js
+docker compose -f docker-compose.stack.yml exec runners-calendar-backend node dist/seed.js
+```
+
+Фронт в браузере обращается к API по префиксу `**/api**` (nginx в образе фронта проксирует на сервис `runners-calendar-backend` в той же сети).
+
+## Документация API и бэкенда
+
+- [Шпаргалка API для фронта](docs/backend-api-for-frontend.md)
+- [Эксплуатация backend](docs/backend.md)
+

backend/migrations/002_finish_place_and_registered_status.sql

@@ -0,0 +1,5 @@
+ALTER TABLE races ADD COLUMN IF NOT EXISTS finish_place TEXT;
+
+ALTER TABLE races DROP CONSTRAINT IF EXISTS races_status_check;
+ALTER TABLE races ADD CONSTRAINT races_status_check
+  CHECK (status IS NULL OR status IN ('planned', 'registered', 'completed'));

backend/migrations/003_cover_image_url.sql

@@ -0,0 +1,2 @@
+ALTER TABLE races
+  ADD COLUMN IF NOT EXISTS cover_image_url TEXT;

backend/migrations/004_auth_and_race_ownership.sql

@@ -0,0 +1,114 @@
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE IF NOT EXISTS users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  email_verified_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS users_email_normalized_key
+  ON users (LOWER(BTRIM(email)));
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL UNIQUE,
+  csrf_token_hash TEXT NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  revoked_at TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS sessions_user_id_idx ON sessions(user_id);
+CREATE INDEX IF NOT EXISTS sessions_expires_at_idx ON sessions(expires_at);
+
+CREATE TABLE IF NOT EXISTS email_verification_tokens (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL UNIQUE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  used_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS email_verification_tokens_user_id_idx
+  ON email_verification_tokens(user_id);
+
+CREATE TABLE IF NOT EXISTS password_reset_tokens (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT NOT NULL UNIQUE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  used_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS password_reset_tokens_user_id_idx
+  ON password_reset_tokens(user_id);
+
+CREATE TABLE IF NOT EXISTS app_settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+DO $$
+DECLARE
+  id_type TEXT;
+  pk_name TEXT;
+BEGIN
+  SELECT data_type INTO id_type
+  FROM information_schema.columns
+  WHERE table_name = 'races' AND column_name = 'id';
+
+  IF id_type IS NOT NULL AND id_type <> 'uuid' THEN
+    SELECT conname INTO pk_name
+    FROM pg_constraint
+    WHERE conrelid = 'races'::regclass AND contype = 'p'
+    LIMIT 1;
+
+    IF pk_name IS NOT NULL THEN
+      EXECUTE format('ALTER TABLE races DROP CONSTRAINT %I', pk_name);
+    END IF;
+
+    IF NOT EXISTS (
+      SELECT 1 FROM information_schema.columns
+      WHERE table_name = 'races' AND column_name = 'slug'
+    ) THEN
+      ALTER TABLE races RENAME COLUMN id TO slug;
+    ELSE
+      ALTER TABLE races DROP COLUMN id;
+    END IF;
+  END IF;
+END $$;
+
+ALTER TABLE races ADD COLUMN IF NOT EXISTS id UUID DEFAULT gen_random_uuid();
+UPDATE races SET id = gen_random_uuid() WHERE id IS NULL;
+ALTER TABLE races ALTER COLUMN id SET NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conrelid = 'races'::regclass AND contype = 'p'
+  ) THEN
+    ALTER TABLE races ADD CONSTRAINT races_pkey PRIMARY KEY (id);
+  END IF;
+END $$;
+
+ALTER TABLE races ADD COLUMN IF NOT EXISTS slug TEXT;
+UPDATE races SET slug = id::text WHERE slug IS NULL OR BTRIM(slug) = '';
+ALTER TABLE races ALTER COLUMN slug SET NOT NULL;
+
+ALTER TABLE races ADD COLUMN IF NOT EXISTS owner_user_id UUID REFERENCES users(id) ON DELETE CASCADE;
+ALTER TABLE races ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'user';
+
+CREATE UNIQUE INDEX IF NOT EXISTS races_owner_slug_key
+  ON races(owner_user_id, slug)
+  WHERE owner_user_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS races_owner_user_id_idx ON races(owner_user_id);

backend/package.json

@@ -1,27 +1,40 @@
 {
   "name": "calendar-run-backend",
-  "version": "1.0.0",
+  "version": "1.4.1",
   "private": true,
   "scripts": {
     "build": "tsc",
     "dev": "ts-node src/index.ts",
     "start": "node dist/index.js",
     "db:migrate": "ts-node src/migrate.ts",
-    "seed": "ts-node src/seed.ts"
+    "seed": "ts-node src/seed.ts",
+    "test": "cross-env CALENDAR_RUN_MOCK_DB=1 tsx --test test/app.test.ts"
   },
   "dependencies": {
+    "argon2": "^0.44.0",
+    "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "csv-parse": "^5.6.0",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
-    "pg": "^8.13.1"
+    "express-rate-limit": "^8.4.1",
+    "helmet": "^8.1.0",
+    "nodemailer": "^8.0.7",
+    "pg": "^8.13.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/cookie-parser": "^1.4.10",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.0",
     "@types/node": "^22.12.0",
+    "@types/nodemailer": "^8.0.0",
     "@types/pg": "^8.11.10",
+    "@types/supertest": "^6.0.2",
+    "cross-env": "^10.1.0",
+    "supertest": "^7.0.0",
     "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.3"
   }
 }

backend/src/app.ts

@@ -0,0 +1,69 @@
+import express, { Request, Response, NextFunction } from "express";
+import cors from "cors";
+import cookieParser from "cookie-parser";
+import helmet from "helmet";
+import { config } from "./config";
+import { loadAuth, requireCsrf } from "./authMiddleware";
+import authRouter from "./routes/auth";
+import healthRouter from "./routes/health";
+import racesRouter from "./routes/races";
+
+const TURNSTILE_ORIGIN = "https://challenges.cloudflare.com";
+
+export function buildHelmetOptions(securityProfile: string) {
+  return {
+    contentSecurityPolicy:
+      securityProfile === "production"
+        ? {
+            directives: {
+              defaultSrc: ["'self'"],
+              scriptSrc: ["'self'", TURNSTILE_ORIGIN],
+              styleSrc: ["'self'"],
+              imgSrc: ["'self'", "data:", "https:"],
+              connectSrc: ["'self'", TURNSTILE_ORIGIN],
+              frameSrc: [TURNSTILE_ORIGIN],
+              objectSrc: ["'none'"],
+              frameAncestors: ["'none'"],
+            },
+          }
+        : false,
+    hsts:
+      securityProfile === "production"
+        ? { maxAge: 31_536_000, includeSubDomains: true }
+        : false,
+    referrerPolicy: { policy: "strict-origin-when-cross-origin" as const },
+  };
+}
+
+export function createApp(): express.Express {
+  const app = express();
+
+  app.use(helmet(buildHelmetOptions(config.securityProfile)));
+  app.use(
+    cors({
+      origin: config.corsOrigin,
+      credentials: true,
+      methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+      allowedHeaders: ["Content-Type", "X-CSRF-Token"],
+    }),
+  );
+  app.use(express.json());
+  app.use(cookieParser(config.session.secret));
+  app.use(loadAuth);
+  app.use(requireCsrf);
+
+  app.use("/api", healthRouter);
+  app.use("/api", authRouter);
+  app.use("/api", racesRouter);
+
+  app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
+    if (err instanceof SyntaxError && "body" in err) {
+      res.status(400).json({ error: "validation_error", details: ["Invalid JSON in request body"] });
+      return;
+    }
+    console.error("[app] Unhandled error:", err);
+    res.status(500).json({ error: "unknown_error", details: ["Internal server error"] });
+  });
+
+  return app;
+}

backend/src/authMiddleware.ts

@@ -0,0 +1,83 @@
+import { NextFunction, Request, Response } from "express";
+import { config } from "./config";
+import { csrfMatches, getSession } from "./authService";
+
+declare global {
+  namespace Express {
+    interface Request {
+      auth?: {
+        user: {
+          id: string;
+          email: string;
+          emailVerifiedAt: string | null;
+        };
+        csrfTokenHash: string;
+        sessionToken: string;
+      };
+    }
+  }
+}
+
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+export function setSessionCookie(res: Response, sessionToken: string): void {
+  res.cookie(config.session.cookieName, sessionToken, {
+    httpOnly: true,
+    secure: config.session.secure,
+    sameSite: "lax",
+    path: "/",
+    maxAge: config.session.ttlDays * 24 * 60 * 60 * 1000,
+  });
+}
+
+export function clearSessionCookie(res: Response): void {
+  res.clearCookie(config.session.cookieName, {
+    httpOnly: true,
+    secure: config.session.secure,
+    sameSite: "lax",
+    path: "/",
+  });
+}
+
+export async function loadAuth(req: Request, _res: Response, next: NextFunction): Promise<void> {
+  const token = req.cookies?.[config.session.cookieName];
+  if (typeof token !== "string" || token.trim() === "") {
+    next();
+    return;
+  }
+  try {
+    const session = await getSession(token);
+    if (session) {
+      req.auth = { ...session, sessionToken: token };
+    }
+  } catch (error) {
+    next(error);
+    return;
+  }
+  next();
+}
+
+export function requireAuth(req: Request, res: Response, next: NextFunction): void {
+  if (!req.auth) {
+    res.status(401).json({ error: "unauthorized", details: ["Authentication required"] });
+    return;
+  }
+  if (!req.auth.user.emailVerifiedAt) {
+    res.status(403).json({ error: "email_not_verified", details: ["Email verification required"] });
+    return;
+  }
+  next();
+}
+
+export function requireCsrf(req: Request, res: Response, next: NextFunction): void {
+  if (!MUTATING_METHODS.has(req.method) || !req.auth) {
+    next();
+    return;
+  }
+  const token = req.header("X-CSRF-Token");
+  if (!token || !csrfMatches(req.auth.csrfTokenHash, token)) {
+    res.status(403).json({ error: "csrf_error", details: ["Invalid CSRF token"] });
+    return;
+  }
+  next();
+}

backend/src/authService.ts

@@ -0,0 +1,396 @@
+import { PoolClient } from "pg";
+import { config } from "./config";
+import { pool } from "./db";
+import { sendMail } from "./mailer";
+import {
+  addDays,
+  addHours,
+  hashPassword,
+  normalizeEmail,
+  randomToken,
+  sha256Hex,
+  timingSafeEqualHex,
+  verifyPassword,
+} from "./security";
+import { anonymizeEmail, securityLog } from "./securityLog";
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  emailVerifiedAt: string | null;
+}
+
+interface UserRow {
+  id: string;
+  email: string;
+  password_hash: string;
+  email_verified_at: Date | string | null;
+}
+
+interface SessionRow {
+  id: string;
+  user_id: string;
+  token_hash: string;
+  csrf_token_hash: string;
+  expires_at: Date | string;
+  email: string;
+  email_verified_at: Date | string | null;
+}
+
+function toIso(value: Date | string | null): string | null {
+  if (!value) {
+    return null;
+  }
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+
+function userFromRow(row: UserRow): AuthUser {
+  return {
+    id: row.id,
+    email: row.email,
+    emailVerifiedAt: toIso(row.email_verified_at),
+  };
+}
+
+function appUrl(path: string, token: string): string {
+  const url = new URL(path, config.appBaseUrl);
+  url.searchParams.set("token", token);
+  return url.toString();
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "23505";
+}
+
+export async function findUserByEmail(email: string): Promise<UserRow | null> {
+  const normalized = normalizeEmail(email);
+  const { rows } = await pool.query<UserRow>(
+    "SELECT id, email, password_hash, email_verified_at FROM users WHERE LOWER(BTRIM(email)) = $1",
+    [normalized],
+  );
+  return rows[0] ?? null;
+}
+
+export async function createVerificationToken(client: PoolClient, userId: string): Promise<string> {
+  await client.query(
+    "UPDATE email_verification_tokens SET used_at = NOW() WHERE user_id = $1 AND used_at IS NULL",
+    [userId],
+  );
+  const token = randomToken(32);
+  await client.query(
+    `INSERT INTO email_verification_tokens (user_id, token_hash, expires_at)
+     VALUES ($1, $2, $3)`,
+    [userId, sha256Hex(token), addHours(new Date(), 24)],
+  );
+  return token;
+}
+
+export async function createResetToken(client: PoolClient, userId: string): Promise<string> {
+  await client.query(
+    "UPDATE password_reset_tokens SET used_at = NOW() WHERE user_id = $1 AND used_at IS NULL",
+    [userId],
+  );
+  const token = randomToken(32);
+  await client.query(
+    `INSERT INTO password_reset_tokens (user_id, token_hash, expires_at)
+     VALUES ($1, $2, $3)`,
+    [userId, sha256Hex(token), addHours(new Date(), 1)],
+  );
+  return token;
+}
+
+export async function sendVerificationEmail(email: string, token: string): Promise<void> {
+  await sendMail(
+    email,
+    "Подтвердите email в Calendar Run",
+    `Откройте ссылку для подтверждения email: ${appUrl("/verify-email", token)}`,
+  );
+}
+
+export async function sendResetEmail(email: string, token: string): Promise<void> {
+  await sendMail(
+    email,
+    "Сброс пароля Calendar Run",
+    `Откройте ссылку для сброса пароля: ${appUrl("/reset-password", token)}`,
+  );
+}
+
+export async function registerUser(email: string, password: string): Promise<void> {
+  const normalized = normalizeEmail(email);
+  const passwordHash = await hashPassword(password);
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    let rows: UserRow[];
+    try {
+      ({ rows } = await client.query<UserRow>(
+        `INSERT INTO users (email, password_hash)
+         VALUES ($1, $2)
+         RETURNING id, email, password_hash, email_verified_at`,
+        [normalized, passwordHash],
+      ));
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        await client.query("ROLLBACK");
+        securityLog("register.existing", { emailHash: anonymizeEmail(normalized) });
+        return;
+      }
+      throw error;
+    }
+    const user = rows[0];
+    if (user) {
+      const token = await createVerificationToken(client, user.id);
+      await client.query("COMMIT");
+      await sendVerificationEmail(user.email, token);
+      securityLog("register.created", { emailHash: anonymizeEmail(normalized) });
+      return;
+    }
+    await client.query("COMMIT");
+    securityLog("register.existing", { emailHash: anonymizeEmail(normalized) });
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function createSession(userId: string): Promise<{ sessionToken: string; csrfToken: string; user: AuthUser }> {
+  const sessionToken = randomToken(32);
+  const csrfToken = randomToken(32);
+  const expiresAt = addDays(new Date(), config.session.ttlDays);
+  const { rows } = await pool.query<SessionRow>(
+    `INSERT INTO sessions (user_id, token_hash, csrf_token_hash, expires_at)
+     VALUES ($1, $2, $3, $4)
+     RETURNING id, user_id, token_hash, csrf_token_hash, expires_at,
+       (SELECT email FROM users WHERE id = $1) AS email,
+       (SELECT email_verified_at FROM users WHERE id = $1) AS email_verified_at`,
+    [userId, sha256Hex(sessionToken), sha256Hex(csrfToken), expiresAt],
+  );
+  const row = rows[0];
+  securityLog("session.issued", { userId });
+  return {
+    sessionToken,
+    csrfToken,
+    user: {
+      id: row.user_id,
+      email: row.email,
+      emailVerifiedAt: toIso(row.email_verified_at),
+    },
+  };
+}
+
+export async function loginUser(email: string, password: string): Promise<{ ok: false } | { ok: true; sessionToken: string; csrfToken: string; user: AuthUser }> {
+  const normalized = normalizeEmail(email);
+  const user = await findUserByEmail(normalized);
+  const passwordOk = await verifyPassword(user?.password_hash ?? null, password);
+  if (!user || !passwordOk || !user.email_verified_at) {
+    securityLog("login.failed", { emailHash: anonymizeEmail(normalized) });
+    return { ok: false };
+  }
+  const session = await createSession(user.id);
+  securityLog("login.succeeded", { userId: user.id });
+  return { ok: true, ...session };
+}
+
+export async function revokeSession(sessionToken: string): Promise<void> {
+  await pool.query("UPDATE sessions SET revoked_at = NOW() WHERE token_hash = $1", [sha256Hex(sessionToken)]);
+  securityLog("session.revoked");
+}
+
+export async function rotateCsrf(sessionToken: string): Promise<string | null> {
+  const csrfToken = randomToken(32);
+  const { rowCount } = await pool.query(
+    `UPDATE sessions
+     SET csrf_token_hash = $2, last_seen_at = NOW()
+     WHERE token_hash = $1 AND revoked_at IS NULL AND expires_at > NOW()`,
+    [sha256Hex(sessionToken), sha256Hex(csrfToken)],
+  );
+  return rowCount && rowCount > 0 ? csrfToken : null;
+}
+
+export async function getSession(sessionToken: string): Promise<{ user: AuthUser; csrfTokenHash: string } | null> {
+  const tokenHash = sha256Hex(sessionToken);
+  const { rows } = await pool.query<SessionRow>(
+    `SELECT s.id, s.user_id, s.token_hash, s.csrf_token_hash, s.expires_at, u.email, u.email_verified_at
+     FROM sessions s
+     JOIN users u ON u.id = s.user_id
+     WHERE s.token_hash = $1 AND s.revoked_at IS NULL AND s.expires_at > NOW()`,
+    [tokenHash],
+  );
+  const row = rows[0];
+  if (!row) {
+    return null;
+  }
+  await pool.query("UPDATE sessions SET last_seen_at = NOW(), expires_at = $2 WHERE id = $1", [
+    row.id,
+    addDays(new Date(), config.session.ttlDays),
+  ]);
+  return {
+    user: {
+      id: row.user_id,
+      email: row.email,
+      emailVerifiedAt: toIso(row.email_verified_at),
+    },
+    csrfTokenHash: row.csrf_token_hash,
+  };
+}
+
+export function csrfMatches(hash: string, token: string): boolean {
+  return timingSafeEqualHex(hash, sha256Hex(token));
+}
+
+export async function verifyEmailToken(token: string): Promise<boolean> {
+  const tokenHash = sha256Hex(token);
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const { rows } = await client.query<{ id: string; user_id: string; token_hash: string }>(
+      `SELECT id, user_id, token_hash
+       FROM email_verification_tokens
+       WHERE token_hash = $1 AND used_at IS NULL AND expires_at > NOW()
+       FOR UPDATE`,
+      [tokenHash],
+    );
+    const row = rows.find((candidate) => timingSafeEqualHex(candidate.token_hash, tokenHash));
+    if (!row) {
+      await client.query("ROLLBACK");
+      return false;
+    }
+    const consumed = await client.query(
+      "UPDATE email_verification_tokens SET used_at = NOW() WHERE id = $1 AND used_at IS NULL RETURNING id",
+      [row.id],
+    );
+    if (consumed.rowCount === 0) {
+      await client.query("ROLLBACK");
+      return false;
+    }
+    await client.query(
+      "UPDATE email_verification_tokens SET used_at = NOW() WHERE user_id = $1 AND id <> $2 AND used_at IS NULL",
+      [row.user_id, row.id],
+    );
+    await client.query("UPDATE users SET email_verified_at = COALESCE(email_verified_at, NOW()), updated_at = NOW() WHERE id = $1", [row.user_id]);
+    await client.query("SELECT pg_advisory_xact_lock(706365)");
+    const claimed = await client.query("SELECT value FROM app_settings WHERE key = 'orphan_races_claimed_by_user_id' FOR UPDATE");
+    if (claimed.rows.length === 0) {
+      await client.query("UPDATE races SET owner_user_id = $1, updated_at = NOW() WHERE owner_user_id IS NULL", [row.user_id]);
+      await client.query(
+        `INSERT INTO app_settings (key, value)
+         VALUES ('orphan_races_claimed_by_user_id', $1)`,
+        [row.user_id],
+      );
+    }
+    await client.query("COMMIT");
+    securityLog("email.verified", { userId: row.user_id });
+    return true;
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function requestPasswordReset(email: string): Promise<void> {
+  const normalized = normalizeEmail(email);
+  const user = await findUserByEmail(normalized);
+  if (!user) {
+    securityLog("password_reset.requested_missing", { emailHash: anonymizeEmail(normalized) });
+    return;
+  }
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const token = await createResetToken(client, user.id);
+    await client.query("COMMIT");
+    await sendResetEmail(user.email, token);
+    securityLog("password_reset.requested", { userId: user.id });
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function resetPassword(token: string, password: string): Promise<boolean> {
+  const tokenHash = sha256Hex(token);
+  const passwordHash = await hashPassword(password);
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const { rows } = await client.query<{ id: string; user_id: string; token_hash: string }>(
+      `SELECT id, user_id, token_hash
+       FROM password_reset_tokens
+       WHERE token_hash = $1 AND used_at IS NULL AND expires_at > NOW()
+       FOR UPDATE`,
+      [tokenHash],
+    );
+    const row = rows.find((candidate) => timingSafeEqualHex(candidate.token_hash, tokenHash));
+    if (!row) {
+      await client.query("ROLLBACK");
+      return false;
+    }
+    const consumed = await client.query(
+      "UPDATE password_reset_tokens SET used_at = NOW() WHERE id = $1 AND used_at IS NULL RETURNING id",
+      [row.id],
+    );
+    if (consumed.rowCount === 0) {
+      await client.query("ROLLBACK");
+      return false;
+    }
+    await client.query(
+      "UPDATE password_reset_tokens SET used_at = NOW() WHERE user_id = $1 AND id <> $2 AND used_at IS NULL",
+      [row.user_id, row.id],
+    );
+    await client.query("UPDATE users SET password_hash = $2, updated_at = NOW() WHERE id = $1", [row.user_id, passwordHash]);
+    await client.query("UPDATE sessions SET revoked_at = NOW() WHERE user_id = $1 AND revoked_at IS NULL", [row.user_id]);
+    await client.query("COMMIT");
+    securityLog("password_reset.completed", { userId: row.user_id });
+    return true;
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function resendVerification(email: string): Promise<void> {
+  const normalized = normalizeEmail(email);
+  const user = await findUserByEmail(normalized);
+  if (!user || user.email_verified_at) {
+    return;
+  }
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const token = await createVerificationToken(client, user.id);
+    await client.query("COMMIT");
+    await sendVerificationEmail(user.email, token);
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+export async function cleanupExpiredAuthRows(): Promise<void> {
+  await pool.query("DELETE FROM sessions WHERE expires_at <= NOW() OR revoked_at < NOW() - INTERVAL '30 days'");
+  await pool.query("DELETE FROM email_verification_tokens WHERE expires_at <= NOW() OR used_at IS NOT NULL");
+  await pool.query("DELETE FROM password_reset_tokens WHERE expires_at <= NOW() OR used_at IS NOT NULL");
+}
+
+export function startAuthCleanupSchedule(intervalHours = config.authCleanupIntervalHours): NodeJS.Timeout {
+  const runCleanup = () => {
+    void cleanupExpiredAuthRows().catch((error) => {
+      console.error("[auth-cleanup] Failed:", error);
+    });
+  };
+  runCleanup();
+  const safeHours = Number.isFinite(intervalHours) && intervalHours > 0 ? intervalHours : 24;
+  const timer = setInterval(runCleanup, safeHours * 60 * 60 * 1000);
+  timer.unref?.();
+  return timer;
+}

backend/src/config.ts

@@ -11,14 +11,106 @@ function requireEnv(name: string): string {
   return value;
 }
 
+function optionalEnv(name: string): string | null {
+  const value = process.env[name]?.trim();
+  return value ? value : null;
+}
+
+function requireEnvUnlessMock(name: string, fallback: string): string {
+  if (useMockDb) {
+    return process.env[name]?.trim() || fallback;
+  }
+  return requireEnv(name);
+}
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value == null || value.trim() === "") {
+    return fallback;
+  }
+  return value === "1" || value.toLowerCase() === "true";
+}
+
+const useMockDb =
+  process.env.CALENDAR_RUN_MOCK_DB === "1" ||
+  process.env.CALENDAR_RUN_MOCK_DB?.toLowerCase() === "true";
+
+const securityProfile = process.env.SECURITY_PROFILE?.trim() || process.env.NODE_ENV || "development";
+
+export function resolveTurnstileBypassToken(params: {
+  rawBypassToken?: string;
+  securityProfile: string;
+  useMockDb: boolean;
+}): string {
+  const raw = params.rawBypassToken?.trim() ?? "";
+  if (raw && params.securityProfile === "production" && !params.useMockDb) {
+    throw new Error("TURNSTILE_BYPASS_TOKEN is not allowed in production");
+  }
+  if (raw) {
+    return raw;
+  }
+  return params.useMockDb ? "mock-turnstile-token" : "";
+}
+
 export const config = {
-  db: {
-    host: requireEnv("DB_HOST"),
-    port: parseInt(requireEnv("DB_PORT"), 10),
-    database: requireEnv("DB_NAME"),
-    user: requireEnv("DB_USER"),
-    password: requireEnv("DB_PASSWORD"),
+  useMockDb,
+  db: useMockDb
+    ? {
+        host: "mock",
+        port: 5432,
+        database: "mock",
+        user: "mock",
+        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),
+  /** Одно значение или несколько через запятую (прод: https://домен) */
+  corsOrigin: parseCorsOrigins(),
+  appBaseUrl: process.env.APP_BASE_URL?.trim() || "http://localhost:5173",
+  session: {
+    secret: requireEnvUnlessMock("SESSION_SECRET", "mock-session-secret-change-me"),
+    cookieName:
+      process.env.SESSION_COOKIE_NAME?.trim() ||
+      (process.env.NODE_ENV === "production" ? "__Host-sid" : "sid"),
+    secure: parseBoolean(process.env.SESSION_COOKIE_SECURE, process.env.NODE_ENV === "production"),
+    ttlDays: parseInt(process.env.SESSION_TTL_DAYS || "30", 10),
   },
-  apiPort: parseInt(process.env.API_PORT || "3001", 10),
-  corsOrigin: process.env.CORS_ORIGIN || "http://localhost:5173",
+  smtp: {
+    host: optionalEnv("SMTP_HOST"),
+    port: parseInt(process.env.SMTP_PORT || "587", 10),
+    secure: parseBoolean(process.env.SMTP_SECURE, false),
+    user: optionalEnv("SMTP_USER"),
+    password: optionalEnv("SMTP_PASSWORD"),
+    from: process.env.SMTP_FROM?.trim() || "Calendar Run <no-reply@example.com>",
+  },
+  turnstile: {
+    secretKey: process.env.TURNSTILE_SECRET_KEY?.trim() || (useMockDb ? "mock-turnstile-secret" : ""),
+    bypassToken: resolveTurnstileBypassToken({
+      rawBypassToken: process.env.TURNSTILE_BYPASS_TOKEN,
+      securityProfile,
+      useMockDb,
+    }),
+  },
+  authCleanupIntervalHours: parseInt(process.env.AUTH_CLEANUP_INTERVAL_HOURS || "24", 10),
+  securityProfile,
 };
+
+function parseCorsOrigins(): string | string[] {
+  const raw = process.env.CORS_ORIGIN?.trim();
+  if (!raw) {
+    return "http://localhost:5173";
+  }
+  const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    return "http://localhost:5173";
+  }
+  if (parts.length === 1) {
+    return parts[0]!;
+  }
+  return parts;
+}

backend/src/db.ts

@@ -1,5 +1,7 @@
-import { Pool, PoolConfig } from "pg";
+import { Pool, PoolConfig, QueryResult, QueryResultRow } from "pg";
+import crypto from "crypto";
 import { config } from "./config";
+import type { RaceRow } from "./mappers/race";
 
 const poolConfig: PoolConfig = {
   host: config.db.host,
@@ -12,13 +14,509 @@ 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();
+  if (!match) {
+    return {
+      id: String(params[0] ?? ""),
+      slug: String(params[0] ?? ""),
+      owner_user_id: null,
+      race_date: "",
+      title: "",
+      distance_km: "0",
+      status: null,
+      official_url: null,
+      cover_image_url: null,
+      start_time: null,
+      cluster_schedule: null,
+      bib_pickup: null,
+      bib_number: null,
+      finish_time: null,
+      finish_place: 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 ?? crypto.randomUUID()),
+    slug: String(row.slug ?? row.id ?? ""),
+    owner_user_id: row.owner_user_id != null ? String(row.owner_user_id) : null,
+    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,
+    cover_image_url: row.cover_image_url != null ? String(row.cover_image_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,
+    finish_place: row.finish_place != null ? String(row.finish_place) : null,
+    notes: row.notes != null ? String(row.notes) : null,
+    created_at: now,
+    updated_at: null,
+  };
+}
 
-pool.on("error", (err) => {
-  console.error("[db] Unexpected pool error:", err.message);
-});
+function createMockPool(): Pool {
+  const emptyResult = <T extends QueryResultRow>(): QueryResult<T> =>
+    ({
+      rows: [],
+      rowCount: 0,
+      command: "",
+      oid: 0,
+      fields: [],
+    }) as QueryResult<T>;
+
+  const store = new Map<string, RaceRow>();
+  const users = new Map<string, any>();
+  const sessions = new Map<string, any>();
+  const verificationTokens = new Map<string, any>();
+  const resetTokens = new Map<string, any>();
+  const appSettings = new Map<string, string>();
+
+  const result = <T extends QueryResultRow>(rows: T[], command = "SELECT"): QueryResult<T> =>
+    ({ rows, rowCount: rows.length, 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 === "BEGIN" || sql === "COMMIT" || sql === "ROLLBACK" || sql.includes("pg_advisory_xact_lock")) {
+      return result<T>([]);
+    }
+
+    if (sql.includes("SELECT COUNT(*)::text AS count FROM users")) {
+      return result([{ count: String(users.size) } as unknown as T]);
+    }
+
+    if (sql.includes("SELECT COUNT(*)::text AS count FROM sessions")) {
+      const tokenHash = p[0] != null ? String(p[0]) : null;
+      const count = Array.from(sessions.values()).filter((row) => !tokenHash || row.token_hash === tokenHash).length;
+      return result([{ count: String(count) } as unknown as T]);
+    }
+
+    if (sql.includes("SELECT COUNT(*)::text AS count FROM email_verification_tokens")) {
+      const tokenHash = p[0] != null ? String(p[0]) : null;
+      const count = Array.from(verificationTokens.values()).filter((row) => !tokenHash || row.token_hash === tokenHash).length;
+      return result([{ count: String(count) } as unknown as T]);
+    }
+
+    if (sql.includes("SELECT COUNT(*)::text AS count FROM password_reset_tokens")) {
+      const tokenHash = p[0] != null ? String(p[0]) : null;
+      const count = Array.from(resetTokens.values()).filter((row) => !tokenHash || row.token_hash === tokenHash).length;
+      return result([{ count: String(count) } as unknown as T]);
+    }
+
+    if (sql.includes("SELECT id FROM users WHERE LOWER(BTRIM(email))")) {
+      const email = String(p[0] ?? "");
+      const user = Array.from(users.values()).find((item) => item.email.trim().toLowerCase() === email);
+      return user ? result([user as T]) : emptyResult();
+    }
+
+    if (sql.includes("SELECT id, email, password_hash, email_verified_at FROM users WHERE LOWER(BTRIM(email))")) {
+      const email = String(p[0] ?? "");
+      const user = Array.from(users.values()).find((item) => item.email.trim().toLowerCase() === email);
+      return user ? result([user as T]) : emptyResult();
+    }
+
+    if (sql.includes("INSERT INTO users")) {
+      const email = String(p[0] ?? "").trim().toLowerCase();
+      const existing = Array.from(users.values()).find((item) => item.email.trim().toLowerCase() === email);
+      if (existing) {
+        const err = new Error("duplicate key") as Error & { code?: string };
+        err.code = "23505";
+        throw err;
+      }
+      const id = crypto.randomUUID();
+      const row = {
+        id,
+        email: String(p[0] ?? ""),
+        password_hash: String(p[1] ?? ""),
+        email_verified_at: null,
+        created_at: new Date(),
+        updated_at: null,
+      };
+      users.set(id, row);
+      return result([row as unknown as T], "INSERT");
+    }
+
+    if (sql.includes("INSERT INTO email_verification_tokens")) {
+      const id = crypto.randomUUID();
+      const row = {
+        id,
+        user_id: String(p[0] ?? ""),
+        token_hash: String(p[1] ?? ""),
+        expires_at: p[2] ?? new Date(),
+        used_at: null,
+        created_at: new Date(),
+      };
+      verificationTokens.set(id, row);
+      return result([row as unknown as T], "INSERT");
+    }
+
+    if (sql.includes("UPDATE email_verification_tokens SET used_at = NOW() WHERE id")) {
+      const id = String(p[0] ?? "");
+      const row = verificationTokens.get(id);
+      if (!row || row.used_at != null) {
+        return result<T>([], "UPDATE");
+      }
+      row.used_at = new Date();
+      return result([{ id: row.id } as unknown as T], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE email_verification_tokens SET used_at = NOW() WHERE user_id")) {
+      const userId = String(p[0] ?? "");
+      const exceptId = p[1] != null ? String(p[1]) : null;
+      for (const row of verificationTokens.values()) {
+        if (row.user_id === userId && row.id !== exceptId && row.used_at == null) {
+          row.used_at = new Date();
+        }
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("FROM email_verification_tokens") && sql.includes("token_hash =")) {
+      const tokenHash = String(p[0] ?? "");
+      const now = Date.now();
+      return result(
+        Array.from(verificationTokens.values()).filter(
+          (row) => row.token_hash === tokenHash && !row.used_at && new Date(row.expires_at).getTime() > now,
+        ) as T[],
+      );
+    }
+
+    if (sql.includes("FROM email_verification_tokens") && sql.includes("WHERE used_at IS NULL")) {
+      const now = Date.now();
+      return result(
+        Array.from(verificationTokens.values()).filter((row) => !row.used_at && new Date(row.expires_at).getTime() > now) as T[],
+      );
+    }
+
+    if (sql.includes("INSERT INTO password_reset_tokens")) {
+      const id = crypto.randomUUID();
+      const row = {
+        id,
+        user_id: String(p[0] ?? ""),
+        token_hash: String(p[1] ?? ""),
+        expires_at: p[2] ?? new Date(),
+        used_at: null,
+        created_at: new Date(),
+      };
+      resetTokens.set(id, row);
+      return result([row as unknown as T], "INSERT");
+    }
+
+    if (sql.includes("UPDATE password_reset_tokens SET used_at = NOW() WHERE id")) {
+      const id = String(p[0] ?? "");
+      const row = resetTokens.get(id);
+      if (!row || row.used_at != null) {
+        return result<T>([], "UPDATE");
+      }
+      row.used_at = new Date();
+      return result([{ id: row.id } as unknown as T], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE password_reset_tokens SET used_at = NOW() WHERE user_id")) {
+      const userId = String(p[0] ?? "");
+      const exceptId = p[1] != null ? String(p[1]) : null;
+      for (const row of resetTokens.values()) {
+        if (row.user_id === userId && row.id !== exceptId && row.used_at == null) {
+          row.used_at = new Date();
+        }
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("FROM password_reset_tokens") && sql.includes("token_hash =")) {
+      const tokenHash = String(p[0] ?? "");
+      const now = Date.now();
+      return result(
+        Array.from(resetTokens.values()).filter(
+          (row) => row.token_hash === tokenHash && !row.used_at && new Date(row.expires_at).getTime() > now,
+        ) as T[],
+      );
+    }
+
+    if (sql.includes("FROM password_reset_tokens") && sql.includes("WHERE used_at IS NULL")) {
+      const now = Date.now();
+      return result(
+        Array.from(resetTokens.values()).filter((row) => !row.used_at && new Date(row.expires_at).getTime() > now) as T[],
+      );
+    }
+
+    if (sql.includes("UPDATE users SET email_verified_at")) {
+      const user = users.get(String(p[0] ?? ""));
+      if (user) {
+        user.email_verified_at = user.email_verified_at ?? new Date();
+        user.updated_at = new Date();
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE users SET password_hash")) {
+      const user = users.get(String(p[0] ?? ""));
+      if (user) {
+        user.password_hash = String(p[1] ?? "");
+        user.updated_at = new Date();
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("INSERT INTO sessions")) {
+      const id = crypto.randomUUID();
+      const user = users.get(String(p[0] ?? ""));
+      const row = {
+        id,
+        user_id: String(p[0] ?? ""),
+        token_hash: String(p[1] ?? ""),
+        csrf_token_hash: String(p[2] ?? ""),
+        expires_at: p[3] ?? new Date(),
+        email: user?.email ?? "",
+        email_verified_at: user?.email_verified_at ?? null,
+        revoked_at: null,
+        created_at: new Date(),
+        last_seen_at: new Date(),
+      };
+      sessions.set(id, row);
+      return result([row as unknown as T], "INSERT");
+    }
+
+    if (sql.includes("FROM sessions s JOIN users u")) {
+      const tokenHash = String(p[0] ?? "");
+      const now = Date.now();
+      const row = Array.from(sessions.values()).find(
+        (item) => item.token_hash === tokenHash && !item.revoked_at && new Date(item.expires_at).getTime() > now,
+      );
+      if (!row) {
+        return emptyResult();
+      }
+      const user = users.get(row.user_id);
+      return result([{ ...row, email: user?.email ?? "", email_verified_at: user?.email_verified_at ?? null } as unknown as T]);
+    }
+
+    if (sql.includes("UPDATE sessions SET csrf_token_hash")) {
+      const tokenHash = String(p[0] ?? "");
+      const row = Array.from(sessions.values()).find((item) => item.token_hash === tokenHash && !item.revoked_at);
+      if (row) {
+        row.csrf_token_hash = String(p[1] ?? "");
+        row.last_seen_at = new Date();
+      }
+      return result<T>(row ? ([{} as unknown as T]) : [], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE sessions SET last_seen_at")) {
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE sessions SET revoked_at = NOW() WHERE token_hash")) {
+      const tokenHash = String(p[0] ?? "");
+      for (const row of sessions.values()) {
+        if (row.token_hash === tokenHash) {
+          row.revoked_at = new Date();
+        }
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("UPDATE sessions SET revoked_at = NOW() WHERE user_id")) {
+      const userId = String(p[0] ?? "");
+      for (const row of sessions.values()) {
+        if (row.user_id === userId && !row.revoked_at) {
+          row.revoked_at = new Date();
+        }
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("DELETE FROM sessions WHERE expires_at <= NOW()")) {
+      const now = Date.now();
+      let deleted = 0;
+      for (const [id, row] of sessions.entries()) {
+        const revokedAt = row.revoked_at ? new Date(row.revoked_at).getTime() : null;
+        const staleRevoked = revokedAt != null && revokedAt < now - 30 * 24 * 60 * 60 * 1000;
+        if (new Date(row.expires_at).getTime() <= now || staleRevoked) {
+          sessions.delete(id);
+          deleted += 1;
+        }
+      }
+      return result<T>(Array.from({ length: deleted }, () => ({} as unknown as T)), "DELETE");
+    }
+
+    if (sql.includes("DELETE FROM email_verification_tokens WHERE expires_at <= NOW()")) {
+      const now = Date.now();
+      let deleted = 0;
+      for (const [id, row] of verificationTokens.entries()) {
+        if (new Date(row.expires_at).getTime() <= now || row.used_at != null) {
+          verificationTokens.delete(id);
+          deleted += 1;
+        }
+      }
+      return result<T>(Array.from({ length: deleted }, () => ({} as unknown as T)), "DELETE");
+    }
+
+    if (sql.includes("DELETE FROM password_reset_tokens WHERE expires_at <= NOW()")) {
+      const now = Date.now();
+      let deleted = 0;
+      for (const [id, row] of resetTokens.entries()) {
+        if (new Date(row.expires_at).getTime() <= now || row.used_at != null) {
+          resetTokens.delete(id);
+          deleted += 1;
+        }
+      }
+      return result<T>(Array.from({ length: deleted }, () => ({} as unknown as T)), "DELETE");
+    }
+
+    if (sql.includes("SELECT value FROM app_settings")) {
+      const value = appSettings.get("orphan_races_claimed_by_user_id");
+      return value ? result([{ value } as unknown as T]) : emptyResult();
+    }
+
+    if (sql.includes("INSERT INTO app_settings")) {
+      appSettings.set("orphan_races_claimed_by_user_id", String(p[0] ?? ""));
+      return result<T>([], "INSERT");
+    }
+
+    if (sql.includes("UPDATE races SET owner_user_id")) {
+      const userId = String(p[0] ?? "");
+      for (const race of store.values()) {
+        if (!race.owner_user_id) {
+          race.owner_user_id = userId;
+          race.updated_at = new Date();
+        }
+      }
+      return result<T>([], "UPDATE");
+    }
+
+    if (sql.includes("INSERT INTO races") && sql.includes("RETURNING")) {
+      const row = mockRowFromInsert(text, p);
+      const conflict = Array.from(store.values()).find(
+        (item) => item.owner_user_id && item.owner_user_id === row.owner_user_id && item.slug === row.slug,
+      );
+      if (conflict) {
+        const err = new Error("duplicate key") as Error & { code?: string };
+        err.code = "23505";
+        throw err;
+      }
+      store.set(row.id, row);
+      return {
+        rows: [row as unknown as T],
+        rowCount: 1,
+        command: "INSERT",
+        oid: 0,
+        fields: [],
+      } as QueryResult<T>;
+    }
+
+    if (sql.includes("DELETE FROM races")) {
+      const id = String(p[0] ?? "");
+      const ownerId = p[1] != null ? String(p[1]) : null;
+      const existing = store.get(id);
+      const existed = Boolean(existing && (!ownerId || existing.owner_user_id === ownerId));
+      if (existed) {
+        store.delete(id);
+      }
+      return {
+        rows: [],
+        rowCount: existed ? 1 : 0,
+        command: "DELETE",
+        oid: 0,
+        fields: [],
+      } as QueryResult<T>;
+    }
+
+    if (sql.includes("UPDATE races") && sql.includes("RETURNING")) {
+      const id = String(p[p.length - 2] ?? p[p.length - 1] ?? "");
+      const ownerId = p[p.length - 1] != null ? String(p[p.length - 1]) : null;
+      const existing = store.get(id);
+      if (!existing || (ownerId && existing.owner_user_id !== ownerId)) {
+        return emptyResult();
+      }
+      const setMatch = sql.match(/UPDATE races SET (.+) WHERE id =/);
+      const updated = { ...existing, updated_at: new Date() };
+      const setColumns =
+        setMatch?.[1]
+          .split(",")
+          .map((part) => part.trim())
+          .filter((part) => !part.startsWith("updated_at"))
+          .map((part) => part.split("=")[0]?.trim())
+          .filter((col): col is string => Boolean(col)) ?? [];
+
+      setColumns.forEach((col, index) => {
+        (updated as unknown as Record<string, unknown>)[col] = p[index] ?? null;
+      });
+      store.set(id, updated);
+      return {
+        rows: [updated as unknown as T],
+        rowCount: 1,
+        command: "UPDATE",
+        oid: 0,
+        fields: [],
+      } as QueryResult<T>;
+    }
+
+    if (sql.includes("SELECT * FROM races WHERE id =")) {
+      const id = String(p[0] ?? "");
+      const ownerId = p[1] != null ? String(p[1]) : null;
+      const row = store.get(id);
+      return row && (!ownerId || row.owner_user_id === ownerId)
+        ? { rows: [row as unknown as T], rowCount: 1, command: "SELECT", oid: 0, fields: [] } as QueryResult<T>
+        : emptyResult();
+    }
+
+    if (sql.includes("SELECT * FROM races")) {
+      const ownerParam = p.find((value) => typeof value === "string" && /^[0-9a-f-]{36}$/i.test(value));
+      const rows = ownerParam
+        ? Array.from(store.values()).filter((row) => row.owner_user_id === ownerParam)
+        : Array.from(store.values());
+      return { rows: rows as unknown as T[], rowCount: rows.length, command: "SELECT", oid: 0, fields: [] } as QueryResult<T>;
+    }
+
+    return emptyResult();
+  };
+
+  const mockPool = {
+    query: mockQuery,
+    connect: async () => {
+      return {
+        query: mockQuery,
+        release() {},
+      };
+    },
+    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/index.ts

@@ -1,16 +1,9 @@
-import express from "express";
-import cors from "cors";
 import { config } from "./config";
-import healthRouter from "./routes/health";
-import racesRouter from "./routes/races";
+import { createApp } from "./app";
+import { startAuthCleanupSchedule } from "./authService";
 
-const app = express();
-
-app.use(cors({ origin: config.corsOrigin, methods: ["GET", "POST", "PATCH", "DELETE"] }));
-app.use(express.json());
-
-app.use(healthRouter);
-app.use(racesRouter);
+const app = createApp();
+startAuthCleanupSchedule();
 
 app.listen(config.apiPort, () => {
   console.log(`[api] Listening on http://localhost:${config.apiPort}`);

backend/src/mailer.ts

@@ -0,0 +1,26 @@
+import nodemailer from "nodemailer";
+import { config } from "./config";
+
+export async function sendMail(to: string, subject: string, text: string): Promise<void> {
+  if (!config.smtp.host) {
+    console.info("[mail] SMTP is not configured; email content follows.", { to, subject, text });
+    return;
+  }
+
+  const transporter = nodemailer.createTransport({
+    host: config.smtp.host,
+    port: config.smtp.port,
+    secure: config.smtp.secure,
+    auth:
+      config.smtp.user && config.smtp.password
+        ? { user: config.smtp.user, pass: config.smtp.password }
+        : undefined,
+  });
+
+  await transporter.sendMail({
+    from: config.smtp.from,
+    to,
+    subject,
+    text,
+  });
+}

backend/src/mappers/race.ts

@@ -1,71 +1,103 @@
-/** Row shape returned by PostgreSQL (snake_case). */
+/**
+ * Row shape returned by PostgreSQL (snake_case).
+ * pg returns DATE as string, NUMERIC as string, TIMESTAMPTZ as Date.
+ */
 export interface RaceRow {
   id: string;
-  race_date: string;
+  slug: string;
+  owner_user_id: string | null;
+  race_date: string | Date;
   title: string;
   distance_km: string;
   status: string | null;
   official_url: string | null;
+  cover_image_url: string | null;
   start_time: string | null;
   cluster_schedule: string | null;
   bib_pickup: string | null;
   bib_number: string | null;
   finish_time: string | null;
+  finish_place: string | null;
   notes: string | null;
-  created_at: string;
-  updated_at: string | null;
+  created_at: Date;
+  updated_at: Date | null;
 }
 
 /** API shape (camelCase). */
 export interface RaceDto {
   id: string;
+  slug: string;
   date: string;
   title: string;
   distanceKm: number;
   status: string | null;
   officialUrl: string | null;
+  coverImageUrl: string | null;
   startTime: string | null;
   clusterSchedule: string | null;
   bibPickup: string | null;
   bibNumber: string | null;
   finishTime: string | null;
+  finishPlace: string | null;
   notes: string | null;
   createdAt: string;
   updatedAt: string | null;
 }
 
+function toISOString(value: Date | string): string {
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+
+/** DATE column may arrive as string or Date; API always exposes YYYY-MM-DD for the calendar day. */
+function raceDateToApiValue(value: string | Date): string {
+  if (typeof value === "string") {
+    const m = value.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m ? m[1]! : value;
+  }
+  const y = value.getFullYear();
+  const mo = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  return `${y}-${mo}-${day}`;
+}
+
 /** Convert a DB row to the API DTO (camelCase). */
 export function rowToDto(row: RaceRow): RaceDto {
   return {
     id: row.id,
-    date: row.race_date,
+    slug: row.slug,
+    date: raceDateToApiValue(row.race_date),
     title: row.title,
     distanceKm: parseFloat(row.distance_km),
     status: row.status,
     officialUrl: row.official_url,
+    coverImageUrl: row.cover_image_url ?? null,
     startTime: row.start_time,
     clusterSchedule: row.cluster_schedule,
     bibPickup: row.bib_pickup,
     bibNumber: row.bib_number,
     finishTime: row.finish_time,
+    finishPlace: row.finish_place,
     notes: row.notes,
-    createdAt: row.created_at,
-    updatedAt: row.updated_at,
+    createdAt: toISOString(row.created_at),
+    updatedAt: row.updated_at ? toISOString(row.updated_at) : null,
   };
 }
 
 /** Map incoming camelCase body fields to snake_case column names. */
 const FIELD_MAP: Record<string, string> = {
+  slug: "slug",
   date: "race_date",
   title: "title",
   distanceKm: "distance_km",
   status: "status",
   officialUrl: "official_url",
+  coverImageUrl: "cover_image_url",
   startTime: "start_time",
   clusterSchedule: "cluster_schedule",
   bibPickup: "bib_pickup",
   bibNumber: "bib_number",
   finishTime: "finish_time",
+  finishPlace: "finish_place",
   notes: "notes",
 };
 

backend/src/raceCoverImage.ts

@@ -0,0 +1,103 @@
+const IMAGE_META_KEYS = new Set([
+  "og:image",
+  "og:image:url",
+  "twitter:image",
+  "twitter:image:src",
+]);
+
+const FETCH_TIMEOUT_MS = 5_000;
+
+function getAttribute(tag: string, name: string): string | null {
+  const pattern = new RegExp(`${name}\\s*=\\s*["']([^"']+)["']`, "i");
+  return tag.match(pattern)?.[1] ?? null;
+}
+
+function toHttpUrl(value: string, baseUrl: string): string | null {
+  try {
+    const url = new URL(value, baseUrl);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+function isRuncRunUrl(value: string): boolean {
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return hostname === "runc.run" || hostname.endsWith(".runc.run");
+  } catch {
+    return false;
+  }
+}
+
+function findRuncIntroImage(html: string, baseUrl: string): string | null {
+  const introMatch = html.match(/<div\b[^>]*class=["'][^"']*\brun-intro__image\b[^"']*["'][^>]*>[\s\S]*?<img\b[^>]*>/i);
+  if (!introMatch) {
+    return null;
+  }
+
+  const src = getAttribute(introMatch[0], "src");
+  return src ? toHttpUrl(src, baseUrl) : null;
+}
+
+function findMetaImage(html: string, baseUrl: string): string | null {
+  const tags = html.match(/<meta\b[^>]*>/gi) ?? [];
+
+  for (const tag of tags) {
+    const key = (getAttribute(tag, "property") || getAttribute(tag, "name") || "").toLowerCase();
+    if (!IMAGE_META_KEYS.has(key)) {
+      continue;
+    }
+
+    const content = getAttribute(tag, "content");
+    if (!content) {
+      continue;
+    }
+
+    const imageUrl = toHttpUrl(content, baseUrl);
+    if (imageUrl) {
+      return imageUrl;
+    }
+  }
+
+  return null;
+}
+
+export function extractRaceCoverImageFromHtml(html: string, pageUrl: string): string | null {
+  if (isRuncRunUrl(pageUrl)) {
+    const runcImage = findRuncIntroImage(html, pageUrl);
+    if (runcImage) {
+      return runcImage;
+    }
+  }
+
+  return findMetaImage(html, pageUrl);
+}
+
+export async function extractRaceCoverImage(officialUrl: string): Promise<string | null> {
+  const normalizedUrl = toHttpUrl(officialUrl, officialUrl);
+  if (!normalizedUrl) {
+    return null;
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(normalizedUrl, {
+      redirect: "follow",
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const html = await response.text();
+    return extractRaceCoverImageFromHtml(html, response.url || normalizedUrl);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

backend/src/routes/auth.ts

@@ -0,0 +1,197 @@
+import { Router, Request, Response } from "express";
+import rateLimit from "express-rate-limit";
+import { z } from "zod";
+import {
+  loginUser,
+  registerUser,
+  requestPasswordReset,
+  resendVerification,
+  resetPassword,
+  rotateCsrf,
+  revokeSession,
+  verifyEmailToken,
+} from "../authService";
+import { clearSessionCookie, setSessionCookie } from "../authMiddleware";
+import { isValidPassword, normalizeEmail } from "../security";
+import { verifyTurnstileToken } from "../turnstile";
+
+const router = Router();
+
+const genericOk = { ok: true };
+const genericAuthError = { error: "invalid_credentials", details: ["Invalid email or password"] };
+
+const registerLimiter = rateLimit({ windowMs: 60 * 60 * 1000, limit: 10, standardHeaders: true, legacyHeaders: false });
+const loginLimiter = rateLimit({ windowMs: 60 * 1000, limit: 20, standardHeaders: true, legacyHeaders: false });
+const loginEmailLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  limit: 5,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => `login:${normalizeEmail(String(req.body?.email ?? ""))}`,
+});
+const emailIpLimiter = rateLimit({ windowMs: 60 * 60 * 1000, limit: 10, standardHeaders: true, legacyHeaders: false });
+const emailAddressLimiter = rateLimit({
+  windowMs: 60 * 60 * 1000,
+  limit: 3,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => `email:${normalizeEmail(String(req.body?.email ?? ""))}`,
+});
+
+const registerSchema = z.object({
+  email: z.string().email(),
+  password: z.string().refine(isValidPassword, "Password must be at least 15 characters"),
+  turnstileToken: z.string().min(1),
+});
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1),
+});
+
+const tokenSchema = z.object({
+  token: z.string().min(16),
+});
+
+const emailSchema = z.object({
+  email: z.string().email(),
+});
+
+const resetSchema = z.object({
+  token: z.string().min(16),
+  password: z.string().refine(isValidPassword, "Password must be at least 15 characters"),
+});
+
+function validationError(res: Response): void {
+  res.status(400).json({ error: "validation_error", details: ["Invalid request body"] });
+}
+
+router.post("/auth/register", registerLimiter, async (req: Request, res: Response, next) => {
+  const parsed = registerSchema.safeParse(req.body);
+  if (!parsed.success) {
+    validationError(res);
+    return;
+  }
+  try {
+    const captchaOk = await verifyTurnstileToken(parsed.data.turnstileToken, req.ip);
+    if (!captchaOk) {
+      res.status(400).json({ error: "captcha_failed", details: ["Captcha verification failed"] });
+      return;
+    }
+    await registerUser(parsed.data.email, parsed.data.password);
+    res.status(202).json(genericOk);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/login", loginLimiter, loginEmailLimiter, async (req: Request, res: Response, next) => {
+  const parsed = loginSchema.safeParse(req.body);
+  if (!parsed.success) {
+    res.status(401).json(genericAuthError);
+    return;
+  }
+  try {
+    const result = await loginUser(parsed.data.email, parsed.data.password);
+    if (!result.ok) {
+      res.status(401).json(genericAuthError);
+      return;
+    }
+    setSessionCookie(res, result.sessionToken);
+    res.json({ user: result.user, csrfToken: result.csrfToken });
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/logout", async (req: Request, res: Response, next) => {
+  try {
+    if (req.auth) {
+      await revokeSession(req.auth.sessionToken);
+    }
+    clearSessionCookie(res);
+    res.status(204).end();
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.get("/auth/me", async (req: Request, res: Response, next) => {
+  if (!req.auth) {
+    res.status(401).json({ error: "unauthorized", details: ["Authentication required"] });
+    return;
+  }
+  try {
+    const csrfToken = await rotateCsrf(req.auth.sessionToken);
+    res.json({ user: req.auth.user, csrfToken });
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/verify-email", emailIpLimiter, async (req: Request, res: Response, next) => {
+  const parsed = tokenSchema.safeParse(req.body);
+  if (!parsed.success) {
+    validationError(res);
+    return;
+  }
+  try {
+    const ok = await verifyEmailToken(parsed.data.token);
+    if (!ok) {
+      res.status(410).json({ error: "invalid_token", details: ["Token is invalid or expired"] });
+      return;
+    }
+    res.json(genericOk);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/resend-verification", emailIpLimiter, emailAddressLimiter, async (req: Request, res: Response, next) => {
+  const parsed = emailSchema.safeParse(req.body);
+  if (!parsed.success) {
+    validationError(res);
+    return;
+  }
+  try {
+    await resendVerification(parsed.data.email);
+    res.status(202).json(genericOk);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/forgot-password", emailIpLimiter, emailAddressLimiter, async (req: Request, res: Response, next) => {
+  const parsed = emailSchema.safeParse(req.body);
+  if (!parsed.success) {
+    validationError(res);
+    return;
+  }
+  try {
+    await requestPasswordReset(parsed.data.email);
+    res.status(202).json(genericOk);
+  } catch (error) {
+    next(error);
+  }
+});
+
+router.post("/auth/reset-password", emailIpLimiter, async (req: Request, res: Response, next) => {
+  const parsed = resetSchema.safeParse(req.body);
+  if (!parsed.success) {
+    validationError(res);
+    return;
+  }
+  try {
+    const ok = await resetPassword(parsed.data.token, parsed.data.password);
+    if (!ok) {
+      res.status(410).json({ error: "invalid_token", details: ["Token is invalid or expired"] });
+      return;
+    }
+    clearSessionCookie(res);
+    res.json(genericOk);
+  } catch (error) {
+    next(error);
+  }
+});
+
+export default router;

backend/src/routes/health.ts

@@ -1,10 +1,16 @@
 import { Router, Request, Response } from "express";
 import { checkDbConnection } from "../db";
+import { getBackendVersion } from "../version";
 
 const router = Router();
 
 router.get("/health", (_req: Request, res: Response) => {
-  res.json({ status: "ok" });
+  res.json({ status: "ok", version: getBackendVersion() });
+});
+
+/** Версия для UI; путь без «health», чтобы реже резался фильтрами/прокси. */
+router.get("/meta", (_req: Request, res: Response) => {
+  res.json({ version: getBackendVersion() });
 });
 
 router.get("/ready", async (_req: Request, res: Response) => {

backend/src/routes/races.ts

@@ -1,29 +1,86 @@
 import { Router, Request, Response } from "express";
 import { pool } from "../db";
 import { rowToDto, bodyToColumns, RaceRow } from "../mappers/race";
+import { extractRaceCoverImage } from "../raceCoverImage";
+import { requireAuth } from "../authMiddleware";
 
 const router = Router();
+router.use(requireAuth);
+
+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) {
+    conditions.push(`owner_user_id = $${idx++}`);
+    params.push(req.auth!.user.id);
+
+    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 ")}` : "";
@@ -42,11 +99,11 @@ router.get("/races", async (req: Request, res: Response) => {
 router.get("/races/:id", async (req: Request, res: Response) => {
   try {
     const { rows } = await pool.query<RaceRow>(
-      "SELECT * FROM races WHERE id = $1",
-      [req.params.id],
+      "SELECT * FROM races WHERE id = $1 AND owner_user_id = $2",
+      [req.params.id, req.auth!.user.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]));
@@ -61,17 +118,28 @@ router.get("/races/:id", async (req: Request, res: Response) => {
 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({
-      error: "validation_error",
-      details: ["Fields id, date, title, distanceKm are required"],
-    });
+  const slug = typeof body.slug === "string" && body.slug.trim() ? body.slug.trim() : body.id;
+
+  if (!slug || !body.date || !body.title || body.distanceKm == null) {
+    validationError(res, ["Fields slug, date, title, distanceKm are required"]);
     return;
   }
 
-  const { columns, values } = bodyToColumns(body);
-  columns.unshift("id");
-  values.unshift(body.id);
+  const payload = { ...body, slug };
+  const hasManualCover = typeof payload.coverImageUrl === "string" && payload.coverImageUrl.trim() !== "";
+  const hasOfficialUrl = typeof payload.officialUrl === "string" && payload.officialUrl.trim() !== "";
+
+  if (!hasManualCover && hasOfficialUrl) {
+    payload.coverImageUrl = await extractRaceCoverImage(payload.officialUrl);
+  }
+
+  const { columns, values } = bodyToColumns(payload);
+  columns.unshift("owner_user_id");
+  values.unshift(req.auth!.user.id);
+  if (!columns.includes("slug")) {
+    columns.push("slug");
+    values.push(slug);
+  }
 
   const placeholders = values.map((_, i) => `$${i + 1}`).join(", ");
   const sql = `INSERT INTO races (${columns.join(", ")}) VALUES (${placeholders}) RETURNING *`;
@@ -81,7 +149,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 slug already exists"],
+      });
       return;
     }
     console.error("[POST /races]", err);
@@ -95,22 +166,20 @@ router.patch("/races/:id", async (req: Request, res: Response) => {
   const { columns, values } = bodyToColumns(req.body);
 
   if (columns.length === 0) {
-    res.status(400).json({
-      error: "validation_error",
-      details: ["No updatable fields provided"],
-    });
+    validationError(res, ["No updatable fields provided"]);
     return;
   }
 
   const sets = columns.map((col, i) => `${col} = $${i + 1}`);
   sets.push(`updated_at = NOW()`);
   values.push(req.params.id);
-  const sql = `UPDATE races SET ${sets.join(", ")} WHERE id = $${values.length} RETURNING *`;
+  values.push(req.auth!.user.id);
+  const sql = `UPDATE races SET ${sets.join(", ")} WHERE id = $${values.length - 1} AND owner_user_id = $${values.length} RETURNING *`;
 
   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]));
@@ -125,11 +194,11 @@ router.patch("/races/:id", async (req: Request, res: Response) => {
 router.delete("/races/:id", async (req: Request, res: Response) => {
   try {
     const { rowCount } = await pool.query(
-      "DELETE FROM races WHERE id = $1",
-      [req.params.id],
+      "DELETE FROM races WHERE id = $1 AND owner_user_id = $2",
+      [req.params.id, req.auth!.user.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();

backend/src/security.ts

@@ -0,0 +1,63 @@
+import crypto from "crypto";
+import argon2 from "argon2";
+
+export const PASSWORD_MIN_LENGTH = 15;
+export const PASSWORD_MAX_LENGTH = 256;
+
+export const ARGON2_OPTIONS: argon2.Options & { raw?: false } = {
+  type: argon2.argon2id,
+  memoryCost: 65_536,
+  timeCost: 3,
+  parallelism: 1,
+  hashLength: 32,
+};
+
+const DUMMY_PASSWORD_HASH =
+  "$argon2id$v=19$m=65536,t=3,p=1$Jkdr1qT0c9cPK5v8m0tEMQ$SLnLmyorTDzBK74I1lrEF92E7S0c6DAm8iMG0YOyAIo";
+
+export function normalizeEmail(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function isValidPassword(value: string): boolean {
+  return value.length >= PASSWORD_MIN_LENGTH && value.length <= PASSWORD_MAX_LENGTH;
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  return argon2.hash(password, ARGON2_OPTIONS);
+}
+
+export async function verifyPassword(hash: string | null, password: string): Promise<boolean> {
+  const candidate = hash ?? DUMMY_PASSWORD_HASH;
+  try {
+    const ok = await argon2.verify(candidate, password);
+    return hash ? ok : false;
+  } catch {
+    return false;
+  }
+}
+
+export function randomToken(bytes = 32): string {
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+export function sha256Hex(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function timingSafeEqualHex(left: string, right: string): boolean {
+  const a = Buffer.from(left, "hex");
+  const b = Buffer.from(right, "hex");
+  if (a.length !== b.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(a, b);
+}
+
+export function addDays(date: Date, days: number): Date {
+  return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+}
+
+export function addHours(date: Date, hours: number): Date {
+  return new Date(date.getTime() + hours * 60 * 60 * 1000);
+}

backend/src/securityLog.ts

@@ -0,0 +1,9 @@
+import { sha256Hex } from "./security";
+
+export function anonymizeEmail(email: string): string {
+  return sha256Hex(email).slice(0, 16);
+}
+
+export function securityLog(event: string, details: Record<string, unknown> = {}): void {
+  console.info("[security]", event, details);
+}

backend/src/seed.ts

@@ -24,10 +24,49 @@ function makeId(date: string, title: string): string {
   return `${date}-${slugify(title)}`;
 }
 
+async function resolveSeedOwnerUserId(client: { query: typeof pool.query }): Promise<string | null> {
+  const explicit = process.env.SEED_OWNER_USER_ID?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  const email = process.env.SEED_OWNER_EMAIL?.trim().toLowerCase();
+  if (email) {
+    const { rows } = await client.query<{ id: string }>(
+      "SELECT id FROM users WHERE LOWER(BTRIM(email)) = $1",
+      [email],
+    );
+    if (rows[0]) {
+      return rows[0].id;
+    }
+    throw new Error("SEED_OWNER_EMAIL does not match an existing user");
+  }
+
+  const { rows } = await client.query<{ count: string }>("SELECT COUNT(*)::text AS count FROM users");
+  const usersCount = Number(rows[0]?.count ?? "0");
+  if (usersCount > 0) {
+    throw new Error("Refusing to seed without SEED_OWNER_USER_ID or SEED_OWNER_EMAIL after users exist");
+  }
+  return null;
+}
+
+const CSV_NAME = "races_2026_calendar.csv";
+
+function resolveCsvPath(): string | null {
+  // Docker image: /app/dist/*.js → ../import = /app/import (matches Dockerfile COPY import ./import)
+  // Local monorepo: backend/dist/*.js → ../../import = repo root import/
+  const candidates = [
+    path.resolve(__dirname, "../import", CSV_NAME),
+    path.resolve(__dirname, "../../import", CSV_NAME),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+
 async function seed() {
-  const csvPath = path.resolve(__dirname, "../../import/races_2026_calendar.csv");
-  if (!fs.existsSync(csvPath)) {
-    console.error(`[seed] CSV not found: ${csvPath}`);
+  const csvPath = resolveCsvPath();
+  if (!csvPath) {
+    console.error(
+      `[seed] CSV not found: ${CSV_NAME}. Tried:\n  - ${path.resolve(__dirname, "../import", CSV_NAME)}\n  - ${path.resolve(__dirname, "../../import", CSV_NAME)}`,
+    );
     process.exit(1);
   }
 
@@ -42,23 +81,28 @@ async function seed() {
 
   const client = await pool.connect();
   try {
+    const ownerUserId = await resolveSeedOwnerUserId(client);
     for (const row of records) {
-      const id = makeId(row.date, row.event);
+      const slug = makeId(row.date, row.event);
       const distanceKm = parseFloat(row.distance_km);
 
-      await client.query(
-        `INSERT INTO races (id, race_date, title, distance_km, status)
-         VALUES ($1, $2, $3, $4, $5)
-         ON CONFLICT (id) DO UPDATE SET
-           race_date    = EXCLUDED.race_date,
-           title        = EXCLUDED.title,
-           distance_km  = EXCLUDED.distance_km,
-           status       = EXCLUDED.status,
-           updated_at   = NOW()`,
-        [id, row.date, row.event, distanceKm, "planned"],
-      );
+      if (ownerUserId) {
+        await client.query(
+          `INSERT INTO races (slug, owner_user_id, race_date, title, distance_km, status, source)
+           VALUES ($1, $2, $3, $4, $5, $6, 'seed')
+           ON CONFLICT DO NOTHING`,
+          [slug, ownerUserId, row.date, row.event, distanceKm, "planned"],
+        );
+      } else {
+        await client.query(
+          `INSERT INTO races (slug, race_date, title, distance_km, status, source)
+           VALUES ($1, $2, $3, $4, $5, 'seed')
+           ON CONFLICT DO NOTHING`,
+          [slug, row.date, row.event, distanceKm, "planned"],
+        );
+      }
 
-      console.log(`[seed] Upserted: ${id}`);
+      console.log(`[seed] Inserted if missing: ${slug}`);
     }
 
     console.log("[seed] Done.");

backend/src/turnstile.ts

@@ -0,0 +1,33 @@
+import { config } from "./config";
+
+export async function verifyTurnstileToken(token: string, remoteIp?: string): Promise<boolean> {
+  if (config.turnstile.bypassToken && token === config.turnstile.bypassToken) {
+    return true;
+  }
+  if (!config.turnstile.secretKey) {
+    return false;
+  }
+
+  const body = new URLSearchParams();
+  body.set("secret", config.turnstile.secretKey);
+  body.set("response", token);
+  if (remoteIp) {
+    body.set("remoteip", remoteIp);
+  }
+
+  try {
+    const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body,
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) {
+      return false;
+    }
+    const payload = (await response.json()) as { success?: boolean };
+    return payload.success === true;
+  } catch {
+    return false;
+  }
+}

backend/src/version.ts

@@ -0,0 +1,24 @@
+import fs from "fs";
+import path from "path";
+
+let cached: string | null = null;
+
+export function getBackendVersion(): string {
+  if (cached) {
+    return cached;
+  }
+  const fromEnv = process.env.APP_VERSION?.trim();
+  if (fromEnv) {
+    cached = fromEnv;
+    return cached;
+  }
+  try {
+    const pkgPath = path.join(__dirname, "..", "package.json");
+    const raw = fs.readFileSync(pkgPath, "utf-8");
+    cached = (JSON.parse(raw) as { version: string }).version;
+    return cached;
+  } catch {
+    cached = "0.0.0";
+    return cached;
+  }
+}

backend/test/app.test.ts

@@ -0,0 +1,405 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import request from "supertest";
+import { buildHelmetOptions, createApp } from "../src/app";
+import {
+  cleanupExpiredAuthRows,
+  createResetToken,
+  createVerificationToken,
+  resetPassword,
+  verifyEmailToken,
+} from "../src/authService";
+import { resolveTurnstileBypassToken } from "../src/config";
+import { pool } from "../src/db";
+import { extractRaceCoverImageFromHtml } from "../src/raceCoverImage";
+import { hashPassword, normalizeEmail } from "../src/security";
+
+const app = createApp();
+let userCounter = 0;
+
+async function authAgent() {
+  userCounter += 1;
+  const email = normalizeEmail(`runner${userCounter}@example.com`);
+  const password = "correct horse battery staple";
+  const passwordHash = await hashPassword(password);
+  const inserted = await pool.query<{ id: string }>(
+    `INSERT INTO users (email, password_hash)
+     VALUES ($1, $2)
+     RETURNING id`,
+    [email, passwordHash],
+  );
+  await pool.query("UPDATE users SET email_verified_at = COALESCE(email_verified_at, NOW()) WHERE id = $1", [
+    inserted.rows[0].id,
+  ]);
+  const agent = request.agent(app);
+  const login = await agent.post("/api/auth/login").send({ email, password }).expect(200);
+  return { agent, csrfToken: login.body.csrfToken as string };
+}
+
+async function createVerifiedUser(email: string, password: string) {
+  return createUser(email, password, true);
+}
+
+async function createUnverifiedUser(email: string, password: string) {
+  return createUser(email, password, false);
+}
+
+async function createUser(email: string, password: string, verified: boolean) {
+  const passwordHash = await hashPassword(password);
+  const inserted = await pool.query<{ id: string }>(
+    `INSERT INTO users (email, password_hash)
+     VALUES ($1, $2)
+     RETURNING id`,
+    [normalizeEmail(email), passwordHash],
+  );
+  if (verified) {
+    await pool.query("UPDATE users SET email_verified_at = COALESCE(email_verified_at, NOW()) WHERE id = $1", [
+      inserted.rows[0].id,
+    ]);
+  }
+  return inserted.rows[0].id;
+}
+
+async function countByTokenHash(table: "sessions" | "email_verification_tokens" | "password_reset_tokens", tokenHash: string) {
+  const { rows } = await pool.query<{ count: string }>(
+    `SELECT COUNT(*)::text AS count FROM ${table} WHERE token_hash = $1`,
+    [tokenHash],
+  );
+  return Number(rows[0]?.count ?? "0");
+}
+
+test("GET /api/health returns ok", async () => {
+  const res = await request(app).get("/api/health").expect(200);
+  assert.equal(res.body.status, "ok");
+  assert.equal(typeof res.body.version, "string");
+  assert.ok(res.body.version.length > 0);
+});
+
+test("GET /api/meta returns version for UI footer", async () => {
+  const res = await request(app).get("/api/meta").expect(200);
+  assert.equal(typeof res.body.version, "string");
+  assert.ok(res.body.version.length > 0);
+});
+
+test("GET /api/ready succeeds with mock database", async () => {
+  const res = await request(app).get("/api/ready").expect(200);
+  assert.equal(res.body.status, "ready");
+  assert.equal(res.body.db, "connected");
+});
+
+test("production config rejects Turnstile bypass token", () => {
+  assert.throws(
+    () =>
+      resolveTurnstileBypassToken({
+        rawBypassToken: "unsafe-bypass",
+        securityProfile: "production",
+        useMockDb: false,
+      }),
+    /TURNSTILE_BYPASS_TOKEN/,
+  );
+  assert.equal(
+    resolveTurnstileBypassToken({
+      rawBypassToken: "dev-bypass",
+      securityProfile: "development",
+      useMockDb: false,
+    }),
+    "dev-bypass",
+  );
+  assert.equal(
+    resolveTurnstileBypassToken({
+      rawBypassToken: "mock-bypass",
+      securityProfile: "production",
+      useMockDb: true,
+    }),
+    "mock-bypass",
+  );
+});
+
+test("production CSP allows Turnstile without unsafe script directives", () => {
+  const options = buildHelmetOptions("production") as any;
+  const directives = options.contentSecurityPolicy.directives;
+
+  assert.ok(directives.scriptSrc.includes("https://challenges.cloudflare.com"));
+  assert.ok(directives.frameSrc.includes("https://challenges.cloudflare.com"));
+  assert.ok(directives.connectSrc.includes("https://challenges.cloudflare.com"));
+  assert.ok(!directives.scriptSrc.includes("'unsafe-inline'"));
+  assert.ok(!directives.scriptSrc.includes("'unsafe-eval'"));
+  assert.deepEqual(directives.frameAncestors, ["'none'"]);
+  assert.deepEqual(directives.objectSrc, ["'none'"]);
+});
+
+test("duplicate registration keeps generic accepted response", async () => {
+  const payload = {
+    email: "duplicate-register@example.com",
+    password: "correct horse battery staple",
+    turnstileToken: "mock-turnstile-token",
+  };
+
+  const first = await request(app).post("/api/auth/register").send(payload).expect(202);
+  const second = await request(app).post("/api/auth/register").send(payload).expect(202);
+
+  assert.deepEqual(first.body, { ok: true });
+  assert.deepEqual(second.body, { ok: true });
+});
+
+test("GET /api/races rejects invalid year", async () => {
+  const { agent } = await authAgent();
+  const res = await agent.get("/api/races?year=bad").expect(400);
+  assert.equal(res.body.error, "validation_error");
+  assert.ok(Array.isArray(res.body.details));
+});
+
+test("GET /api/races rejects month out of range", async () => {
+  const { agent } = await authAgent();
+  const res = await agent.get("/api/races?month=13").expect(400);
+  assert.equal(res.body.error, "validation_error");
+});
+
+test("GET /api/races accepts year and month", async () => {
+  const { agent } = await authAgent();
+  const res = await agent.get("/api/races?year=2026&month=5").expect(200);
+  assert.ok(Array.isArray(res.body));
+});
+
+test("GET /api/races/:id returns not_found", async () => {
+  const { agent } = await authAgent();
+  const res = await agent.get("/api/races/does-not-exist").expect(404);
+  assert.equal(res.body.error, "not_found");
+  assert.ok(Array.isArray(res.body.details));
+});
+
+test("GET /api/races requires authentication", async () => {
+  const res = await request(app).get("/api/races").expect(401);
+  assert.equal(res.body.error, "unauthorized");
+});
+
+test("login uses generic response for missing user and wrong password", async () => {
+  const password = "correct horse battery staple";
+  await createVerifiedUser("generic@example.com", password);
+
+  const wrongPassword = await request(app)
+    .post("/api/auth/login")
+    .send({ email: "generic@example.com", password: "wrong password" })
+    .expect(401);
+  const missingUser = await request(app)
+    .post("/api/auth/login")
+    .send({ email: "missing@example.com", password })
+    .expect(401);
+
+  assert.deepEqual(missingUser.body, wrongPassword.body);
+});
+
+test("GET /api/races/:id returns not_found for another user's race", async () => {
+  const first = await authAgent();
+  const created = await first.agent
+    .post("/api/races")
+    .set("X-CSRF-Token", first.csrfToken)
+    .send({
+      slug: "2026-07-01-private-race",
+      date: "2026-07-01",
+      title: "Private Race",
+      distanceKm: 10,
+    })
+    .expect(201);
+
+  const second = await authAgent();
+  const res = await second.agent.get(`/api/races/${created.body.id}`).expect(404);
+  assert.equal(res.body.error, "not_found");
+});
+
+test("new password reset token invalidates previous token", async () => {
+  const userId = await createVerifiedUser("reset@example.com", "correct horse battery staple");
+  const client = await pool.connect();
+  const first = await createResetToken(client, userId);
+  const second = await createResetToken(client, userId);
+  client.release();
+
+  assert.equal(await resetPassword(first, "new correct horse battery staple"), false);
+  assert.equal(await resetPassword(second, "new correct horse battery staple"), true);
+  assert.equal(await resetPassword(second, "new correct horse battery staple"), false);
+});
+
+test("email verification token is single use", async () => {
+  const userId = await createUnverifiedUser("verify-once@example.com", "correct horse battery staple");
+  const client = await pool.connect();
+  const token = await createVerificationToken(client, userId);
+  client.release();
+
+  assert.equal(await verifyEmailToken(token), true);
+  assert.equal(await verifyEmailToken(token), false);
+});
+
+test("auth cleanup removes expired rows and keeps active rows", async () => {
+  const userId = await createVerifiedUser("cleanup@example.com", "correct horse battery staple");
+  const past = new Date(Date.now() - 60_000);
+  const future = new Date(Date.now() + 60_000);
+  const expiredSession = "expired-session-token-hash";
+  const activeSession = "active-session-token-hash";
+  const expiredVerify = "expired-verify-token-hash";
+  const activeVerify = "active-verify-token-hash";
+  const expiredReset = "expired-reset-token-hash";
+  const activeReset = "active-reset-token-hash";
+
+  await pool.query(
+    "INSERT INTO sessions (user_id, token_hash, csrf_token_hash, expires_at) VALUES ($1, $2, $3, $4)",
+    [userId, expiredSession, "expired-csrf", past],
+  );
+  await pool.query(
+    "INSERT INTO sessions (user_id, token_hash, csrf_token_hash, expires_at) VALUES ($1, $2, $3, $4)",
+    [userId, activeSession, "active-csrf", future],
+  );
+  await pool.query(
+    "INSERT INTO email_verification_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+    [userId, expiredVerify, past],
+  );
+  await pool.query(
+    "INSERT INTO email_verification_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+    [userId, activeVerify, future],
+  );
+  await pool.query(
+    "INSERT INTO password_reset_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+    [userId, expiredReset, past],
+  );
+  await pool.query(
+    "INSERT INTO password_reset_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)",
+    [userId, activeReset, future],
+  );
+
+  await cleanupExpiredAuthRows();
+
+  assert.equal(await countByTokenHash("sessions", expiredSession), 0);
+  assert.equal(await countByTokenHash("sessions", activeSession), 1);
+  assert.equal(await countByTokenHash("email_verification_tokens", expiredVerify), 0);
+  assert.equal(await countByTokenHash("email_verification_tokens", activeVerify), 1);
+  assert.equal(await countByTokenHash("password_reset_tokens", expiredReset), 0);
+  assert.equal(await countByTokenHash("password_reset_tokens", activeReset), 1);
+});
+
+test("extractRaceCoverImageFromHtml prefers runc.run intro image", () => {
+  const html = `
+    <meta property="og:image" content="https://example.com/og.jpg">
+    <div class="run-intro__image">
+      <div class="run-intro__image-left-shadow"></div>
+      <img src="/uploads/race_landing_header_backgrounds/header.jpg" alt="">
+      <div class="run-intro__image-right-shadow"></div>
+    </div>
+  `;
+
+  assert.equal(
+    extractRaceCoverImageFromHtml(html, "https://aprilrun5km.runc.run/"),
+    "https://aprilrun5km.runc.run/uploads/race_landing_header_backgrounds/header.jpg",
+  );
+});
+
+test("extractRaceCoverImageFromHtml reads Open Graph and Twitter images", () => {
+  assert.equal(
+    extractRaceCoverImageFromHtml(
+      '<meta property="og:image" content="/cover.png">',
+      "https://example.com/race",
+    ),
+    "https://example.com/cover.png",
+  );
+  assert.equal(
+    extractRaceCoverImageFromHtml(
+      '<meta name="twitter:image" content="https://cdn.example.com/twitter.jpg">',
+      "https://example.com/race",
+    ),
+    "https://cdn.example.com/twitter.jpg",
+  );
+});
+
+test("POST /api/races stores manual coverImageUrl", async () => {
+  const { agent, csrfToken } = await authAgent();
+  const coverImageUrl = "https://example.com/manual.jpg";
+  const res = await agent
+    .post("/api/races")
+    .set("X-CSRF-Token", csrfToken)
+    .send({
+      slug: "2026-06-01-manual-cover",
+      date: "2026-06-01",
+      title: "Manual Cover",
+      distanceKm: 10,
+      officialUrl: "https://example.com/race",
+      coverImageUrl,
+    })
+    .expect(201);
+
+  assert.equal(res.body.coverImageUrl, coverImageUrl);
+});
+
+test("POST /api/races auto extracts coverImageUrl from officialUrl", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () =>
+    new Response('<meta property="og:image" content="/auto.jpg">', {
+      status: 200,
+      headers: { "content-type": "text/html" },
+    });
+
+  try {
+    const { agent, csrfToken } = await authAgent();
+    const res = await agent
+      .post("/api/races")
+      .set("X-CSRF-Token", csrfToken)
+      .send({
+        slug: "2026-06-02-auto-cover",
+        date: "2026-06-02",
+        title: "Auto Cover",
+        distanceKm: 21.1,
+        officialUrl: "https://example.com/race",
+      })
+      .expect(201);
+
+    assert.equal(res.body.coverImageUrl, "https://example.com/auto.jpg");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("POST /api/races succeeds when cover extraction fails", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => {
+    throw new Error("network down");
+  };
+
+  try {
+    const { agent, csrfToken } = await authAgent();
+    const res = await agent
+      .post("/api/races")
+      .set("X-CSRF-Token", csrfToken)
+      .send({
+        slug: "2026-06-03-cover-fail",
+        date: "2026-06-03",
+        title: "Cover Fail",
+        distanceKm: 5,
+        officialUrl: "https://example.com/race",
+      })
+      .expect(201);
+
+    assert.equal(res.body.coverImageUrl, null);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("PATCH /api/races/:id updates coverImageUrl explicitly", async () => {
+  const { agent, csrfToken } = await authAgent();
+  const created = await agent
+    .post("/api/races")
+    .set("X-CSRF-Token", csrfToken)
+    .send({
+      slug: "2026-06-04-patch-cover",
+      date: "2026-06-04",
+      title: "Patch Cover",
+      distanceKm: 10,
+    })
+    .expect(201);
+
+  const coverImageUrl = "https://example.com/patched.jpg";
+  const res = await agent
+    .patch(`/api/races/${created.body.id}`)
+    .set("X-CSRF-Token", csrfToken)
+    .send({ coverImageUrl })
+    .expect(200);
+
+  assert.equal(res.body.coverImageUrl, coverImageUrl);
+});

docker-compose.stack.yml

@@ -0,0 +1,53 @@
+# Backend + frontend в сети с уже поднятым PostgreSQL (external network).
+#
+# Подготовка: из корня репозитория скопируйте .env.example → .env и задайте DB_*
+# и CORS_ORIGIN (для фронта на :3033 — http://localhost:3033).
+#
+# Сеть (имя должно существовать, как у вашего Postgres):
+#   docker network ls
+#
+# Запуск:
+#   docker compose -f docker-compose.stack.yml up -d --build
+#
+# Миграции и seed (один раз после появления БД):
+#   docker compose -f docker-compose.stack.yml exec runners-calendar-backend node dist/migrate.js
+#   docker compose -f docker-compose.stack.yml exec runners-calendar-backend node dist/seed.js
+#
+# NPM: проброс на порт 3033. Браузер ходит на /api → nginx во фронте → runners-calendar-backend:3000.
+# Имя сервиса уникально в общей сети (не «backend»), чтобы не пересекаться с другими стеками.
+
+services:
+  runners-calendar-backend:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend
+    container_name: runners-calendar-backend
+    env_file:
+      - .env
+    environment:
+      - PORT=3000
+    ports:
+      - "3001:3000"
+    volumes:
+      # CSV и прочие данные import/ на хосте (Synology: ./import рядом с compose) без пересборки образа
+      - ./import:/app/import:ro
+    restart: unless-stopped
+    networks:
+      - postgres_default
+
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile.frontend
+    container_name: runners-calendar-frontend
+    depends_on:
+      - runners-calendar-backend
+    ports:
+      - "3033:80"
+    restart: unless-stopped
+    networks:
+      - postgres_default
+
+networks:
+  postgres_default:
+    external: true

docker/nginx.frontend.conf

@@ -0,0 +1,20 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+
+  # Браузер ходит на тот же origin: /api/* → бэкенд с тем же префиксом /api
+  location /api/ {
+    proxy_pass http://runners-calendar-backend:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}

docs/agent-backend-instruction.md

@@ -1,161 +0,0 @@
-# Инструкция агенту: реализация бэкенда по [PLAN.md](../PLAN.md)
-
-Документ для ИИ-агента или разработчика, который создаёт **backend** монорепозитория «календарь забегов». Продуктовые цели и модель данных — в корневом **PLAN.md**; здесь — порядок работ, ограничения и **обязательные итоговые артефакты для фронтенда**.
-
----
-
-## 0. Ограничение: нет возможности проверить подключение к БД
-
-1. **Всё равно реализовать полноценный бэкенд «как для прод»**: миграции SQL, пул подключений `pg`, переменные `DB_*`, `docker-compose.yml` с PostgreSQL в корне репозитория.
-2. **Не блокировать работу отсутствием живой БД у исполнителя:**
-   - код миграций и seed должен быть **валидным и согласованным** с PLAN;
-   - при старте API при невозможности подключиться к БД — **ясное сообщение в лог** и **корректный HTTP-ответ** на зависящих от БД маршрутах (например 503 с телом `{"error":"database_unavailable",...}`) **или** падение процесса на старте с понятной ошибкой (выбрать одну стратегию и описать её в `docs/backend.md`).
-3. **Не выдумывать обход БД** (in-memory «режим без Postgres»), если это не согласовано отдельно — фронт и план рассчитаны на PostgreSQL.
-4. Автотесты, требующие Docker/Postgres, помечать как **опциональные** или давать инструкцию «как прогнать локально», не считая провал из-за отсутствия БД у агента блокером для merge кода.
-
----
-
-## 1. Ветка и расположение в репо
-
-- Если репозиторий под git: создать ветку `feature/backend-api` (или аналог по соглашению команды).
-- Каталог **`backend/`** в корне проекта рядом с будущим `frontend/`.
-- Корневой **`docker-compose.yml`** — сервис `postgres` (порт, пользователь, БД, пароль — согласовать с `.env.example`).
-
----
-
-## 2. Порядок реализации (обязательный)
-
-### Шаг A. Каркас
-
-- Node **LTS**, **TypeScript**, **`backend/package.json`**.
-- Фреймворк: **Fastify** или **Express** (выбрать один, не смешивать).
-- Загрузка env: `dotenv` или встроенные средства; **валидация** наличия `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` при старте (или при первом запросе к БД — но тогда задокументировать).
-- Сервер слушает порт из **`PORT`** или **`API_PORT`** (значение по умолчанию, напр. `3001`, указать в `.env.example`).
-
-### Шаг B. CORS
-
-- Читать **`CORS_ORIGIN`** (например `http://localhost:5173` для Vite в dev). В prod — origin фронта.
-- Разрешить методы и заголовки, нужные для `GET/POST/PATCH` + `Content-Type: application/json`.
-
-### Шаг C. Миграции
-
-- Каталог миграций, напр. `backend/migrations/` с нумерованными SQL-файлами **или** один миграционный runner (node-pg-migrate, graphile-migrate, собственный скрипт — на выбор, зафиксировать в `docs/backend.md`).
-- Первая миграция: таблица **`races`** со столбцами, соответствующими PLAN (см. раздел 3 ниже).
-- Команда **`npm run db:migrate`** (или эквивалент в `backend/`) — идемпотентное накатывание на чистую БД.
-
-### Шаг D. Доступ к данным
-
-- Клиент **`pg`**: `Pool` с параметрами из `DB_*`.
-- Слой репозитория или прямые запросы в обработчиках — на усмотрение, без лишних абстракций сверх задачи.
-
-### Шаг E. HTTP API
-
-Реализовать минимум:
-
-| Метод | Путь | Назначение |
-|--------|------|------------|
-| `GET` | `/health` | Liveness: процесс жив; **не обязан** проверять БД (или опционально — задокументировать). |
-| `GET` | `/ready` (опционально) | Readiness: проверка соединения с БД — полезно для оркестраторов. |
-| `GET` | `/races` | Список забегов; **query**: `year`, `month` (1–12) — фильтрация для экранов календаря; без параметров — все строки или разумный лимит + документация пагинации если добавите позже. |
-| `GET` | `/races/:id` | Одна запись по `id`. |
-| `POST` | `/races` | Создание; тело JSON в **camelCase** как в PLAN. |
-| `PATCH` | `/races/:id` | Частичное обновление; только переданные поля. |
-| `DELETE` | `/races/:id` | Опционально по PLAN; если не нужен фронту — можно не делать, но тогда явно написать в документации «удаление не поддерживается». |
-
-**Ошибки:**
-
-- 400 — валидация тела/параметров.
-- 404 — нет `id`.
-- 409 — конфликт уникального `id` при POST (если клиент прислал уже существующий).
-- 503 или 500 — недоступна БД (согласовать с разделом 0).
-
-Формат ошибки: JSON, единообразно, напр. `{"error":"validation_error","details":[...]}`.
-
-### Шаг F. Seed (разовый скрипт)
-
-- Команда **`npm run seed`** в `backend/` (или корне монорепо с `workspace` — единообразно).
-- Читает **`import/races_2026_calendar.csv`** (путь от корня репо); парсинг с учётом кавычек в поле названия.
-- Генерирует **`id`** стабильно: например `{date}-{slug-from-title}`; при коллизии — суффикс или upsert по `id`.
-- **`INSERT ... ON CONFLICT (id) DO UPDATE`** (upsert) — удобно для повторного запуска seed.
-- Seed **не** вызывается из HTTP handlers.
-
-### Шаг G. Корневой `.env.example`
-
-- Все переменные: `DB_*`, `PORT`/`API_PORT`, `CORS_ORIGIN`.
-- **Без** реальных паролей; комментарии к каждой переменной.
-
----
-
-## 3. Соответствие полей PLAN ↔ SQL ↔ JSON API
-
-**В JSON API (запрос/ответ)** — **camelCase**, как в PLAN:
-
-`id`, `date`, `title`, `distanceKm`, `status`, `officialUrl`, `startTime`, `clusterSchedule`, `bibPickup`, `bibNumber`, `finishTime`, `notes`.
-
-**В PostgreSQL** — **snake_case**, например:
-
-| SQL column | Тип (рекомендация) |
-|------------|---------------------|
-| `id` | `TEXT` PRIMARY KEY |
-| `race_date` | `DATE` |
-| `title` | `TEXT` |
-| `distance_km` | `NUMERIC(6,3)` |
-| `status` | `TEXT` CHECK (опционально) |
-| `official_url` | `TEXT` |
-| `start_time` | `TEXT` |
-| `cluster_schedule` | `TEXT` |
-| `bib_pickup` | `TEXT` |
-| `bib_number` | `TEXT` |
-| `finish_time` | `TEXT` |
-| `notes` | `TEXT` |
-| `created_at` | `TIMESTAMPTZ` DEFAULT now() |
-| `updated_at` | `TIMESTAMPTZ` |
-
-Маппинг **строго** в одном модуле (например `backend/src/mappers/race.ts`), чтобы фронт всегда видел camelCase.
-
-**Типы `date`:** в API строка `YYYY-MM-DD`. **`distanceKm`:** число. **`finishTime`:** строка времени как в PLAN; бэкенд **не обязан** парсить для бизнес-логики (PR считает фронт), но может валидировать формат по желанию.
-
----
-
-## 4. Обязательный итог для упрощения фронтенда
-
-После того как код бэкенда готов, агент **обязан** добавить в репозиторий документ:
-
-### Файл: `docs/backend-api-for-frontend.md`
-
-В нём **кратко и без пробелов в фактах**:
-
-1. **Base URL** — что подставлять во фронт (`VITE_API_BASE_URL`), пример для dev.
-2. **CORS** — какой `CORS_ORIGIN` ожидается в dev.
-3. **Таблица эндпоинтов** — метод, путь, query, тело запроса (пример JSON), пример успешного ответа, коды ошибок.
-4. **Модель `Race`** — перечень полей в **camelCase** с типами и обязательностью для POST vs PATCH.
-5. **Фильтр списка** — как именно работают `year` и `month` на `GET /races` (включая границы: пустой месяц, только год и т.д.).
-6. **Идемпотентность seed** — одна фраза: upsert по `id`, откуда берётся CSV.
-7. **Поведение при недоступной БД** — что возвращает API / что в логах (как в реализации).
-
-Дополнительно можно дублировать суть в **`docs/backend.md`** (общая эксплуатация: docker, migrate, seed, запуск), но **`backend-api-for-frontend.md`** — главная «шпаргалка» для разработчика SPA.
-
----
-
-## 5. Критерии готовности (чеклист агента)
-
-- [ ] `docker-compose.yml` поднимает Postgres с параметрами, совместимыми с `.env.example`.
-- [ ] Миграция создаёт `races`; есть команда миграции.
-- [ ] Реализованы `GET /races`, `GET /races/:id`, `POST /races`, `PATCH /races/:id` согласно PLAN.
-- [ ] Реализован seed из `import/races_2026_calendar.csv`.
-- [ ] `GET /health` (и при наличии `/ready` — описано).
-- [ ] Корневой `.env.example` обновлён.
-- [ ] Написан **`docs/backend-api-for-frontend.md`** (раздел 4).
-- [ ] `docs/backend.md` содержит команды: установка зависимостей, migrate, seed, `npm run dev` для API.
-
----
-
-## 6. Не входит в объём бэкенда (напоминание)
-
-- Авторизация, пользователи, сессии.
-- Парсинг сайтов организаторов.
-- Отдача статики фронта с того же процесса (фронт — отдельно Vite/build).
-
----
-
-*Конец инструкции. Источник требований к продукту — всегда [PLAN.md](../PLAN.md).*

docs/auth-rollout.md

@@ -0,0 +1,13 @@
+# Auth rollout
+
+Before applying auth and ownership migrations in production:
+
+1. Run `pg_dump` for the target database and keep the dump until verification is complete.
+2. Record the rollback command for restoring that dump if migration or legacy race claiming fails.
+3. Record the current race count with `SELECT count(*) FROM races;`.
+4. Run migrations.
+5. After the first email-verified user claims legacy races, verify:
+   - `SELECT count(*) FROM races;` matches the pre-migration count.
+   - `SELECT count(*) FROM races WHERE owner_user_id IS NULL;` is `0` before planning the follow-up `NOT NULL` migration.
+
+Seed/import after auth requires `SEED_OWNER_USER_ID` or `SEED_OWNER_EMAIL` once users exist. It inserts missing seed races for that owner and does not overwrite user-edited races.

docs/backend-api-for-frontend.md

@@ -2,11 +2,10 @@
 
 ## 1. Base URL
 
-```
-VITE_API_BASE_URL=http://localhost:3001
-```
+SPA всегда отправляет запросы на относительный префикс `/api` текущего origin.
 
-В коде SPA: `import.meta.env.VITE_API_BASE_URL`.
+- В dev (`npm run dev`): Vite proxy отправляет `/api/*` на `http://localhost:3001/api/*`.
+- В Docker/проде: nginx фронта проксирует `/api/*` на хост `runners-calendar-backend:3000` в той же сети (уникальное имя сервиса Compose, без коллизий с чужими стеками).
 
 ## 2. CORS
 
@@ -20,7 +19,7 @@ CORS_ORIGIN=http://localhost:5173
 
 ## 3. Эндпоинты
 
-### `GET /health`
+### `GET /api/health`
 
 Liveness-проверка (без обращения к БД).
 
@@ -32,7 +31,7 @@ Liveness-проверка (без обращения к БД).
 
 ---
 
-### `GET /ready`
+### `GET /api/ready`
 
 Readiness-проверка (проверяет подключение к БД).
 
@@ -50,7 +49,7 @@ Readiness-проверка (проверяет подключение к БД).
 
 ---
 
-### `GET /races`
+### `GET /api/races`
 
 Список забегов, отсортированных по дате.
 
@@ -68,7 +67,7 @@ Readiness-проверка (проверяет подключение к БД).
 **Пример запроса:**
 
 ```
-GET /races?year=2026&month=5
+GET /api/races?year=2026&month=5
 ```
 
 **Ответ 200:**
@@ -82,11 +81,13 @@ GET /races?year=2026&month=5
     "distanceKm": 42.195,
     "status": "planned",
     "officialUrl": null,
+    "coverImageUrl": null,
     "startTime": null,
     "clusterSchedule": null,
     "bibPickup": null,
     "bibNumber": null,
     "finishTime": null,
+    "finishPlace": null,
     "notes": null,
     "createdAt": "2026-03-31T12:00:00.000Z",
     "updatedAt": null
@@ -96,21 +97,21 @@ GET /races?year=2026&month=5
 
 ---
 
-### `GET /races/:id`
+### `GET /api/races/:id`
 
 Одна запись по `id`.
 
 **Ответ 200:** объект `Race` (см. модель ниже).
 
-**Ответ 404:**
+**Ответ 404:** тело JSON, поле `details` — массив пояснений (можно показывать в UI или игнорировать).
 
 ```json
-{ "error": "not_found" }
+{ "error": "not_found", "details": ["Race not found"] }
 ```
 
 ---
 
-### `POST /races`
+### `POST /api/races`
 
 Создание забега.
 
@@ -124,11 +125,13 @@ GET /races?year=2026&month=5
   "distanceKm": 10,
   "status": "planned",
   "officialUrl": "https://example.com",
+  "coverImageUrl": "https://example.com/cover.jpg",
   "startTime": "09:30",
   "clusterSchedule": null,
   "bibPickup": null,
   "bibNumber": null,
   "finishTime": null,
+  "finishPlace": null,
   "notes": null
 }
 ```
@@ -151,7 +154,7 @@ GET /races?year=2026&month=5
 
 ---
 
-### `PATCH /races/:id`
+### `PATCH /api/races/:id`
 
 Частичное обновление — передавать **только** изменяемые поля.
 
@@ -160,12 +163,13 @@ GET /races?year=2026&month=5
 ```json
 {
   "finishTime": "1:45:30",
+  "finishPlace": "12/340",
   "bibNumber": "1234",
   "status": "completed"
 }
 ```
 
-**Допустимые поля:** `date`, `title`, `distanceKm`, `status`, `officialUrl`, `startTime`, `clusterSchedule`, `bibPickup`, `bibNumber`, `finishTime`, `notes`.
+**Допустимые поля:** `date`, `title`, `distanceKm`, `status`, `officialUrl`, `coverImageUrl`, `startTime`, `clusterSchedule`, `bibPickup`, `bibNumber`, `finishTime`, `finishPlace`, `notes`.
 
 **Ответ 200:** обновлённый объект `Race`.
 
@@ -178,12 +182,12 @@ GET /races?year=2026&month=5
 **Ответ 404:**
 
 ```json
-{ "error": "not_found" }
+{ "error": "not_found", "details": ["Race not found"] }
 ```
 
 ---
 
-### `DELETE /races/:id`
+### `DELETE /api/races/:id`
 
 Удаление забега.
 
@@ -192,7 +196,7 @@ GET /races?year=2026&month=5
 **Ответ 404:**
 
 ```json
-{ "error": "not_found" }
+{ "error": "not_found", "details": ["Race not found"] }
 ```
 
 ## 4. Модель `Race` (camelCase)
@@ -203,18 +207,20 @@ GET /races?year=2026&month=5
 | `date` | string | да | да | `YYYY-MM-DD` |
 | `title` | string | да | да | Название забега |
 | `distanceKm` | number | да | да | Дистанция в км |
-| `status` | string \| null | нет | да | `"planned"` / `"completed"` |
+| `status` | string \| null | нет | да | `"planned"` / `"registered"` / `"completed"` |
 | `officialUrl` | string \| null | нет | да | URL организатора |
-| `startTime` | string \| null | нет | да | Время старта, напр. `"09:30"` |
+| `coverImageUrl` | string \| null | нет | да | URL обложки забега. При `POST` может быть найден автоматически по `officialUrl`, если не передан вручную |
+| `startTime` | string \| null | нет | да | Время старта, напр. `"09:30"` или `"09:30:00"` (часы:минуты:секунды) |
 | `clusterSchedule` | string \| null | нет | да | Расписание кластеров |
 | `bibPickup` | string \| null | нет | да | Выдача номеров |
 | `bibNumber` | string \| null | нет | да | Стартовый номер |
-| `finishTime` | string \| null | нет | да | Финишное время `H:MM:SS` |
+| `finishTime` | string \| null | нет | да | Финишное время `H:MM:SS` или `MM:SS` |
+| `finishPlace` | string \| null | нет | да | Место на финише (произвольная строка) |
 | `notes` | string \| null | нет | да | Заметки |
 | `createdAt` | string | — | — | ISO timestamp (read-only) |
 | `updatedAt` | string \| null | — | — | ISO timestamp (read-only) |
 
-## 5. Фильтрация списка (`GET /races`)
+## 5. Фильтрация списка (`GET /api/races`)
 
 - **`year`** — целое число, фильтрует по `EXTRACT(YEAR FROM race_date)`.
 - **`month`** — целое число 1–12, фильтрует по `EXTRACT(MONTH FROM race_date)`.
@@ -228,7 +234,7 @@ Seed-скрипт (`npm run seed` в `backend/`) выполняет **upsert**
 
 ## 7. Поведение при недоступной БД
 
-- `GET /health` — всегда `200` (не проверяет БД).
-- `GET /ready` — `503 { "error": "database_unavailable", "db": "disconnected" }`.
+- `GET /api/health` — всегда `200` (не проверяет БД).
+- `GET /api/ready` — при недоступной БД: `503 { "error": "database_unavailable", "db": "disconnected" }`. В режиме **`CALENDAR_RUN_MOCK_DB`** (dev/CI без Postgres) readiness возвращает успех без реального подключения — см. `docs/backend.md`.
 - Все остальные маршруты — `503 { "error": "database_unavailable" }`.
 - В логах сервера: строка ошибки с контекстом маршрута.

docs/backend.md

@@ -62,27 +62,33 @@ npm run build    # компиляция в dist/
 npm start        # запуск из dist/
 ```
 
-API слушает порт из `API_PORT` (по умолчанию `3001`).
+API слушает порт: **`PORT`** (если задан), иначе **`API_PORT`**, иначе **`3001`**.
 
 ## Переменные окружения
 
 | Переменная | Описание | По умолчанию |
 |---|---|---|
-| `DB_HOST` | Хост PostgreSQL | — (обязательна) |
-| `DB_PORT` | Порт PostgreSQL | — (обязательна) |
-| `DB_NAME` | Имя базы данных | — (обязательна) |
-| `DB_USER` | Пользователь БД | — (обязательна) |
-| `DB_PASSWORD` | Пароль БД | — (обязательна) |
+| `DB_HOST` | Хост PostgreSQL | — (обязательна без mock, см. ниже) |
+| `DB_PORT` | Порт PostgreSQL | — (обязательна без mock) |
+| `DB_NAME` | Имя базы данных | — (обязательна без mock) |
+| `DB_USER` | Пользователь БД | — (обязательна без mock) |
+| `DB_PASSWORD` | Пароль БД | — (обязательна без mock) |
+| `CALENDAR_RUN_MOCK_DB` | `1` или `true` — режим без PostgreSQL для HTTP API (dev/CI) | выкл. |
+| `PORT` | Порт API (приоритетнее `API_PORT`) | — |
 | `API_PORT` | Порт API-сервера | `3001` |
 | `CORS_ORIGIN` | Разрешённый origin для CORS | `http://localhost:5173` |
 
-При отсутствии любой из `DB_*` процесс падает при старте с сообщением `Missing required environment variable: <NAME>`.
+Фронтенд всегда обращается к API по префиксу `/api` на текущем origin. В локальной разработке этот префикс проксирует Vite (`frontend/vite.config.ts`) на `http://localhost:3001`; в Docker-стеке — nginx фронта проксирует на `runners-calendar-backend:3000`.
+
+**Без mock:** при отсутствии любой из `DB_*` процесс падает при старте: `Missing required environment variable: <NAME>`.
+
+**С `CALENDAR_RUN_MOCK_DB=1`:** переменные `DB_*` не обязательны; реальный пул не поднимается. **Не использовать** mock для `npm run db:migrate` и `npm run seed` — нужен настоящий Postgres и корректные `DB_*`.
 
 ## Поведение при недоступной БД
 
 - **Старт сервера** — проходит успешно (env валидирован, Express слушает порт).
-- **`GET /health`** — всегда `200 { "status": "ok" }` (liveness, без обращения к БД).
-- **`GET /ready`** — пробует подключиться к БД; возвращает `200` если ОК, `503 { "error": "database_unavailable" }` если нет.
+- **`GET /api/health`** — всегда `200 { "status": "ok" }` (liveness, без обращения к БД).
+- **`GET /api/ready`** — при обычном режиме пробует подключиться к БД; `200` если ОК, `503 { "error": "database_unavailable", ... }` если нет. В режиме **`CALENDAR_RUN_MOCK_DB`** readiness считается успешным без реального подключения (удобно для CI/smoke API).
 - **Все остальные маршруты** при ошибке БД возвращают `503 { "error": "database_unavailable" }`.
 
 ## Структура каталога
@@ -90,18 +96,26 @@ API слушает порт из `API_PORT` (по умолчанию `3001`).
 ```
 backend/
 ├── migrations/
-│   └── 001_create_races.sql
+│   ├── 001_create_races.sql
+│   └── 002_finish_place_and_registered_status.sql
 ├── src/
+│   ├── app.ts             # фабрика Express (тесты)
 │   ├── config.ts          # загрузка и валидация env
-│   ├── db.ts              # pg Pool
-│   ├── index.ts           # точка входа Express
+│   ├── db.ts              # pg Pool или mock
+│   ├── index.ts           # запуск сервера
 │   ├── migrate.ts         # раннер миграций
 │   ├── seed.ts            # разовый импорт CSV
 │   ├── mappers/
 │   │   └── race.ts        # snake_case ↔ camelCase
 │   └── routes/
-│       ├── health.ts      # /health, /ready
-│       └── races.ts       # CRUD /races
+│       ├── health.ts      # /api/health, /api/ready, /api/meta
+│       └── races.ts       # CRUD /api/races
 ├── package.json
 └── tsconfig.json
 ```
+
+## Docker: стек backend + frontend
+
+Файл [`docker-compose.stack.yml`](../docker-compose.stack.yml) поднимает API и nginx со статикой SPA в **внешней** сети Docker (рядом с уже запущенным Postgres). Переменные — в **корневом** `.env` (шаблон [`.env.example`](../.env.example)): как минимум `DB_*`, `CORS_ORIGIN` (для выдачи фронта на порту 3033 задайте `http://localhost:3033`). Перед первым `up` файл `.env` должен существовать.
+
+Порядок после старта контейнеров: `node dist/migrate.js` и `node dist/seed.js` внутри сервиса `runners-calendar-backend` (см. комментарии в compose-файле).

docs/plan-korrektirovok-starty.md

@@ -0,0 +1,52 @@
+# План корректировок: форма старта, время, календарь стартов
+
+Краткое описание реализованных изменений в клиенте **runners-calendar** (версия клиента см. в футере приложения).
+
+## 1. Форма старта (редактирование прошедшего события)
+
+При **редактировании** старта, чья **дата уже в прошлом**, в блоке «Организация» скрыты поля, неактуальные после забега:
+
+- сайт организатора;
+- время старта;
+- расписание кластеров;
+- выдача номеров.
+
+Значения по-прежнему хранятся в состоянии формы и отправляются при сохранении (не затираются). Утилита: `isRaceDateInPast` в `frontend/src/lib/raceMetrics.ts`.
+
+## 2. Время старта
+
+Вместо свободного текста — три селекта (часы, минуты, секунды), компонент `StartTimeSelects` в `frontend/src/components/StartTimeSelects.tsx`. Сохраняется строка `HH:mm:ss` или пусто → `null` в API. Поддерживается разбор старых значений `HH:mm` при загрузке.
+
+## 3. Список на странице «Календарь стартов»
+
+Для стартов со статусом **«внесите результат»** вся карточка — ссылка на `/races/:id/edit` с лёгким увеличением и тенью при наведении/фокусе (токен `--shadow-card-lift`).
+
+## 4. Виды: список и календарь
+
+- Переключатель **Список / Календарь**, выбор сохраняется в `sessionStorage` (`races-view-mode`).
+- **Календарь:** загрузка гонок за выбранный **год** (без фильтра месяца в запросе), отображение сетки месяцев.
+- При выборе **месяца** в фильтре — крупная сетка этого месяца и компактная навигация по остальным месяцам + «Весь год».
+
+## 5. Ячейка даты в календаре
+
+- Наведение или фокус: всплывающая панель — либо «Стартов нет» и кнопка **Добавить** (`/races/new?date=YYYY-MM-DD`), либо список стартов со ссылками на карточки и **Добавить**.
+- Клик по числу — страница дня `/races/day/:ymd`.
+
+## 6. Страница дня
+
+Маршрут `races/day/:ymd`: список стартов на дату, пустое состояние, кнопка **Добавить** с предзаполнением даты через query.
+
+## 7. Новый старт с датой из календаря
+
+`RaceFormPage` читает query-параметр `?date=YYYY-MM-DD` при создании старта.
+
+## Основные файлы
+
+| Область | Файлы |
+|--------|--------|
+| Метрики даты | `frontend/src/lib/raceMetrics.ts`, `frontend/src/lib/calendarUtils.ts` |
+| Форма | `frontend/src/pages/RaceFormPage.tsx`, `frontend/src/components/StartTimeSelects.tsx` |
+| Список и календарь | `frontend/src/pages/RacesPage.tsx`, `frontend/src/components/RacesCalendar.tsx` |
+| День | `frontend/src/pages/RaceDayPage.tsx`, `frontend/src/app/router.tsx` |
+| Стили | `frontend/src/styles/global.css`, `frontend/src/styles/tokens.css` |
+| API-док | `docs/backend-api-for-frontend.md` (формат `startTime`) |

frontend/.env.example

@@ -0,0 +1,4 @@
+# Для production-регистрации укажите публичный site key Cloudflare Turnstile.
+# Без значения локально используется dev bypass token, если он разрешён бэкендом.
+# VITE_TURNSTILE_SITE_KEY=
+# Полный список переменных окружения — в корневом .env.example репозитория.

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Календарь стартов</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.7.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/public/favicon.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Календарь стартов">
+  <defs>
+    <linearGradient id="bg" x1="12" y1="4" x2="52" y2="60" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#1168d8" />
+      <stop offset="1" stop-color="#071927" />
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="16" fill="url(#bg)" />
+  <path
+    d="M18 20h28a5 5 0 0 1 5 5v21a5 5 0 0 1-5 5H18a5 5 0 0 1-5-5V25a5 5 0 0 1 5-5Z"
+    fill="#ffffff"
+  />
+  <path d="M13 29h38" stroke="#d6e1ea" stroke-width="4" />
+  <path d="M23 14v11M41 14v11" stroke="#b9f24a" stroke-width="5" stroke-linecap="round" />
+  <path
+    d="M22 41c5-8 13-8 18 0M22 41h18"
+    fill="none"
+    stroke="#1168d8"
+    stroke-width="5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  />
+  <circle cx="44" cy="44" r="5" fill="#ff6f5e" />
+</svg>

frontend/src/api/auth.ts

@@ -0,0 +1,69 @@
+import { requestJson, setCsrfToken } from "./http";
+import type { AuthUser } from "./types";
+
+interface AuthResponse {
+  user: AuthUser;
+  csrfToken: string | null;
+}
+
+function applyAuthResponse(response: AuthResponse): AuthResponse {
+  setCsrfToken(response.csrfToken);
+  return response;
+}
+
+export async function getCurrentUser(): Promise<AuthResponse> {
+  return applyAuthResponse(await requestJson<AuthResponse>("/auth/me"));
+}
+
+export async function register(payload: {
+  email: string;
+  password: string;
+  turnstileToken: string;
+}): Promise<void> {
+  await requestJson<void>("/auth/register", {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}
+
+export async function login(payload: { email: string; password: string }): Promise<AuthResponse> {
+  return applyAuthResponse(
+    await requestJson<AuthResponse>("/auth/login", {
+      method: "POST",
+      body: JSON.stringify(payload),
+    }),
+  );
+}
+
+export async function logout(): Promise<void> {
+  await requestJson<void>("/auth/logout", { method: "POST" });
+  setCsrfToken(null);
+}
+
+export async function verifyEmail(token: string): Promise<void> {
+  await requestJson<void>("/auth/verify-email", {
+    method: "POST",
+    body: JSON.stringify({ token }),
+  });
+}
+
+export async function resendVerification(email: string): Promise<void> {
+  await requestJson<void>("/auth/resend-verification", {
+    method: "POST",
+    body: JSON.stringify({ email }),
+  });
+}
+
+export async function forgotPassword(email: string): Promise<void> {
+  await requestJson<void>("/auth/forgot-password", {
+    method: "POST",
+    body: JSON.stringify({ email }),
+  });
+}
+
+export async function resetPassword(token: string, password: string): Promise<void> {
+  await requestJson<void>("/auth/reset-password", {
+    method: "POST",
+    body: JSON.stringify({ token, password }),
+  });
+}

frontend/src/api/errors.ts

@@ -0,0 +1,132 @@
+export type ApiErrorCode =
+  | "validation_error"
+  | "not_found"
+  | "database_unavailable"
+  | "conflict"
+  | "unauthorized"
+  | "email_not_verified"
+  | "csrf_error"
+  | "captcha_failed"
+  | "invalid_credentials"
+  | "invalid_token"
+  | "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" ||
+    value === "unauthorized" ||
+    value === "email_not_verified" ||
+    value === "csrf_error" ||
+    value === "captcha_failed" ||
+    value === "invalid_credentials" ||
+    value === "invalid_token" ||
+    value === "unknown_error"
+  ) {
+    return value;
+  }
+  return "unknown_error";
+}
+
+function isGatewayStatus(status: number): boolean {
+  return status === 502 || status === 503 || status === 504;
+}
+
+export function isStructuredApiErrorPayload(payload: unknown): payload is ApiErrorPayload {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    return false;
+  }
+  return typeof (payload as ApiErrorPayload).error === "string";
+}
+
+export function toApiError(status: number, payload: unknown): ApiError {
+  if (isGatewayStatus(status) && !isStructuredApiErrorPayload(payload)) {
+    return new ApiError({
+      code: "network_error",
+      status,
+      message: "Сервер временно недоступен. Попробуйте обновить страницу.",
+    });
+  }
+
+  if (!isStructuredApiErrorPayload(payload) && (status === 401 || status === 403 || status === 404)) {
+    return new ApiError({
+      code: "network_error",
+      status,
+      message:
+        status === 404
+          ? "API не найден по этому адресу. Проверьте прокси и префикс /api."
+          : "Запрос отклонён сервером. Проверьте переменную CORS_ORIGIN на бэкенде.",
+    });
+  }
+
+  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 "unauthorized":
+      return "Нужно войти в аккаунт.";
+    case "email_not_verified":
+      return "Подтвердите email, чтобы продолжить.";
+    case "csrf_error":
+      return "Сессия устарела. Обновите страницу и попробуйте снова.";
+    case "captcha_failed":
+      return "Проверка капчи не пройдена.";
+    case "invalid_credentials":
+      return "Неверный email или пароль.";
+    case "invalid_token":
+      return "Ссылка недействительна или устарела.";
+    case "network_error":
+      return "Не удалось связаться с сервером.";
+    case "unknown_error":
+      return "Сервер не смог обработать запрос. Попробуйте позже или обновите страницу.";
+    default:
+      return "Произошла неизвестная ошибка.";
+  }
+}

frontend/src/api/health.ts

@@ -0,0 +1,19 @@
+import { requestJson } from "./http";
+
+export type HealthResponse = {
+  status: string;
+  version: string;
+};
+
+export type BackendMetaResponse = {
+  version: string;
+};
+
+export async function getHealth(init?: RequestInit): Promise<HealthResponse> {
+  return requestJson<HealthResponse>("/health", init);
+}
+
+/** Версия бэкенда для футера (отдельный путь от /health — меньше ложных блокировок). */
+export async function getBackendMeta(init?: RequestInit): Promise<BackendMetaResponse> {
+  return requestJson<BackendMetaResponse>("/meta", init);
+}

frontend/src/api/http.ts

@@ -0,0 +1,123 @@
+import { ApiError, isStructuredApiErrorPayload, toApiError } from "./errors";
+
+const API_ROOT = "/api";
+let csrfToken: string | null = null;
+
+export function setCsrfToken(token: string | null): void {
+  csrfToken = token;
+}
+
+function buildUrl(path: string): string {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${API_ROOT}${normalizedPath}`;
+}
+
+async function parseResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) {
+    return null;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return null;
+    }
+  }
+
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+const GATEWAY_RETRY_STATUSES = new Set([502, 503, 504]);
+
+/** Повтор при «пустом» 404: часто бывает при нескольких инстансах/прокси до полного деплоя. */
+function shouldRetryIdempotentError(status: number, payload: unknown): boolean {
+  if (GATEWAY_RETRY_STATUSES.has(status)) {
+    return true;
+  }
+  return status === 404 && !isStructuredApiErrorPayload(payload);
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export async function requestJson<T>(path: string, init?: RequestInit): Promise<T> {
+  const method = (init?.method ?? "GET").toUpperCase();
+  const idempotent = method === "GET" || method === "HEAD";
+  const maxAttempts = idempotent ? 3 : 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const defaultHeaders: Record<string, string> = {};
+      if (method !== "GET" && method !== "HEAD") {
+        defaultHeaders["Content-Type"] = "application/json";
+      }
+      if (csrfToken && ["POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+        defaultHeaders["X-CSRF-Token"] = csrfToken;
+      }
+
+      const response = await fetch(buildUrl(path), {
+        ...init,
+        credentials: "include",
+        headers: {
+          ...defaultHeaders,
+          ...(init?.headers ?? {}),
+        },
+      });
+
+      if (response.status === 204) {
+        return undefined as T;
+      }
+
+      const payload = await parseResponseBody(response);
+
+      if (!response.ok) {
+        const retryable = idempotent && attempt < maxAttempts && shouldRetryIdempotentError(response.status, payload);
+        if (retryable) {
+          await delay(80 * attempt);
+          continue;
+        }
+        throw toApiError(response.status, payload);
+      }
+
+      return payload as T;
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw error;
+      }
+      const retryable = idempotent && attempt < maxAttempts;
+      if (retryable) {
+        await delay(80 * attempt);
+        continue;
+      }
+      throw new ApiError({
+        code: "network_error",
+        status: null,
+        message: "Не удалось связаться с сервером.",
+      });
+    }
+  }
+
+  throw new ApiError({
+    code: "network_error",
+    status: null,
+    message: "Не удалось связаться с сервером.",
+  });
+}

frontend/src/api/index.ts

@@ -0,0 +1,15 @@
+export type { AuthUser, CreateRacePayload, Race, RacesQuery, RaceStatus, UpdateRacePayload } from "./types";
+export { ApiError, getApiErrorMessage } from "./errors";
+export type { BackendMetaResponse, HealthResponse } from "./health";
+export { getBackendMeta, getHealth } from "./health";
+export { getRaceById, getRaces, createRace, updateRace, deleteRace } from "./races";
+export {
+  forgotPassword,
+  getCurrentUser,
+  login,
+  logout,
+  register,
+  resendVerification,
+  resetPassword,
+  verifyEmail,
+} from "./auth";

frontend/src/api/races.ts

@@ -0,0 +1,125 @@
+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 isOptionalNullableString(value: unknown): value is string | null | undefined {
+  return value === undefined || isNullableString(value);
+}
+
+function normalizeRace(input: unknown): Race {
+  const race = input as Partial<Race>;
+
+  const isValid =
+    isString(race?.id) &&
+    isString(race?.slug) &&
+    isString(race?.date) &&
+    isString(race?.title) &&
+    typeof race?.distanceKm === "number" &&
+    (race?.status === null ||
+      race?.status === "planned" ||
+      race?.status === "registered" ||
+      race?.status === "completed") &&
+    isNullableString(race?.officialUrl) &&
+    isOptionalNullableString(race?.coverImageUrl) &&
+    isNullableString(race?.startTime) &&
+    isNullableString(race?.clusterSchedule) &&
+    isNullableString(race?.bibPickup) &&
+    isNullableString(race?.bibNumber) &&
+    isNullableString(race?.finishTime) &&
+    isNullableString(race?.finishPlace) &&
+    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,
+    slug: race.slug,
+    date: race.date,
+    title: race.title,
+    distanceKm: race.distanceKm,
+    status: race.status,
+    officialUrl: race.officialUrl,
+    coverImageUrl: race.coverImageUrl ?? null,
+    startTime: race.startTime,
+    clusterSchedule: race.clusterSchedule,
+    bibPickup: race.bibPickup,
+    bibNumber: race.bibNumber,
+    finishTime: race.finishTime,
+    finishPlace: race.finishPlace,
+    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, init?: RequestInit): Promise<Race[]> {
+  const response = await requestJson<unknown[]>(`/races${buildRacesQuery(query)}`, init);
+  if (!Array.isArray(response)) {
+    throw new ApiError({
+      code: "unknown_error",
+      status: null,
+      message: "Некорректный формат списка забегов от API.",
+    });
+  }
+
+  return response.map(normalizeRace);
+}
+
+export async function getRaceById(id: string, init?: RequestInit): Promise<Race> {
+  return normalizeRace(await requestJson<unknown>(`/races/${id}`, init));
+}
+
+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,51 @@
+export type RaceStatus = "planned" | "registered" | "completed";
+
+export interface Race {
+  id: string;
+  slug: string;
+  date: string;
+  title: string;
+  distanceKm: number;
+  status: RaceStatus | null;
+  officialUrl: string | null;
+  coverImageUrl: string | null;
+  startTime: string | null;
+  clusterSchedule: string | null;
+  bibPickup: string | null;
+  bibNumber: string | null;
+  finishTime: string | null;
+  finishPlace: string | null;
+  notes: string | null;
+  createdAt: string;
+  updatedAt: string | null;
+}
+
+export interface RacesQuery {
+  year?: number;
+  month?: number;
+}
+
+export interface CreateRacePayload {
+  slug: string;
+  date: string;
+  title: string;
+  distanceKm: number;
+  status?: RaceStatus | null;
+  officialUrl?: string | null;
+  coverImageUrl?: string | null;
+  startTime?: string | null;
+  clusterSchedule?: string | null;
+  bibPickup?: string | null;
+  bibNumber?: string | null;
+  finishTime?: string | null;
+  finishPlace?: string | null;
+  notes?: string | null;
+}
+
+export type UpdateRacePayload = Partial<Omit<CreateRacePayload, "id">>;
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  emailVerifiedAt: string | null;
+}

frontend/src/app/auth/AuthContext.tsx

@@ -0,0 +1,68 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import type { AuthUser } from "../../api";
+import { ApiError, getCurrentUser, login as loginRequest, logout as logoutRequest } from "../../api";
+
+interface AuthContextValue {
+  user: AuthUser | null;
+  isLoading: boolean;
+  login(email: string, password: string): Promise<void>;
+  logout(): Promise<void>;
+  refresh(): Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export function AuthProvider(props: { children: React.ReactNode }): JSX.Element {
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    try {
+      const response = await getCurrentUser();
+      setUser(response.user);
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 401) {
+        setUser(null);
+        return;
+      }
+      setUser(null);
+    }
+  }, []);
+
+  useEffect(() => {
+    let mounted = true;
+    void refresh().finally(() => {
+      if (mounted) {
+        setIsLoading(false);
+      }
+    });
+    return () => {
+      mounted = false;
+    };
+  }, [refresh]);
+
+  const login = useCallback(async (email: string, password: string) => {
+    const response = await loginRequest({ email, password });
+    setUser(response.user);
+  }, []);
+
+  const logout = useCallback(async () => {
+    await logoutRequest();
+    setUser(null);
+  }, []);
+
+  const value = useMemo(
+    () => ({ user, isLoading, login, logout, refresh }),
+    [user, isLoading, login, logout, refresh],
+  );
+
+  return <AuthContext.Provider value={value}>{props.children}</AuthContext.Provider>;
+}
+
+export function useAuth(): AuthContextValue {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used inside AuthProvider");
+  }
+  return context;
+}

frontend/src/app/auth/RequireAuth.tsx

@@ -0,0 +1,26 @@
+import { Navigate, Outlet, useLocation } from "react-router-dom";
+import { useAuth } from "./AuthContext";
+
+export function RequireAuth(): JSX.Element {
+  const { user, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return (
+      <section className="page page--auth" aria-busy="true">
+        <h1 className="page__title">Загрузка</h1>
+        <p className="page__subtitle">Проверяем сессию...</p>
+      </section>
+    );
+  }
+
+  if (!user) {
+    return <Navigate to="/login" replace state={{ from: location }} />;
+  }
+
+  if (!user.emailVerifiedAt) {
+    return <Navigate to="/verify-email" replace />;
+  }
+
+  return <Outlet />;
+}

frontend/src/app/layouts/AppLayout.tsx

@@ -0,0 +1,62 @@
+import { Link, NavLink, Outlet } from "react-router-dom";
+import { useAuth } from "../auth/AuthContext";
+import { AppShellFooter } from "./AppShellFooter";
+
+export function AppLayout(): JSX.Element {
+  const { user, logout } = useAuth();
+
+  return (
+    <div className="app-shell">
+      <header className="app-shell__header">
+        <Link className="app-shell__brand" to="/">
+          Календарь стартов
+        </Link>
+        <nav className="app-shell__nav" aria-label="Основная навигация">
+          <NavLink
+            to="/"
+            end
+            className={({ isActive }) =>
+              isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+            }
+          >
+            Обзор
+          </NavLink>
+          <NavLink
+            to="/races"
+            className={({ isActive }) =>
+              isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+            }
+          >
+            Старты
+          </NavLink>
+          <NavLink
+            to="/races/new"
+            className={({ isActive }) =>
+              isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+            }
+          >
+            + Добавить
+          </NavLink>
+          {user ? (
+            <button className="app-shell__link app-shell__link--button" type="button" onClick={() => void logout()}>
+              Выйти
+            </button>
+          ) : (
+            <NavLink
+              to="/login"
+              className={({ isActive }) =>
+                isActive ? "app-shell__link app-shell__link--active" : "app-shell__link"
+              }
+            >
+              Войти
+            </NavLink>
+          )}
+        </nav>
+      </header>
+      <main className="app-shell__main">
+        <Outlet />
+      </main>
+      <AppShellFooter />
+    </div>
+  );
+}

frontend/src/app/layouts/AppShellFooter.tsx

@@ -0,0 +1,59 @@
+import { useEffect, useState } from "react";
+import { getBackendMeta } from "../../api";
+import { FRONTEND_VERSION } from "../../frontendVersion";
+import { readCachedBackendVersion, writeCachedBackendVersion } from "../../lib/backendVersionCache";
+
+function isAbortError(error: unknown): boolean {
+  return (
+    (error instanceof DOMException && error.name === "AbortError") ||
+    (error instanceof Error && error.name === "AbortError")
+  );
+}
+
+export function AppShellFooter(): JSX.Element {
+  const [backendVersion, setBackendVersion] = useState<string | null>(() => readCachedBackendVersion());
+
+  useEffect(() => {
+    const ac = new AbortController();
+    void getBackendMeta({ signal: ac.signal })
+      .then((meta) => {
+        if (ac.signal.aborted) {
+          return;
+        }
+        const v = meta.version;
+        const label = typeof v === "string" && v.length > 0 ? v : "не указана";
+        writeCachedBackendVersion(label);
+        setBackendVersion(label);
+      })
+      .catch((err) => {
+        if (ac.signal.aborted || isAbortError(err)) {
+          return;
+        }
+        setBackendVersion((prev) => {
+          const cached = readCachedBackendVersion();
+          if (cached) {
+            return cached;
+          }
+          if (prev !== null) {
+            return prev;
+          }
+          return "недоступна";
+        });
+      });
+    return () => ac.abort();
+  }, []);
+
+  const backendLabel = backendVersion === null ? "…" : backendVersion;
+
+  return (
+    <footer className="app-shell__footer">
+      <p className="app-shell__footer-versions">
+        Версия клиента: {FRONTEND_VERSION}
+        <span className="app-shell__footer-sep" aria-hidden="true">
+          {" · "}
+        </span>
+        Версия сервера: {backendLabel}
+      </p>
+    </footer>
+  );
+}

frontend/src/app/router.tsx

@@ -0,0 +1,34 @@
+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";
+import { RaceFormPage } from "../pages/RaceFormPage";
+import { RaceDayPage } from "../pages/RaceDayPage";
+import { ForgotPasswordPage, LoginPage, RegisterPage, ResetPasswordPage, VerifyEmailPage } from "../pages/AuthPages";
+import { RequireAuth } from "./auth/RequireAuth";
+
+export const appRouter = createBrowserRouter([
+  {
+    path: "/",
+    element: <AppLayout />,
+    children: [
+      { path: "login", element: <LoginPage /> },
+      { path: "register", element: <RegisterPage /> },
+      { path: "verify-email", element: <VerifyEmailPage /> },
+      { path: "forgot-password", element: <ForgotPasswordPage /> },
+      { path: "reset-password", element: <ResetPasswordPage /> },
+      {
+        element: <RequireAuth />,
+        children: [
+          { index: true, element: <DashboardPage /> },
+          { path: "races", element: <RacesPage /> },
+          { path: "races/new", element: <RaceFormPage /> },
+          { path: "races/day/:ymd", element: <RaceDayPage /> },
+          { path: "races/:raceId", element: <RaceDetailsPage /> },
+          { path: "races/:raceId/edit", element: <RaceFormPage /> },
+        ],
+      },
+    ],
+  },
+]);

frontend/src/components/DatePickerField.tsx

@@ -0,0 +1,197 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { buildMonthCells, toYmd, WEEKDAY_LABELS_SHORT_RU } from "../lib";
+
+const MONTH_NAMES_RU = [
+  "Январь",
+  "Февраль",
+  "Март",
+  "Апрель",
+  "Май",
+  "Июнь",
+  "Июль",
+  "Август",
+  "Сентябрь",
+  "Октябрь",
+  "Ноябрь",
+  "Декабрь",
+];
+
+interface DatePickerFieldProps {
+  value: string;
+  name: string;
+  required?: boolean;
+  onChange: (value: string) => void;
+}
+
+function parseYmd(value: string): { year: number; monthIndex: number; day: number } | null {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return null;
+  }
+
+  const year = Number(value.slice(0, 4));
+  const monthIndex = Number(value.slice(5, 7)) - 1;
+  const day = Number(value.slice(8, 10));
+
+  if (!Number.isInteger(year) || !Number.isInteger(monthIndex) || !Number.isInteger(day)) {
+    return null;
+  }
+  if (monthIndex < 0 || monthIndex > 11) {
+    return null;
+  }
+
+  return { year, monthIndex, day };
+}
+
+function getInitialVisibleMonth(value: string): { year: number; monthIndex: number } {
+  const parsed = parseYmd(value);
+  if (parsed) {
+    return { year: parsed.year, monthIndex: parsed.monthIndex };
+  }
+
+  const now = new Date();
+  return { year: now.getFullYear(), monthIndex: now.getMonth() };
+}
+
+export function DatePickerField(props: DatePickerFieldProps): JSX.Element {
+  const { value, name, required, onChange } = props;
+  const [isOpen, setIsOpen] = useState(false);
+  const [visibleMonth, setVisibleMonth] = useState(() => getInitialVisibleMonth(value));
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const parsed = parseYmd(value);
+    if (!parsed) {
+      return;
+    }
+    setVisibleMonth({ year: parsed.year, monthIndex: parsed.monthIndex });
+  }, [value]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    function handlePointerDown(event: MouseEvent): void {
+      if (rootRef.current?.contains(event.target as Node)) {
+        return;
+      }
+      setIsOpen(false);
+    }
+
+    function handleKeyDown(event: KeyboardEvent): void {
+      if (event.key === "Escape") {
+        setIsOpen(false);
+      }
+    }
+
+    document.addEventListener("mousedown", handlePointerDown);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("mousedown", handlePointerDown);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [isOpen]);
+
+  const selected = parseYmd(value);
+  const todayYmd = toYmd(new Date().getFullYear(), new Date().getMonth(), new Date().getDate());
+  const cells = useMemo(
+    () => buildMonthCells(visibleMonth.year, visibleMonth.monthIndex),
+    [visibleMonth],
+  );
+  const monthTitle = `${MONTH_NAMES_RU[visibleMonth.monthIndex]} ${visibleMonth.year}`;
+
+  function shiftMonth(delta: number): void {
+    setVisibleMonth((prev) => {
+      const next = new Date(Date.UTC(prev.year, prev.monthIndex + delta, 1));
+      return { year: next.getUTCFullYear(), monthIndex: next.getUTCMonth() };
+    });
+  }
+
+  return (
+    <div className="date-picker" ref={rootRef}>
+      <div className="date-picker__control">
+        <input
+          className="race-form__input date-picker__input"
+          type="text"
+          inputMode="numeric"
+          name={name}
+          value={value}
+          onChange={(event) => {
+            onChange(event.target.value);
+          }}
+          onFocus={() => setIsOpen(true)}
+          placeholder="2026-05-03"
+          autoComplete="off"
+          required={required}
+        />
+        <button
+          className="date-picker__toggle"
+          type="button"
+          aria-label="Открыть календарь"
+          aria-expanded={isOpen}
+          onClick={() => setIsOpen((prev) => !prev)}
+        >
+          ▾
+        </button>
+      </div>
+
+      {isOpen ? (
+        <div className="date-picker__popover" role="dialog" aria-label="Выбор даты">
+          <div className="date-picker__header">
+            <button
+              className="date-picker__nav"
+              type="button"
+              aria-label="Предыдущий месяц"
+              onClick={() => shiftMonth(-1)}
+            >
+              ‹
+            </button>
+            <p className="date-picker__title">{monthTitle}</p>
+            <button
+              className="date-picker__nav"
+              type="button"
+              aria-label="Следующий месяц"
+              onClick={() => shiftMonth(1)}
+            >
+              ›
+            </button>
+          </div>
+          <div className="date-picker__weekdays" aria-hidden>
+            {WEEKDAY_LABELS_SHORT_RU.map((weekday) => (
+              <span key={weekday} className="date-picker__weekday">
+                {weekday}
+              </span>
+            ))}
+          </div>
+          <div className="date-picker__cells">
+            {cells.map((day, idx) => {
+              if (day === null) {
+                return <span key={`empty-${idx}`} className="date-picker__cell date-picker__cell--empty" />;
+              }
+
+              const ymd = toYmd(visibleMonth.year, visibleMonth.monthIndex, day);
+              const isSelected =
+                selected?.year === visibleMonth.year &&
+                selected.monthIndex === visibleMonth.monthIndex &&
+                selected.day === day;
+
+              return (
+                <button
+                  key={ymd}
+                  className={`date-picker__day${isSelected ? " date-picker__day--selected" : ""}${ymd === todayYmd ? " date-picker__day--today" : ""}`}
+                  type="button"
+                  onClick={() => {
+                    onChange(ymd);
+                    setIsOpen(false);
+                  }}
+                >
+                  {day}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/PaceTrendChart.tsx

@@ -0,0 +1,92 @@
+import type { Race } from "../api";
+import { formatRaceDate, isCloseDistance, parseFinishTimeToSeconds, parseRaceDate } from "../lib";
+
+type PaceTrendChartProps = {
+  races: Race[];
+  distanceKm: number;
+};
+
+/** Линейный график: время финиша (минуты) по завершённым стартам выбранной дистанции. */
+export function PaceTrendChart(props: PaceTrendChartProps): JSX.Element {
+  const { races, distanceKm } = props;
+
+  const series = races
+    .filter(
+      (race) =>
+        race.status === "completed" &&
+        isCloseDistance(race.distanceKm, distanceKm) &&
+        parseFinishTimeToSeconds(race.finishTime) != null,
+    )
+    .sort(
+      (a, b) => parseRaceDate(a.date).getTime() - parseRaceDate(b.date).getTime(),
+    )
+    .map((race) => {
+      const seconds = parseFinishTimeToSeconds(race.finishTime)!;
+      return { race, minutes: seconds / 60 };
+    });
+
+  if (series.length < 2) {
+    return (
+      <p className="pace-chart__empty">
+        Нужно минимум два завершённых старта с временем на выбранной дистанции.
+      </p>
+    );
+  }
+
+  const minutes = series.map((s) => s.minutes);
+  const minM = Math.min(...minutes);
+  const maxM = Math.max(...minutes);
+  const range = maxM - minM || 1;
+  const n = series.length;
+
+  const pad = 4;
+  const w = 100;
+  const h = 36;
+  const innerW = w - pad * 2;
+  const innerH = h - pad * 2;
+
+  const points = series
+    .map((s, i) => {
+      const x = pad + (n === 1 ? innerW / 2 : (i / (n - 1)) * innerW);
+      const norm = (maxM - s.minutes) / range;
+      const y = pad + (1 - norm) * innerH;
+      return `${x},${y}`;
+    })
+    .join(" ");
+
+  const last = series[series.length - 1]!;
+  const best = series.reduce((currentBest, item) => (item.minutes < currentBest.minutes ? item : currentBest), series[0]!);
+  const dotPoints = series.map((s, i) => {
+    const x = pad + (n === 1 ? innerW / 2 : (i / (n - 1)) * innerW);
+    const norm = (maxM - s.minutes) / range;
+    const y = pad + (1 - norm) * innerH;
+    return { x, y, id: s.race.id };
+  });
+
+  return (
+    <div className="pace-chart">
+      <svg className="pace-chart__svg" viewBox={`0 0 ${w} ${h}`} role="img" aria-label="Динамика времени на дистанции">
+        <line className="pace-chart__grid-line" x1={pad} y1={pad} x2={w - pad} y2={pad} />
+        <line className="pace-chart__grid-line" x1={pad} y1={h - pad} x2={w - pad} y2={h - pad} />
+        <polyline className="pace-chart__line" fill="none" points={points} />
+        {dotPoints.map((point, index) => (
+          <circle
+            key={point.id}
+            className={index === dotPoints.length - 1 ? "pace-chart__dot pace-chart__dot--last" : "pace-chart__dot"}
+            cx={point.x}
+            cy={point.y}
+            r="1.6"
+          />
+        ))}
+      </svg>
+      <div className="pace-chart__stats">
+        <p className="pace-chart__caption">
+          Последний: {formatRaceDate(last.race.date)} · {last.race.finishTime} · {last.minutes.toFixed(1)} мин
+        </p>
+        <p className="pace-chart__caption pace-chart__caption--best">
+          Лучший: {formatRaceDate(best.race.date)} · {best.race.finishTime} · {best.minutes.toFixed(1)} мин
+        </p>
+      </div>
+    </div>
+  );
+}

frontend/src/components/RacesCalendar.tsx

@@ -0,0 +1,291 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { Link, useNavigate } from "react-router-dom";
+import type { Race } from "../api";
+import { buildMonthCells, groupRacesByYmd, isRaceDateInPast, toYmd, WEEKDAY_LABELS_SHORT_RU } from "../lib";
+
+const MONTH_NAMES_RU_SHORT = [
+  "янв.",
+  "февр.",
+  "мар.",
+  "апр.",
+  "май",
+  "июн.",
+  "июл.",
+  "авг.",
+  "сент.",
+  "окт.",
+  "нояб.",
+  "дек.",
+];
+
+const POPOVER_LEAVE_MS = 140;
+
+function toLocalYmd(date: Date): string {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+interface RacesCalendarProps {
+  displayYear: number;
+  monthFilter: string;
+  races: Race[];
+  onMonthFilterChange: (value: string) => void;
+}
+
+function DayPopover(props: {
+  ymd: string;
+  races: Race[];
+  onCancelClose: () => void;
+  onScheduleClose: () => void;
+}): JSX.Element {
+  const { ymd, races, onCancelClose, onScheduleClose } = props;
+  const hasRaces = races.length > 0;
+
+  return (
+    <div
+      className="races-cal__popover"
+      role="tooltip"
+      onMouseEnter={onCancelClose}
+      onMouseLeave={onScheduleClose}
+    >
+      {hasRaces ? (
+        <ul className="races-cal__popover-list">
+          {races.map((r) => (
+            <li key={r.id} className="races-cal__popover-item">
+              <Link className="races-cal__popover-link" to={`/races/${r.id}`} onClick={onCancelClose}>
+                {r.title}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p className="races-cal__popover-empty">Стартов нет</p>
+      )}
+      <Link
+        className="btn btn--secondary races-cal__popover-add"
+        to={`/races/new?date=${ymd}`}
+        onClick={onCancelClose}
+      >
+        Добавить
+      </Link>
+    </div>
+  );
+}
+
+function CalendarMonthBlock(props: {
+  year: number;
+  monthIndex: number;
+  racesByYmd: Map<string, Race[]>;
+  compact: boolean;
+  navigate: ReturnType<typeof useNavigate>;
+  openYmd: string | null;
+  setOpenYmd: (v: string | null) => void;
+  scheduleClose: () => void;
+  cancelClose: () => void;
+  onMonthSelect?: (monthIndex: number) => void;
+  todayYmd: string;
+}): JSX.Element {
+  const {
+    year,
+    monthIndex,
+    racesByYmd,
+    compact,
+    navigate,
+    openYmd,
+    setOpenYmd,
+    scheduleClose,
+    cancelClose,
+    onMonthSelect,
+    todayYmd,
+  } = props;
+  const cells = useMemo(() => buildMonthCells(year, monthIndex), [year, monthIndex]);
+  const title = `${MONTH_NAMES_RU_SHORT[monthIndex]} ${year}`;
+
+  const blockClass = compact ? "races-cal__month races-cal__month--compact" : "races-cal__month";
+
+  return (
+    <div className={blockClass}>
+      <h3 className="races-cal__month-title">
+        {onMonthSelect ? (
+          <button
+            type="button"
+            className="races-cal__month-title-button"
+            onClick={() => {
+              onMonthSelect(monthIndex);
+            }}
+          >
+            {title}
+          </button>
+        ) : (
+          title
+        )}
+      </h3>
+      <div className="races-cal__weekdays" aria-hidden>
+        {WEEKDAY_LABELS_SHORT_RU.map((d) => (
+          <span key={d} className="races-cal__weekday">
+            {d}
+          </span>
+        ))}
+      </div>
+      <div className="races-cal__cells">
+        {cells.map((day, idx) => {
+          if (day === null) {
+            return <div key={`e-${idx}`} className="races-cal__cell races-cal__cell--empty" />;
+          }
+          const ymd = toYmd(year, monthIndex, day);
+          const dayRaces = racesByYmd.get(ymd) ?? [];
+          const hasRaces = dayRaces.length > 0;
+          const isOpen = openYmd === ymd;
+          const isPast = isRaceDateInPast(ymd);
+          const isToday = ymd === todayYmd;
+          const cellClassName = [
+            "races-cal__cell",
+            hasRaces ? "races-cal__cell--has-race" : "",
+            isOpen ? "races-cal__cell--open" : "",
+            isPast ? "races-cal__cell--past" : "",
+            isToday ? "races-cal__cell--today" : "",
+          ]
+            .filter(Boolean)
+            .join(" ");
+
+          return (
+            <div
+              key={ymd}
+              className={cellClassName}
+              onMouseEnter={() => {
+                cancelClose();
+                setOpenYmd(hasRaces ? ymd : null);
+              }}
+              onMouseLeave={scheduleClose}
+            >
+              <button
+                type="button"
+                className="races-cal__day-btn"
+                onClick={() => {
+                  navigate(`/races/day/${ymd}`);
+                }}
+                onFocus={() => {
+                  cancelClose();
+                  setOpenYmd(hasRaces ? ymd : null);
+                }}
+                onBlur={(e) => {
+                  const next = e.relatedTarget as Node | null;
+                  if (next && e.currentTarget.closest(".races-cal__cell")?.contains(next)) {
+                    return;
+                  }
+                  scheduleClose();
+                }}
+              >
+                {day}
+              </button>
+              {isOpen && hasRaces ? (
+                <DayPopover
+                  ymd={ymd}
+                  races={dayRaces}
+                  onCancelClose={cancelClose}
+                  onScheduleClose={scheduleClose}
+                />
+              ) : null}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export function RacesCalendar(props: RacesCalendarProps): JSX.Element {
+  const { displayYear, monthFilter, races, onMonthFilterChange } = props;
+  const navigate = useNavigate();
+  const [openYmd, setOpenYmd] = useState<string | null>(null);
+  const leaveTimerRef = useRef<number | null>(null);
+
+  const cancelClose = useCallback(() => {
+    if (leaveTimerRef.current !== null) {
+      window.clearTimeout(leaveTimerRef.current);
+      leaveTimerRef.current = null;
+    }
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    cancelClose();
+    leaveTimerRef.current = window.setTimeout(() => {
+      setOpenYmd(null);
+      leaveTimerRef.current = null;
+    }, POPOVER_LEAVE_MS);
+  }, [cancelClose]);
+
+  const racesByYmd = useMemo(() => groupRacesByYmd(races), [races]);
+  const todayYmd = useMemo(() => toLocalYmd(new Date()), []);
+
+  const focusedMonthIndex = monthFilter === "" ? null : parseInt(monthFilter, 10) - 1;
+
+  return (
+    <div className="races-cal">
+      <p className="races-cal__hint">Наведите на дату с забегом — краткая информация. Клик — страница дня.</p>
+      {focusedMonthIndex === null || Number.isNaN(focusedMonthIndex) ? (
+        <div className="races-cal__year">
+          {MONTH_NAMES_RU_SHORT.map((_, mi) => (
+            <CalendarMonthBlock
+              key={mi}
+              year={displayYear}
+              monthIndex={mi}
+              racesByYmd={racesByYmd}
+              compact
+              navigate={navigate}
+              openYmd={openYmd}
+              setOpenYmd={setOpenYmd}
+              scheduleClose={scheduleClose}
+              cancelClose={cancelClose}
+              onMonthSelect={(mi) => {
+                onMonthFilterChange(String(mi + 1));
+                setOpenYmd(null);
+              }}
+              todayYmd={todayYmd}
+            />
+          ))}
+        </div>
+      ) : (
+        <div className="races-cal__month-focus">
+          <nav className="races-cal__month-nav" aria-label="Месяцы года">
+            {MONTH_NAMES_RU_SHORT.map((label, mi) => (
+              <button
+                key={label}
+                type="button"
+                className={`races-cal__month-nav-item${mi === focusedMonthIndex ? " races-cal__month-nav-item--active" : ""}`}
+                onClick={() => {
+                  onMonthFilterChange(String(mi + 1));
+                }}
+              >
+                {label}
+              </button>
+            ))}
+            <button
+              type="button"
+              className="races-cal__month-nav-item races-cal__month-nav-item--all"
+              onClick={() => {
+                onMonthFilterChange("");
+              }}
+            >
+              Весь год
+            </button>
+          </nav>
+          <CalendarMonthBlock
+            year={displayYear}
+            monthIndex={focusedMonthIndex}
+            racesByYmd={racesByYmd}
+            compact={false}
+            navigate={navigate}
+            openYmd={openYmd}
+            setOpenYmd={setOpenYmd}
+            scheduleClose={scheduleClose}
+            cancelClose={cancelClose}
+            todayYmd={todayYmd}
+          />
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/StartTimeSelects.tsx

@@ -0,0 +1,157 @@
+import { useCallback, useMemo } from "react";
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function parseToParts(value: string): { h: number | null; m: number | null; s: number | null } {
+  const t = value.trim();
+  if (!t) {
+    return { h: null, m: null, s: null };
+  }
+  const parts = t.split(":").map((p) => p.trim());
+  if (parts.length === 2) {
+    const h = Number(parts[0]);
+    const m = Number(parts[1]);
+    if (Number.isInteger(h) && Number.isInteger(m) && h >= 0 && h <= 23 && m >= 0 && m <= 59) {
+      return { h, m, s: 0 };
+    }
+  }
+  if (parts.length >= 3) {
+    const h = Number(parts[0]);
+    const m = Number(parts[1]);
+    const s = Number(parts[2]);
+    if (
+      Number.isInteger(h) &&
+      Number.isInteger(m) &&
+      Number.isInteger(s) &&
+      h >= 0 &&
+      h <= 23 &&
+      m >= 0 &&
+      m <= 59 &&
+      s >= 0 &&
+      s <= 59
+    ) {
+      return { h, m, s };
+    }
+  }
+  return { h: null, m: null, s: null };
+}
+
+function partsToString(h: number | null, m: number | null, s: number | null): string {
+  if (h === null || m === null || s === null) {
+    return "";
+  }
+  return `${pad2(h)}:${pad2(m)}:${pad2(s)}`;
+}
+
+const HOURS = Array.from({ length: 24 }, (_, i) => i);
+const MIN_SEC = Array.from({ length: 60 }, (_, i) => i);
+
+interface StartTimeSelectsProps {
+  value: string;
+  onChange: (next: string) => void;
+  disabled?: boolean;
+}
+
+export function StartTimeSelects(props: StartTimeSelectsProps): JSX.Element {
+  const { value, onChange, disabled } = props;
+  const { h, m, s } = useMemo(() => parseToParts(value), [value]);
+
+  const emit = useCallback(
+    (nextH: number | null, nextM: number | null, nextS: number | null) => {
+      onChange(partsToString(nextH, nextM, nextS));
+    },
+    [onChange],
+  );
+
+  const hourVal = h === null ? "" : String(h);
+  const minVal = m === null ? "" : String(m);
+  const secVal = s === null ? "" : String(s);
+
+  return (
+    <div className="race-form__time-picker">
+      <label className="race-form__time-picker__unit">
+        <span className="race-form__time-picker__label">Часы</span>
+        <select
+          className="race-form__input race-form__time-picker__select"
+          aria-label="Часы"
+          disabled={disabled}
+          value={hourVal}
+          onChange={(e) => {
+            const v = e.target.value;
+            if (v === "") {
+              emit(null, null, null);
+              return;
+            }
+            const nh = Number(v);
+            emit(nh, m ?? 0, s ?? 0);
+          }}
+        >
+          <option value="">—</option>
+          {HOURS.map((n) => (
+            <option key={n} value={String(n)}>
+              {pad2(n)}
+            </option>
+          ))}
+        </select>
+      </label>
+      <span className="race-form__time-picker__sep" aria-hidden>
+        :
+      </span>
+      <label className="race-form__time-picker__unit">
+        <span className="race-form__time-picker__label">Минуты</span>
+        <select
+          className="race-form__input race-form__time-picker__select"
+          aria-label="Минуты"
+          disabled={disabled}
+          value={minVal}
+          onChange={(e) => {
+            const v = e.target.value;
+            if (v === "") {
+              emit(null, null, null);
+              return;
+            }
+            const nm = Number(v);
+            emit(h ?? 0, nm, s ?? 0);
+          }}
+        >
+          <option value="">—</option>
+          {MIN_SEC.map((n) => (
+            <option key={n} value={String(n)}>
+              {pad2(n)}
+            </option>
+          ))}
+        </select>
+      </label>
+      <span className="race-form__time-picker__sep" aria-hidden>
+        :
+      </span>
+      <label className="race-form__time-picker__unit">
+        <span className="race-form__time-picker__label">Секунды</span>
+        <select
+          className="race-form__input race-form__time-picker__select"
+          aria-label="Секунды"
+          disabled={disabled}
+          value={secVal}
+          onChange={(e) => {
+            const v = e.target.value;
+            if (v === "") {
+              emit(null, null, null);
+              return;
+            }
+            const ns = Number(v);
+            emit(h ?? 0, m ?? 0, ns);
+          }}
+        >
+          <option value="">—</option>
+          {MIN_SEC.map((n) => (
+            <option key={n} value={String(n)}>
+              {pad2(n)}
+            </option>
+          ))}
+        </select>
+      </label>
+    </div>
+  );
+}

frontend/src/components/index.ts

@@ -0,0 +1,4 @@
+export { DatePickerField } from "./DatePickerField";
+export { PaceTrendChart } from "./PaceTrendChart";
+export { RacesCalendar } from "./RacesCalendar";
+export { StartTimeSelects } from "./StartTimeSelects";

frontend/src/frontendVersion.ts

@@ -0,0 +1,3 @@
+import packageJson from "../package.json";
+
+export const FRONTEND_VERSION: string = packageJson.version;

frontend/src/lib/backendVersionCache.ts

@@ -0,0 +1,21 @@
+const STORAGE_KEY = "calendar_run.backendVersion.v1";
+
+export function readCachedBackendVersion(): string | null {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw !== null && raw.trim().length > 0 ? raw.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCachedBackendVersion(version: string): void {
+  try {
+    if (version === "недоступна" || version === "не указана") {
+      return;
+    }
+    sessionStorage.setItem(STORAGE_KEY, version);
+  } catch {
+    // private mode / quota
+  }
+}

frontend/src/lib/calendarUtils.ts

@@ -0,0 +1,53 @@
+import type { Race } from "../api";
+
+export const WEEKDAY_LABELS_SHORT_RU: string[] = ["Пн", "Вт", "Ср", "Чт", "Пт", "Сб", "Вс"];
+
+/** Monday-based week: Mon=0 ... Sun=6 */
+function mondayIndexFromJsDay(jsDay: number): number {
+  return (jsDay + 6) % 7;
+}
+
+/** Monday-based week: Mon=0 ... Sun=6 */
+export function mondayIndexFromDate(d: Date): number {
+  return mondayIndexFromJsDay(d.getDay());
+}
+
+/** Grid cells for one month: `null` = empty, `1..31` = day of month. Padded to full weeks, at least 6 rows. */
+export function buildMonthCells(year: number, monthIndex: number): (number | null)[] {
+  const lead = mondayIndexFromJsDay(new Date(Date.UTC(year, monthIndex, 1)).getUTCDay());
+  const dim = new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();
+  const cells: (number | null)[] = [];
+  for (let i = 0; i < lead; i += 1) {
+    cells.push(null);
+  }
+  for (let day = 1; day <= dim; day += 1) {
+    cells.push(day);
+  }
+  while (cells.length % 7 !== 0) {
+    cells.push(null);
+  }
+  while (cells.length < 42) {
+    cells.push(null);
+  }
+  return cells;
+}
+
+export function toYmd(year: number, monthIndex: number, day: number): string {
+  const m = String(monthIndex + 1).padStart(2, "0");
+  const d = String(day).padStart(2, "0");
+  return `${year}-${m}-${d}`;
+}
+
+export function groupRacesByYmd(races: Race[]): Map<string, Race[]> {
+  const map = new Map<string, Race[]>();
+  for (const race of races) {
+    const ymd = race.date.slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(ymd)) {
+      continue;
+    }
+    const list = map.get(ymd) ?? [];
+    list.push(race);
+    map.set(ymd, list);
+  }
+  return map;
+}

frontend/src/lib/index.ts

@@ -0,0 +1,20 @@
+export {
+  formatDistance,
+  formatRaceDate,
+  getPaceLabel,
+  getRaceCountdownLabel,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+  isCloseDistance,
+  isRaceDateInPast,
+  parseFinishTimeToSeconds,
+  parseRaceDate,
+  raceNeedsResultEntry,
+  sortByDateAsc,
+  sortByDateDesc,
+  splitRacesByDate,
+} from "./raceMetrics";
+
+export { buildMonthCells, groupRacesByYmd, toYmd, WEEKDAY_LABELS_SHORT_RU } from "./calendarUtils";
+export { getRaceVisual } from "./raceVisuals";
+export type { RaceVisualVariant } from "./raceVisuals";

frontend/src/lib/raceMetrics.ts

@@ -0,0 +1,169 @@
+import type { Race } from "../api";
+
+const MS_IN_DAY = 24 * 60 * 60 * 1000;
+
+/** API date: YYYY-MM-DD или ISO-строка от сериализации (не склеивать с «T00:00:00» повторно). */
+export function parseRaceDate(date: string): Date {
+  const ymd = date.slice(0, 10);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(ymd)) {
+    return new Date(`${ymd}T00:00:00`);
+  }
+  const parsed = new Date(date);
+  return parsed;
+}
+
+/** Дата старта (календарный день) строго раньше сегодняшней полуночи по локали. */
+export function isRaceDateInPast(raceDate: string, now: Date = new Date()): boolean {
+  const today = new Date(now);
+  today.setHours(0, 0, 0, 0);
+  return parseRaceDate(raceDate).getTime() < today.getTime();
+}
+
+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),
+  };
+}
+
+function pluralizeDays(n: number): string {
+  const mod10 = n % 10;
+  const mod100 = n % 100;
+
+  if (mod100 >= 11 && mod100 <= 19) {
+    return "дней";
+  }
+  if (mod10 === 1) {
+    return "день";
+  }
+  if (mod10 >= 2 && mod10 <= 4) {
+    return "дня";
+  }
+  return "дней";
+}
+
+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 "сегодня";
+  }
+  return `через ${days} ${pluralizeDays(days)}`;
+}
+
+export function isCloseDistance(left: number, right: number): boolean {
+  return Math.abs(left - right) < 0.05;
+}
+
+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")} /км`;
+}
+
+function isPastDateNeedingResult(status: Race["status"], raceDate: string): boolean {
+  if (status !== "planned" && status !== "registered") {
+    return false;
+  }
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  return parseRaceDate(raceDate).getTime() < today.getTime();
+}
+
+export function raceNeedsResultEntry(race: Race): boolean {
+  return isPastDateNeedingResult(race.status, race.date);
+}
+
+export function getRaceStatusClassName(status: Race["status"], raceDate?: string): string {
+  const base = "race-card__status";
+  let tier = `${base}--planned`;
+  if (status === "completed") {
+    tier = `${base}--completed`;
+  } else if (status === "registered") {
+    tier = `${base}--registered`;
+  }
+  const needs =
+    raceDate && isPastDateNeedingResult(status, raceDate) ? ` ${base}--needs-result` : "";
+  return `${base} ${tier}${needs}`;
+}
+
+export function getRaceStatusLabel(status: Race["status"], raceDate?: string): string {
+  if (raceDate && isPastDateNeedingResult(status, raceDate)) {
+    return "внесите результат";
+  }
+  if (status === "completed") {
+    return "пробежал";
+  }
+  if (status === "registered") {
+    return "зарегистрирован";
+  }
+  return "планирую";
+}

frontend/src/lib/raceVisuals.ts

@@ -0,0 +1,215 @@
+import type { Race } from "../api";
+
+export type RaceVisualVariant = "short" | "half" | "marathon" | "trail" | "night";
+export type RaceVisualFit = "cover" | "contain";
+
+interface RaceVisual {
+  variant: RaceVisualVariant;
+  imageSrc: string;
+  fallbackSrc: string;
+  imageFit: RaceVisualFit;
+  label: string;
+}
+
+interface OfficialRaceVisual {
+  keywords: string[];
+  imageSrc: string;
+  imageFit?: RaceVisualFit;
+  label: string;
+}
+
+const FALLBACK_VISUALS: Record<RaceVisualVariant, RaceVisual> = {
+  short: {
+    variant: "short",
+    imageSrc: "/images/race-short.jpg",
+    fallbackSrc: "/images/race-short.jpg",
+    imageFit: "cover",
+    label: "Городской темп",
+  },
+  half: {
+    variant: "half",
+    imageSrc: "/images/race-half.jpg",
+    fallbackSrc: "/images/race-half.jpg",
+    imageFit: "cover",
+    label: "Полумарафон",
+  },
+  marathon: {
+    variant: "marathon",
+    imageSrc: "/images/race-marathon.jpg",
+    fallbackSrc: "/images/race-marathon.jpg",
+    imageFit: "cover",
+    label: "Марафон",
+  },
+  trail: {
+    variant: "trail",
+    imageSrc: "/images/race-trail.jpg",
+    fallbackSrc: "/images/race-trail.jpg",
+    imageFit: "cover",
+    label: "Трейл",
+  },
+  night: {
+    variant: "night",
+    imageSrc: "/images/race-night.jpg",
+    fallbackSrc: "/images/race-night.jpg",
+    imageFit: "cover",
+    label: "Ночной старт",
+  },
+};
+
+const OFFICIAL_VISUALS: OfficialRaceVisual[] = [
+  {
+    keywords: ["забег апрель"],
+    imageSrc: "https://aprilrun5km.runc.run/uploads/page_card_photos/AprilRun_photo_1.jpg",
+    label: "Забег Апрель",
+  },
+  {
+    keywords: ["быстрый пес"],
+    imageSrc: "https://fastdogxc.runc.run/uploads/page_card_photos/Dog_spring_2026-5.jpg",
+    label: "Кросс",
+  },
+  {
+    keywords: ["лисья гора"],
+    imageSrc: "https://foxhillxc.runc.run/uploads/page_card_photos/Fox_Spring_2026-0.jpg",
+    label: "Кросс",
+  },
+  {
+    keywords: ["казанский марафон"],
+    imageSrc: "https://static.tildacdn.com/tild3961-6436-4462-b738-356665613039/Frame_2131327895.png",
+    imageFit: "contain",
+    label: "Казанский марафон",
+  },
+  {
+    keywords: ["мышкинский полумарафон", "по шести холмам"],
+    imageSrc: "https://static.tildacdn.com/tild6133-6137-4865-b166-623532313531/photo.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["забег.рф", "забег рф"],
+    imageSrc: "https://xn--80acghh.xn--p1ai/zabeg.jpg",
+    label: "ЗаБег.РФ",
+  },
+  {
+    keywords: ["переславский марафон", "александровские версты"],
+    imageSrc: "https://static.tildacdn.com/tild6432-3338-4533-b262-633339353335/photo_1.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["красочный забег"],
+    imageSrc: "https://colorrun5km.runc.run/uploads/page_card_photos/ColorRun2026-1.jpg",
+    label: "Красочный забег",
+  },
+  {
+    keywords: ["здорово кострома", "здорово, кострома"],
+    imageSrc: "https://static.tildacdn.com/tild6139-3539-4661-b232-386230336431/kostroma.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["ночной забег москва"],
+    imageSrc: "https://nightrun10km.runc.run/uploads/page_card_photos/NightRun_2026-9.jpg",
+    label: "Ночной забег",
+  },
+  {
+    keywords: ["белые ночи"],
+    imageSrc: "https://wnmarathon.runc.run/uploads/page_card_photos/WN_photo_01.jpg",
+    label: "Белые ночи",
+  },
+  {
+    keywords: ["сергиевым путем", "сергиевым путём"],
+    imageSrc: "https://static.tildacdn.com/tild6236-3466-4239-b666-393061326338/serg.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["ночной забег нижний новгород"],
+    imageSrc: "https://rrweb.russiarunning.com/-x740/generalimages/0531a1b8-3876-4620-8961-2fa374e474e5.png",
+    imageFit: "contain",
+    label: "Ночной забег",
+  },
+  {
+    keywords: ["suvorov extreme"],
+    imageSrc: "https://goldenultra.ru/grut/files/photos/100.jpg",
+    label: "Трейл",
+  },
+  {
+    keywords: ["рыбинский полумарафон", "великий хлебный путь"],
+    imageSrc: "https://static.tildacdn.com/tild6130-3230-4332-b932-366166366633/photo.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["ярославский полумарафон", "золотое кольцо"],
+    imageSrc: "https://static.tildacdn.com/tild6331-6333-4635-b635-376262373361/photo.jpg",
+    label: "Золотое кольцо",
+  },
+  {
+    keywords: ["моя столица"],
+    imageSrc: "https://static.tildacdn.com/tild3263-3036-4639-b830-653365663832/-min.jpg",
+    imageFit: "contain",
+    label: "Моя столица",
+  },
+];
+
+function normalizeTitle(value: string): string {
+  return value
+    .toLowerCase()
+    .replaceAll("ё", "е")
+    .replace(/[«»|]/g, " ")
+    .replace(/[^\p{L}\p{N}.&]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function getFallbackRaceVisual(race: Race): RaceVisual {
+  const title = normalizeTitle(race.title);
+
+  if (title.includes("ночной")) {
+    return FALLBACK_VISUALS.night;
+  }
+
+  if (
+    title.includes("trail") ||
+    title.includes("extreme") ||
+    title.includes("suvorov") ||
+    title.includes("трейл") ||
+    title.includes("экстрим")
+  ) {
+    return FALLBACK_VISUALS.trail;
+  }
+
+  if (Math.abs(race.distanceKm - 42.2) < 0.8) {
+    return FALLBACK_VISUALS.marathon;
+  }
+
+  if (Math.abs(race.distanceKm - 21.1) < 0.4) {
+    return FALLBACK_VISUALS.half;
+  }
+
+  return FALLBACK_VISUALS.short;
+}
+
+export function getRaceVisual(race: Race): RaceVisual {
+  const fallback = getFallbackRaceVisual(race);
+
+  if (race.coverImageUrl) {
+    return {
+      ...fallback,
+      imageSrc: race.coverImageUrl,
+      fallbackSrc: fallback.imageSrc,
+    };
+  }
+
+  const title = normalizeTitle(race.title);
+  const official = OFFICIAL_VISUALS.find((visual) =>
+    visual.keywords.some((keyword) => title.includes(normalizeTitle(keyword))),
+  );
+
+  if (!official) {
+    return fallback;
+  }
+
+  return {
+    ...fallback,
+    imageSrc: official.imageSrc,
+    fallbackSrc: fallback.imageSrc,
+    imageFit: official.imageFit ?? fallback.imageFit,
+    label: official.label,
+  };
+}

frontend/src/main.tsx

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

frontend/src/pages/AuthPages.tsx

@@ -0,0 +1,253 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Link, Navigate, useLocation, useNavigate, useSearchParams } from "react-router-dom";
+import {
+  ApiError,
+  forgotPassword,
+  register,
+  resendVerification,
+  resetPassword,
+  verifyEmail,
+} from "../api";
+import { useAuth } from "../app/auth/AuthContext";
+
+function errorMessage(error: unknown, fallback: string): string {
+  if (error instanceof ApiError) {
+    return error.details.length > 0 ? error.details.join("; ") : error.message;
+  }
+  return fallback;
+}
+
+function TurnstileField(props: { onToken(token: string): void }): JSX.Element {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const siteKey = import.meta.env.VITE_TURNSTILE_SITE_KEY;
+  const { onToken } = props;
+
+  useEffect(() => {
+    if (!siteKey || !ref.current) {
+      onToken("mock-turnstile-token");
+      return;
+    }
+
+    const scriptId = "turnstile-script";
+    if (!document.getElementById(scriptId)) {
+      const script = document.createElement("script");
+      script.id = scriptId;
+      script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+      script.async = true;
+      script.defer = true;
+      document.head.appendChild(script);
+    }
+
+    let widgetId: string | null = null;
+    const timer = window.setInterval(() => {
+      if (window.turnstile && ref.current && !widgetId) {
+        widgetId = window.turnstile.render(ref.current, {
+          sitekey: siteKey,
+          callback: onToken,
+          "expired-callback": () => onToken(""),
+        });
+        window.clearInterval(timer);
+      }
+    }, 100);
+
+    return () => {
+      window.clearInterval(timer);
+      if (widgetId && window.turnstile) {
+        window.turnstile.remove(widgetId);
+      }
+    };
+  }, [onToken, siteKey]);
+
+  return <div className="auth-form__captcha" ref={ref} />;
+}
+
+export function LoginPage(): JSX.Element {
+  const { user, login } = useAuth();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  if (user?.emailVerifiedAt) {
+    return <Navigate to="/" replace />;
+  }
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setIsSubmitting(true);
+    setError(null);
+    try {
+      await login(email, password);
+      const from = (location.state as { from?: Location } | null)?.from?.pathname ?? "/";
+      navigate(from, { replace: true });
+    } catch (err) {
+      setError(errorMessage(err, "Не удалось войти."));
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <section className="page page--auth">
+      <h1 className="page__title">Вход</h1>
+      <form className="auth-form" onSubmit={handleSubmit}>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Email</span>
+          <input className="auth-form__input" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+        </label>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Пароль</span>
+          <input className="auth-form__input" type="password" value={password} onChange={(e) => setPassword(e.target.value)} required />
+        </label>
+        {error ? <p className="page__subtitle page__subtitle--error">{error}</p> : null}
+        <button className="btn btn--primary" type="submit" disabled={isSubmitting}>
+          Войти
+        </button>
+      </form>
+      <p className="auth-form__links">
+        <Link className="page-link" to="/register">Регистрация</Link>
+        <Link className="page-link" to="/forgot-password">Забыли пароль?</Link>
+      </p>
+    </section>
+  );
+}
+
+export function RegisterPage(): JSX.Element {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [turnstileToken, setTurnstileToken] = useState("");
+  const [message, setMessage] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleToken = useCallback((token: string) => setTurnstileToken(token), []);
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setError(null);
+    setMessage(null);
+    try {
+      await register({ email, password, turnstileToken });
+      setMessage("Проверьте почту: мы отправили ссылку для подтверждения email.");
+    } catch (err) {
+      setError(errorMessage(err, "Не удалось зарегистрироваться."));
+    }
+  };
+
+  return (
+    <section className="page page--auth">
+      <h1 className="page__title">Регистрация</h1>
+      <form className="auth-form" onSubmit={handleSubmit}>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Email</span>
+          <input className="auth-form__input" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+        </label>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Пароль</span>
+          <input className="auth-form__input" type="password" minLength={15} value={password} onChange={(e) => setPassword(e.target.value)} required />
+        </label>
+        <TurnstileField onToken={handleToken} />
+        {message ? <p className="page__subtitle">{message}</p> : null}
+        {error ? <p className="page__subtitle page__subtitle--error">{error}</p> : null}
+        <button className="btn btn--primary" type="submit" disabled={!turnstileToken}>Создать аккаунт</button>
+      </form>
+      <p className="auth-form__links">
+        <Link className="page-link" to="/login">Уже есть аккаунт</Link>
+      </p>
+    </section>
+  );
+}
+
+export function VerifyEmailPage(): JSX.Element {
+  const { user, refresh } = useAuth();
+  const [params] = useSearchParams();
+  const [email, setEmail] = useState(user?.email ?? "");
+  const [message, setMessage] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const token = params.get("token");
+    if (!token) {
+      return;
+    }
+    void verifyEmail(token)
+      .then(async () => {
+        await refresh();
+        setMessage("Email подтверждён. Теперь можно пользоваться календарём.");
+      })
+      .catch((err) => setError(errorMessage(err, "Ссылка недействительна.")));
+  }, [params, refresh]);
+
+  const resend = async () => {
+    setError(null);
+    await resendVerification(email);
+    setMessage("Если email зарегистрирован и ещё не подтверждён, письмо отправлено.");
+  };
+
+  return (
+    <section className="page page--auth">
+      <h1 className="page__title">Подтверждение email</h1>
+      <p className="page__subtitle">Для доступа к календарю подтвердите email по ссылке из письма.</p>
+      <form className="auth-form" onSubmit={(e) => { e.preventDefault(); void resend(); }}>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Email</span>
+          <input className="auth-form__input" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />
+        </label>
+        {message ? <p className="page__subtitle">{message}</p> : null}
+        {error ? <p className="page__subtitle page__subtitle--error">{error}</p> : null}
+        <button className="btn btn--primary" type="submit">Отправить письмо ещё раз</button>
+      </form>
+    </section>
+  );
+}
+
+export function ForgotPasswordPage(): JSX.Element {
+  const [email, setEmail] = useState("");
+  const [message, setMessage] = useState<string | null>(null);
+
+  return (
+    <section className="page page--auth">
+      <h1 className="page__title">Сброс пароля</h1>
+      <form className="auth-form" onSubmit={async (e) => { e.preventDefault(); await forgotPassword(email); setMessage("Если email зарегистрирован, ссылка отправлена."); }}>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Email</span>
+          <input className="auth-form__input" type="email" value={email} onChange={(event) => setEmail(event.target.value)} required />
+        </label>
+        {message ? <p className="page__subtitle">{message}</p> : null}
+        <button className="btn btn--primary" type="submit">Отправить ссылку</button>
+      </form>
+    </section>
+  );
+}
+
+export function ResetPasswordPage(): JSX.Element {
+  const [params] = useSearchParams();
+  const [password, setPassword] = useState("");
+  const [message, setMessage] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  return (
+    <section className="page page--auth">
+      <h1 className="page__title">Новый пароль</h1>
+      <form className="auth-form" onSubmit={async (e) => {
+        e.preventDefault();
+        const token = params.get("token") ?? "";
+        try {
+          await resetPassword(token, password);
+          setMessage("Пароль обновлён. Теперь войдите заново.");
+        } catch (err) {
+          setError(errorMessage(err, "Не удалось обновить пароль."));
+        }
+      }}>
+        <label className="auth-form__field">
+          <span className="auth-form__label">Пароль</span>
+          <input className="auth-form__input" type="password" minLength={15} value={password} onChange={(event) => setPassword(event.target.value)} required />
+        </label>
+        {message ? <p className="page__subtitle">{message}</p> : null}
+        {error ? <p className="page__subtitle page__subtitle--error">{error}</p> : null}
+        <button className="btn btn--primary" type="submit">Сохранить пароль</button>
+      </form>
+    </section>
+  );
+}

frontend/src/pages/DashboardPage.tsx

@@ -0,0 +1,379 @@
+import type { CSSProperties } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { Link } from "react-router-dom";
+import type { Race } from "../api";
+import { ApiError, getRaces } from "../api";
+import { PaceTrendChart } from "../components";
+import {
+  formatDistance,
+  formatRaceDate,
+  getRaceCountdownLabel,
+  getRaceVisual,
+  getPaceLabel,
+  isCloseDistance,
+  parseFinishTimeToSeconds,
+  parseRaceDate,
+  splitRacesByDate,
+} from "../lib";
+
+const PR_DISTANCES = [5, 10, 21.1, 42.2] as const;
+
+type DashboardHeroStyle = CSSProperties & {
+  "--dashboard-hero-image"?: string;
+};
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить данные обзора.";
+}
+
+function toCssUrl(value: string): string {
+  return `url(${JSON.stringify(value)})`;
+}
+
+export function DashboardPage(): JSX.Element {
+  const [races, setRaces] = useState<Race[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [chartDistanceKm, setChartDistanceKm] = useState<number>(10);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    let isMounted = true;
+
+    async function loadDashboardData(): Promise<void> {
+      try {
+        const items = await getRaces(undefined, { signal: ac.signal });
+        if (!isMounted || ac.signal.aborted) {
+          return;
+        }
+        setRaces(items);
+        setErrorMessage(null);
+      } catch (error) {
+        if (ac.signal.aborted || !isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted && !ac.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadDashboardData();
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+  }, []);
+
+  const dashboardMetrics = useMemo(() => {
+    const { upcoming, past } = splitRacesByDate(races);
+
+    const nextRace = upcoming[0] ?? null;
+    const lastResult = past.find((race) => race.status === "completed") ?? null;
+
+    const lastPersonalRecord =
+      past.find(
+        (race) => race.status === "completed" && parseFinishTimeToSeconds(race.finishTime) !== null,
+      ) ?? null;
+
+    const currentYear = new Date().getFullYear();
+    const seasonRaces = races.filter((race) => parseRaceDate(race.date).getFullYear() === currentYear);
+    const seasonCompleted = seasonRaces.filter((race) => race.status === "completed");
+
+    return {
+      nextRace,
+      lastResult,
+      lastPersonalRecord,
+      seasonTotal: seasonRaces.length,
+      seasonCompletedCount: seasonCompleted.length,
+    };
+  }, [races]);
+
+  const personalRecordsByDistance = useMemo(() => {
+    return PR_DISTANCES.map((distanceKm) => {
+      const candidates = races.filter((race) => {
+        return (
+          race.status === "completed" &&
+          isCloseDistance(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: parseRaceDate(race.date).getFullYear(),
+        title: race.title,
+        distance: formatDistance(race.distanceKm),
+        finishTime: race.finishTime ?? "время не указано",
+        pace: getPaceLabel(race.finishTime, race.distanceKm) ?? "не удалось вычислить",
+        place: race.finishPlace?.trim() ? race.finishPlace : "нет данных",
+      }))
+      .sort((left, right) => right.year - left.year || left.title.localeCompare(right.title, "ru-RU"));
+  }, [races]);
+
+  const seasonProgress =
+    dashboardMetrics.seasonTotal > 0
+      ? Math.round((dashboardMetrics.seasonCompletedCount / dashboardMetrics.seasonTotal) * 100)
+      : 0;
+  const dashboardHeroVisual = dashboardMetrics.nextRace ? getRaceVisual(dashboardMetrics.nextRace) : null;
+  const dashboardHeroStyle: DashboardHeroStyle | undefined = dashboardHeroVisual
+    ? { "--dashboard-hero-image": toCssUrl(dashboardHeroVisual.imageSrc) }
+    : undefined;
+
+  if (isLoading) {
+    return (
+      <section className="page page--dashboard" aria-busy="true">
+        <h1 className="page__title">Обзор</h1>
+        <p className="page__subtitle">Загружаем ваши старты...</p>
+      </section>
+    );
+  }
+
+  if (errorMessage) {
+    return (
+      <section className="page page--dashboard" role="alert">
+        <h1 className="page__title">Обзор</h1>
+        <p className="page__subtitle page__subtitle--error">{errorMessage}</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="page page--dashboard">
+      <section
+        className={`dashboard-hero${dashboardHeroVisual ? " dashboard-hero--with-image" : ""}`}
+        style={dashboardHeroStyle}
+        aria-label="Обзор сезона"
+      >
+        <div className="dashboard-hero__content">
+          <p className="dashboard-hero__eyebrow">Календарь сезона</p>
+          <h1 className="dashboard-hero__title">Беговой штаб</h1>
+          <p className="dashboard-hero__text">
+            Планируйте старты, держите фокус на ближайшей гонке и сравнивайте прогресс по дистанциям.
+          </p>
+          <div className="dashboard-hero__actions">
+            <Link className="btn btn--primary" to="/races">
+              Смотреть старты
+            </Link>
+            <Link className="btn btn--secondary dashboard-hero__secondary" to="/races/new">
+              Добавить старт
+            </Link>
+          </div>
+        </div>
+        <div className="dashboard-hero__panel">
+          <p className="dashboard-hero__panel-label">Ближайший старт</p>
+          {dashboardMetrics.nextRace ? (
+            <Link className="dashboard-hero__race-link" to={`/races/${dashboardMetrics.nextRace.id}`}>
+              <span className="dashboard-hero__race-title">{dashboardMetrics.nextRace.title}</span>
+              <span className="dashboard-hero__race-meta">
+                {formatRaceDate(dashboardMetrics.nextRace.date)} · {formatDistance(dashboardMetrics.nextRace.distanceKm)}
+              </span>
+              <span className="dashboard-hero__race-countdown">
+                {getRaceCountdownLabel(dashboardMetrics.nextRace.date)}
+              </span>
+            </Link>
+          ) : (
+            <p className="dashboard-hero__empty">Запланируйте первый старт сезона.</p>
+          )}
+        </div>
+      </section>
+
+      <div className="dashboard-grid" aria-label="Ключевые метрики">
+        <article
+          className={`dashboard-card dashboard-card--accent-blue${dashboardMetrics.nextRace ? " dashboard-card--linked" : ""}`}
+        >
+          {dashboardMetrics.nextRace ? (
+            <Link
+              className="dashboard-card__link-surface"
+              to={`/races/${dashboardMetrics.nextRace.id}`}
+              aria-label={`Ближайший старт: ${dashboardMetrics.nextRace.title}`}
+            >
+              <h2 className="dashboard-card__title">Ближайший старт</h2>
+              <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>
+            </Link>
+          ) : (
+            <>
+              <h2 className="dashboard-card__title">Ближайший старт</h2>
+              <p className="dashboard-card__empty">Нет запланированных стартов.</p>
+            </>
+          )}
+        </article>
+
+        <article
+          className={`dashboard-card dashboard-card--accent-coral${dashboardMetrics.lastResult ? " dashboard-card--linked" : ""}`}
+        >
+          {dashboardMetrics.lastResult ? (
+            <Link
+              className="dashboard-card__link-surface"
+              to={`/races/${dashboardMetrics.lastResult.id}`}
+              aria-label={`Последний результат: ${dashboardMetrics.lastResult.title}`}
+            >
+              <h2 className="dashboard-card__title">Последний результат</h2>
+              <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>
+            </Link>
+          ) : (
+            <>
+              <h2 className="dashboard-card__title">Последний результат</h2>
+              <p className="dashboard-card__empty">Пока нет завершённых стартов.</p>
+            </>
+          )}
+        </article>
+
+        <article
+          className={`dashboard-card dashboard-card--accent-lime${dashboardMetrics.lastPersonalRecord ? " dashboard-card--linked" : ""}`}
+        >
+          {dashboardMetrics.lastPersonalRecord ? (
+            <Link
+              className="dashboard-card__link-surface"
+              to={`/races/${dashboardMetrics.lastPersonalRecord.id}`}
+              aria-label={`Последний личный рекорд: ${dashboardMetrics.lastPersonalRecord.title}`}
+            >
+              <h2 className="dashboard-card__title">Последний личный рекорд</h2>
+              <p className="dashboard-card__value">
+                {dashboardMetrics.lastPersonalRecord.finishTime ?? "время не указано"}
+              </p>
+              <p className="dashboard-card__meta">
+                {dashboardMetrics.lastPersonalRecord.title} ·{" "}
+                {formatDistance(dashboardMetrics.lastPersonalRecord.distanceKm)}
+              </p>
+              <p className="dashboard-card__hint">{formatRaceDate(dashboardMetrics.lastPersonalRecord.date)}</p>
+            </Link>
+          ) : (
+            <>
+              <h2 className="dashboard-card__title">Последний личный рекорд</h2>
+              <p className="dashboard-card__empty">Нет завершённых стартов с финишным временем.</p>
+            </>
+          )}
+        </article>
+
+        <article className="dashboard-card dashboard-card--season dashboard-card--accent-violet">
+          <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>
+          <div className="dashboard-card__progress" aria-label={`Сезон завершен на ${seasonProgress}%`}>
+            <span style={{ width: `${seasonProgress}%` }} />
+          </div>
+        </article>
+      </div>
+
+      <section className="dashboard-section" aria-label="Динамика времени на дистанции">
+        <h2 className="dashboard-section__title">Прогресс по времени</h2>
+        <p className="dashboard-section__intro">
+          Линия по завершённым стартам выбранной дистанции: выше — лучше время (короче гонка).
+        </p>
+        <label className="races-filter__field">
+          <span className="races-filter__label">Дистанция для графика</span>
+          <select
+            className="races-filter__select"
+            value={String(chartDistanceKm)}
+            onChange={(event) => {
+              setChartDistanceKm(Number(event.target.value));
+            }}
+          >
+            {PR_DISTANCES.map((d) => (
+              <option key={d} value={d}>
+                {formatDistance(d)}
+              </option>
+            ))}
+          </select>
+        </label>
+        <PaceTrendChart races={races} distanceKm={chartDistanceKm} />
+      </section>
+
+      <section className="dashboard-section" aria-label="Личные рекорды по дистанциям">
+        <h2 className="dashboard-section__title">Рекорды по дистанциям</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">Нет завершённых стартов для сравнения.</p>
+        )}
+      </section>
+    </section>
+  );
+}

frontend/src/pages/RaceDayPage.tsx

@@ -0,0 +1,170 @@
+import { useEffect, useMemo, useState } from "react";
+import { Link, useParams } from "react-router-dom";
+import type { Race } from "../api";
+import { ApiError, getRaces } from "../api";
+import {
+  formatDistance,
+  formatRaceDate,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+  getRaceVisual,
+  sortByDateAsc,
+} from "../lib";
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить старты.";
+}
+
+export function RaceDayPage(): JSX.Element {
+  const { ymd } = useParams<{ ymd: string }>();
+  const [races, setRaces] = useState<Race[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const validYmd = ymd && /^\d{4}-\d{2}-\d{2}$/.test(ymd) ? ymd : null;
+  const year = validYmd ? parseInt(validYmd.slice(0, 4), 10) : NaN;
+
+  useEffect(() => {
+    if (!validYmd || Number.isNaN(year)) {
+      setIsLoading(false);
+      setRaces([]);
+      return;
+    }
+
+    const ac = new AbortController();
+    let mounted = true;
+
+    async function load(): Promise<void> {
+      setIsLoading(true);
+      try {
+        const items = await getRaces({ year }, { signal: ac.signal });
+        if (!mounted || ac.signal.aborted) {
+          return;
+        }
+        const forDay = items.filter((r) => r.date.slice(0, 10) === validYmd);
+        setRaces(sortByDateAsc(forDay));
+        setErrorMessage(null);
+      } catch (e) {
+        if (ac.signal.aborted || !mounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(e));
+        setRaces([]);
+      } finally {
+        if (mounted && !ac.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void load();
+    return () => {
+      mounted = false;
+      ac.abort();
+    };
+  }, [validYmd, year]);
+
+  const heading = useMemo(() => {
+    if (!validYmd) {
+      return "Дата не указана";
+    }
+    return formatRaceDate(validYmd);
+  }, [validYmd]);
+
+  if (!validYmd) {
+    return (
+      <section className="page page--race-day">
+        <div className="race-day-hero">
+          <p className="race-day-hero__eyebrow">Страница дня</p>
+          <h1 className="page__title">Некорректная дата</h1>
+          <Link className="page-link" to="/races">
+            Вернуться к календарю стартов
+          </Link>
+        </div>
+      </section>
+    );
+  }
+
+  return (
+    <section className="page page--race-day">
+      <section className="race-day-hero" aria-label="Старты дня">
+        <Link className="page-link" to="/races">
+          ← Календарь стартов
+        </Link>
+        <p className="race-day-hero__eyebrow">Старты дня</p>
+        <h1 className="page__title">{heading}</h1>
+        <p className="page__subtitle">
+          {isLoading
+            ? "Загружаем расписание..."
+            : races.length > 0
+              ? `Запланировано стартов: ${races.length}`
+              : "Проверьте расписание или добавьте старт на эту дату."}
+        </p>
+      </section>
+
+      {errorMessage ? (
+        <p className="page__subtitle page__subtitle--error" role="alert">
+          {errorMessage}
+        </p>
+      ) : null}
+
+      {isLoading ? (
+        <p className="page__subtitle" aria-busy="true">
+          Загружаем…
+        </p>
+      ) : null}
+
+      {!isLoading && !errorMessage && races.length === 0 ? (
+        <p className="page__subtitle">На эту дату стартов нет.</p>
+      ) : null}
+
+      {!isLoading && races.length > 0 ? (
+        <ul className="race-day__list">
+          {races.map((race) => {
+            const visual = getRaceVisual(race);
+
+            return (
+              <li key={race.id} className="race-day__item">
+                <Link className="race-day__link" to={`/races/${race.id}`}>
+                  <img
+                    className={`race-day__image${
+                      visual.imageFit === "contain" ? " race-day__image--contain" : ""
+                    }`}
+                    src={visual.imageSrc}
+                    alt=""
+                    loading="lazy"
+                    referrerPolicy="no-referrer"
+                    onError={(event) => {
+                      event.currentTarget.onerror = null;
+                      event.currentTarget.classList.remove("race-day__image--contain");
+                      event.currentTarget.src = visual.fallbackSrc;
+                    }}
+                  />
+                  <span className="race-day__body">
+                    <span className="race-day__kicker">{visual.label}</span>
+                    <span className="race-day__title">{race.title}</span>
+                    <span className="race-day__meta">
+                      {formatDistance(race.distanceKm)} ·{" "}
+                      <span className={getRaceStatusClassName(race.status, race.date)}>
+                        {getRaceStatusLabel(race.status, race.date)}
+                      </span>
+                    </span>
+                  </span>
+                </Link>
+              </li>
+            );
+          })}
+        </ul>
+      ) : null}
+
+      <div className="race-day__actions">
+        <Link className="btn btn--primary" to={`/races/new?date=${validYmd}`}>
+          Добавить
+        </Link>
+      </div>
+    </section>
+  );
+}

frontend/src/pages/RaceDetailsPage.tsx

@@ -0,0 +1,281 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Link, useNavigate, useParams } from "react-router-dom";
+import { ApiError, deleteRace, getRaceById } from "../api";
+import {
+  formatDistance,
+  formatRaceDate,
+  getPaceLabel,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+  getRaceVisual,
+  raceNeedsResultEntry,
+} from "../lib";
+import type { Race } from "../api";
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить карточку старта.";
+}
+
+function DetailItem(props: { label: string; value: string | null | undefined }): JSX.Element | null {
+  const text = props.value?.trim();
+  if (!text) {
+    return null;
+  }
+  return (
+    <div className="race-details-meta__item">
+      <dt className="race-details-meta__key">{props.label}</dt>
+      <dd className="race-details-meta__value">{text}</dd>
+    </div>
+  );
+}
+
+function DetailLink(props: { label: string; url: string | null | undefined }): JSX.Element | null {
+  const href = props.url?.trim();
+  if (!href) {
+    return null;
+  }
+  return (
+    <div className="race-details-meta__item">
+      <dt className="race-details-meta__key">{props.label}</dt>
+      <dd className="race-details-meta__value">
+        <a href={href} target="_blank" rel="noopener noreferrer" className="race-details-meta__link">
+          {href}
+        </a>
+      </dd>
+    </div>
+  );
+}
+
+export function RaceDetailsPage(): JSX.Element {
+  const { raceId } = useParams<{ raceId: string }>();
+  const navigate = useNavigate();
+  const [race, setRace] = useState<Race | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [isDeleting, setIsDeleting] = useState<boolean>(false);
+  const [showDeleteConfirm, setShowDeleteConfirm] = useState<boolean>(false);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    let isMounted = true;
+
+    async function loadRace(): Promise<void> {
+      if (!raceId) {
+        setErrorMessage("Не найден идентификатор старта.");
+        setIsLoading(false);
+        return;
+      }
+
+      try {
+        const item = await getRaceById(raceId, { signal: ac.signal });
+        if (!isMounted || ac.signal.aborted) {
+          return;
+        }
+        setRace(item);
+        setErrorMessage(null);
+      } catch (error) {
+        if (ac.signal.aborted || !isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted && !ac.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadRace();
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+  }, [raceId]);
+
+  const paceLabel = useMemo(() => {
+    if (!race || race.status !== "completed") {
+      return null;
+    }
+    return getPaceLabel(race.finishTime, race.distanceKm);
+  }, [race]);
+
+  const handleDelete = useCallback(async () => {
+    if (!raceId) {
+      return;
+    }
+    setIsDeleting(true);
+    try {
+      await deleteRace(raceId);
+      navigate("/races", { replace: true });
+    } catch (error) {
+      setErrorMessage(error instanceof ApiError ? error.message : "Не удалось удалить старт.");
+      setShowDeleteConfirm(false);
+    } finally {
+      setIsDeleting(false);
+    }
+  }, [raceId, navigate]);
+
+  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";
+  const visual = getRaceVisual(race);
+
+  return (
+    <section className="page page--race-details">
+      <section className={`race-details-hero race-details-hero--${visual.variant}`} aria-label="Карточка старта">
+        <img
+          className={`race-details-hero__image${
+            visual.imageFit === "contain" ? " race-details-hero__image--contain" : ""
+          }`}
+          src={visual.imageSrc}
+          alt=""
+          loading="eager"
+          referrerPolicy="no-referrer"
+          onError={(event) => {
+            event.currentTarget.onerror = null;
+            event.currentTarget.classList.remove("race-details-hero__image--contain");
+            event.currentTarget.src = visual.fallbackSrc;
+          }}
+        />
+        <div className="race-details-hero__shade" aria-hidden="true" />
+        <div className="race-details-hero__content">
+          <Link className="race-details-hero__back" to="/races">
+            ← Календарь стартов
+          </Link>
+          <p className="race-details-hero__eyebrow">{visual.label}</p>
+          <h1 className="page__title">{race.title}</h1>
+          <p className="page__subtitle">
+            {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
+          </p>
+          <span className={getRaceStatusClassName(race.status, race.date)}>
+            {getRaceStatusLabel(race.status, race.date)}
+          </span>
+        </div>
+      </section>
+
+      {raceNeedsResultEntry(race) ? (
+        <p className="race-details-past-hint" role="status">
+          Дата старта уже прошла —{" "}
+          <Link className="race-details-past-hint__link" to={`/races/${race.id}/edit`}>
+            внесите результат или обновите статус
+          </Link>
+          .
+        </p>
+      ) : null}
+
+      <div className="race-details-actions">
+        <Link className="btn btn--primary" to={`/races/${race.id}/edit`}>
+          Редактировать
+        </Link>
+        <button
+          className="btn btn--danger"
+          type="button"
+          onClick={() => setShowDeleteConfirm(true)}
+        >
+          Удалить
+        </button>
+      </div>
+
+      {showDeleteConfirm ? (
+        <div className="confirm-banner" role="alertdialog" aria-label="Подтверждение удаления">
+          <p className="confirm-banner__text">Удалить «{race.title}»? Это действие необратимо.</p>
+          <div className="confirm-banner__actions">
+            <button
+              className="btn btn--danger"
+              type="button"
+              disabled={isDeleting}
+              onClick={handleDelete}
+            >
+              {isDeleting ? "Удаляем…" : "Да, удалить"}
+            </button>
+            <button
+              className="btn btn--secondary"
+              type="button"
+              disabled={isDeleting}
+              onClick={() => setShowDeleteConfirm(false)}
+            >
+              Отмена
+            </button>
+          </div>
+        </div>
+      ) : null}
+
+      <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, race.date)}</dd>
+            </div>
+            <DetailLink label="Сайт организатора" url={race.officialUrl} />
+            <DetailItem label="Время старта" value={race.startTime} />
+            <DetailItem label="Расписание кластеров" value={race.clusterSchedule} />
+            <DetailItem label="Выдача номеров" value={race.bibPickup} />
+            <DetailItem label="Стартовый номер" value={race.bibNumber} />
+          </dl>
+        </article>
+
+        <article className="race-details-card">
+          <h2 className="race-details-card__title">Результаты</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>
+              <DetailItem label="Место" value={race.finishPlace} />
+            </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/RaceFormPage.tsx

@@ -0,0 +1,488 @@
+import { useCallback, useEffect, useState } from "react";
+import { Link, useNavigate, useParams, useSearchParams } from "react-router-dom";
+import { ApiError, createRace, getRaceById, updateRace } from "../api";
+import type { CreateRacePayload, Race, RaceStatus, UpdateRacePayload } from "../api";
+import { DatePickerField, StartTimeSelects } from "../components";
+import { isRaceDateInPast, parseFinishTimeToSeconds } from "../lib";
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[«»"]/g, "")
+    .replace(/[^a-zа-яё0-9]+/gi, "-")
+    .replace(/(^-|-$)/g, "")
+    .substring(0, 60);
+}
+
+function generateId(date: string, title: string): string {
+  return `${date}-${slugify(title)}`;
+}
+
+const STATUS_OPTIONS: { value: string; label: string }[] = [
+  { value: "", label: "Не указан" },
+  { value: "planned", label: "Планирую" },
+  { value: "registered", label: "Зарегистрирован" },
+  { value: "completed", label: "Пробежал" },
+];
+
+interface FormData {
+  date: string;
+  title: string;
+  distanceKm: string;
+  status: string;
+  officialUrl: string;
+  coverImageUrl: string;
+  startTime: string;
+  clusterSchedule: string;
+  bibPickup: string;
+  bibNumber: string;
+  finishTime: string;
+  finishPlace: string;
+  notes: string;
+}
+
+const EMPTY_FORM: FormData = {
+  date: "",
+  title: "",
+  distanceKm: "",
+  status: "planned",
+  officialUrl: "",
+  coverImageUrl: "",
+  startTime: "",
+  clusterSchedule: "",
+  bibPickup: "",
+  bibNumber: "",
+  finishTime: "",
+  finishPlace: "",
+  notes: "",
+};
+
+function raceToFormData(race: Race): FormData {
+  const dateValue = race.date.length >= 10 ? race.date.slice(0, 10) : race.date;
+  return {
+    date: dateValue,
+    title: race.title,
+    distanceKm: String(race.distanceKm),
+    status: race.status ?? "",
+    officialUrl: race.officialUrl ?? "",
+    coverImageUrl: race.coverImageUrl ?? "",
+    startTime: race.startTime ?? "",
+    clusterSchedule: race.clusterSchedule ?? "",
+    bibPickup: race.bibPickup ?? "",
+    bibNumber: race.bibNumber ?? "",
+    finishTime: race.finishTime ?? "",
+    finishPlace: race.finishPlace ?? "",
+    notes: race.notes ?? "",
+  };
+}
+
+function emptyToNull(value: string): string | null {
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function validateForm(form: FormData): string[] {
+  const errors: string[] = [];
+  if (!form.date.trim()) {
+    errors.push("Дата обязательна.");
+  }
+  if (!form.title.trim()) {
+    errors.push("Название обязательно.");
+  }
+  const km = parseFloat(form.distanceKm);
+  if (Number.isNaN(km) || km <= 0) {
+    errors.push("Дистанция должна быть положительным числом.");
+  }
+  return errors;
+}
+
+function isRaceDateTodayOrPast(date: string): boolean {
+  if (!date.trim()) {
+    return false;
+  }
+  const today = new Date();
+  const y = today.getFullYear();
+  const m = String(today.getMonth() + 1).padStart(2, "0");
+  const d = String(today.getDate()).padStart(2, "0");
+  return isRaceDateInPast(date) || date.slice(0, 10) === `${y}-${m}-${d}`;
+}
+
+export function RaceFormPage(): JSX.Element {
+  const { raceId } = useParams<{ raceId: string }>();
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const isEditMode = Boolean(raceId);
+
+  const [form, setForm] = useState<FormData>(EMPTY_FORM);
+  const [isLoading, setIsLoading] = useState<boolean>(isEditMode);
+  const [isSaving, setIsSaving] = useState<boolean>(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [validationErrors, setValidationErrors] = useState<string[]>([]);
+
+  useEffect(() => {
+    if (!raceId) {
+      return;
+    }
+
+    let isMounted = true;
+
+    async function loadRace(): Promise<void> {
+      try {
+        const race = await getRaceById(raceId!);
+        if (!isMounted) {
+          return;
+        }
+        setForm(raceToFormData(race));
+        setErrorMessage(null);
+      } catch (error) {
+        if (!isMounted) {
+          return;
+        }
+        setErrorMessage(error instanceof ApiError ? error.message : "Не удалось загрузить данные старта.");
+      } finally {
+        if (isMounted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadRace();
+    return () => {
+      isMounted = false;
+    };
+  }, [raceId]);
+
+  useEffect(() => {
+    if (isEditMode) {
+      return;
+    }
+    const d = searchParams.get("date");
+    if (d && /^\d{4}-\d{2}-\d{2}$/.test(d)) {
+      setForm((prev) => (prev.date === d ? prev : { ...prev, date: d }));
+    }
+  }, [isEditMode, searchParams]);
+
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => {
+      const { name, value } = event.target;
+      setForm((prev) => {
+        const next = { ...prev, [name]: value };
+        if (name === "finishTime") {
+          const trimmed = value.trim();
+          if (trimmed !== "" && parseFinishTimeToSeconds(trimmed) !== null) {
+            return { ...next, status: "completed" };
+          }
+        }
+        return next;
+      });
+    },
+    [],
+  );
+
+  const handleSubmit = useCallback(
+    async (event: React.FormEvent) => {
+      event.preventDefault();
+      setErrorMessage(null);
+
+      const errors = validateForm(form);
+      setValidationErrors(errors);
+      if (errors.length > 0) {
+        return;
+      }
+
+      setIsSaving(true);
+
+      try {
+        const finishTrimmed = form.finishTime.trim();
+        const hasParsedFinish =
+          finishTrimmed !== "" && parseFinishTimeToSeconds(finishTrimmed) !== null;
+        let statusValue: RaceStatus | null =
+          form.status === "planned" || form.status === "registered" || form.status === "completed"
+            ? form.status
+            : null;
+        if (hasParsedFinish) {
+          statusValue = "completed";
+        }
+
+        if (isEditMode && raceId) {
+          const payload: UpdateRacePayload = {
+            date: form.date.trim(),
+            title: form.title.trim(),
+            distanceKm: parseFloat(form.distanceKm),
+            status: statusValue,
+            officialUrl: emptyToNull(form.officialUrl),
+            coverImageUrl: emptyToNull(form.coverImageUrl),
+            startTime: emptyToNull(form.startTime),
+            clusterSchedule: emptyToNull(form.clusterSchedule),
+            bibPickup: emptyToNull(form.bibPickup),
+            bibNumber: emptyToNull(form.bibNumber),
+            finishTime: emptyToNull(form.finishTime),
+            finishPlace: emptyToNull(form.finishPlace),
+            notes: emptyToNull(form.notes),
+          };
+
+          await updateRace(raceId, payload);
+          navigate(`/races/${raceId}`);
+        } else {
+          const slug = generateId(form.date.trim(), form.title.trim());
+          const payload: CreateRacePayload = {
+            slug,
+            date: form.date.trim(),
+            title: form.title.trim(),
+            distanceKm: parseFloat(form.distanceKm),
+            status: statusValue,
+            officialUrl: emptyToNull(form.officialUrl),
+            coverImageUrl: emptyToNull(form.coverImageUrl),
+            startTime: emptyToNull(form.startTime),
+            clusterSchedule: emptyToNull(form.clusterSchedule),
+            bibPickup: emptyToNull(form.bibPickup),
+            bibNumber: emptyToNull(form.bibNumber),
+            finishTime: emptyToNull(form.finishTime),
+            finishPlace: emptyToNull(form.finishPlace),
+            notes: emptyToNull(form.notes),
+          };
+
+          const created = await createRace(payload);
+          navigate(`/races/${created.id}`);
+        }
+      } catch (error) {
+        if (error instanceof ApiError) {
+          setErrorMessage(error.details.length > 0 ? error.details.join("; ") : error.message);
+        } else {
+          setErrorMessage("Произошла ошибка при сохранении.");
+        }
+      } finally {
+        setIsSaving(false);
+      }
+    },
+    [form, isEditMode, raceId, navigate],
+  );
+
+  const hideOrgScheduleFields = isEditMode && isRaceDateInPast(form.date);
+  const showResultFields = isRaceDateTodayOrPast(form.date);
+  const pageTitle = isEditMode ? "Редактирование старта" : "Новый старт";
+
+  if (isLoading) {
+    return (
+      <section className="page page--race-form" aria-busy="true">
+        <h1 className="page__title">{pageTitle}</h1>
+        <p className="page__subtitle">Загружаем данные...</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="page page--race-form">
+      <h1 className="page__title">{pageTitle}</h1>
+
+      {errorMessage ? (
+        <p className="page__subtitle page__subtitle--error" role="alert">{errorMessage}</p>
+      ) : null}
+
+      {validationErrors.length > 0 ? (
+        <ul className="form-errors" role="alert">
+          {validationErrors.map((msg) => (
+            <li key={msg} className="form-errors__item">{msg}</li>
+          ))}
+        </ul>
+      ) : null}
+
+      <form className="race-form" onSubmit={handleSubmit} noValidate>
+        <fieldset className="race-form__group">
+          <legend className="race-form__legend">Основная информация</legend>
+
+          <div className="race-form__field">
+            <span className="race-form__label">Дата *</span>
+            <DatePickerField
+              name="date"
+              value={form.date}
+              onChange={(next) => {
+                setForm((prev) => ({ ...prev, date: next }));
+              }}
+              required
+            />
+          </div>
+
+          <label className="race-form__field">
+            <span className="race-form__label">Название *</span>
+            <input
+              className="race-form__input"
+              type="text"
+              name="title"
+              value={form.title}
+              onChange={handleChange}
+              required
+              placeholder="Казанский марафон"
+            />
+          </label>
+
+          <label className="race-form__field">
+            <span className="race-form__label">Дистанция, км *</span>
+            <input
+              className="race-form__input"
+              type="number"
+              name="distanceKm"
+              value={form.distanceKm}
+              onChange={handleChange}
+              required
+              min="0.1"
+              step="0.001"
+              placeholder="21.1"
+            />
+          </label>
+
+          <label className="race-form__field">
+            <span className="race-form__label">Статус</span>
+            <select
+              className="race-form__input"
+              name="status"
+              value={form.status}
+              onChange={handleChange}
+            >
+              {STATUS_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>{opt.label}</option>
+              ))}
+            </select>
+          </label>
+        </fieldset>
+
+        <fieldset className="race-form__group">
+          <legend className="race-form__legend">Организация</legend>
+
+          {hideOrgScheduleFields ? null : (
+            <label className="race-form__field">
+              <span className="race-form__label">Сайт организатора</span>
+              <input
+                className="race-form__input"
+                type="url"
+                name="officialUrl"
+                value={form.officialUrl}
+                onChange={handleChange}
+                placeholder="https://…"
+              />
+            </label>
+          )}
+
+          <label className="race-form__field">
+            <span className="race-form__label">URL обложки</span>
+            <input
+              className="race-form__input"
+              type="url"
+              name="coverImageUrl"
+              value={form.coverImageUrl}
+              onChange={handleChange}
+              placeholder="https://…"
+            />
+          </label>
+
+          {hideOrgScheduleFields ? null : (
+            <div className="race-form__field">
+              <span className="race-form__label">Время старта</span>
+              <StartTimeSelects
+                value={form.startTime}
+                onChange={(next) => {
+                  setForm((prev) => ({ ...prev, startTime: next }));
+                }}
+              />
+            </div>
+          )}
+
+          {hideOrgScheduleFields ? null : (
+            <label className="race-form__field">
+              <span className="race-form__label">Расписание кластеров</span>
+              <input
+                className="race-form__input"
+                type="text"
+                name="clusterSchedule"
+                value={form.clusterSchedule}
+                onChange={handleChange}
+              />
+            </label>
+          )}
+
+          {hideOrgScheduleFields ? null : (
+            <label className="race-form__field">
+              <span className="race-form__label">Выдача номеров</span>
+              <input
+                className="race-form__input"
+                type="text"
+                name="bibPickup"
+                value={form.bibPickup}
+                onChange={handleChange}
+              />
+            </label>
+          )}
+
+          <label className="race-form__field">
+            <span className="race-form__label">Стартовый номер</span>
+            <input
+              className="race-form__input"
+              type="text"
+              name="bibNumber"
+              value={form.bibNumber}
+              onChange={handleChange}
+              placeholder="1234"
+            />
+          </label>
+        </fieldset>
+
+        {showResultFields ? (
+          <fieldset className="race-form__group">
+            <legend className="race-form__legend">Результаты</legend>
+
+            <label className="race-form__field">
+              <span className="race-form__label">Финишное время</span>
+              <input
+                className="race-form__input"
+                type="text"
+                name="finishTime"
+                value={form.finishTime}
+                onChange={handleChange}
+                placeholder="1:45:30"
+              />
+            </label>
+
+            <label className="race-form__field">
+              <span className="race-form__label">Место на финише</span>
+              <input
+                className="race-form__input"
+                type="text"
+                name="finishPlace"
+                value={form.finishPlace}
+                onChange={handleChange}
+                placeholder="12/340"
+              />
+            </label>
+          </fieldset>
+        ) : null}
+
+        <fieldset className="race-form__group">
+          <legend className="race-form__legend">Дополнительно</legend>
+
+          <label className="race-form__field">
+            <span className="race-form__label">Заметки</span>
+            <textarea
+              className="race-form__input race-form__input--textarea"
+              name="notes"
+              value={form.notes}
+              onChange={handleChange}
+              rows={4}
+            />
+          </label>
+        </fieldset>
+
+        <div className="race-form__actions">
+          <button className="btn btn--primary" type="submit" disabled={isSaving}>
+            {isSaving ? "Сохраняем…" : isEditMode ? "Сохранить" : "Создать"}
+          </button>
+          <Link
+            className="btn btn--secondary"
+            to={isEditMode && raceId ? `/races/${raceId}` : "/races"}
+          >
+            Отмена
+          </Link>
+        </div>
+      </form>
+    </section>
+  );
+}

frontend/src/pages/RacesPage.tsx

@@ -0,0 +1,377 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Link } from "react-router-dom";
+import type { Race, RacesQuery } from "../api";
+import { ApiError, getRaces } from "../api";
+import { RacesCalendar } from "../components/RacesCalendar";
+import {
+  formatDistance,
+  formatRaceDate,
+  getRaceVisual,
+  getRaceStatusClassName,
+  getRaceStatusLabel,
+  parseRaceDate,
+  sortByDateAsc,
+  sortByDateDesc,
+} from "../lib";
+
+const MONTH_OPTIONS: { value: string; label: string }[] = [
+  { value: "", label: "Все месяцы" },
+  { value: "1", label: "Январь" },
+  { value: "2", label: "Февраль" },
+  { value: "3", label: "Март" },
+  { value: "4", label: "Апрель" },
+  { value: "5", label: "Май" },
+  { value: "6", label: "Июнь" },
+  { value: "7", label: "Июль" },
+  { value: "8", label: "Август" },
+  { value: "9", label: "Сентябрь" },
+  { value: "10", label: "Октябрь" },
+  { value: "11", label: "Ноябрь" },
+  { value: "12", label: "Декабрь" },
+];
+
+const VIEW_STORAGE_KEY = "races-view-mode";
+
+type ViewMode = "list" | "calendar";
+type RaceListTab = "upcoming" | "completed";
+
+function yearSelectOptions(): number[] {
+  const current = new Date().getFullYear();
+  const start = current - 2;
+  const end = current + 4;
+  const years: number[] = [];
+  for (let y = start; y <= end; y += 1) {
+    years.push(y);
+  }
+  return years;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return "Не удалось загрузить календарь стартов.";
+}
+
+function readInitialViewMode(): ViewMode {
+  try {
+    const v = sessionStorage.getItem(VIEW_STORAGE_KEY);
+    return v === "calendar" ? "calendar" : "list";
+  } catch {
+    return "list";
+  }
+}
+
+function RaceList(props: { title: string; races: Race[]; variant: RaceListTab }): JSX.Element {
+  const { title, races, variant } = props;
+
+  return (
+    <section className={`race-list race-list--${variant}`} aria-label={title}>
+      <h2 className="race-list__title">{title}</h2>
+      {races.length > 0 ? (
+        <ul className="race-list__items">
+          {races.map((race) => {
+            const visual = getRaceVisual(race);
+            const parsedDate = parseRaceDate(race.date);
+            const day = parsedDate.toLocaleDateString("ru-RU", { day: "2-digit" });
+            const month = parsedDate.toLocaleDateString("ru-RU", { month: "short" });
+
+            return (
+              <li key={race.id} className={`race-card race-card--action race-card--poster race-card--${visual.variant}`}>
+                <Link
+                  className="race-card__link-surface"
+                  to={`/races/${race.id}`}
+                  aria-label={`Старт: ${race.title}`}
+                >
+                  <div className="race-card__image-wrap">
+                    <img
+                      className={`race-card__image${
+                        visual.imageFit === "contain" ? " race-card__image--contain" : ""
+                      }`}
+                      src={visual.imageSrc}
+                      alt=""
+                      loading="lazy"
+                      referrerPolicy="no-referrer"
+                      onError={(event) => {
+                        event.currentTarget.onerror = null;
+                        event.currentTarget.classList.remove("race-card__image--contain");
+                        event.currentTarget.src = visual.fallbackSrc;
+                      }}
+                    />
+                    <span className="race-card__date-badge">
+                      <span>{day}</span>
+                      <span>{month}</span>
+                    </span>
+                  </div>
+                  <div className="race-card__content">
+                    <div className="race-card__main">
+                      <p className="race-card__kicker">{visual.label}</p>
+                      <p className="race-card__title">
+                        <span className="race-card__title-text">{race.title}</span>
+                      </p>
+                      <p className="race-card__meta">
+                        {formatRaceDate(race.date)} · {formatDistance(race.distanceKm)}
+                      </p>
+                    </div>
+                    <div className="race-card__footer">
+                      <span className={getRaceStatusClassName(race.status, race.date)}>
+                        {getRaceStatusLabel(race.status, race.date)}
+                      </span>
+                      <span className="race-card__cta">Открыть</span>
+                    </div>
+                  </div>
+                </Link>
+              </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);
+  const [yearFilter, setYearFilter] = useState<string>("");
+  const [monthFilter, setMonthFilter] = useState<string>("");
+  const [viewMode, setViewMode] = useState<ViewMode>(() => readInitialViewMode());
+  const [activeListTab, setActiveListTab] = useState<RaceListTab>("upcoming");
+
+  const setViewModePersist = useCallback((mode: ViewMode) => {
+    setViewMode(mode);
+    try {
+      sessionStorage.setItem(VIEW_STORAGE_KEY, mode);
+    } catch {
+      /* ignore */
+    }
+  }, []);
+
+  const handleViewList = useCallback(() => {
+    setViewModePersist("list");
+  }, [setViewModePersist]);
+
+  const handleViewCalendar = useCallback(() => {
+    setViewModePersist("calendar");
+    setYearFilter((prev) => (prev === "" ? String(new Date().getFullYear()) : prev));
+  }, [setViewModePersist]);
+
+  const listQuery = useMemo((): RacesQuery | undefined => {
+    if (viewMode === "calendar") {
+      const y = yearFilter !== "" ? parseInt(yearFilter, 10) : new Date().getFullYear();
+      if (!Number.isNaN(y)) {
+        return { year: y };
+      }
+      return undefined;
+    }
+    const q: RacesQuery = {};
+    if (yearFilter !== "") {
+      const y = parseInt(yearFilter, 10);
+      if (!Number.isNaN(y)) {
+        q.year = y;
+      }
+    }
+    if (monthFilter !== "") {
+      const m = parseInt(monthFilter, 10);
+      if (!Number.isNaN(m)) {
+        q.month = m;
+      }
+    }
+    return Object.keys(q).length > 0 ? q : undefined;
+  }, [viewMode, yearFilter, monthFilter]);
+
+  const displayYear = useMemo(() => {
+    if (yearFilter !== "") {
+      const y = parseInt(yearFilter, 10);
+      return Number.isNaN(y) ? new Date().getFullYear() : y;
+    }
+    return new Date().getFullYear();
+  }, [yearFilter]);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    let isMounted = true;
+
+    async function loadRaces(): Promise<void> {
+      setIsLoading(true);
+      try {
+        const items = await getRaces(listQuery, { signal: ac.signal });
+        if (!isMounted || ac.signal.aborted) {
+          return;
+        }
+        setRaces(items);
+        setErrorMessage(null);
+      } catch (error) {
+        if (ac.signal.aborted || !isMounted) {
+          return;
+        }
+        setErrorMessage(getErrorMessage(error));
+      } finally {
+        if (isMounted && !ac.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    void loadRaces();
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+  }, [listQuery]);
+
+  const { upcoming, completed } = useMemo(
+    () => ({
+      upcoming: sortByDateAsc(races.filter((race) => race.status !== "completed")),
+      completed: sortByDateDesc(races.filter((race) => race.status === "completed")),
+    }),
+    [races],
+  );
+  const statusMessage = useMemo(() => {
+    if (errorMessage && !isLoading) {
+      return errorMessage;
+    }
+    if (isLoading) {
+      return "Загружаем данные...";
+    }
+    if (viewMode === "calendar" && monthFilter === "") {
+      return "Выберите месяц, чтобы увидеть его крупным планом.";
+    }
+    return "";
+  }, [errorMessage, isLoading, monthFilter, viewMode]);
+  const statusClassName = [
+    "races-status__message",
+    !statusMessage ? "races-status__message--empty" : "",
+    errorMessage && !isLoading ? "races-status__message--error" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  if (errorMessage && races.length === 0 && !isLoading) {
+    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">
+      <section className="races-hero" aria-label="Календарь стартов">
+        <div className="races-hero__content">
+          <p className="races-hero__eyebrow">Сезонная афиша</p>
+          <h1 className="page__title">Календарь стартов</h1>
+          <p className="page__subtitle">Будущие и прошедшие старты в одном месте.</p>
+          <div className="races-view-toggle" role="group" aria-label="Вид отображения">
+            <button
+              type="button"
+              className={`races-view-toggle__btn${viewMode === "list" ? " races-view-toggle__btn--active" : ""}`}
+              onClick={handleViewList}
+            >
+              Список
+            </button>
+            <button
+              type="button"
+              className={`races-view-toggle__btn${viewMode === "calendar" ? " races-view-toggle__btn--active" : ""}`}
+              onClick={handleViewCalendar}
+            >
+              Календарь
+            </button>
+          </div>
+        </div>
+        <div className="races-hero__filters">
+          <div className="races-filter" role="search" aria-label="Фильтр по дате">
+            <label className="races-filter__field">
+              <span className="races-filter__label">Год</span>
+              <select
+                className="races-filter__select"
+                value={viewMode === "list" ? yearFilter : yearFilter || String(displayYear)}
+                onChange={(event) => {
+                  setYearFilter(event.target.value);
+                }}
+              >
+                {viewMode === "list" ? <option value="">Все года</option> : null}
+                {yearSelectOptions().map((y) => (
+                  <option key={y} value={String(y)}>
+                    {y}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="races-filter__field">
+              <span className="races-filter__label">Месяц</span>
+              <select
+                className="races-filter__select"
+                value={monthFilter}
+                onChange={(event) => {
+                  setMonthFilter(event.target.value);
+                }}
+              >
+                {MONTH_OPTIONS.map((opt) => (
+                  <option key={opt.value || "all"} value={opt.value}>
+                    {opt.label}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+        </div>
+      </section>
+
+      <div className="races-status" aria-live="polite">
+        <p
+          className={statusClassName}
+          role={errorMessage && !isLoading ? "alert" : undefined}
+          aria-busy={isLoading || undefined}
+          aria-hidden={!statusMessage || undefined}
+        >
+          {statusMessage || "\u00a0"}
+        </p>
+      </div>
+
+      {viewMode === "list" ? (
+        <>
+          <div className="race-list-tabs" role="tablist" aria-label="Раздел стартов">
+            <button
+              type="button"
+              role="tab"
+              aria-selected={activeListTab === "upcoming"}
+              className={`race-list-tabs__btn${activeListTab === "upcoming" ? " race-list-tabs__btn--active" : ""}`}
+              onClick={() => setActiveListTab("upcoming")}
+            >
+              Будущие
+              <span className="race-list-tabs__count">{upcoming.length}</span>
+            </button>
+            <button
+              type="button"
+              role="tab"
+              aria-selected={activeListTab === "completed"}
+              className={`race-list-tabs__btn${activeListTab === "completed" ? " race-list-tabs__btn--active" : ""}`}
+              onClick={() => setActiveListTab("completed")}
+            >
+              Прошедшие
+              <span className="race-list-tabs__count">{completed.length}</span>
+            </button>
+          </div>
+          <div className={`race-lists race-lists--mobile-${activeListTab}`}>
+            <RaceList title="Будущие" races={upcoming} variant="upcoming" />
+            <RaceList title="Завершенные" races={completed} variant="completed" />
+          </div>
+        </>
+      ) : (
+        <div className="races-cal-wrap">
+          <RacesCalendar
+            displayYear={displayYear}
+            monthFilter={monthFilter}
+            races={races}
+            onMonthFilterChange={setMonthFilter}
+          />
+        </div>
+      )}
+    </section>
+  );
+}

frontend/src/styles/tokens.css

@@ -0,0 +1,40 @@
+:root {
+  --color-bg: #edf3f6;
+  --color-bg-deep: #071927;
+  --color-surface: #ffffff;
+  --color-surface-soft: #f7fafc;
+  --color-text: #0e1f2d;
+  --color-text-muted: #647483;
+  --color-accent: #1168d8;
+  --color-accent-strong: #0c48a0;
+  --color-lime: #b9f24a;
+  --color-coral: #ff6f5e;
+  --color-violet: #6d5dfc;
+  --color-border: #d6e1ea;
+  --color-success: #168657;
+  --color-warning: #b77716;
+  --color-error: #c43333;
+
+  --font-family-base: "Inter", "Segoe UI", Arial, sans-serif;
+  --font-size-h1: 2.35rem;
+  --font-size-h2: 1.35rem;
+  --font-size-body: 1rem;
+  --font-size-caption: 0.875rem;
+  --line-height-base: 1.45;
+
+  --space-1: 0.25rem;
+  --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.625rem;
+  --radius-lg: 0.75rem;
+
+  --shadow-card: 0 10px 30px rgba(14, 31, 45, 0.08);
+  --shadow-card-lift: 0 16px 34px rgba(14, 31, 45, 0.16);
+  --shadow-hero: 0 22px 60px rgba(7, 25, 39, 0.24);
+}

frontend/src/vite-env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_TURNSTILE_SITE_KEY?: string;
+}
+
+interface Window {
+  turnstile?: {
+    render(container: HTMLElement, options: { sitekey: string; callback(token: string): void; "expired-callback"(): void }): string;
+    remove(widgetId: string): void;
+  };
+}

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,14 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    proxy: {
+      "/api": {
+        target: "http://localhost:3001",
+        changeOrigin: true,
+      },
+    },
+  },
+});