Polotsk Transit API

Система управления информацией об общественном транспорте города Полоцка с REST API, веб-панелью администратора и поддержкой offline-синхронизации.

🚀 Возможности

MVP (Версия 1.0 - статические данные)

• ✅ REST API для маршрутов и остановок
• ✅ Геопространственные запросы (PostGIS)
• ✅ Расчет ETA на основе расписания
• ✅ Offline-синхронизация для мобильных приложений
• ✅ Веб-панель администратора
• ✅ Кеширование через Redis
• ✅ Аутентификация по API ключам
• ✅ Rate limiting

Технологический стек

Backend:

• Node.js + Express
• PostgreSQL + PostGIS
• Redis
• Docker

Frontend (Admin Panel):

• React + Vite
• Tailwind CSS
• React Leaflet (карты)
• Axios

📋 Требования

• Docker и Docker Compose
• Node.js 18+ (для разработки без Docker)
• Статический IP или динамический DNS
• ~2GB свободного места на диске

🛠 Установка и запуск

1. Клонирование и настройка

# Создайте .env файл из примера
cp .env.example .env

# Настройте переменные окружения
nano .env

Важные переменные в .env:

# Обязательно измените в продакшене!
DB_PASSWORD=your_secure_password_here
API_KEY_SALT=generate_random_salt_with_openssl
ADMIN_PASSWORD=your_secure_admin_password_here

# Для разработки/деплоя через встроенный proxy оставьте как есть
CORS_ORIGIN=http://localhost:3001
API_URL=/api/v1

Генерация безопасного salt:

openssl rand -base64 32

2. Запуск с Docker (рекомендуется)

# Сборка и запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

# Просмотр логов
docker-compose logs -f

Сервисы будут доступны:

• API: http://localhost:3000
• Admin Panel: http://localhost:3001
• PostgreSQL: localhost:5432
• Redis: localhost:6379

Мастер-аккаунт создается автоматически при старте backend:

• login: admin
• password: значение ADMIN_PASSWORD из .env (если не задано, fallback admin123)

3. Проверка работоспособности

# Проверка API
curl http://localhost:3000/health

# Проверка базы данных
docker exec -it polotsk-transit-db psql -U transit_admin -d polotsk_transit -c "SELECT COUNT(*) FROM routes;"

4. Разработка без Docker

Backend:

cd backend
npm install
cp .env.example .env

# Убедитесь, что PostgreSQL и Redis запущены локально
# Настройте DATABASE_URL и REDIS_URL в .env

npm run dev

Frontend:

cd frontend
npm install
cp .env.example .env

npm run dev

📱 Использование API

Аутентификация

Все запросы требуют API ключ в заголовке:

curl -H "X-API-Key: dev_key_12345678" http://localhost:3000/api/v1/routes

Основные эндпоинты

Маршруты:

GET    /api/v1/routes              # Все маршруты
GET    /api/v1/routes/:id          # Маршрут с остановками
POST   /api/v1/routes              # Создать маршрут
PUT    /api/v1/routes/:id          # Обновить маршрут
DELETE /api/v1/routes/:id          # Удалить маршрут

Остановки:

GET    /api/v1/stops                                    # Все остановки
GET    /api/v1/stops/:id                                # Конкретная остановка
GET    /api/v1/stops/nearby?lat=55.4869&lon=28.7856&radius=500  # Ближайшие
POST   /api/v1/stops                                    # Создать остановку
PUT    /api/v1/stops/:id                                # Обновить остановку
DELETE /api/v1/stops/:id                                # Удалить остановку

ETA (расчет времени прибытия):

POST /api/v1/eta/calculate
{
  "stopId": 1,
  "routeId": 1
}

GET /api/v1/eta/stop/:stopId  # ETA для всех маршрутов на остановке

Синхронизация (для offline-режима):

