@golemio/public-transport 0.1.0

package/docs/cache/types/redis.md

@@ -0,0 +1,605 @@
+# 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 `/v1/public-transport/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í nejméně 3x za minutu (rabín 2x) pomocí queue-message
+  -  Používají redis-mutex na zamykání, aby neběželo více shodných tasků v jeden okamžik
+  -  Pokud generování stíhá běžet rychleji, task se snaží do ±7 vteřin svého běhu spustit nové generování souborů (opět přes queue-message).
+
+### 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 /v1/public-transport/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:*
+
+- key = `*${route_id}_${run_number}`
+- retence dat aktivne v tride `DataCacheManager` 
+- TTL podle casu vygenerovane ho z methody `getNextExpireTimestamp`
+- hodnota je `string`
+- cache obsaguje data z tabulky ropidgtfs_precomputed_trip_schedule
+
+```mermaid
+flowchart TD;
+    psql[("PSQL ropidgtfs_precomputed_trip_schedule")];
+    redis_trip_schedule[("Redis gtfsRunSchedule:*")];
+    connector[("OG Redis connector")];
+    repository["IE RunTripsRedisRepository"];
+
+    propagateDelay["propagateDelay"];
+
+
+    repository<--GET*.runTuple--->propagateDelay;
+    runManager["AbstractGTFSTripRunManager"]
+    get_gtfsrt["GET /v2/departureboards"];
+
+    initial["Zpráva z vozidla"];
+    initial--process-->runManager;
+    repository--GET*.runTuple<-->redis_trip_schedule;
+    runManager--GET*.runTuple<-->repository;
+    runManager--SET *.runTuple-->repository;
+    repository--SET *.runTuple-->redis_trip_schedule;
+    runManager--SELECT if not found in redis<-->psql;
+
+    get_gtfsrt-->connector;
+    connector--**MGET** *runTuple<-->redis_trip_schedule;
+```
+
+### gtfsBlockSchedule:*
+
+- key = `*gtfs_block_id`
+- retence dat aktivne v tride `DataCacheManager` 
+- TTL podle casu vygenerovane ho z methody `getNextExpireTimestamp`
+- hodnota je `string`
+- cache obsahuje data trip_stops podle gtfs block_id
+
+```mermaid
+flowchart TD;
+    psql[("PSQL ropidgtfs_stop_times")];
+    cache[("Redis gtfsBlockSchedule:*")];
+    repository["IE BlockStopsRedisRepository"];
+    updateDelay["updateDelay"];
+    updateGTFSTripId["updateGTFSTripId"];
+    tripStopsManager["tripStopsManager"];
+    initial["Zpráva z vozidla"];
+
+    initial--process-->updateGTFSTripId;
+    updateGTFSTripId<--create cache for trip stops-->tripStopsManager;
+    updateGTFSTripId-->updateDelay;
+    updateDelay<--get/update cache for trip stops-->tripStopsManager;
+    updateDelay-->propagateDelay;
+    propagateDelay-->propagateTrainDelay;
+    propagateTrainDelay<--get/update cache for trip stops-->tripStopsManager;
+
+
+
+    repository--GET*.blockId<-->redis_trip_schedule;
+    tripStopsManager--GET*.blockId<-->repository;
+    tripStopsManager--SET *.blockId-->repository;
+    repository--SET *.blockId-->cache;
+    tripStopsManager--SELECT if not found in redis<-->psql;
+
+```
+### gtfsDelayComputation:*
+
+- key = `*${gtfs_trip_id}`
+- TTL nastavovano na valid_to posledni pozice kdyz je znama kdyz ne tak na 30 min 
+- hodnota je `json`
+- cache obsahuje informace o tripu
+  - stop_times
+  - shapes_anchor_points
+  - shapes
+  
+### Flowchart
+
+```mermaid
+flowchart TD;
+
+updateDelay["UpdateDelay Task"];
+
+saveRunToDb["save*RunToDb Task"];
+updateRunsGTFSTripId["updateRunsGTFSTripId Task"]
+processRegionalBusPositions["processRegionalBusPositions Task"]
+processRegionalBusRunMessages["processRegionalBusRunMessages Task"]
+repository["DelayComputationRedisRepository"];
+cache["Redis gtfsDelayComputation:*"];
+initial["Zprava z vozidla"]
+
+initial-->saveRunToDb
+saveRunToDb--common message-->updateRunsGTFSTripId
+updateRunsGTFSTripId-->updateDelay;
+updateDelay<--getTripPropertiesBatch-->repository;
+updateDelay<--cacheTripDataBatch-->repository;
+
+saveRunToDb--ArrivaCity run message-->processRegionalBusRunMessages
+processRegionalBusRunMessages-->processRegionalBusPositions
+processRegionalBusPositions<--getTripPropertiesBatch-->repository;
+processRegionalBusPositions<--cacheTripDataBatch-->repository;
+
+repository--JSON.GET-->cache
+repository--JSON.SET-->cache
+
+```
+
+## Cache pro předzpracování a párování dat z Telmaxu (Arriva City)
+
+### vpRegionalBusCisLookup:*
+
+- key = `*${external_trip_id}`
+- TTL podle casu vygenerovane ho z methody `getNextExpireTimestamp`
+- hodnota je string (JSON.stringify())
+- cache obsahuje cis informace o tripu
+  - cis_line_id
+  - cis_trip_number
+  - registration_number
+  
+```mermaid
+flowchart TD
+    cache["vpRegionalBusCisLookup:*"]
+
+    repo["RegionalBusCisCacheRepository"]
+    telmax["Telmax (Arriva City)"]
+    task["saveArrivaCityRunsToDB task"]
+
+    telmax-->|bus position message|task
+    task-->|lookup CIS ID|repo
+    repo-->|get/set|cache
+    task-->|update cache|repo
+    cache-->|return data|repo
+```
+
+### vpRegionalBusGtfsLookup:*
+
+- key = `*${cis_line_id}_${cis_trip_number}`
+- TTL zadne nema
+- retence dat aktivne v tride `DataCacheManager` 
+- hodnota je string (JSON.stringify())
+- cache obsahuje gtfs informace o tripu
+    - gtfs_trip_id
+    - route_name
+    - run_number
+    - agency_name
+    - is_wheelchair_accessible
+
+  
+```mermaid
+flowchart TD
+    cache["vpRegionalBusGtfsLookup:*"]
+
+    repo["RegionalBusGtfsCacheRepository"]
+    telmax["Telmax (Arriva City)"]
+    task["processRegionalBusRunMessages Task"]
+    psql["gtfs data in DB"]
+
+
+
+    telmax-->|bus position message|task
+    task<--No gtfs data for trip in cache-->psql
+    task-->|lookup GTFS trip|repo
+    repo-->|get/set|cache
+    task-->|update cache|repo
+    cache-->|return data|repo
+```
+
+## 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é)
+- Populace `future-trip-*`, `future-vehicle-*` a `canceled-trips-*` sub-klíčů je řízena stavem spoje (před trasou / zrušen) a nesouvisí s logikou deduplikace odjezdů v `/v2/public/departureboards` – ta pracuje nad `gtfsPublicDepartureCache` a tuto cache neovlivňuje
+
+### 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
+  - `stop_name` - název zastávky
+  - `assigned_stop_id` - GTFS `stop_id` konkrétního nástupištního záznamu (pro vlaky, kde se podařilo spárovat CIS `cis_stop_platform_code` s nástupištní zastávkou v GTFS); `null` pokud k přiřazení nedošlo nebo nejde o vlak; zdroj: pohled `v_public_vehiclepositions_combined_stop_times` (self-join na `ropidgtfs_stops` přes `parent_station` + `platform_code = cis_stop_platform_code`, `location_type = 0`)
+- 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 je JSON string s informacemi o odjezdu:
+  - `stop_id` – GTFS id zastávky
+  - `departure_datetime` – plánovaný čas odjezdu (ISO 8601)
+  - `arrival_datetime` – plánovaný čas příjezdu (ISO 8601), nebo `null`
+  - `route_short_name` – název linky
+  - `route_type` – typ dopravy (GTFS route_type)
+  - `trip_id` – GTFS id spoje
+  - `stop_sequence` – pořadí zastávky v spoji
+  - `platform_code` – označení nástupiště, nebo `null`
+  - `trip_headsign` – cílová zastávka spoje (nebo `stop_headsign`, pokud je definován)
+  - `trip_headsign_icons` – ikony přestupů u cílové zastávky jako řetězec dvouznaková kódů (např. `"MbMcSb"`), nebo `null`
+  - `connections` – seznam garantovaných přestupů čekajících na tento spoj, nebo `null`; každý záznam obsahuje:
+    - `from_trip_id` – GTFS id spoje, na který se čeká
+    - `max_wait_sec` – maximální čekací doba v sekundách
+    - Přednačítá se z tabulky `ropidgtfs_precomputed_trip_connections` (původně z `transfers.txt` kde `transfer_type = 1`), JOIN na odjezdy přes `to_trip_id` a `to_stop_id`
+  - `wheelchair_accessible` – přístupnost vozidla pro vozíčkáře z GTFS `trips.txt` (`0` = bez informace, `1` = přístupné, `2` = nepřístupné), nebo `null`
+  - `direction_id` – směr jízdy z GTFS `trips.txt` (`0` nebo `1`), nebo `null`; využívá se při seskupování odjezdů podle směru a filtrování opačného směru v přestupních tabulích
+  - `flags` – nepovinný objekt s příznaky spoje, vyplněn pouze pokud má alespoň jeden z příznaků hodnotu `1` (zdroj `ropidgtfs_departures.is_night/is_regional/is_substitute_transport`); v objektu se objeví pouze pravdivé klíče:
+    - `night` (`1`) – noční spoj
+    - `reg` (`1`) – regionální spoj
+    - `subst` (`1`) – náhradní doprava
+- 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
+- Využití v endpointu přestupních tabulí (`/v4/pid/transferboards`)
+
+### 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;
+```
+
+## Cache pro API přestupních tabulí (transfer boards)
+
+*(přestupní tabule využívají také cache pro Public API, která je již popsána výše)*
+
+### gtfsStopsCache:*
+
+- Jednotlivé komponenty cache jsou členěny do sad s `$setId`
+    - `$setId` je id vygenerované datové sady (4 náhodné bajty reprezentované hexadecimálně)
+    - Nová sada je vytvořena při každém přenačtení cache
+    - Id `$setId` nejnovější datové sady se propaguje přes PubSub channel `gtfsStopsCache` a je také uloženo v cache jako hodnota položky `gtfsStopsCache:activeSetName`
+- Komponenty:
+  - `gtfsStopsCache:$setId:aswNodeToGtfsStops` - Hash mapa, mapující daný ASW node na seznam pod něj spadajících zastávek (GTFS ids zastávek, odděleny čárkami)
+  - `gtfsStopsCache:$setId:cisToAswNode` - Hash mapa, mapující dané CIS id zastávky na příslušný ASW node
+- TTL žádné (mimo přenačtení cache, kdy je namísto okamžitého promazání původnímu setu nastaveno TTL 1 minuta)
+- Cache je celá přenačtena vždy po přenačtení jízdních řádů (tedy 1-2x denně při stavu k červenci 2025)
+
+### jisCache:*
+
+- Jednotlivé komponenty cache jsou členěny do sad s `$setId`
+    - `$setId` je id vygenerované datové sady (4 náhodné bajty reprezentované hexadecimálně)
+    - Nová sada je vytvořena při každém přenačtení cache
+    - Id `$setId` nejnovější datové sady se propaguje přes PubSub channel `jisCache` a je také uloženo v cache jako hodnota položky `jisCache:activeSetName`
+- Komponenty:
+  - `jisCache:$setId:infotexts` - Hash mapa, mapující dané id infotextu na informace o onom infotextu (JSON jako string)
+  - `jisCache:$setId:stops-infotexts` - Hash mapa, mapující dané GTFS id zástavky na seznam infotextů s ní asociovaných (ids infotextů, odděleny čárkami)
+- TTL žádné (mimo přenačtení cache, kdy je namísto okamžitého promazání původnímu setu nastaveno TTL 1 minuta)
+- Cache je celá přenačtena při každé aktualizaci infotextů (tento proces je více popsán v [Dokumentaci propisu VYMI (JIS) dat do datové platformy](../../jis/index.md))
+
+### Flowchart (refresh gtfsStopsCache:*)
+
+```mermaid
+flowchart LR
+    finish_up_gtfs("`Dokončení zpracování GTFS JŘ`");
+
+    psql_ropidgtfs_cis_stops[("`PSQL ropidgtfs_cis_stops`")];
+    psql_ropidgtfs_stops[("`PSQL ropidgtfs_stops`")];
+
+    redis_gtfsStopsCache[("`Redis gtfsStopsCache:\*`")];
+
+    amqp_refreshGtfsStopsCache["`AMQP refreshGtfsStopsCache`"];
+
+    task_RefreshGtfsStopsCacheTask["`RefreshGtfsStopsCacheTask`"];
+
+    finish_up_gtfs --> amqp_refreshGtfsStopsCache;
+    amqp_refreshGtfsStopsCache --> task_RefreshGtfsStopsCacheTask;
+    task_RefreshGtfsStopsCacheTask <-- "`ASW ids a CIS ids zastávek`" --> psql_ropidgtfs_cis_stops;
+    task_RefreshGtfsStopsCacheTask <-- "`ASW nodes a GTFS ids zastávek`" --> psql_ropidgtfs_stops;
+    task_RefreshGtfsStopsCacheTask -- "`HSET gtfsStopsCache:$setId:aswNodeToGtfsStops a gtfsStopsCache:$setId:cisToAswNode, EXPIRE staré sady`" --> redis_gtfsStopsCache;
+```
+
+### Flowchart (refresh jisCache:*)
+
+```mermaid
+flowchart LR
+    refresh_infotexts("`Aktualizace infotextů`");
+
+    psql_jis_infotexts[("`PSQL jis_infotexts`")];
+    psql_jis_infotexts_ropidgtfs_stops[("`PSQL jis_infotexts_ropidgtfs_stops`")];
+
+    redis_jisCache[("`Redis jisCache:\*`")];
+
+    amqp_refreshJISInfotextsCache["`AMQP refreshJISInfotextsCache`"];
+
+    task_RefreshJISInfotextsCacheTask["`RefreshJISInfotextsCacheTask`"];
+
+    refresh_infotexts --> amqp_refreshJISInfotextsCache;
+    amqp_refreshJISInfotextsCache --> task_RefreshJISInfotextsCacheTask;
+    task_RefreshJISInfotextsCacheTask <-- "`Data infotextů`" --> psql_jis_infotexts;
+    task_RefreshJISInfotextsCacheTask <-- "`GTFS ids zastávek a ids infotextů`" --> psql_jis_infotexts_ropidgtfs_stops;
+    task_RefreshJISInfotextsCacheTask -- "`HSET jisCache:$setId:infotexts a jisCache:$setId:stops-infotexts, EXPIRE staré sady`" --> redis_jisCache;
+```
+
+### gtfsTripStopsCache:*
+
+- Klíč `gtfsTripStopsCache:*`, kde `*` je GTFS `trip_id`
+- Hodnota je JSON string s polem zastávek seřazených podle `stop_sequence`:
+  - `stops` – pole dvojic `[stop_id, stop_name]`
+- TTL 6 hodin (musí přesáhnout maximální dobu jízdy spoje ~3,5h + interval tasku 1h)
+- Cache se přegeneruje jednou za hodinu (cron přes `EnsureCacheTask`) a po přenačtení GTFS jízdních řádů (přes `CheckSavedRowsAndReplaceTablesTask`)
+- SQL dotaz vybírá všechny spoje, jejichž první zastávka (`stop_sequence = 1`) má `departure_datetime` v okně `now() − 1h` až `now() + 2h`, a pro každý takový spoj agreguje všechny zastávky
+- Zapisuje `GtfsTripStopsCacheRepository` (IE) v dávkách po 200 klíčích přes Redis pipeline; před zápisem se validují data přes AJV schéma, nevalidní záznamy se přeskočí a zalogují
+- Čte `GtfsTripStopsRepository` (OG) přes `MGET` — využívá `TransferFacade.findRelevantTripIdsFromLines()` pro filtrování přestupních linek
+
+### Flowchart (v4 transferboards API)
+
+![flowchart.svg](../../assets/V4Transferboards.svg)
+
+link na .drawio [soubor](../../assets/V4Transferboards.drawio)
+
+## Cache pro konfiguraci
+
+### config:notPublicVehicles
+
+- Klíč `config:notPublicVehicles` (jednoduchý klíč, žádný wildcard)
+- Hodnota je JSON string struktury `INotPublicVehicles`:
+  - `tram.registrationNumbers` – seznam evidenčních čísel tramvají bez platného GTFS spoje
+  - `road.registrationNumbers` – seznam evidenčních čísel autobusů a trolejbusů bez platného GTFS spoje (`road` pokrývá obě kategorie, protože sdílejí číselnou řadu)
+  - `routeIds` – whitelist čísel linek (např. `"861"` pro náhradní autobus X-C při výluce metra C) zobrazovaných i bez platného JŘ spoje
+- TTL žádné – hodnota se přepíše při každém spuštění `SaveStaticDataTask` (po načtení nových JŘ)
+- Zapisuje `NotPublicVehiclesRedisRepository` (IE), čte `TripsRepository` / `PositionsMapper` (IE) a `UpdateRunsGtfsTripIdTask` (IE) pro povolení průchodu vozidel bez GTFS spoje
+
+## Manuální refresh cache (EnsureCacheTask)
+
+`EnsureCacheTask` slouží jako manuální spouštěč obnovy všech 5 caches, jejichž data nejsou real-time obnovována. Po přijetí prázdné zprávy na frontě `vehicle-positions.ropidgtfs.ensureCache` odešle paralelně prázdné zprávy do všech 5 cílových front. Dvě z nich míří do různých workerů (cross-worker routing přes RabbitMQ exchange), tři míří do stejného workeru (TimetableWorker).
+
+### Flowchart
+
+```mermaid
+flowchart LR
+    trigger["`Zpráva do fronty ensureCache`"]
+    task["`EnsureCacheTask (TimetableWorker)`"]
+
+    exchange_vp["`Exchange ${RABBIT_EXCHANGE_NAME}.vehiclepositions (VPWorker)`"]
+    exchange_self["`Exchange this.queuePrefix (TimetableWorker)`"]
+    exchange_jis["`Exchange ${RABBIT_EXCHANGE_NAME}.jis (JISWorker)`"]
+
+    q1["`AMQP refreshGTFSTripData`"]
+    q2["`AMQP refreshPublicGtfsDepartureCache`"]
+    q3["`AMQP refreshGtfsStopsCache`"]
+    q4["`AMQP refreshGtfsTripStopsCache`"]
+    q5["`AMQP refreshJISInfotextsCache`"]
+
+    trigger --> task
+    task -- cross-worker --> exchange_vp --> q1
+    task -- same-worker --> exchange_self --> q2
+    exchange_self --> q3
+    exchange_self --> q4
+    task -- cross-worker --> exchange_jis --> q5
+```
+

package/docs/examples/not_public_vehicles.json

@@ -0,0 +1,9 @@
+{
+    "tram": {
+        "registrationNumbers": ["2210", "5572"]
+    },
+    "road": {
+        "registrationNumbers": ["1234", "5678", "9999"]
+    },
+    "routeIds": ["X1", "X2", "X3", "NAD"]
+}