Files

CI / build-and-test (pull_request) Has been cancelled

Details

chore: drop agent/plan docs, unify .env for Docker stack

- Remove PLAN/agent instruction files; single root .env.example for DB + API
- Stack compose uses env_file .env; delete stack env example duplicate
- Refresh README, backend docs, API doc; trim gitignore/dockerignore

Made-with: Cursor

2026-04-07 00:30:29 +03:00

5.3 KiB

Raw Blame History

Calendar Run — план продукта

Монорепозиторий: backend (Express + PostgreSQL) и frontend (React + Vite). Цель — календарь стартов с метриками бегуна: планирование, результаты, PR и сравнение.

Вне объёма (намеренно)

Авторизация, мультипользовательность, личные кабинеты.
Парсинг сайтов организаторов и автозагрузка результатов.
Отдача статики SPA с того же процесса, что и API (фронт — отдельный Vite/build).

Модель данных `Race` (API — camelCase)

Поле	Тип	Описание
`id`	string	Стабильный ключ, например `{YYYY-MM-DD}-{slug}`
`date`	string	`YYYY-MM-DD`
`title`	string	Название
`distanceKm`	number	Дистанция, км
`status`	`planned`	`registered`
`officialUrl`	string	null
`startTime`	string	null
`clusterSchedule`	string	null
`bibPickup`	string	null
`bibNumber`	string	null
`finishTime`	string	null
`finishPlace`	string	null
`notes`	string	null
`createdAt`	string	ISO, read-only
`updatedAt`	string	null

PostgreSQL: snake_case столбцы, маппинг в [backend/src/mappers/race.ts](backend/src/mappers/race.ts).

HTTP API (минимум)

GET /health — liveness без БД.
GET /ready — readiness (подключение к БД; в режиме mock считается доступной — только для dev/CI).
GET /races — список; query: year, month (целые; month 1–12).
GET /races/:id, POST /races, PATCH /races/:id, DELETE /races/:id.

Ошибки: JSON, единый стиль (validation_error, not_found, conflict, database_unavailable). Подробности — [docs/backend-api-for-frontend.md](docs/backend-api-for-frontend.md).

Seed

Файл [import/races_2026_calendar.csv](import/races_2026_calendar.csv).
Стабильный id, upsert по id. Повторный запуск безопасен.

Режим без PostgreSQL (dev/CI)

Переменная CALENDAR_RUN_MOCK_DB=1 (или true): HTTP-обработчики используют заглушку пула без реальной БД. Не использовать для npm run db:migrate и npm run seed — нужен настоящий Postgres и DB_*.

Frontend (SPA)

Маршруты: дашборд (/), список стартов (/races), карточка (/races/:id).
Дашборд: ближайший старт, последний результат, PR, сезон, PR по ключевым дистанциям, сравнение завершённых стартов, при необходимости — лёгкая визуализация прогресса.
Список: будущие / прошедшие; фильтрация по году и месяцу через API.
Стили: BEM и дизайн-токены; ориентир по духу — [agent-frontend-ui-instructions.md](agent-frontend-ui-instructions.md).

Критерии готовности текущей итерации

Документация согласована с кодом: [README.md](README.md), [docs/backend.md](docs/backend.md), [docs/backend-api-for-frontend.md](docs/backend-api-for-frontend.md).
Миграции и seed воспроизводимы; контракт API покрыт smoke-тестами в CI при необходимости с mock-БД.

5.3 KiB Raw Blame History Unescape Escape