# Структура проекта Polotsk Transit API

## 📁 Обзор директорий

```
polotsk-transit-api/
├── backend/                      # Node.js API сервер
│   ├── src/
│   │   ├── config/              # Конфигурация (DB, Redis, Logger)
│   │   ├── controllers/         # Бизнес-логика
│   │   │   ├── routesController.js       # Управление маршрутами
│   │   │   ├── stopsController.js        # Управление остановками + PostGIS
│   │   │   ├── etaController.js          # Расчет ETA
│   │   │   └── syncController.js         # Offline синхронизация
│   │   ├── middleware/          # Middleware (Auth, Rate Limiting)
│   │   ├── routes/              # Express маршруты
│   │   └── index.js             # Точка входа
│   ├── migrations/              # SQL миграции (PostGIS схема)
│   ├── package.json
│   └── Dockerfile
│
├── frontend/                     # React админ-панель
│   ├── src/
│   │   ├── components/          # React компоненты
│   │   │   ├── RouteForm.jsx            # Форма маршрута
│   │   │   └── StopForm.jsx             # Форма остановки
│   │   ├── pages/               # Страницы
│   │   │   ├── Dashboard.jsx            # Главная страница
│   │   │   ├── RoutesPage.jsx           # Управление маршрутами
│   │   │   ├── StopsPage.jsx            # Остановки + карта Leaflet
│   │   │   └── SchedulesPage.jsx        # Расписания (заглушка)
│   │   ├── services/            # API клиент
│   │   ├── App.jsx              # Главный компонент + роутинг
│   │   ├── main.jsx             # Точка входа
│   │   └── index.css            # Tailwind стили
│   ├── package.json
│   ├── vite.config.js
│   └── Dockerfile
│
├── nginx/                        # Reverse proxy конфигурация
│   └── nginx.conf               # Nginx для API + Admin + SSL
│
├── docker-compose.yml           # Оркестрация всех сервисов
├── .env.example                 # Шаблон переменных окружения
├── .gitignore
├── README.md                    # Полная документация
└── QUICKSTART.md               # Быстрый старт

```

## 🎯 Ключевые файлы

### Backend

**Конфигурация:**
- `backend/src/config/database.js` - PostgreSQL connection pool
- `backend/src/config/redis.js` - Redis клиент для кеширования
- `backend/src/config/logger.js` - Winston logger

**Контроллеры:**
- `backend/src/controllers/routesController.js` - CRUD маршрутов + кеширование
- `backend/src/controllers/stopsController.js` - CRUD остановок + PostGIS геопоиск
- `backend/src/controllers/etaController.js` - Умный расчет времени прибытия
- `backend/src/controllers/syncController.js` - Полная и инкрементальная синхронизация

**Middleware:**
- `backend/src/middleware/auth.js` - API key аутентификация
- `backend/src/middleware/rateLimiter.js` - Rate limiting с Redis

**Миграции:**
- `backend/migrations/001_init.sql` - Полная схема БД с PostGIS

### Frontend

**Страницы:**
- `frontend/src/pages/Dashboard.jsx` - Статистика и быстрый старт
- `frontend/src/pages/RoutesPage.jsx` - Управление маршрутами с карточками
- `frontend/src/pages/StopsPage.jsx` - Карта Leaflet + список остановок
- `frontend/src/pages/SchedulesPage.jsx` - Заглушка для будущего функционала

**Компоненты:**
- `frontend/src/components/RouteForm.jsx` - Форма создания/редактирования маршрута
- `frontend/src/components/StopForm.jsx` - Форма создания/редактирования остановки

**API сервис:**
- `frontend/src/services/api.js` - Axios клиент со всеми endpoints

### Инфраструктура

**Docker:**
- `docker-compose.yml` - 5 сервисов (PostgreSQL, Redis, Backend, Frontend, Nginx)
- `backend/Dockerfile` - Node.js production образ
- `frontend/Dockerfile` - Multi-stage build с Nginx

**Nginx:**
- `nginx/nginx.conf` - Reverse proxy с SSL, rate limiting, безопасностью

## 🔧 Основные технологии

| Компонент | Технология | Назначение |
|-----------|------------|------------|
| API Server | Express.js | REST API |
| База данных | PostgreSQL + PostGIS | Хранение данных + геопространственные запросы |
| Кеш | Redis | Кеширование + pub/sub для WebSocket |
| Frontend | React + Vite | Админ-панель |
| Карты | React Leaflet | Интерактивная карта |
| Стили | Tailwind CSS | Быстрая разработка UI |
| Контейнеризация | Docker Compose | Оркестрация сервисов |
| Reverse Proxy | Nginx | SSL, rate limiting, безопасность |

## 📊 Схема базы данных (кратко)

```sql
routes          -- Маршруты (номер, название, тип, цвет)
stops           -- Остановки (название, GEOGRAPHY(Point), адрес)
route_stops     -- М:М связь маршрутов и остановок (с sequence и time_offset)
schedules       -- Расписания (departure_times[], day_type)
vehicles        -- Транспортные средства
historical_delays -- Статистика задержек для умного ETA
alerts          -- Уведомления и алерты
api_keys        -- API ключи для аутентификации
sync_log        -- Лог изменений для offline синхронизации
```

## 🚀 Что уже работает

✅ Полный REST API
✅ CRUD для маршрутов и остановок
✅ PostGIS геопространственные запросы (ближайшие остановки)
✅ Расчет ETA на основе расписания + исторических задержек
✅ Offline синхронизация (полная и инкрементальная)
✅ Веб админ-панель с картой
✅ Docker deployment
✅ API key аутентификация
✅ Rate limiting
✅ Кеширование через Redis
✅ Логирование

## 📝 Что добавить в будущем

**Версия 2.0 (Краудсорсинг):**
- [ ] WebSocket для реалтайм GPS
- [ ] Endpoint для приема GPS от пользователей
- [ ] Агрегация и фильтрация GPS данных
- [ ] Функция "Я еду в маршруте"

**Версия 3.0 (Продвинутые функции):**
- [ ] IoT GPS-трекеры
- [ ] ML для предсказания задержек
- [ ] Push уведомления
- [ ] Детальная аналитика

## 💡 Советы по развертыванию

1. **Обязательно смените пароли** в `.env` перед продакшеном
2. **Используйте Cloudflare Tunnel** для скрытия домашнего IP
3. **Настройте SSL** через Let's Encrypt или Cloudflare
4. **Включите fail2ban** для защиты от брутфорса
5. **Настройте бэкапы** PostgreSQL (pg_dump + cron)
6. **Мониторинг** через Docker stats или Prometheus

## 🎓 Интеграция с мобильными приложениями

Используйте эндпоинт `/api/v1/sync` для offline-first подхода:

1. При первом запуске - полная синхронизация (без `lastSync`)
2. При последующих - инкрементальная (с `lastSync=timestamp`)
3. Храните данные локально (SQLite, Realm, Core Data)
4. Обновляйте в фоне каждые 5-10 минут

Пример для iOS:
```swift
func syncData() async {
    let lastSync = UserDefaults.standard.object(forKey: "lastSync") as? Date
    let params = lastSync != nil ? ["lastSync": ISO8601DateFormatter().string(from: lastSync!)] : [:]
    
    let data = try await api.get("/sync", params: params)
    await database.updateLocalData(data)
    
    UserDefaults.standard.set(Date(), forKey: "lastSync")
}
```

---

**Создано для Полоцка 🇧🇾 | MIT License**