Content
Nasza aplikacja udostępnia MCP po HTTP, dlatego skorzystaliśmy z MCP Inspector.
Po włączeniu aplikacji należy w terminalu, w folderze projektu, wykonać:
```npx -y @modelcontextprotocol/inspector```
owtorzy się w przeglądarce mcp inspector.
Należy uzupełnić:
- Transportation type: Streamabale http
- URL: http://localhost:8080/mcp
i kliknąć "Connect".
Następnie należy w Tools wybrać "List tools"
Aplikacja Spring Boot integrująca dane **GTFS Realtime** (położenie pojazdów) oraz **GTFS Static** (rozkłady jazdy) komunikacji miejskiej w Krakowie. Udostępnia API REST do pobierania losowych odjazdów oraz wyszukiwania najszybszych połączeń bezpośrednich.
---
## Co robi aplikacja
Aplikacja realizuje dwa główne zadania:
### 1. Obsługa Danych Realtime (Kamień Milowy 1)
- Pobiera plik **`TripUpdates.pb`** (Protobuf) z API ZTP Kraków.
- Parsuje dane binarne do obiektów Java.
- Wykorzystuje mechanizm **Cache** (`@Cacheable`, `@CachePut`) dla wydajności i odciążenia serwera ZTP.
- Wystawia endpoint zwracający losowy, aktualny odjazd tramwaju/autobusu.
### 2. Wyszukiwarka Połączeń i Baza Danych (Kamień Milowy 2)
- Pobiera i przetwarza plik **`GTFS_KRK.zip`** (dane statyczne: przystanki, trasy, kalendarz, czasy przejazdów).
- Importuje dane do lokalnej bazy **SQLite** przy starcie aplikacji (zabezpieczenie przed duplikacją danych).
- Posiada wyszukiwarkę najszybszych **połączeń bezpośrednich** między dwoma przystankami.
- Uwzględnia:
- **Kalendarz kursowania** (dni tygodnia + wyjątki z `calendar_dates.txt`).
- **Opóźnienia rzeczywiste** (Realtime Delay) pobierane na żywo z modułu Realtime.
---
## Architektura Aplikacji
```mermaid
graph LR
%% Aktorzy i Systemy Zewnętrzne
Client((Użytkownik))
AI_Client((Klient AI / MCP))
ZTP_Real[("ZTP API<br/>(Realtime PB)")]
ZTP_Static[("ZTP API<br/>(Static ZIP)")]
DB[("Baza SQLite<br/>(trams.db)")]
%% Aplikacja
subgraph "Aplikacja: trams_web"
style Client fill:#1e88e5,color:white
style AI_Client fill:#9c27b0,color:white
style ZTP_Real fill:#546e7a,color:white
style ZTP_Static fill:#546e7a,color:white
style DB fill:#546e7a,color:white
%% 1. Warstwa Prezentacji
subgraph "Warstwa Prezentacji"
DepController["DepartureController<br/>(/departure)"]
ConnController["DirectConnectionController<br/>(/connections)"]
McpTools["TramsMcpTools<br/>(MCP Server)"]
end
%% 2. Warstwa Biznesowa
subgraph "Warstwa Biznesowa"
RealService["GtfsRealtimeService"]
ConnService["DirectConnectionService"]
NextService["NextDepartureService"]
CalendarService["GtfsCalendarService"]
StopService["StopQueryService"]
subgraph "Logika wyboru"
PickerInt("«interface»<br/>DeparturePicker")
PickerImpl["RandomDeparturePicker"]
end
end
%% 3. Warstwa Dostępu do Danych
subgraph "Warstwa Danych"
GtfsClient["GtfsClient<br/>(Cache Realtime)"]
StaticLoader["GtfsStaticLoader"]
ImportService["GtfsStaticImportService"]
Repositories["JPA Repositories"]
end
%% Relacje
Client --> ConnController
ConnController --> ConnService
Client --> DepController
DepController --> RealService
AI_Client --> McpTools
McpTools --> ConnService
McpTools --> NextService
McpTools --> RealService
McpTools --> StopService
ConnService --> Repositories
ConnService --> CalendarService
ConnService --> RealService
NextService --> Repositories
NextService --> CalendarService
NextService --> RealService
StopService --> Repositories
RealService --> GtfsClient
RealService --> PickerInt
PickerInt -.-> PickerImpl
Repositories -.-> DB
GtfsClient -.-> ZTP_Real
StaticLoader -.-> ZTP_Static
StaticLoader --> ImportService
ImportService --> Repositories
end
%% Style
classDef spring fill:#4f8014,stroke:#333,stroke-width:1px;
class DepController,ConnController,McpTools,RealService,ConnService,NextService,CalendarService,GtfsClient,StaticLoader,ImportService,Repositories,PickerInt,PickerImpl,StopService spring;
```
---
## Kluczowe komponenty
## Moduł Realtime (Losowy odjazd)
- **Controller**: `DepartureController` – obsługa HTTP (`GET /departure`) i delegowanie do serwisu.
- **Service**: `GtfsRealtimeService` – pobiera feed z `GtfsClient` i wybiera odjazd przez `DeparturePicker`.
- **Client**: `GtfsClient` – pobieranie `TripUpdates.pb`, parsowanie protobuf, cache (`@Cacheable`) i odświeżanie (`@Scheduled` + `@CachePut`).
- **Strategy**: `DeparturePicker` (interfejs) oraz `RandomDeparturePicker` (implementacja losowania odjazdu).
- **Domain**: `Departure` – rekord domenowy zwracany przez API.
- **Exceptions**:
- `DepartureNotFoundException` → HTTP 404
- `GtfsConnectionException` → HTTP 500
## Moduł Static & Connections (Wyszukiwarka)
- **Controller**: `DirectConnectionController` – obsługa HTTP (`GET /connections`).
- **Service**: `DirectConnectionService` – łączy dane statyczne (rozkład), sprawdza kalendarz (GtfsCalendarService) i dodaje opóźnienia (Realtime).
- **Loader**: `GtfsStaticLoader` – pobiera plik ZIP przy starcie aplikacji.
- **Repository**: `StopTimeRepository` – wykonuje natywne zapytanie SQL (Self-Join) szukające połączeń.
---
## API Endpoints
## 1. Losowy Odjazd
### `GET /departure`
Zwraca losowy odjazd jako obiekt `Departure`.
**200 OK** (gdy znaleziono odjazd):
```json
{
"routeId": "52",
"tripId": "123456",
"stopId": "1234",
"departureTime": "2025-12-15T10:30:00Z"
}
```
**404 NOT FOUND**
Gdy w danych GTFS nie ma żadnych odjazdów spełniających warunek (brak `departure.time`).
Rzucany jest `DepartureNotFoundException`.
**500 INTERNAL SERVER ERROR**
Gdy nie udało się pobrać lub sparsować feedu (np. problem sieciowy, niepoprawne dane).
Rzucany jest `GtfsConnectionException`.
## 2. Wyszukiwarka Połączeń (Najszybsze)
Zwraca najszybsze bezpośrednie połączenie między dwoma przystankami.
Parametry:
- **from**: Nazwa przystanku początkowego (np. "Teatr Bagatela")
- **to**: Nazwa przystanku końcowego (np. "Bronowice")
**200 OK** (gdy znaleziono połączenie):
```json
{
"lineNumber": "173",
"fromStopName": "Muzeum Narodowe",
"toStopName": "Przybyszewskiego",
"departureTime": "2026-01-07T14:35:00",
"arrivalTime": "2026-01-07T14:42:00",
"delaySeconds": 120
}
```
**400 BAD REQUEST**
Gdy podano nieistniejącą nazwę przystanku. Rzucany jest `InvalidStopException`.
**404 NOT FOUND**
Gdy nie znaleziono żadnego bezpośredniego połączenia. Rzucany jest `ConnectionNotFoundException`.
**500 INTERNAL SERVER ERROR**
Błąd serwera.
