@golemio/pid 3.13.2-dev.1802603210 → 3.13.2-dev.1803100353

package/docs/cache/index.md

@@ -0,0 +1,5 @@
+# Dokumentace pro práci s cache
+
+- [**Redis cache**](./types/redis.md)
+- [**In-memory cache**](./types/in_memory.md)
+- [**PostgreSQL cache**](./types/psql.md)

package/docs/cache/types/in_memory.md

@@ -0,0 +1,58 @@
+# In-memory cache
+
+- Cachování v paměti instance služby
+- Nejdříve se načtou data z PSQL, následně si instance služby data drží v paměti
+- Variabilní nebo žádné TTL (tedy pro obnovení dat je nutné službu/instanci/pod restartovat)
+- Vhodné pro data, která se často nemění, ale zároveň se nevyplatí je ukládat do Redisu
+
+## Kolejové obvody
+
+- Třída [CachedMetroRailTrackLookup](../../../src/integration-engine/vehicle-positions/workers/vehicle-positions/data-access/metro/CachedMetroRailtrackLookup.ts)
+- Využití v rámci procesování metro zpráv manipulací shape anchor pointů na trase pro přesnější určení stavu vozidla (`on_track` X `at_stop`) a zpoždění na příjezdu/odjezdu do/ze zastávky
+  - Viz [MetroShapePointsFixer](../../../src/integration-engine/vehicle-positions/workers/vehicle-positions/helpers/metro/MetroShapePointsFixer.ts)
+- TTL žádné
+  - :warning: Dříve se nové kolejové obvody načítaly podle potřeby ROPIDu (zpravidla 2x za rok), takže současný způsob cachování byl v pořádku. Nyní se načítají každý den spolu s JŘ stažením z Blob Storage (kde si soubor ROPIDu spravuje sám), takže je absence TTL kvůli neaktualizaci dat problematická (neaktuálnost kolejových obvodů a špatné určení stavu vozidla, případně zpoždění v zastávce), je potřeba to řešit jinak
+
+```mermaid
+flowchart TB;
+  initial[Příjem zprávy, zpárování s GTFS, uložení do DB]-->amqp_updateDelay[AMQP updateDelay];
+  amqp_updateDelay--select-->trips[(PSQL trips)];
+  amqp_updateDelay--select-->positions[(PSQL positions)];
+
+  trips--Anchor pointy neexistují-->anchor_points_new[Vytvoření anchor points podle GTFS shapes];
+  positions--Anchor pointy neexistují-->anchor_points_new;
+  trips--Anchor pointy existují-->anchor_points_exist[Načtení anchor points z Redisu];
+  positions--Anchor pointy existují-->anchor_points_exist;
+
+  anchor_points_new-->fixer[MetroShapePointsFixer];
+  fixer-->lookup[CachedMetroRailTrackLookup];
+  lookup--select pokud cache miss<-->railtrack[(PSQL metro railtrack data)];
+  lookup-->save_anchor_points[Uložení anchor points do Redisu];
+  save_anchor_points-->continue[Pokračování ve zpracování zprávy];
+
+  anchor_points_exist-->continue;
+```
+
+## Popisky vozidel
+
+- Třída [VehicleDescriptorCachedRepository](../../../src/output-gateway/public/data-access/VehicleDescriptorCachedRepository.ts)
+- Využití v rámci:
+  - Public VP detailu pro získání dodatečných informací o konkrétním vozidle na trase (pokud si uživatel vyžádá `scope[]=vehicle_descriptor`)
+  - Public odjezdů pro získání dodatečných informací (USB nabíječky, klimatizace) o vozidle na každém odjezdu z vybraných zastávek, pokud už víme, které vozidlo daný spoj obsluhuje
+- TTL 4 hodiny
+- Data stahujeme 2x denně, takže současný způsob cachování teď ničemu úplně nevadí
+
+```mermaid
+flowchart TB;
+  api_request_vp[GET /v2/public/vehiclepositions/$vehicle_id]-->process_vp[Zpracování API requestu];
+  api_request_departures[GET /v2/public/departureboards]-->process_departures[Zpracování API requestu];
+  
+  process_vp--uživatel vyžádal vehicle_descriptor-->descriptor_repository[VehicleDescriptorCachedRepository];
+  process_vp--uživatel nevyžádal vehicle_descriptor-->continue[Pokračování ve zpracování];
+
+  process_departures--známe vozidlo k odjezdu-->descriptor_repository;
+  process_departures--neznáme vozidlo k odjezdu-->continue;
+
+  descriptor_repository--select pokud cache miss<-->descriptors[(PSQL vehicle descriptors)];
+  descriptor_repository-->continue;
+```

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

