Zakhar Timoshenko
f7f0b039dd
- Implemented Telegram cancellation parsing logic in `telegramCancellationParser.js`. - Created unit tests for cancellation parsing in `telegramCancellationParser.test.js`. - Developed integration tests for Telegram import service in `telegramImport.integration.test.js`. - Added API tests for Telegram import endpoints in `telegramImportApi.test.js`. - Introduced service tests for Telegram import logic in `telegramImportService.test.js`. - Documented the Telegram cancellation import process in `telegram-cancellation-import.md`. - Built a React component for managing Telegram imports in `TelegramImportPanel.jsx`.
375 lines
12 KiB
Markdown
375 lines
12 KiB
Markdown
# RideBus DE API
|
||
|
||
Система управления информацией об общественном транспорте города Полоцка с REST API, веб-панелью администратора и поддержкой offline-синхронизации.
|
||
|
||
## 🚀 Возможности
|
||
|
||
### MVP (Версия 1.0 - статические данные)
|
||
- ✅ REST API для маршрутов и остановок
|
||
- ✅ Геопространственные запросы (PostGIS)
|
||
- ✅ Расчет ETA на основе расписания
|
||
- ✅ Offline-синхронизация для мобильных приложений
|
||
- ✅ Веб-панель администратора
|
||
- ✅ Кеширование через Redis
|
||
- ✅ Аутентификация по API ключам
|
||
- ✅ Rate limiting
|
||
- ✅ Серверные push-уведомления об алертах через Firebase Cloud Messaging
|
||
- ✅ Импорт отмен из Telegram через отдельный аккаунт, проверка в админке и срок действия до полуночи ([настройка](docs/telegram-cancellation-import.md))
|
||
|
||
### Технологический стек
|
||
|
||
**Backend:**
|
||
- Node.js + Express
|
||
- PostgreSQL + PostGIS
|
||
- Redis
|
||
- Docker
|
||
|
||
**Frontend (Admin Panel):**
|
||
- React + Vite
|
||
- Tailwind CSS
|
||
- React Leaflet (карты)
|
||
- Axios
|
||
|
||
## 📋 Требования
|
||
|
||
- Docker и Docker Compose
|
||
- Node.js 22+ (для разработки без Docker и Firebase Admin SDK)
|
||
- Статический IP или динамический DNS
|
||
- ~2GB свободного места на диске
|
||
|
||
## 🛠 Установка и запуск
|
||
|
||
### 1. Клонирование и настройка
|
||
|
||
```bash
|
||
# Создайте .env файл из примера
|
||
cp .env.example .env
|
||
|
||
# Настройте переменные окружения
|
||
nano .env
|
||
```
|
||
|
||
Важные переменные в `.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
|
||
|
||
# Push отключён по умолчанию
|
||
FCM_ENABLED=false
|
||
|
||
# Для пассажирского режима backend проверяет Firebase ID token.
|
||
# Укажите проект из google-services.json мобильного приложения и путь к service account JSON.
|
||
FIREBASE_PROJECT_ID=your-firebase-project-id
|
||
GOOGLE_APPLICATION_CREDENTIALS=/absolute/private/path/firebase-service-account.json
|
||
```
|
||
|
||
Для входа по passkey на публичном адресе укажите в `.env` точный домен панели
|
||
и используйте HTTPS: `WEBAUTHN_RP_ID=admin.example.by` и
|
||
`WEBAUTHN_ORIGIN=https://admin.example.by`. В `WEBAUTHN_ORIGIN` не применяются
|
||
wildcard-маски; при нескольких разрешённых адресах перечислите их через запятую.
|
||
|
||
Генерация безопасного salt:
|
||
```bash
|
||
openssl rand -base64 32
|
||
```
|
||
|
||
### 2. Запуск с Docker (рекомендуется)
|
||
|
||
```bash
|
||
# Сборка и запуск всех сервисов
|
||
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. Проверка работоспособности
|
||
|
||
```bash
|
||
# Проверка 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:**
|
||
```bash
|
||
cd backend
|
||
npm install
|
||
cp ../.env.example .env
|
||
|
||
# Убедитесь, что PostgreSQL и Redis запущены локально
|
||
# Настройте DATABASE_URL и REDIS_URL в .env
|
||
|
||
npm run dev
|
||
```
|
||
|
||
**Frontend:**
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
cp .env.example .env
|
||
|
||
npm run dev
|
||
```
|
||
|
||
## 📱 Использование API
|
||
|
||
### Аутентификация
|
||
|
||
Все запросы требуют API ключ в заголовке:
|
||
```bash
|
||
curl -H "X-API-Key: dev_key_12345678" http://localhost:3000/api/v1/routes
|
||
```
|
||
|
||
### Основные эндпоинты
|
||
|
||
**Маршруты:**
|
||
```bash
|
||
GET /api/v1/routes # Все маршруты
|
||
GET /api/v1/routes/:id # Маршрут с остановками
|
||
POST /api/v1/routes # Создать маршрут
|
||
PUT /api/v1/routes/:id # Обновить маршрут
|
||
DELETE /api/v1/routes/:id # Удалить маршрут
|
||
```
|
||
|
||
**Остановки:**
|
||
```bash
|
||
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 (расчет времени прибытия):**
|
||
```bash
|
||
POST /api/v1/eta/calculate
|
||
{
|
||
"stopId": 1,
|
||
"routeId": 1
|
||
}
|
||
|
||
GET /api/v1/eta/stop/:stopId # ETA для всех маршрутов на остановке
|
||
```
|
||
|
||
**Синхронизация (для offline-режима):**
|
||
```bash
|
||
GET /api/v1/sync # Полная синхронизация
|
||
GET /api/v1/sync?lastSync=2025-11-19T10:00:00Z # Инкрементальная
|
||
GET /api/v1/sync/status # Статус системы
|
||
```
|
||
|
||
**Алерты:**
|
||
```bash
|
||
GET /api/v1/alerts/active # Активные алерты для клиентов
|
||
POST /api/v1/alerts # Создать алерт и, если он активен, отправить FCM
|
||
```
|
||
|
||
Настройка Firebase, контракт сообщения, идемпотентность и способы локальной
|
||
проверки описаны в [документации FCM-уведомлений](docs/fcm-alert-notifications.md).
|
||
|
||
### Примеры запросов
|
||
|
||
**Создание маршрута:**
|
||
```bash
|
||
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": "Основной маршрут через центр города"
|
||
}'
|
||
```
|
||
|
||
**Создание остановки:**
|
||
```bash
|
||
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"
|
||
}'
|
||
```
|
||
|
||
**Поиск ближайших остановок:**
|
||
```bash
|
||
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** (рекомендуется):
|
||
```bash
|
||
# Установка 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:**
|
||
```bash
|
||
# Получение сертификата Let's Encrypt
|
||
sudo certbot --nginx -d api.yourdomain.com -d admin.yourdomain.com
|
||
|
||
# Сертификаты автоматически обновятся
|
||
```
|
||
|
||
3. **Fail2ban:**
|
||
```bash
|
||
sudo apt install fail2ban
|
||
sudo systemctl enable fail2ban
|
||
sudo systemctl start fail2ban
|
||
```
|
||
|
||
4. **Мониторинг:**
|
||
```bash
|
||
# Установка Prometheus + Grafana (опционально)
|
||
# Или простой мониторинг через Docker stats
|
||
docker stats
|
||
```
|
||
|
||
### Создание API ключей
|
||
|
||
API ключи можно создать через базу данных:
|
||
|
||
```sql
|
||
INSERT INTO api_keys (key, app_name, rate_limit)
|
||
VALUES ('your_secure_key_here', 'iOS App', 10000);
|
||
```
|
||
|
||
Или через скрипт:
|
||
```javascript
|
||
const crypto = require('crypto');
|
||
const apiKey = crypto.randomBytes(32).toString('hex');
|
||
console.log(apiKey);
|
||
```
|
||
|
||
## 📊 Админ-панель
|
||
|
||
Откройте http://localhost:3001 в браузере.
|
||
|
||
**Функции:**
|
||
- Управление маршрутами
|
||
- Создание и редактирование остановок на карте
|
||
- Просмотр статистики
|
||
- Управление расписаниями (в разработке)
|
||
|
||
## 🗄 Структура базы данных
|
||
|
||
```sql
|
||
routes # Маршруты
|
||
stops # Остановки (с PostGIS геометрией)
|
||
route_stops # Связь маршрутов и остановок
|
||
schedules # Расписания
|
||
vehicles # Транспортные средства
|
||
historical_delays # Статистика задержек
|
||
alerts # Уведомления
|
||
api_keys # API ключи
|
||
sync_log # Лог изменений для синхронизации
|
||
```
|
||
|
||
## 🔄 Обновления
|
||
|
||
```bash
|
||
# Остановка сервисов
|
||
docker-compose down
|
||
|
||
# Обновление кода
|
||
git pull
|
||
|
||
# Перезапуск
|
||
docker-compose up -d --build
|
||
```
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
**База данных не стартует:**
|
||
```bash
|
||
docker-compose logs postgres
|
||
docker-compose down -v # Удалит volumes, ОСТОРОЖНО!
|
||
docker-compose up -d
|
||
```
|
||
|
||
**API не отвечает:**
|
||
```bash
|
||
docker-compose logs backend
|
||
docker-compose restart backend
|
||
```
|
||
|
||
**Frontend не собирается:**
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
**PostGIS ошибки:**
|
||
```bash
|
||
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-трекеры интеграция
|
||
- [ ] Машинное обучение для предсказания задержек
|
||
- [x] Push-уведомления о новых активных алертах
|
||
- [ ] Аналитика и отчеты
|
||
|
||
## 🤝 Контакты и поддержка
|
||
|
||
Создано для города Полоцка 🇧🇾
|
||
|
||
## 📄 Лицензия
|
||
|
||
MIT License - используйте свободно!
|