feat: scaffold frontend app structure

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

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