# Инструкция агенту: устранение рассинхронизации 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/` не менялись для "закрытия" замечаний.