naLinii – komunikacja miejska Poznania w czasie rzeczywistym

Aplikacja webowa do podglądu pojazdów, przystanków i odjazdów ZTM Poznań na żywo (GTFS + GTFS‑Realtime), z mapą Leaflet, wsparciem PWA i własną bazą danych taborowych (XLSX). Projekt nie jest obecnie rozwijany, ale repozytorium zawiera pełny fundament do wznowienia prac.

---

Spis treści

• Funkcje
• Technologie
• Szybki start
• Konfiguracja
• Struktura
• Dane: GTFS / GTFS‑RT
• Testy
• Podziękowania

---

Funkcje

• Mapa czasu rzeczywistego (Leaflet) z ikonami pojazdów i stanem ruchu (GTFS‑Realtime).
• Przystanki i rozkłady – szczegóły, planowane odjazdy, brygady.
• Automatyczne pobieranie najnowszych rozkładów i korekt z ZTM (GTFS).
• Tabor – autorski XLSX: klimatyzacja, rampa, model, rok, norma emisji itd.
• PWA – instalacja jako aplikacja, cache statycznych zasobów.
• Wyszukiwarka – przystanki i pojazdy po nazwie, numerze taborowym, marce i modelu.

Uwaga: część funkcji realtime zależy od dostępności źródła GTFS‑RT.

---

Technologie

• Backend: Python, Flask, SQLAlchemy
• Baza: MariaDB (MySQL compatible)
• Frontend: Leaflet, moduły ES (bez bundlera)
• Dane: GTFS (statyczny) + GTFS‑RT (dynamiczny)
• PWA: manifest + własny service worker

---

Szybki start

Wymagania

• Python 3.10+
• MariaDB / MySQL
• pip, venv

Instalacja

# 1) Klon repo
git clone https://github.com/<twoj-user>/naLinii.git
cd naLinii

# 2) Virtualenv
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3) Zależności
pip install -r requirements.txt

# 4) Utwórz bazę danych (MariaDB)
#    CREATE DATABASE naLinii CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 5) Konfiguracja
cp .env.example .env        # uzupełnij DATABASE_URL i ZTM_API_TOKEN

# 6) Tabele i pierwszy rozkład
flask --app wsgi init-db
flask --app wsgi gtfs sync

# 7) Uruchom aplikację (dev)
flask --app wsgi run --host=0.0.0.0 --port=5000 --debug

Aplikacja będzie dostępna pod adresem: http://localhost:5000/.

Produkcyjnie: gunicorn "wsgi:app".

Komendy

Komenda	Opis
flask init-db	tworzy tabele
flask gtfs sync	pobiera i wgrywa rozkład (--force pomija sprawdzanie wersji)
flask gtfs describe-stops	przelicza rodzaj przystanku, kierunek i listę linii
flask realtime	pobiera pozycje pojazdów bez serwera WWW

---

Konfiguracja

Wszystkie ustawienia pochodzą ze zmiennych środowiskowych — wzór w .env.example. Nic wrażliwego nie leży w kodzie.

Zmienna	Domyślnie	Opis
FLASK_ENV	development	development, testing lub production
SECRET_KEY	—	klucz sesji
DATABASE_URL	mysql+pymysql://root:@localhost/naLinii	połączenie do bazy
ZTM_API_TOKEN	—	token do API ZTM Poznań
GTFS_DATA_DIR	data/gtfs	katalog na rozpakowany rozkład
REALTIME_POLL_INTERVAL	3	co ile sekund pobierać pozycje pojazdów
REALTIME_WORKER_ENABLED	true	czy serwer ma uruchamiać wątek GTFS‑RT
LOG_LEVEL	INFO	poziom logowania

---

Struktura

nalinii/
├── web/            widoki HTML i pliki PWA
├── api/            kontrolery JSON pod /api
├── services/       logika aplikacji
├── repositories/   dostęp do bazy
├── domain/         reguły bez bazy i bez Flaska
├── models/         mapowanie ORM
└── gtfs/           pobieranie i import danych ZTM

Szczegóły i przepływ danych: doc/ARCHITECTURE.md.

API

Metoda	Adres	Zwraca
GET	/api/vehicles	pozycje wszystkich pojazdów
GET	/api/vehicles/<id>	dane taborowe pojazdu
GET	/api/trips/<id>/stops	trasa kursu
GET	/api/trips/<id>/shape	geometria trasy
GET	/api/stops	wszystkie słupki
GET	/api/stops/<kod>	pojedynczy słupek
GET	/api/stops/<id>/departures	najbliższe odjazdy
GET	/api/stops/<id>/routes	linie z przystanku
GET	/api/routes	linie w podziale na tramwajowe i autobusowe
GET	/api/routes/<id>	przebieg linii
GET	/api/brigades/<linia>/<brygada>	rozkład brygady
GET	/api/search?q=	wyszukiwarka
POST	/api/reports	zgłoszenie z formularza

---

Dane: GTFS / GTFS‑RT

Rozkład statyczny wgrywa flask gtfs sync — pobiera archiwum, sprawdza czy jest nowsze niż to w bazie i wczytuje je w jednej transakcji. Pozycje pojazdów pobiera wątek uruchamiany razem z aplikacją (albo osobno przez flask realtime).

Baza tworzona jest przez flask init-db. Przy zmianie schematu warto sięgnąć po Flask‑Migrate (Alembic) zamiast create_all().

---

Testy

pip install -r requirements-dev.txt
pytest

Testy działają na SQLite w pamięci i nie odpytują API ZTM.

---

Podziękowania

• Dane: ZTM Poznań – GTFS + GTFS‑RT

---