@golemio/pid 3.13.1 → 3.13.2-dev.1803100353

package/docs/cache/types/psql.md

@@ -0,0 +1,76 @@
+# PostgreSQL cache
+
+- V současnosti cachujeme pouze kontext k danému RT spoji - tedy stav vozidla/spoje po poslední zpracované zprávě
+- Nemusíme tedy dotahovat předchozí pozice z DB, ale veškeré informace máme ve sloupci `last_position_context` v tabulce `vehicle_positions_trips`
+- Uložen jako JSON objekt s variabilními daty a atributy - v závislosti na stavu vozidla/spoje některé atributy chybí nebo jsou prázdné/null
+- Pokud se jedná o první pozici na spoji, pak všechny atributy kromě `tripId` budou null a nepovinné atributy můžou chybět
+- Aktuální interface viz [IVPTripsLastPositionContext](../../../src/schema-definitions/vehicle-positions/models/interfaces/VPTripsLastPositionInterfaces.ts)
+
+```typescript
+interface IVPTripsLastPositionContext {
+    lastPositionId: string | null;
+    lastPositionLat?: number | null;
+    lastPositionLng?: number | null;
+    lastPositionOriginTimestamp: number | null;
+    lastPositionTracking: Feature<Point, IVPTripsPositionAttributes> | null;
+    lastPositionCanceled: boolean | null;
+    lastPositionLastStop: {
+        id: string | null;
+        sequence: number | null;
+        arrival_time: number | null;
+        arrival_delay: number | null;
+        departure_time: number | null;
+        departure_delay: number | null;
+    };
+    lastPositionDelay: number | null;
+    atStopStreak: IVPTripsComputedPositionAtStopStreak;
+    lastPositionBeforeTrackDelayed: {
+        delay: number | null;
+        origin_timestamp: Date;
+    } | null;
+    lastPositionState: StatePositionEnum | null;
+    lastStopSequence?: number | null;
+    lastPositionStateChange: string | null;
+    tripId: string;
+}
+```
+
+- **lastPositionId** - ID poslední pozice, koresponduje ID záznamu v tabulce `vehiclepositions_positions`
+    - _poznámka_: využití během aktualizace tripu v databázi (lze nahradit přímo pozicí). Rovněž se využívá během propagace zpoždění
+- **lastPositionLat** - poslední známá zeměpisná šířka vozidla
+    - _poznámka_: nepoužívá se a může být null, pokud je spoj zrušen a nepodařilo se zjistit poslední známou polohu
+- **lastPositionLng** - poslední známá zeměpisná délka vozidla
+    - _poznámka_: nepoužívá se a může být null, pokud je spoj zrušen a nepodařilo se zjistit poslední známou polohu
+- **lastPositionOriginTimestamp** - `origin_timestamp` poslední pozice (timestamp odeslání zprávy z vozidla)
+    - _poznámka_: využití během propagace zpoždění a určení duplikovaných zpráv. :warning: unix timestamp v milisekundách
+- **lastPositionTracking** - pokud je poslední pozice tracked, pak je zde uložena jako GeoJSON objekt, jinak null
+    - _poznámka_: využití během určení stavu vozidla jedoucího z/do garáže, projetí poslední zastávky a ujeté trasy `shape_dist_traveled` a azimutu u propagované pozice
+- **lastPositionCanceled** - indikátor, zda byl spoj předchozí zprávou deklarován jako zrušený
+    - _poznámka_: využití během aktualizace tripu v databázi. Zbytečné a lze nahradit stavem pozice
+- **lastPositionLastStop** - informace o poslední zastávce, kterou vozidlo projelo
+    - _poznámka_: využití pouze pro výpočet zpoždění na zastávce
+    - **id** - GTFS ID zastávky. V současnosti je vždy null a nepoužívá se
+    - **sequence** - pořadí zastávky v rámci GTFS stop times
+    - **arrival_time** - čas příjezdu na zastávku podle GTFS
+    - **arrival_delay** - vypočítané zpoždění příjezdu na zastávku oproti GTFS v sekundách
+    - **departure_time** - čas odjezdu ze zastávky podle GTFS
+    - **departure_delay** - vypočítané zpoždění odjezdu ze zastávky oproti GTFS v sekundách
+- **lastPositionDelay** - poslední vypočítané zpoždění vozidla na spoji
+    - _poznámka_: využití pouze pro výpočet zpoždění na zastávce
+- **atStopStreak** - informace o délce pobytu vozidla na zastávce
+    - _poznámka_: využití pro přesnější určení zpoždění vozidla během pobytu na zastávce a taky pro výpočet zpoždění během příjezdu a odjezdu na zastávku
+    - **firstPositionTimestamp** - timestamp první pozice na zastávce
+    - **firstPositionDelay** - zpoždění v sekundách během první pozice na zastávce. Liší se od zpoždění během příjezdu na zastávku, které se počítá jinak
+    - **stop_sequence** - pořadí zastávky v rámci GTFS stop times
+- **lastPositionBeforeTrackDelayed** - dodatečné informace o poslední pozici
+    - _poznámka_: vyplněno pouze v případě, že poslední pozice spoje byla zpropagována z předchozího spoje na oběhu, jinak null. Využití pro určení zpozdění vozidla a taky pro určení stavu vozidla jedoucího z/do garáže
+    - **delay** - zpoždění poslední pozice oproti GTFS v sekundách
+    - **origin_timestamp** - timestamp poslední pozice (timestamp odeslání zprávy z vozidla)
+- **lastPositionState** - stav vozidla během poslední pozice
+    - _poznámka_: využití pro určení stavu a správné určení segmentu trasy (mezi jakými zastávkami se vozidlo nachází, díky tomu přesnější zpoždění vozidla)
+- **lastStopSequence** - pořadí poslední projeté zastávky v rámci GTFS stop times
+    - _poznámka_: využití během určení, zda se vozidlo navrátilo na trase zpět
+- **lastPositionStateChange** - timestamp poslední změny stavu vozidla
+    - _poznámka_: využití pro určení stavu vozidla a zda se má vůbec vypočítat zpoždění
+- **tripId** - RT ID spoje, ke kterému se kontext vztahuje. Koresponduje ID záznamu v tabulce `vehiclepositions_trips`
+    - _poznámka_: využití během aktualizace tripu v databázi. Zbytečné, šlo by udělat lépe

