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

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