GET /api/v1/sync                           # Полная синхронизация
GET /api/v1/sync?lastSync=2025-11-19T10:00:00Z  # Инкрементальная
GET /api/v1/sync/status                    # Статус системы

Примеры запросов

Создание маршрута:

curl -X POST http://localhost:3000/api/v1/routes \
  -H "X-API-Key: dev_key_12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "route_number": "1",
    "name": "Центр - Вокзал",
    "type": "bus",
    "color": "#0066CC",
    "description": "Основной маршрут через центр города"
  }'

Создание остановки:

curl -X POST http://localhost:3000/api/v1/stops \
  -H "X-API-Key: dev_key_12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Площадь Свободы",
    "latitude": 55.4869,
    "longitude": 28.7856,
    "address": "ул. Ленина, 1"
  }'

Поиск ближайших остановок:

curl -H "X-API-Key: dev_key_12345678" \
  "http://localhost:3000/api/v1/stops/nearby?lat=55.4869&lon=28.7856&radius=500"

🔐 Безопасность домашнего сервера

Обязательные меры безопасности

1. Cloudflare Tunnel (рекомендуется):

# Установка cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
sudo mv cloudflared /usr/local/bin/
sudo chmod +x /usr/local/bin/cloudflared

# Аутентификация
cloudflared tunnel login

# Создание туннеля
cloudflared tunnel create polotsk-transit

# Запуск
cloudflared tunnel run polotsk-transit

2. Настройка SSL в Nginx:

# Получение сертификата Let's Encrypt
sudo certbot --nginx -d api.yourdomain.com -d admin.yourdomain.com

# Сертификаты автоматически обновятся

3. Fail2ban:

sudo apt install fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

4. Мониторинг:

# Установка Prometheus + Grafana (опционально)
# Или простой мониторинг через Docker stats
docker stats

Создание API ключей

API ключи можно создать через базу данных:

INSERT INTO api_keys (key, app_name, rate_limit) 
VALUES ('your_secure_key_here', 'iOS App', 10000);

Или через скрипт:

const crypto = require('crypto');
const apiKey = crypto.randomBytes(32).toString('hex');
console.log(apiKey);

📊 Админ-панель

Откройте http://localhost:3001 в браузере.

Функции:

• Управление маршрутами
• Создание и редактирование остановок на карте
• Просмотр статистики
• Управление расписаниями (в разработке)

🗄 Структура базы данных

routes          # Маршруты
stops           # Остановки (с PostGIS геометрией)
route_stops     # Связь маршрутов и остановок
schedules       # Расписания
vehicles        # Транспортные средства
historical_delays  # Статистика задержек
alerts          # Уведомления
api_keys        # API ключи
sync_log        # Лог изменений для синхронизации

🔄 Обновления

# Остановка сервисов
docker-compose down

# Обновление кода
git pull

# Перезапуск
docker-compose up -d --build

🐛 Troubleshooting

База данных не стартует:

docker-compose logs postgres
docker-compose down -v  # Удалит volumes, ОСТОРОЖНО!
docker-compose up -d

API не отвечает:

docker-compose logs backend
docker-compose restart backend

Frontend не собирается:

cd frontend
npm install
npm run build

PostGIS ошибки:

docker exec -it polotsk-transit-db psql -U transit_admin -d polotsk_transit
SELECT PostGIS_Version();

📝 Следующие шаги (Roadmap)

Версия 2.0 - Краудсорсинг GPS

• Endpoint для получения GPS от пользователей
• Агрегация и фильтрация GPS данных
• WebSocket для реалтайм-обновлений
• Функция "Я еду в маршруте" в приложениях

Версия 3.0 - Продвинутые функции

• IoT GPS-трекеры интеграция
• Машинное обучение для предсказания задержек
• Push-уведомления
• Аналитика и отчеты

🤝 Контакты и поддержка

Создано для города Полоцка 🇧🇾

📄 Лицензия

MIT License - используйте свободно!