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