Initial commit: project plan and seed data
Made-with: Cursor
This commit is contained in:
Anton
161
docs/agent-backend-instruction.md
Normal file
161
docs/agent-backend-instruction.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Инструкция агенту: реализация бэкенда по [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).*
|
||||
Reference in New Issue
Block a user