package/docs/processing/input_realtime_data/tcp_telmax_arriva_city.md

@@ -0,0 +1,44 @@
+# TCP Telmax Arriva City + Arriva City Neratovice
+
+```xml
+<M>
+
+<V imei="860425047186836" rz="5SB8545" pkt="573" lat="50.0451" lng="14.44866" tm="2025-03-30T18:07:09" events="Z" rych="13" smer="49" />
+
+<V imei="862430061982423" rz="6SN8270" pkt="5527" lat="50.10773" lng="14.60353" tm="2025-03-30T18:07:11" events="P" line="100204" conn="4032" rych="0" smer="320" evc="9018" turnus="204716" ridic="200602" akt="55207" konc="55250" />
+
+<V imei="867377023798816" rz="6SU3222" pkt="2837" lat="49.95867" lng="14.8828" tm="2025-03-30T18:07:09" events="Z" rych="39" smer="350" />
+
+<V imei="867377023795952" rz="9U89136" pkt="1002" lat="49.86153" lng="14.58563" tm="2025-03-30T18:07:13" events="L" rych="48" smer="193" />
+
+<V imei="867377023798816" rz="6SU3222" pkt="2838" lat="49.95876" lng="14.88278" tm="2025-03-30T18:07:10" events="Z" rych="39" smer="351" />
+
+<V imei="867377023797230" rz="9U89064" pkt="939" lat="50.038" lng="14.45776" tm="2025-03-30T18:07:12" events="R" rych="11" smer="40" />
+
+<V imei="867377023812609" rz="6AB1843" pkt="5024" lat="50.12651" lng="14.51493" tm="2025-03-30T18:07:11" events="T" rych="0" smer="347" />
+
+<V imei="868711063963758" rz="6SU2942" pkt="4016" lat="50.07414" lng="14.56016" tm="2025-03-30T18:07:11" events="RZ" rych="13" smer="244" />
+
+<V imei="867377023797214" rz="6AJ8958" pkt="4597" lat="50.09357" lng="14.49805" tm="2025-03-30T18:07:15" events="A" rych="15" smer="294" />
+
+<V imei="867377023820230" rz="4AV4134" pkt="3974" lat="50.08041" lng="14.48195" tm="2025-03-30T18:07:11" events="L" rych="30" smer="78" />
+
+</M>
+```
+- **imei** - identifikátor palubního počítače/vozidla, u nás `external_trip_id`
+- **rz** - SPZ, nepoužíváme
+- **pkt** - identifikátor zprávy z vozidla/číslo TCP packetu??? Nepoužíváme
+- **lat** - zeměpisná šířka
+- **lng** - zeměpisná délka
+- **tm** - timestamp odeslání právy z vozidla
+- **events** - událost asociovaná se zprávou
+	- **R** - výjezd ze zastávky
+- **line** - označení linky podle CIS
+- **conn** - označení spoje podle CIS
+- **rych** - rychlost vozidla
+- **smer** - azimut
+- **evc** - [Evidenční číslo vozidla](https://cs.wikipedia.org/wiki/Eviden%C4%8Dn%C3%AD_%C4%8D%C3%ADslo_vozidla)
+- **turnus** - jiný formát než DPP???, nepoužíváme
+- **ridic** - ??? nepoužíváme
+- **akt** - aktuální zastávka , nepoužíváme
+- **konc** - poslední zastávka, nepoužíváme

package/docs/processing/state_position_tracking/http_mpvnet.md

@@ -0,0 +1,55 @@
+# HTTP MPVNet state_position
+
+-   Batch data chodí na VP-IG (vyšší jednotky MB během špičky)
+-   Formát vstupních dat viz [input_realtime_data/http_mpvnet.md](../input_realtime_data/http_mpvnet.md)
+-   (HTTP) Input Gateway
+    -   Raw data se uloží na blob storage
+    -   knihovnou `xml2js` se transformují na JSON
+    -   validují se vůči JSON schématu a pošlou na Rabbita do fronty `saveDataToDB`
+-   saveDataToDB
+    -   data se napasují na struktury tabulek `vehiclepositions_trips` a `vehiclepositions_positions` (stav je `unknown`, `tracking` se bere ze vstupních dat)
+    -   všechny spoje se upsertují, nové spoje a jejich pozice se pošlou do fronty `updateGTFSTripId`, existující do `updateDelay`
+-   updateGTFSTripId
+    -   duplikace vlakových spojů a pozic podle block id (určení tracking podle cis stop id)
+    -   obohacení spojů GTFS daty (včetně oběhu a kmenové linky)
+    -   upsert asociovaných pozic
+    -   spoje se pošlou do fronty `updateDelay`
+-   updateDelay
+    -   opět duplikace vlakových spojů, upsert asociovaných pozic
+    -   opětovné načtení asociovaných pozic z DB
+    -   určení trasy spoje podle GTFS shapes a stop times
+    -   processing pozic, uložení do databáze
+        -   Not tracking (`tracking` je `0` a nebo nepřišly souřadnice)
+            -   pokud je poslední pozice neznámá, nebo je známá a ve stavu `on_track` nebo `at_stop`, je aktuální stav `before_track`
+            -   pokud je poslední známá pozice s `tracking 2`
+                -   pokud je pozice duplicitní (existuje pozice se stejným `origin_timestamp`), stav je `duplicate`
+                -   jinak je stav `after_track`
+        -   Tracking (`tracking` je `2`, souřadnice jsou známy)
+            -   pokud je vozidlo 200 metrů od nejblizšího bodu (anchor points) na trase, stav je `off_track`
+            -   pokud je nejbližší bod v zastávce, nastaví se stav na `at_stop`
+            -   jinak je stav `on_track`
+        -   Zrušený spoj (příznak `canceled` u pozice)
+            -   stav je vždy `canceled`
+-   propagateDelay
+    -   podle kmenové linky a oběhu vyhledáme navazující spoje
+    -   podle GTFS trip id a registračního čísla poslední pozici ve stavu `before_track`
+    -   přepsání stavu na `before_track_delayed`
+
+```mermaid
+flowchart TB;
+  A[HTTP data]-->B[VP HTTP Input Gateway]--raw data-->Blob[Azure Blob Storage];
+  B--JSON xml2js-->C[AMQP saveDataToDB]--upsert-->trips[(DB trips)];
+  C--nové spoje bez GTFS dat-->D[AMQP updateGTFSTripId];
+  C--existující spoje-->E[AMQP updateDelay];
+  D--upsert-->trips;
+  D--upsert-->positions[(DB positions)];
+  D--nové spoje s GTFS daty-->E;
+  E--upsert-->trips;
+  E--upsert-->positions;
+  E--select-->trips;
+  E--select-->positions;
+  E--uložené spoje-->F[AMQP propagateDelay];
+  F--select-->trips;
+  F--select-->positions;
+  F--upsert-->positions;
+```

package/docs/{state_position_tracking/tcp_common.md → processing/state_position_tracking/tcp_dpp_common.md}

@@ -1,19 +1,7 @@
-# TCP common state_position
+# TCP DPP common state_position
 
 -   Data chodí na TCP-IG
-
-```xml
-<M>
-    <V turnus="17/3" line="17" evc="9168" np="ano" lat="50.05440" lng="14.41812" akt="03030001" takt="2022-08-02T21:56:22" konc="26200002" tjr="2022-08-02T21:56:00" pkt="1885317" tm="2022-08-02T21:56:22" events="O" />
-</M>
-```
-
-```xml
-<M>
-    <V turnus="134/3" line="134" evc="3738" np="ano" lat="50.03952" lng="14.42919" akt="07960001" takt="2022-06-29T17:28:13" konc="01100005" tjr="2022-06-29T17:23:00" pkt="12709236" tm="2022-06-29T17:28:22" events="O" />
-</M>
-```
-
+-   Formát vstupních dat viz [input_realtime_data/http_mpvnet.md](../input_realtime_data/tcp_dpp_bus.md) a [input_realtime_data/tcp_dpp_tram.md](../input_realtime_data/tcp_dpp_tram.md)
 -   Transport (TCP) Input Gateway
     -   Raw data se uloží na blob storage (1MB buffer)
     -   knihovnou `xml2js` transformují na JSON

package/docs/{state_position_tracking/tcp_metro.md → processing/state_position_tracking/tcp_dpp_metro.md}

@@ -1,14 +1,7 @@
-# TCP metro state_position
+# TCP DPP metro state_position
 
 -   Data chodí na TCP-IG
-
-```xml
-<m linka="A" tm="2022-07-20T13:45:34Z" gvd="GD20a">
-    <vlak csp=" 3" csr=" 3" cv="279" ko="1809" odch="25" />
-    <!--...-->
-</m>
-```
-
+-   Formát vstupních dat viz [input_realtime_data/tcp_dpp_metro.md](../input_realtime_data/tcp_dpp_metro.md)
 -   Transport (TCP) Input Gateway
     -   Raw data se uloží na blob storage (1MB buffer)
     -   knihovnou `xml2js` transformují na JSON

package/docs/processing/state_position_tracking/tcp_telmax_arriva_city.md

@@ -0,0 +1,7 @@
+# TCP Telmax Arriva City state_position
+
+-   Data chodí na TCP-IG
+-   Data využíváme pouze na rabínovi, na produkci bereme z MPVNetu
+-   Formát vstupních dat viz [input_realtime_data/tcp_telmax_arriva_city.md](../input_realtime_data/tcp_telmax_arriva_city.md)
+-   Transport (TCP) Input Gateway
+-   TODO doplnit

package/docs/processing/vehicle_types.md

@@ -0,0 +1,32 @@
+# Mapování MPVNet vehicle type na GTFS
+
+## Typ vozidel podle MPV
+- 0 - neznámý nebo vlak
+- 1 - metro
+- 2 - tramvaj
+- 3 - autobus MHD
+- 4 - příměstský autobus
+- 5 - noční autobus
+- 6 - noční tramvaj
+- 7 - náhradní doprava
+- 8 - lanovka
+- 9 - školní spoj
+- 10 - spoj pro lidi s hendikepem
+- 11 - smluvní spoj
+- 12 - loď
+- 13 - vlak
+- 14 - náhradní autobus za vlak
+- 15 - náhradní tramvaj
+- 16 - noční příměstský autobus
+- 17 - ostatní
+- 18 - trolejbus
+
+## Typ vozidel podle GTFS
+- 0 - tramvaj, podle MPV 2, 6, 15
+- 1 - metro, podle MPV 1
+- 2 - vlak, podle MPV 0 a 13
+- 3 - autobus, podle MPV 3, 4, 5, 7, 16 
+- 4 - loď, podle MPV 12
+- 7 - lanovka, podle MPV 8
+- 11 - trolejbus, podle MPV 18
+- 1700 - smíšený nebo neznámý, nemapujeme z MPV

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/pid",
-    "version": "3.13.2-dev.1802603210",
+    "version": "3.13.2-dev.1803100353",
     "description": "Golemio PID Module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/docs/state_position_tracking/http.md

@@ -1,113 +0,0 @@
-# HTTP state_position
-
--   Batch data chodí na VP-IG (několik MB)
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<m disp="http://77.93.194.81:8716/api">
-    <spoj ka="2" kb="0" den="2023-03-21" lin="100115" alias="115" spoj="1061" dopr="ČSAD POLKOST"
-        doprSkut="ČSAD POLKOST" kmenl="115" t="3" tcis="A" np="true" po="39" vuzevc="1861"
-        skol="false" posl="false" sled="0" lat="50.0307" lng="14.49185" cpoz="10:00:04" azimut="337"
-        rychl="26">
-        <zast stan="B" odj="10:30" zast="56714" asw="520091" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="B" odj="10:32" zast="56794" asw="11310002" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="A" odj="10:34" zast="59066" asw="13410001" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="A" odj="10:36" zast="67975" asw="11320001" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="B" odj="10:37" zast="58953" asw="13340002" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="A" odj="10:40" zast="58789" asw="1810001" zpoz_typ_odj="2" zpoz_odj="0" />
-        <zast stan="A" odj="10:41" zast="56794" asw="11310001" />
-        <zast stan="F" prij="10:43" zast="56714" asw="520002" />
-    </spoj>
-    <spoj ka="2" kb="0" den="2023-03-21" lin="100117" alias="117" spoj="1016" dopr="ABOUT ME"
-        doprSkut="ABOUT ME" kmenl="117" t="3" tcis="A" np="true" po="6" vuzevc="1950" skol="false"
-        posl="false" sled="0" lat="50.04645" lng="14.46061" cpoz="09:59:56" azimut="165" rychl="0"
-        zast="57408" asw="500006" zpoz_prij="14">
-        <zast stan="B" odj="08:55" zast="66826" asw="32360002" zpoz_typ_odj="3" zpoz_odj="35" />
-        <zast stan="B" odj="08:55" zast="67375" asw="9910002" zpoz_typ_odj="3" zpoz_odj="81" />
-        <zast stan="C" odj="08:56" zast="55206" asw="2800053" zpoz_typ_odj="3" zpoz_odj="119" />
-        <zast stan="B" odj="08:58" zast="55181" asw="620002" zpoz_typ_odj="3" zpoz_odj="113" />
-        <zast stan="H8" odj="08:59" zast="51228" asw="10060052" zpoz_typ_odj="3" zpoz_odj="121" />
-        <zast stan="A" odj="09:00" zast="67477" asw="26020001" zpoz_typ_odj="3" zpoz_odj="85" />
-        <zast stan="E" odj="09:02" zast="51227" asw="9290005" zpoz_typ_odj="3" zpoz_odj="68" />
-        <zast stan="A" odj="09:03" zast="51226" asw="9390001" zpoz_typ_odj="3" zpoz_odj="91" />
-        <zast stan="A" odj="09:05" zast="55233" asw="11580001" zpoz_typ_odj="3" zpoz_odj="81" />
-        <zast stan="D" odj="09:07" zast="43729" asw="760051" zpoz_typ_odj="3" zpoz_odj="2" />
-        <zast stan="A" odj="09:08" zast="55214" asw="170001" zpoz_typ_odj="3" zpoz_odj="31" />
-        <zast stan="A" odj="09:09" zast="55183" asw="7270001" zpoz_typ_odj="3" zpoz_odj="36" />
-        <zast stan="A" odj="09:11" zast="55257" asw="7720001" zpoz_typ_odj="3" zpoz_odj="-9" />
-        <zast stan="A" odj="09:12" zast="55220" asw="9950001" zpoz_typ_odj="3" zpoz_odj="-15" />
-        <zast stan="B" odj="09:13" zast="55188" asw="9270002" zpoz_typ_odj="3" zpoz_odj="-2" />
-        <zast stan="B" odj="09:15" zast="58807" asw="6250002" zpoz_typ_odj="3" zpoz_odj="-20" />
-        <zast stan="B" odj="09:16" zast="58781" asw="4460002" zpoz_typ_odj="3" zpoz_odj="-5" />
-        <zast stan="B" odj="09:17" zast="58863" asw="6580002" zpoz_typ_odj="3" zpoz_odj="1" />
-        <zast stan="D" odj="09:18" zast="58863" asw="6580004" zpoz_typ_odj="3" zpoz_odj="-9" />
-        <zast stan="A" odj="09:19" zast="59095" asw="3280001" zpoz_typ_odj="3" zpoz_odj="-24" />
-        <zast stan="A" odj="09:20" zast="58972" asw="600001" zpoz_typ_odj="3" zpoz_odj="-8" />
-        <zast stan="B" odj="09:21" zast="58836" asw="4940002" zpoz_typ_odj="3" zpoz_odj="-11" />
-        <zast stan="B" odj="09:22" zast="58976" asw="8570002" zpoz_typ_odj="3" zpoz_odj="22" />
-        <zast stan="D" odj="09:24" zast="58837" asw="4970004" zpoz_typ_odj="3" zpoz_odj="-4" />
-        <zast stan="A" odj="09:25" zast="58869" asw="7220001" zpoz_typ_odj="3" zpoz_odj="-3" />
-        <zast stan="B" odj="09:27" zast="47119" asw="8930002" zpoz_typ_odj="3" zpoz_odj="-28" />
-        <zast stan="H" odj="09:29" zast="27948" asw="4880008" zpoz_typ_odj="3" zpoz_odj="-56" />
-        <zast stan="A" odj="09:32" zast="57400" asw="4410001" zpoz_typ_odj="3" zpoz_odj="-38" />
-        <zast stan="B" odj="09:33" zast="57401" asw="10480002" zpoz_typ_odj="3" zpoz_odj="-7" />
-        <zast stan="B" odj="09:34" zast="59152" asw="9370002" zpoz_typ_odj="3" zpoz_odj="-11" />
-        <zast stan="B" odj="09:35" zast="59258" asw="9380002" zpoz_typ_odj="3" zpoz_odj="-6" />
-        <zast stan="B" odj="09:37" zast="58814" asw="3430002" zpoz_typ_odj="3" zpoz_odj="48" />
-        <zast stan="L" prij="09:39" zast="57408" asw="500006" zpoz_typ_prij="3" zpoz_prij="14" />
-    </spoj>
-    <!--...-->
-</m>
-```
-
--   (HTTP) Input Gateway
-    -   Raw data se uloží na blob storage
-    -   knihovnou `xml2js` se transformují na JSON
-    -   validují se vůči JSON schématu a pošlou na Rabbita do fronty `saveDataToDB`
--   saveDataToDB
-    -   data se napasují na struktury tabulek `vehiclepositions_trips` a `vehiclepositions_positions` (stav je `unknown`, `tracking` se bere ze vstupních dat)
-    -   všechny spoje se upsertují, nové spoje a jejich pozice se pošlou do fronty `updateGTFSTripId`, existující do `updateDelay`
--   updateGTFSTripId
-    -   duplikace vlakových spojů a pozic podle block id (určení tracking podle cis stop id)
-    -   obohacení spojů GTFS daty (včetně oběhu a kmenové linky)
-    -   upsert asociovaných pozic
-    -   spoje se pošlou do fronty `updateDelay`
--   updateDelay
-    -   opět duplikace vlakových spojů, upsert asociovaných pozic
-    -   opětovné načtení asociovaných pozic z DB
-    -   určení trasy spoje podle GTFS shapes a stop times
-    -   processing pozic, uložení do databáze
-        -   Not tracking (`tracking` je `0` a nebo nepřišly souřadnice)
-            -   pokud je poslední pozice neznámá, nebo je známá a ve stavu `on_track` nebo `at_stop`, je aktuální stav `before_track`
-            -   pokud je poslední známá pozice s `tracking 2`
-                -   pokud je pozice duplicitní (existuje pozice se stejným `origin_timestamp`), stav je `duplicate`
-                -   jinak je stav `after_track`
-        -   Tracking (`tracking` je `2`, souřadnice jsou známy)
-            -   pokud je vozidlo 200 metrů od nejblizšího bodu (anchor points) na trase, stav je `off_track`
-            -   pokud je nejbližší bod v zastávce, nastaví se stav na `at_stop`
-            -   jinak je stav `on_track`
-        -   Zrušený spoj (příznak `canceled` u pozice)
-            -   stav je vždy `canceled`
--   propagateDelay
-    -   podle kmenové linky a oběhu vyhledáme navazující spoje
-    -   podle GTFS trip id a registračního čísla poslední pozici ve stavu `before_track`
-    -   přepsání stavu na `before_track_delayed`
-
-```mermaid
-flowchart TB;
-  A[HTTP data]-->B[VP HTTP Input Gateway]--raw data-->Blob[Azure Blob Storage];
-  B--JSON xml2js-->C[AMQP saveDataToDB]--upsert-->trips[(DB trips)];
-  C--nové spoje bez GTFS dat-->D[AMQP updateGTFSTripId];
-  C--existující spoje-->E[AMQP updateDelay];
-  D--upsert-->trips;
-  D--upsert-->positions[(DB positions)];
-  D--nové spoje s GTFS daty-->E;
-  E--upsert-->trips;
-  E--upsert-->positions;
-  E--select-->trips;
-  E--select-->positions;
-  E--uložené spoje-->F[AMQP propagateDelay];
-  F--select-->trips;
-  F--select-->positions;
-  F--upsert-->positions;
-```