package/docs/cache/types/redis.md

@@ -0,0 +1,314 @@
+# Redis cache
+
+## Cache pro načítání GTFS jízdních řádů
+
+### files:gtfsStatic:*
+
+- Klíč `files:gtfsStatic:*`, kde `*` je název souboru, popř. cesta k souboru v případě ZIP archivu
+- Hodnota CSV/JSON jako string
+- TTL žádné
+- Retence dat až do úspěšného načtení GTFS jíždních řádů
+- Cache obsahuje všechny načtené soubory z ROPID FTP (viz [implementační dokumentace](../../implementation_documentation.md#files-gtfs-static#ropid-ftp-obecně))
+- Menší soubory jsou ukládány pomocí `SET`, větší jsou streamovány pomocí knihovny [redis-wstream](https://github.com/jeffbski/redis-wstream) (`SET` + `APPEND`)
+- Menší soubory jsou následně načteny pomocí `GET`, větší jsou streamovány z Redisu do PSQL pomocí knihovny [redis-rstream](https://github.com/jeffbski/redis-rstream) (`GETRANGE`)
+
+### Flowchart
+
+```mermaid
+flowchart TD;
+    redis_1[("Redis files:gtfsStatic:*")];
+    redis_2[("Redis files:gtfsStatic:*")];
+    redis_3[("Redis files:gtfsStatic:*")];
+
+    psql[("PSQL ropidgtfs_*_tmp")];
+    amqp_transformAndSaveData[AMQP transformAndSaveData];
+
+    initial["Zpráva z cronu, stažení z ROPID FTP"];
+    initial--SET malý soubor-->redis_1;
+    initial--Wstream velký soubor-->redis_1;
+    initial-->amqp_transformAndSaveData;
+
+    amqp_transformAndSaveData--GET malý soubor<-->redis_2;
+    amqp_transformAndSaveData--Rstream velký soubor<-->redis_2;
+    amqp_transformAndSaveData--INSERT malý soubor-->psql;
+    amqp_transformAndSaveData--COPY stream velký soubor-->psql;
+
+    continue[Pokračování v načítání JŘ];
+    amqp_transformAndSaveData-->continue;
+
+    cache_manager["DataCacheManager"];
+    continue-->cache_manager;
+    cache_manager--Truncate-->redis_3;
+
+```
+
+## Cache pro GTFS-RT feedy
+
+### files:gtfsRt
+
+- Klíč `files:gtfsRt`, pomocný `files:gtfsRt_*_timestamp`, kde `*` je název feedu bez přípony
+- Hodnota je hash mapa, kde klíč je název feedu s příponou `.pb`
+  - `trip_updates.pb`
+  - `vehicle_positions.pb`
+  - `pid_feed.pb`
+  - `alerts.pb`
+- Hodnota v hash mapě je binární blob reprezentující specifický GTFS-RT feed
+- Hodnota v pomocném klíči je unix timestamp poslední aktualizace daného feed v milisekundách
+- TTL žádné
+- Retence dat aktivní, vždy uchováváme nejnovější feedy
+- Všechny feedy jsou ukládány pomocí `HSET`, pomocné timestampy pomocí `SET`
+- Feedy jsou nabízený přes API `/v2/vehiclepositions/gtfsrt/{feed}`, kde `{feed}` je název feedu s příponou `.pb`
+  -  Žádaný feed se načte pomocí `HGET` a vrátí se jako binární blob. Pokud feed neexistuje, vrátí se 404
+  -  Pomocný timestamp se načte pomocí `GET` a vrátí se jako hodnota hlavičky `Last-Modified` převedená na ISO string. Pokud timestamp neexistuje, hodnota hlavičky bude unix timestamp 0 jako ISO string. Využívá se především pro monitoring a alerting
+- Feedy se generují 3x za minutu (rabín 2x)
+
+### Flowchart
+
+```mermaid
+flowchart TD;
+    redis_f_1[("Redis files:gtfsRt")];
+    redis_t_1[("Redis files:gtfsRt_*_timestamp")];
+    psql[("PSQL vehiclepositions_*, ropidvymi_*")];
+
+    connector[("OG Redis connector")];
+    repository["IE GtfsRtRedisRepository"];
+
+    get_gtfsrt["GET /v2/vehiclepositions/gtfsrt/$feed"];
+
+    initial["Zpráva z cronu, vygenerování feedů"];
+    initial--Select<-->psql;
+    initial-->repository;
+    repository--HSET *.pb-->redis_f_1;
+    repository--SET *_timestamp-->redis_t_1;
+
+    get_gtfsrt-->connector;
+    connector--HGET *.pb<-->redis_f_1;
+    connector--GET *_timestamp<-->redis_t_1;
+```
+
+## Cache pro zpracování RT dat
+
+### gtfsRunSchedule:*
+
+- TODO doplnit
+
+### gtfsBlockSchedule:*
+
+- TODO doplnit
+
+### gtfsDelayComputation:*
+
+- TODO doplnit
+
+### Flowchart
+
+```mermaid
+flowchart TD;
+    todo["TODO"];
+```
+
+## Cache pro předzpracování a párování dat z Telmaxu (Arriva City)
+
+### vpRegionalBusCisLookup:*
+
+- TODO doplnit
+
+### vpRegionalBusGtfsLookup:*
+
+- TODO doplnit
+
+### Flowchart
+
+```mermaid
+flowchart TD;
+    todo["TODO"];
+```
+
+## Cache pro public API
+
+### vpPublicCache:*
+
+- Hlavní komponentou je sorted set `vpPublicCache:$setId`, kde `$setId` je ID vygenerované datové sady (4 náhodné bajty reprentované hexadecimálně)
+- Score je GPS souřadnice (`GEOADD`), member je ID vozidla. Sorted set se používá jako základ pro public VP (`GEOSEARCH`)
+- ID nejnovější datové sady se propaguje přes PubSub channel `vpPublicCache`
+- Další komponenty:
+  - `vpPublicCache:$setId:trip-$gtfsTripId` - list ID vozidel asociovaných s daným GTFS trip id (možnost více vozidel na jednom spoji)
+  - `vpPublicCache:$setId:vehicle-$vehicleId` - JSON jako string s informacemi o vozidle a spoji, které vykonává
+  - `vpPublicCache:$setId:future-trip-$gtfsTripId` - list ID vozidel asociovaných s daným GTFS trip id (možnost více vozidel na jednom spoji). Vozidlo je před trasou a vykonává předchozí spoj na oběhu (nemá se zobrazit na mapě). Využití v public odjezdech
+  - `vpPublicCache:$setId:future-vehicle-$vehicleId-$gtfsTripId` - JSON jako string s informacemi o vozidle. Vozidlo je před trasou a vykonává předchozí spoj na oběhu (nemá se zobrazit na mapě). Využití v public odjezdech a public VP detailu s GTFS lookupem
+  - `vpPublicCache:$setId:canceled-trips-$gtfsTripId` - JSON jako string s informacemi o zrušeném spoji. Využití v public odjezdech
+- TTL 1 minuta
+- Nová datová sada se generuje přibližně jednou za 3 vteřiny a obsahuje všechny RT spoje (aktivní, budoucí a zrušené)
+
+### vpPublicStopTimeCache:*
+
+- Klíč `vpPublicStopTimeCache:*`, kde `*` je kombinace ID vozidla a GTFS id spoje (možnost více vozidel na jednom spoji)
+- Hodnota je JSON jako string s informacemi o zastávkách a jejich časech
+  - `sequence` - pořadí zastávky podle GTFS stop times
+  - `arr_delay` - čas příjezdu na zastávku - reálný čas u projetých zastávek, predikce u budoucích
+  - `dep_delay` - čas odjezdu ze zastávky - reálný čas u projetých zastávek, predikce u budoucích
+  - `cis_stop_platform_code` - nástupiště/kolej podle CIS u vlakových zastávek, jinde null
+  - `platform_code` - označení zastávky podle GTFS
+  - `stop_id` - GTFS id zastávky
+- TTL 1 hodina a 5 minut
+- Automatické promazání dat po úspěšném načtení GTFS jíždních řádů
+- Cca jednou za 5 vteřin se přenačtou stop times pro všechny aktivní spoje. Generování může běžet pouze jednou, po dokončení tasku se spustí znovu (max čekání 4.8 vteřin)
+
+### gtfsPublicDepartureCache:*
+
+- Klíč `gtfsPublicDepartureCache:*`, kde `*` je GTFS id zastávky
+- Hodnota je sorted set, kde score je unix timestamp odjezdu v sekundách a member jsou relevantní informace o odjezdu
+- Existuje záznam pro každou zastávku v GTFS. Pokud v ní ale není žádný odjezd, je vyplněný pouze jeden prázdný member - detekce validní zastávky bez odjezdu
+- TTL 7 hodin
+- Retence dat aktivní, jednou za hodinu se smažou všechny odjezdy starší než 3 hodiny
+- Jednou za hodinu se vygenerují nové odjezdy pro všechny zastávky v intervalu +5 hodin až +7 hodin, po přenačtení JŘ se přegenerují všechny odjezdy v interval -3 hodiny až +7 hodin
+- Ukládá se pomocí `ZADD`, čte se pomocí `ZRANGEBYSCORE` (-inf, now + `minutesAfter`)
+- Využití v public odjezdech
+
+### Flowchart (refresh)
+
+```mermaid
+flowchart LR;
+    finish_up_gtfs["Dokončení zpracování GTFS JŘ"];
+
+    psql_rt[("PSQL vehiclepositions_*")];
+    psql_stop_times[("PSQL v_public_vehiclepositions_combined_stop_times")];
+    psql_departures[("PSQL ropidgtfs_departures")];
+
+    redis_pubsub_channel["Redis channel vpPublicCache"];
+    redis_public_cache[("Redis vpPublicCache:*")];
+    redis_stop_times[("Redis vpPublicStopTimeCache:*")];
+    redis_departures[("Redis gtfsPublicDepartureCache:*")];
+
+    amqp_refreshPublicTripCache[AMQP refreshPublicTripCache];
+    %% amqp_refreshPublicTripCache--"Čekání max 2.4 vteřin od spuštění tasku"-->amqp_refreshPublicTripCache;
+    amqp_refreshPublicStopTimeCache[AMQP refreshPublicStopTimeCache];
+    %% amqp_refreshPublicStopTimeCache--"Čekání max 4.8 vteřin od spuštění tasku"-->amqp_refreshPublicStopTimeCache;
+    amqp_refreshPublicGtfsDepartureCache[AMQP refreshPublicGtfsDepartureCache];
+
+    cron_public_cache["Cron public VP 1x za minutu (backup)"];
+    cron_public_cache-->amqp_refreshPublicTripCache;
+
+    cron_stop_times["Cron zastávky spojů 1x za minutu (backup)"];
+    cron_stop_times-->amqp_refreshPublicStopTimeCache;
+
+    cron_departures["Cron odjezdy 1x za hodinu"];
+    cron_departures--"{fromHours: 5, toHours: 7}"-->amqp_refreshPublicGtfsDepartureCache;
+
+    finish_up_gtfs--"Truncate"-->redis_stop_times;
+    finish_up_gtfs--"{fromHours: -3, toHours: 7}"-->amqp_refreshPublicGtfsDepartureCache;
+
+    amqp_refreshPublicTripCache--"Aktivní spoje a jejich polohy"<-->psql_rt;
+    amqp_refreshPublicTripCache--"GEOADD + RPUSH + SET"-->redis_public_cache;
+    amqp_refreshPublicTripCache--"ID/název nové datové sady"-->redis_pubsub_channel;
+
+    amqp_refreshPublicStopTimeCache--"Zastávky u všech aktivních spojů"<-->psql_stop_times;
+    amqp_refreshPublicStopTimeCache--"MSET"-->redis_stop_times;
+
+    amqp_refreshPublicGtfsDepartureCache--"Odjezdy v intervalu"<-->psql_departures;
+    amqp_refreshPublicGtfsDepartureCache--"ZREMRANGEBYSCORE + ZADD"-->redis_departures;
+```
+
+### Flowchart (public API VP)
+```mermaid
+flowchart TD;
+    redis_pubsub_channel["Redis channel vpPublicCache"];
+    redis_subscriber["VPSubscriber"];
+    redis_public_cache[("Redis vpPublicCache:* (RT info)")];
+    redis_public_cache_misc[("Redis vpPublicCache:* (aktivní, budoucí a zrušené spoje)")];
+    redis_repository["OG PublicVehiclePositionsRepository"];
+
+    redis_repository<-->redis_public_cache_misc;
+    redis_repository<-->redis_public_cache;
+
+    redis_subscriber--"Přihlášení k odběru"-->redis_pubsub_channel;
+    redis_pubsub_channel--"ID/název nové datové sady"-->redis_subscriber--"setCurrentSetName"-->redis_repository;
+
+    get_vp["GET /v2/public/vehiclepositions"];
+    get_vp--"GEOSEARCH + vehicle_id lookup pouze aktivních spojů"-->redis_repository;
+```
+
+### Flowchart (public API VP detail)
+```mermaid
+flowchart TD;
+    redis_pubsub_channel["Redis channel vpPublicCache"];
+    redis_subscriber["VPSubscriber"];
+    redis_public_cache[("Redis vpPublicCache:* (RT info)")];
+    redis_public_cache_misc[("Redis vpPublicCache:* (aktivní, budoucí a zrušené spoje)")];
+    redis_stop_times[("Redis vpPublicStopTimeCache:*")];
+    redis_delay_computation[("Redis gtfsDelayComputation:* (pouze shapes)")];
+    redis_repository["OG PublicVehiclePositionsRepository"];
+    redis_repository<-->redis_public_cache_misc;
+    redis_repository<-->redis_public_cache;
+
+    redis_subscriber--"Přihlášení k odběru"-->redis_pubsub_channel;
+    redis_pubsub_channel--"ID/název nové datové sady"-->redis_subscriber--"setCurrentSetName"-->redis_repository;
+
+    get_vp_detail["GET /v2/public/vehiclepositions/$vehicle_id"];
+
+    get_vp_detail--"Lookup aktivního GTFS spoje"-->redis_repository;
+    get_vp_detail--"scope[]=stop_times"<-->redis_stop_times;
+    get_vp_detail--"scope[]=shapes"<-->redis_delay_computation;
+```
+
+### Flowchart (public API VP detail with GTFS)
+```mermaid
+flowchart TD;
+    redis_pubsub_channel["Redis channel vpPublicCache"];
+    redis_subscriber["VPSubscriber"];
+    redis_public_cache[("Redis vpPublicCache:* (RT info)")];
+    redis_public_cache_misc[("Redis vpPublicCache:* (aktivní, budoucí a zrušené spoje)")];
+    redis_stop_times[("Redis vpPublicStopTimeCache:*")];
+    redis_delay_computation[("Redis gtfsDelayComputation:* (pouze shapes)")];
+    redis_repository["OG PublicVehiclePositionsRepository"];
+
+    redis_repository<-->redis_public_cache_misc;
+    redis_repository<-->redis_public_cache;
+
+    redis_subscriber--"Přihlášení k odběru"-->redis_pubsub_channel;
+    redis_pubsub_channel--"ID/název nové datové sady"-->redis_subscriber--"setCurrentSetName"-->redis_repository;
+
+    get_vp_detail_with_gtfs["GET /v2/public/vehiclepositions/$vehicle_id;gtfsTripId=$gtfsTripId"];
+
+    get_vp_detail_with_gtfs--"Lookup aktivního nebo budoucího GTFS spoje (exact match)"-->redis_repository;
+    get_vp_detail_with_gtfs--"scope[]=stop_times"<-->redis_stop_times;
+    get_vp_detail_with_gtfs--"scope[]=shapes"<-->redis_delay_computation;
+```
+
+### Flowchart (public API GTFS static lookup)
+
+:warning: GTFS static lookup neřeší RT informace a jako jediný EP je napojený přímo na PSQL. Kvůli předpokládáně nižšímu využití (detail odjezdů v budoucnosti) to tolik nevadí
+
+```mermaid
+flowchart TD;
+    psql_trip[("PSQL ropidgtfs_trips, ropidgtfs_routes, ropidgtfs_precomputed_trip_schedule")];
+    psql_stop_times[("PSQL ropidgtfs_stop_times, ropidgtfs_stops")];
+    psql_shapes[("PSQL ropidgtfs_shapes")];
+
+    get_gtfs_detail["GET /v2/public/gtfs/trips/$trip_id"];
+    get_gtfs_detail--"Lookup GTFS trip id"<-->psql_trip;
+    get_gtfs_detail--"scope[]=stop_times"<-->psql_stop_times;
+    get_gtfs_detail--"scope[]=shapes"<-->psql_shapes;
+```
+
+### Flowchart (public API departures)
+```mermaid
+flowchart TD;
+    redis_pubsub_channel["Redis channel vpPublicCache"];
+    redis_subscriber["VPSubscriber"];
+    redis_public_cache[("Redis vpPublicCache:* (RT info)")];
+    redis_public_cache_misc[("Redis vpPublicCache:* (aktivní, budoucí a zrušené spoje)")];
+    redis_departures[("Redis gtfsPublicDepartureCache:*")];
+    redis_repository["OG PublicVehiclePositionsRepository"];
+
+    redis_subscriber--"Přihlášení k odběru"-->redis_pubsub_channel;
+    redis_pubsub_channel--"ID/název nové datové sady"-->redis_subscriber--"setCurrentSetName"-->redis_repository;
+
+    get_departures["GET /v2/public/departureboards"];
+
+    get_departures--"Odjezdy pro zastávky"-->redis_departures;
+    get_departures--"Aktivní vozidlo podle GTFS trip id"-->redis_repository<-->redis_public_cache_misc;
+    rt_info["Obohacení o RT informace"];
+    get_departures--"Alespoň jedno vozidlo připadá nějakému spoji (aktivní, budoucí i zrušené) na odjezdu"-->rt_info;
+    rt_info--"RT informace o spoji"-->redis_repository<-->redis_public_cache;
+```

package/docs/processing/index.md

@@ -0,0 +1,17 @@
+# Dokumentace zpracování vstupních RT dat
+
+- **Popis vstupních dat podle poskytovatele**
+    - [HTTP MPVNet](./input_realtime_data/http_mpvnet.md)
+        - [Městské a příměstské autobusy (mimo DPP)](./input_realtime_data/http_mpvnet.md#městské-a-příměstské-autobusy-mimo-dpp)
+        - [Přívozy](./input_realtime_data/http_mpvnet.md#přívozy)
+        - [Vlaky](./input_realtime_data/http_mpvnet.md#vlaky)
+    - [TCP DPP tramvaje](./input_realtime_data/tcp_dpp_tram.md)
+    - [TCP DPP autobusy a trolejbusy](./input_realtime_data/tcp_dpp_bus.md)
+    - [TCP DPP metro](./input_realtime_data/tcp_dpp_metro.md)
+    - [TCP Telmax Arriva City](./input_realtime_data/tcp_telmax_arriva_city.md)
+- **Popis určení stavu vozidla na trase podle poskytovatele**
+    - [HTTP MPVNet](./state_position_tracking/http_mpvnet.md)
+    - [TCP DPP](./state_position_tracking/tcp_dpp_common.md)
+    - [TCP DPP metro](./state_position_tracking/tcp_dpp_metro.md)
+    - [TCP Telmax Arriva City](./state_position_tracking/tcp_telmax_arriva_city.md)
+- [**Mapování MPVNet vehicle type na GTFS**](./vehicle_types.md)

package/docs/processing/input_realtime_data/http_mpvnet.md

@@ -0,0 +1,153 @@
+# HTTP MPVNet
+
+## Městské a příměstské autobusy (mimo DPP)
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+
+<m disp="http://77.93.194.81:8716/api">
+
+<spoj ka="2" kb="0" den="2025-03-30" lin="100194" alias="194" spoj="4009" dopr="ABOUT ME" doprSkut="ABOUT ME" kmenl="194" t="3" tcis="A" np="true" po="2" vuzevc="1907" skol="false" posl="false" sled="2" lat="50.09078" lng="14.42738" cpoz="09:34:59" azimut="76" rychl="1" zast="63505" asw="14100002" zpoz_prij="-59">
+	<zast stan="A" odj="09:20" zast="59168" asw="29530001" zpoz_typ_odj="3" zpoz_odj="28" />
+	
+	<zast stan="D" odj="09:23" zast="59104" asw="3610004" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-33" zpoz_odj="9" />
+	
+	<zast stan="I" odj="09:26" zast="57811" asw="3600009" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-84" zpoz_odj="-44" />
+	
+	<zast stan="A" odj="09:27" zast="59299" asw="7030081" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-36" zpoz_odj="-3" />
+	
+	<zast stan="B" odj="09:29" zast="63506" asw="14080002" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-70" zpoz_odj="5" />
+	
+	<zast stan="A" odj="09:32" zast="59300" asw="29620001" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-94" zpoz_odj="-9" />
+	
+	<zast stan="A" odj="09:33" zast="59108" asw="29630001" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="-18" zpoz_odj="-1" />
+	
+	<zast stan="B" odj="09:35" zast="63505" asw="14100002" zpoz_typ_prij="3" zpoz_typ_odj="2" zpoz_prij="-59" zpoz_odj="0" />
+	
+	<zast stan="A" odj="09:37" zast="63507" asw="14090001" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="0" zpoz_odj="0" />
+	
+	<zast stan="B" odj="09:39" zast="59203" asw="29560002" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="0" zpoz_odj="0" />
+	
+	<zast stan="B" odj="09:40" zast="58766" asw="320052" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="0" zpoz_odj="0" />
+	
+	<zast stan="H" prij="09:41" zast="27863" asw="6890008" zpoz_typ_prij="2" zpoz_prij="0" />
+</spoj>
+
+</m>
+```
+- _spoj_ - informace o spoji a vozidlu
+	- **ka** - ??? nepoužíváme
+	- **kb** - ??? nepoužíváme
+	- **den** - datum, kdy spoj vyjel
+	- **lin** - označení linky podle CIS
+	- **alias** - číslo/označení linky podle CIS
+	- **spoj** - označení spoje podle CIS
+	- **dopr** - smluvní dopravce podle JŘ
+	- **doprSkut** - reálný dopravce vykonávající oběh
+	- **kmenl** - kmenová linka, může se lišit od **alias**
+	- **t** - typ vozidla, viz [vehicle_types.md](../vehicle_types.md)
+	- **tcis** - ??? nepoužíváme
+	- **np** - indikátor nízkopodlažnosti
+	- **po** - oběhové číslo
+	- **vuzevc** -  [Evidenční číslo vozidla](https://cs.wikipedia.org/wiki/Eviden%C4%8Dn%C3%AD_%C4%8D%C3%ADslo_vozidla)
+	- **skol** - nejspíš indikátor školního spoje ??? nepoužíváme
+	- **posl** - nejspíš indikátor poslední spoje na oběhu ??? nepoužíváme
+	- **sled** - indikátor, zda je spoj sledovaný (tracked)
+		- 0 - nesledovaný (spoj je před trasou nebo dojel nebo je zrušen)
+		- 2 - sledovaný (spoj je na trase nebo v zastávce)
+	- **lat** - zeměpisná šířka
+	- **lng** - zeměpisná délka
+	- **cpoz** - čas odeslání zprávy (nejspíš z vozidla), nesmí být více než 5 minut v budoucnu
+	- **azimut** - azimut
+	- **rychl** - rychlost vozidla
+	- **zast** - aktuální nebo poslední projetá zastávka CIS (miniuzel)
+	- **asw** - aktuální nebo poslední projetá zastávka ASW
+	- **zpoz_prij** - zpoždění na příjezdu do aktuální nebo poslední projeté zastávky
+	- **zpoz_odj** - zpoždění na odjezdu z poslední projeté zastávky. Pokud je vozidlo v zastávce, pak není vyplněno
+	- **zrus** - indikátor, zda byl spoj zrušen
+	- **zrusod** - příklad 59168/A, nejspíš od které zastávky byl spoj zrušen ???
+- _zast_ - informace o projetých i budoucích zastávkách spoje
+	- **stan** - stanoviště/nástupiště/kolej podle CIS
+	- **odj** - čas odjezdu za zastávky podle JŘ
+	- **prij** - čas příjezdu do zastávky podle JŘ
+	- **zast** - identifikátor miniuzlu (CIS), kam zastávka patří 
+	- **asw** - ASW identifikátor zastávky
+	- **zpoz_typ_prij** - typ zpoždění příjezd do zastávky (2 predikce, 3 reálný stav)
+	- **zpoz_typ_odj** - typ zpoždění odjezd ze zastávky (2 predikce, 3 reálný stav)
+	- **zpoz_prij** - zpoždění příjezd do zastávky
+	- **zpoz_odj** - zpoždění příjezd do zastávky
+
+## Přívozy
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+
+<m disp="http://77.93.194.81:8716/api">
+
+<spoj ka="2" kb="0" den="2025-03-30" lin="199693" alias="P3" spoj="4096" dopr="VITTUS GROUP" doprSkut="VITTUS GROUP" kmenl="1803" t="12" tcis="P" np="true" po="1" vuzevc="302" skol="false" posl="false" sled="0" lat="50.04807" lng="14.41222" cpoz="09:18:29" azimut="337" rychl="2">
+	<zast stan="K" odj="09:32" zast="58997" asw="1100011" zpoz_typ_odj="2" zpoz_odj="0" />
+	
+	<zast stan="K" prij="09:34" zast="28003" asw="3370011" zpoz_typ_prij="2" zpoz_prij="0" />
+</spoj>
+
+</m>
+```
+
+## Vlaky
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+
+<m disp="http://77.93.194.81:8716/api">
+
+<spoj ka="1" kb="0" den="2025-03-30" lin="" alias="S8" spoj="9055" dopr="ČESKÉ DRÁHY" t="0" np="true" skol="false" posl="false" sled="2" lat="49.8657227" lng="14.4618721" cpoz="09:35:19" zast="5455746" zpoz_prij="600" zpoz_odj="600">
+	<zast stan="5S/22S" odj="08:25" zast="5457076" zpoz_typ_odj="3" zpoz_odj="720" />
+
+	<zast stan="-/6" prij="08:29" odj="08:30" zast="5457276" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="780" />
+
+	<zast stan="-/1" odj="08:34" zast="5457287" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="780" />
+
+	<zast stan="-/2" odj="08:38" zast="5457156" zpoz_zxtyp_prij="3" zpoz_typ_odj="3" zpoz_prij="660" zpoz_odj="720" />
+	
+	<zast stan="2/-" prij="08:42" odj="08:43" zast="5457016" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="660" zpoz_odj="660" />
+
+	<zast stan="-/2" prij="08:46" odj="08:47" zast="5457386" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast stan="-/1" odj="08:49" zast="5455526" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="780" zpoz_odj="840" />
+	
+	<zast stan="-/3" odj="08:53" zast="5455536" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="780" />
+	
+	<zast stan="-/1" odj="08:57" zast="5455556" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="780" />
+	
+	<zast stan="2/3" prij="09:01" odj="09:02" zast="5455546" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast stan="-/1" odj="09:05" zast="5458316" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="660" zpoz_odj="660" />
+	
+	<zast stan="-/2" prij="09:12" odj="09:13" zast="5455696" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="600" zpoz_odj="600" />
+	
+	<zast stan="-/1" odj="09:16" zast="5455716" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="600" zpoz_odj="660" />
+	
+	<zast stan="-/1" odj="09:19" zast="5455726" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="600" zpoz_odj="660" />
+	
+	<zast stan="-/1" odj="09:24" zast="5455746" zpoz_typ_prij="3" zpoz_typ_odj="3" zpoz_prij="600" zpoz_odj="600" />
+	
+	<zast stan="-/1" prij="09:30" odj="09:31" zast="5455736" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="09:35" odj="09:36" zast="5455756" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="09:38" odj="09:39" zast="5455776" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="09:42" odj="09:43" zast="5455766" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast odj="09:46" zast="5455796" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="09:49" odj="10:03" zast="5455786" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="10:06" odj="10:07" zast="5455806" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="10:11" odj="10:12" zast="5455816" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="10:14" odj="10:15" zast="5455096" zpoz_typ_prij="2" zpoz_typ_odj="2" zpoz_prij="720" zpoz_odj="720" />
+	
+	<zast prij="10:19" zast="5455046" zpoz_typ_prij="2" zpoz_prij="300" />
+</spoj>
+
+</m>
+```

package/docs/processing/input_realtime_data/tcp_dpp_bus.md

@@ -0,0 +1,27 @@
+# TCP DPP autobusy a trolejbusy
+
+```xml
+<M>
+
+<V turnus="144/3" line="144" evc="3885" np="ano" lat="50.12460" lng="14.45489" akt="06750004" takt="2025-03-30T18:10:04" konc="06490001" tjr="2025-03-30T18:10:00" pkt="473060" tm="2025-03-30T18:10:06" events="P"/>
+
+</M>
+```
+
+- **turnus** - oběh
+- **line** - linka
+- **evc** - [Evidenční číslo vozidla](https://cs.wikipedia.org/wiki/Eviden%C4%8Dn%C3%AD_%C4%8D%C3%ADslo_vozidla)
+- **np** - indikátor nízkopodlažnosti
+- **lat** - zeměpisná šířka
+- **lng** - zeměpisná délka
+- **akt** - poslední projetá zastávka, nepoužíváme
+- **takt** - timestamp odeslání zprávy z vozidla
+- **konc** - poslední ASW zastávka spoje, nepoužíváme
+- **tjr** - timestamp odeslání zprávy podle JŘ (v jaký čas mělo vozidlo na daném bodě být)
+- **pkt** -  identifikátor zprávy z vozidla/číslo TCP packetu??? Nepoužíváme
+- **tm** - timestamp odeslání zprávy od DPP
+- **events** -  událost asociovaná se zprávou
+	- P - příjezd do zastávky
+	- O - odjezd ze zastávky
+	- V - spoj ukončen
+	- T - checkpoint na trase, vozidlo jen o sobě dává vědět

package/docs/processing/input_realtime_data/tcp_dpp_metro.md

@@ -0,0 +1,24 @@
+# TCP DPP metro
+
+```xml
+<m linka="C" tm="2025-03-03T09:07:59Z" gvd="GD29c">
+
+<vlak csp=" 6" csr=" 6" cv="225" ko="282901" odch="-25" />
+
+<vlak csp="10" csr="10" cv="229" ko="313207" odch="0" />
+
+<vlak csp="16" csr="16" cv="260" ko="3704" odch="15" />
+
+<vlak csp="18" csr="18" cv="245" ko="4709" odch="50" />
+
+</m>
+```
+
+- **linka** - označení linky, koresponduje s GTFS `route.short_name`
+- **tm** - timestamp odeslání zprávy od DPP
+- **gvd** - grafikon, nepoužíváme
+- **csp** - oběhové číslo podle JŘ, nevěříme
+- **csr** - oběhové číslo doopravdy, nevěříme
+- **cv** - číslo spoje, koresponduje s trip_number v obehy.csv, unikátní v rámci linky
+- **ko** - kolejový obvod, určení GPS souřadnic
+- **odch** - odchylka oproti `tm`, určení zpoždění (záporné číslo znamená zpoždění)

package/docs/processing/input_realtime_data/tcp_dpp_tram.md

@@ -0,0 +1,26 @@
+# TCP DPP tramvaje
+
+```xml
+<M>
+
+<V turnus="12/2" line="12" evc="8544" lat="50.10486" lng="14.53100" akt="51440002" takt="2025-03-30T18:11:52" konc="00720002" tjr="2025-03-30T18:10:00" pkt="591646" tm="2025-03-30T18:11:52" events="O"/>
+
+</M>
+```
+- **turnus** - oběh
+- **line** - linka
+- **evc** - [Evidenční číslo vozidla](https://cs.wikipedia.org/wiki/Eviden%C4%8Dn%C3%AD_%C4%8D%C3%ADslo_vozidla)
+- **np** - indikátor nízkopodlažnosti
+- **lat** - zeměpisná šířka
+- **lng** - zeměpisná délka
+- **akt** - poslední projetá zastávka, nepoužíváme
+- **takt** - timestamp odeslání zprávy z vozidla
+- **konc** - poslední ASW zastávka spoje, nepoužíváme
+- **tjr** - timestamp odeslání zprávy podle JŘ (v jaký čas mělo vozidlo na daném bodě být)
+- **pkt** -  identifikátor zprávy z vozidla/číslo TCP packetu??? Nepoužíváme
+- **tm** - timestamp odeslání zprávy od DPP
+- **events** -  událost asociovaná se zprávou
+	- P - příjezd do zastávky
+	- O - odjezd ze zastávky
+	- V - spoj ukončen
+	- T - checkpoint na trase, vozidlo jen o sobě dává vědět