Files

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

Details

feat: align docs with code, finish_place, registered status, UI filters, tests, CI

- Add PLAN.md and sync backend docs, .env.example, API doc (404 details)
- Document mock DB and PORT/API_PORT in docs/backend.md; README monorepo + frontend/.env.example
- Migration 002: finish_place column, status registered; mapper and mock DB updated
- Frontend: registered status, finishPlace, calendar year/month filters, pace sparkline
- Extract createApp for tests; supertest + tsx; GitHub Actions CI

Made-with: Cursor

2026-04-06 22:20:31 +03:00

4.8 KiB

Raw Blame History

Backend — эксплуатация

Стек

Node.js LTS + TypeScript
Express (HTTP-фреймворк)
pg (PostgreSQL клиент)
csv-parse (парсинг CSV для seed)

Быстрый старт

1. Поднять PostgreSQL

# из корня проекта
docker-compose up -d

Параметры подключения берутся из .env (см. .env.example в корне).

2. Установить зависимости

cd backend
npm install

3. Создать `.env`

Скопировать .env.example из корня проекта и при необходимости отредактировать:

cp ../.env.example ../.env

4. Миграции

npm run db:migrate

Миграционный раннер — собственный скрипт src/migrate.ts:

хранит историю применённых файлов в таблице _migrations;
идемпотентный — повторный запуск не применяет уже выполненные миграции;
файлы миграций: backend/migrations/*.sql, применяются в алфавитном порядке.

5. Seed (начальный набор данных)

npm run seed

Читает import/races_2026_calendar.csv из корня репо.
Генерирует стабильный id в формате {date}-{slug}.
Выполняет upsert (INSERT … ON CONFLICT DO UPDATE) — безопасно для повторного запуска.

6. Запуск API

npm run dev      # dev-режим через ts-node
npm run build    # компиляция в dist/
npm start        # запуск из dist/

API слушает порт: PORT (если задан), иначе API_PORT, иначе 3001.

Переменные окружения

Переменная	Описание	По умолчанию
`DB_HOST`	Хост PostgreSQL	— (обязательна без mock, см. ниже)
`DB_PORT`	Порт PostgreSQL	— (обязательна без mock)
`DB_NAME`	Имя базы данных	— (обязательна без mock)
`DB_USER`	Пользователь БД	— (обязательна без mock)
`DB_PASSWORD`	Пароль БД	— (обязательна без mock)
`CALENDAR_RUN_MOCK_DB`	`1` или `true` — режим без PostgreSQL для HTTP API (dev/CI)	выкл.
`PORT`	Порт API (приоритетнее `API_PORT`)	—
`API_PORT`	Порт API-сервера	`3001`
`CORS_ORIGIN`	Разрешённый origin для CORS	`http://localhost:5173`

Без mock: при отсутствии любой из DB_* процесс падает при старте: Missing required environment variable: <NAME>.

С CALENDAR_RUN_MOCK_DB=1: переменные DB_* не обязательны; реальный пул не поднимается. Не использовать mock для npm run db:migrate и npm run seed — нужен настоящий Postgres и корректные DB_*.

Поведение при недоступной БД

Старт сервера — проходит успешно (env валидирован, Express слушает порт).
GET /health — всегда 200 { "status": "ok" } (liveness, без обращения к БД).
GET /ready — при обычном режиме пробует подключиться к БД; 200 если ОК, 503 { "error": "database_unavailable", ... } если нет. В режиме CALENDAR_RUN_MOCK_DB readiness считается успешным без реального подключения (удобно для CI/smoke API).
Все остальные маршруты при ошибке БД возвращают 503 { "error": "database_unavailable" }.

Структура каталога

backend/
├── migrations/
│   ├── 001_create_races.sql
│   └── 002_finish_place_and_registered_status.sql
├── src/
│   ├── app.ts             # фабрика Express (тесты)
│   ├── config.ts          # загрузка и валидация env
│   ├── db.ts              # pg Pool или mock
│   ├── index.ts           # запуск сервера
│   ├── migrate.ts         # раннер миграций
│   ├── seed.ts            # разовый импорт CSV
│   ├── mappers/
│   │   └── race.ts        # snake_case ↔ camelCase
│   └── routes/
│       ├── health.ts      # /health, /ready
│       └── races.ts       # CRUD /races
├── package.json
└── tsconfig.json

4.8 KiB Raw Blame History Unescape Escape