@golemio/pid 5.7.2-dev.2373093983 → 5.7.2-dev.2373103436

package/docs/asyncapi.yaml

@@ -707,8 +707,12 @@ components:
                     type: string
                     description: The timestamp when the message was last sent.
                 wheelchair_accessible:
-                    type: boolean
-                    description: Indicates if the vehicle is wheelchair accessible.
+                    type: [boolean, "null"]
+                    description: |
+                        Raw wheelchair accessibility flag from vehiclepositions_trips.
+                        Mapped to wheelchairAccessible proto enum in GTFS-RT VehicleDescriptor:
+                        null → WHEELCHAIR_ACCESSIBLE_UNSPECIFIED (0), true → WHEELCHAIR_ACCESSIBLE (1), false → WHEELCHAIR_INACCESSIBLE (2).
+                        The OVAPI extension .transit_realtime.ovapiVehicleDescriptor.wheelchairAccessible retains the raw boolean/null value alongside the standard field.
         ICommonRunsMessagesModel:
             type: object
             properties:

package/docs/cache/types/redis.md

@@ -275,6 +275,7 @@ flowchart TD
   - `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:*
 
@@ -294,14 +295,29 @@ flowchart TD
 ### 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
+- 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`
 - 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í
+- Využití v endpointu přestupních tabulí (`/v4/pid/transferboards`)
 
 ### Flowchart (refresh)
 
@@ -528,3 +544,15 @@ flowchart LR
 ![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

package/docs/implementation_documentation.md

@@ -264,12 +264,14 @@ _:warning: Původním záměrem bylo využití OIS číselníku během zpracová
     -   baseUrl: module.pid.staticData.baseUrl
     -   departure directions url: module.pid.staticData.departuresDirection.path
     -   metro rail track url: module.pid.staticData.metroRailTracks.path
+    -   not public vehicles url: module.pid.staticData.notPublicVehicles.path
 -   formát dat
     -   protokol: http
-    -   datový typ: csv
+    -   datový typ: csv (DeparturesDirection, MetroRailTrack), json (NotPublicVehicles)
     -   validační schéma:
         -   [MetroRailTrack](../src/schema-definitions/datasources/static-data/MetroRailTrackJsonSchema.ts)
         -   [DeparturesDirection](../src/schema-definitions/datasources/static-data/DeparturesDirectionsJsonSchema.ts)
+        -   [NotPublicVehicles](../src/schema-definitions/datasources/static-data/interfaces/NotPublicVehiclesDataInterface.ts) – interface `INotPublicVehicles`
     -   příklad vstupnich dat: viz zdroj data
 -   frekvence stahování
     -   Po nacteni jizdnich radu (fronta: vehicle-positions.ropidgtfs.checkForNewData)
@@ -512,6 +514,9 @@ Všechny tabulky se nachází ve schématu `pid`
     -   [RopidGTFSRunNumbersTransformation](https://gitlab.com/operator-ict/golemio/code/modules/pid/-/blob/development/src/integration-engine/ropid-gtfs/transformations/RopidGTFSRunNumbersTransformation.ts)
     -   [RopidGtfsRouteSubAgencyTransformation](https://gitlab.com/operator-ict/golemio/code/modules/pid/-/blob/development/src/integration-engine/ropid-gtfs/transformations/RopidGtfsRouteSubAgencyTransformation.ts)
         -   on top of transformation functionality it also removes duplicates. Rule: If there are multiple rows with same `route_id` and `sub_agency_id` only the first with filled licence number is kept.
+-   rozšířené sloupce GTFS souborů (nestandardní rozšíření ROPID)
+    -   `trips.txt` – sloupec `headsign_icons`: řetězec dvouznakových kódů ikon (např. `"MbSb"`), uložen do `ropidgtfs_trips.headsign_icons`
+    -   `stop_times.txt` – sloupec `headsign_icons`: přepis na úrovni zastávky, uložen do `ropidgtfs_stop_times.headsign_icons`; má přednost před hodnotou z `trips.txt` pokud je zároveň vyplněn `stop_headsign`
 -   data modely
     -   RopidGTFSMetadataModel `ropidgtfs_metadata`
     -   RopidGTFSAgencyModel `ropidgtfs_agency`
@@ -562,6 +567,7 @@ Všechny tabulky se nachází ve schématu `pid`
     -   RopidGTFSPrecomputedMinMaxStopSequencesModel `ropidgtfs_precomputed_minmax_stop_sequences`
     -   RopidGTFSPrecomputedDeparturesModel `ropidgtfs_precomputed_departures`
     -   RopidGTFSPrecomputedTripScheduleModel `ropidgtfs_precomputed_trip_schedule`
+    -   RopidGTFSPrecomputedTripConnectionsModel `ropidgtfs_precomputed_trip_connections`
 
 #### task _RefreshPrecomputedTables_
 
@@ -581,6 +587,7 @@ Všechny tabulky se nachází ve schématu `pid`
     -   RopidGTFSPrecomputedMinMaxStopSequencesModel `ropidgtfs_precomputed_minmax_stop_sequences`
     -   RopidGTFSPrecomputedDeparturesModel `ropidgtfs_precomputed_departures`
     -   RopidGTFSPrecomputedTripScheduleModel `ropidgtfs_precomputed_trip_schedule`
+    -   RopidGTFSPrecomputedTripConnectionsModel `ropidgtfs_precomputed_trip_connections`
 
 #### task _RefreshPublicGtfsDepartureCacheTask_
 
@@ -596,8 +603,10 @@ Task se stará o aktualizaci cache pro public odjezdy. Pouští se pravidelně c
     -   ROPID FTP
 -   transformace
     -   [PublicDepartureCacheTransformation](../src/integration-engine/ropid-gtfs/transformations/PublicDepartureCacheTransformation.ts)
+        -   výsledný cache záznam obsahuje pole `connections` (garantované přestupy – přednačtené z `ropidgtfs_precomputed_trip_connections`, původně z `transfers.txt` kde `transfer_type = 1`) a pole `wheelchair_accessible` (přístupnost vozidla pro vozíčkáře z GTFS `trips.txt`)
+        -   pole `trip_headsign_icons`: pokud je pro danou zastávku spoje vyplněn `stop_headsign`, použije se `stop_headsign_icons` z `ropidgtfs_stop_times`; jinak se použije `headsign_icons` z `ropidgtfs_trips`; výsledek je řetězec dvouznakových kódů (např. `"MbMcSb"`) nebo `null`
 -   data modely
-    -   RopidGTFSPrecomputedDeparturesModel `ropidgtfs_precomputed_departures`
+    -   RopidGTFSPrecomputedDeparturesModel `ropidgtfs_precomputed_departures` (obsahuje JOIN na `ropidgtfs_precomputed_trip_connections_tmp` přes `to_trip_id` a `to_stop_id`)
 
 #### task _SaveStaticData_
 
@@ -613,9 +622,19 @@ Task se stará o aktualizaci statickych dat. Pouští se po dokončení načten
 -   transformace
     -   [DeparturesDirectionTransformation](../src/integration-engine/ropid-gtfs/workers/timetables/tasks/transformations/DeparturesDirectionTransformation.ts)
     -   [MetroRailtrackDataTransformation](../src/integration-engine/ropid-gtfs/workers/timetables/tasks/transformations/MetroRailtrackDataTransformation.ts)
+    -   `NotPublicVehicles` – data se ukládají přímo do cache klíče `config:notPublicVehicles` přes `NotPublicVehiclesRedisRepository` (žádná DB tabulka)
 -   data modely
     -   RopidDeparturesDirections `ropid_departures_directions`
     -   RopidGtfsMetroRailtrackGps `ropidgtfs_metro_railtrack_gps`
+    -   Cache `config:notPublicVehicles` – JSON blob struktury `INotPublicVehicles`:
+        ```json
+        {
+          "tram":  { "registrationNumbers": ["string"] },
+          "road":  { "registrationNumbers": ["string"] },
+          "routeIds": ["string"]
+        }
+        ```
+        `road` pokrývá autobusy i trolejbusy (evidenční čísla se mohou překrývat s tramvajemi, proto jsou oddělena). `routeIds` je whitelist číselných identifikátorů náhradních nebo dočasných linek (např. náhradní autobus za metro při výluce nebo mimořádné události), které se mají zobrazovat i bez platného JŘ spoje.
 
 
 
@@ -1062,6 +1081,18 @@ Worker má na starost generování souborů s realtime daty pro `gtfsrt` endpoin
     -   VPTripsModel `vehiclepositions_trips`
     -   VPPositionsModel `vehiclepositions_positions`
 
+**`wheelchairAccessible` ve VehicleDescriptor**
+
+Pole `wheelchairAccessible` je součástí standardního `VehicleDescriptor` ve feedech `vehicle_positions.pb` a `pid_feed.pb`:
+
+| Interní hodnota | Proto enum |
+|---|---|
+| `null` | `WHEELCHAIR_ACCESSIBLE_UNSPECIFIED = 0` |
+| `true` | `WHEELCHAIR_ACCESSIBLE = 1` |
+| `false` | `WHEELCHAIR_INACCESSIBLE = 2` |
+
+Zdrojem je pole `wheelchair_accessible` z tabulky `vehiclepositions_trips` (přenášené přes `IGtfsRtTripDto`). Vedle standardního pole zůstává zachováno rozšíření `.transit_realtime.ovapiVehicleDescriptor.wheelchairAccessible` s původní boolean/null hodnotou.
+
 **Určení zpoždění v trip_updates.pb**
 
 Predikce odjezdů probíhá podle vzorce:
@@ -1167,6 +1198,10 @@ Worker má na starost stahování VYMI (JIS) událostí a infotextů, jejich tra
 -   data modely
     -   JISEventsModel `jis_events`
     -   JISEventsRopidGTFSRoutesModel `jis_events_ropidgtfs_routes`
+-   poznámky k datovému modelu
+    -   pole `effects` je pole až 3 unikátních řetězců; v GTFS-RT `Alert.effect` se použije pouze `effects[0]`, zbývající hodnoty jsou dostupné pouze v custom-format exportu
+    -   pole `cause_detail` je volný text zpřesňující příčinu události; může být `null`
+    -   pole `cause` obsahuje překlady do češtiny i angličtiny; anglické hodnoty jsou zahrnuty i ve výstupu GTFS-RT alert feedu
 
 #### _task: RefreshJISInfotextsTask_
 
@@ -1261,7 +1296,7 @@ Worker má na starost stahování VYMI (JIS) událostí a infotextů, jejich tra
 -   retence dat
     -   jízdní řády se generují 1-2x denně na 14 dní dopředu
     -   polohová data si uchováváme 24 hodin (30 minut od poslední aktualizace, poté v historických tabulkách)
-    -   popis vozidel si uchováváme 24 hodin
+    -   popis vozidel se nepromazává – přetrvávají do přepsání novými daty (fixní TTL bylo odstraněno)
     -   preset logy si uchováváme 8 hodin
     -   JIS události a infotexty si uchováváme neomezeně
 
@@ -1404,6 +1439,12 @@ Worker má na starost stahování VYMI (JIS) událostí a infotextů, jejich tra
 
 -   zdrojové tabulky
     -   `ropidgtfs_precomputed_departures`, `ropidgtfs_stops`, `ropidgtfs_cis_stops`, `jis_infotexts`, `jis_infotexts_ropidgtfs_stops`, `ropid_departures_directions`, `vehiclepositions_positions`, `vehiclepositions_trips`
+-   odpověď obsahuje hlavičku `X-Golemio-Preset-Metadata: airConditionPossible=0|1`
+    -   `1` pokud byl zadán query parametr `airCondition` s pravdivou hodnotou, `0` jinak
+    -   slouží monitorovacím systémům (preset systémy monitorovacího centra ROPID) k detekci aktivního filtrování dle klimatizace
+-   kód nástupiště (`platform_code`)
+    -   **vlaky**: preferuje se CIS hodnota `cis_stop_platform_code` uložená z MPVNet zpráv (`PlatformCodeResolver`); MPVNet atribut `$.stan` je před uložením oříznut na první platný segment (viz [parsování `stan` u vlaků](../processing/input_realtime_data/http_mpvnet.md#parsování-stanoviště-stan-u-vlaků))
+    -   **ostatní typy**: používá se GTFS `platform_code` ze `stop_times.txt`
 
 ### PID Departure Boards v3
 
@@ -1411,6 +1452,42 @@ Worker má na starost stahování VYMI (JIS) událostí a infotextů, jejich tra
 
 -   načte odjezdy pro přestupní tabule ve vozidlech a aktivní infotexty exportované z aplikace VYMI (JIS) Infotexty
 
+### PID Departure Boards v4
+
+#### _/v4/pid/transferboards_
+
+-   načte odjezdy pro přestupní tabule ve vozidlech na základě aktuální polohy vozidla a aktivní infotexty exportované z aplikace VYMI (JIS) Infotexty
+-   parametry
+    -   `aswId` + `vehicleRegistrationNumber` + `routeType` – identifikace zastávky a vozidla přes ASW číselník (vzájemně se vylučuje s `cisId`+`tripNumber`)
+    -   `cisId` + `tripNumber` – identifikace zastávky a spoje přes CIS číselník (zatím neimplementováno, vrací 501)
+    -   `timeFrom` – volitelný ISO8601 čas příjezdu (pokud není zadán, použije se reálný čas příjezdu z RT dat)
+    -   `limit` – volitelný počet odjezdů (výchozí 8, max 30)
+-   cachováno na 5 sekund (stale-while-revalidate 5 sekund)
+-   zdrojové cache záznamy
+    -   `gtfsStopsCache:*` – převod ASW node ID na GTFS stop_id
+    -   `gtfsDelayComputation:*` – zjištění zastávek spoje a predikovaného času příjezdu
+    -   `vpPublicCache:*` – aktuální poloha a zpoždění vozidla
+    -   `gtfsPublicDepartureCache:*` – statické odjezdy ze zastávek (vč. `connections` a `wheelchair_accessible`)
+    -   `vpPublicStopTimeCache:*` – live zastávkové časy pro spoje se známou polohou
+    -   `jisCache:*` – aktivní infotexty pro dané zastávky
+-   načítání odjezdů z cache (`gtfsPublicDepartureCache`)
+    -   z každé zastávky se načte `max(80, min(120, limit × 10))` položek v časovém okně `[plannedTimeFrom − 61 min, plannedTimeFrom + 60 min + delay]`; lookback 61 minut zajišťuje, že se zachytí i navazující spoj, jehož plánovaný odjezd je v minulosti, ale díky vlastnímu zpoždění (až 60 minut) dorazí na zastávku až po příjezdu aktuálního vozidla
+    -   ihned po načtení se aplikuje pre-filter: odjezdy autobusů, tramvají a trolejbusů ze zastávek s jiným názvem než aktuální zastávka jsou zahozeny; metro/vlak/přívoz/lanovka procházejí vždy; odjezdy s neprázdným polem `connections[]` jsou zachovány bez ohledu na název zastávky (potenciální garantovaný přestup)
+-   garantované přestupy (`is_guaranteed_transfer`)
+    -   označují odjezdy, které na příjezd aktuálního spoje čekají – detekováno z pole `connections` v `gtfsPublicDepartureCache`, kde `from_trip_id` odpovídá aktuálnímu spoji a `arrivalTime < departure_datetime + max_wait_sec`
+    -   zobrazované minuty u garantovaného přestupu jsou nastaveny na čas příjezdu aktuálního spoje (ne na plánovaný odjezd navazujícího spoje)
+    -   garantované přestupy jsou vyjmuty z filtru opačného směru a filtru podskupiny linky – jsou přidány do `tripIdsToKeep` před spuštěním `findRelevantTripIdsFromLines`, takže projdou bez ohledu na zastávkovou sekvenci
+    -   typy "vždy zobrazit" (metro, vlak, přívoz, lanovka) filtr `findRelevantTripIdsFromLines` zcela přeskakují
+-   dostupnost pro vozíčkáře (`is_wheelchair_accessible`)
+    -   **metro**: určeno výhradně podle `wheelchair_boarding` zastávky (hodnota `1` = přístupná)
+    -   **ostatní typy dopravy**: primárně z RT dat vozidla (`detailed_info.is_wheelchair_accessible`); pokud RT data nejsou k dispozici, použije se GTFS příznak `wheelchair_accessible` z `trips.txt` (`1` = přístupné vozidlo)
+-   seskupování a omezení výstupu (`TransferDepartureCacheTransformation`)
+    -   **metro**: seskupuje se podle `route_short_name + stop_id`; na jeden záznam výstupu připadají až 2 hodnoty v poli `departure_timestamp.minutes[]`
+    -   **ostatní typy**: seskupuje se podle `route_short_name + direction_id`; na skupinu připadají nejvýše 2 samostatné záznamy odjezdů; `direction_id` se získává z cache poloh vozidel (klíč `route_short_name + trip_headsign`), výchozí hodnota je `0`
+-   konfigurace filtrování opačného směru (backtracking)
+    -   `module.pid.vehicle-positions.transferboards.isOppositeDirectionFilterStopNameStrict` (boolean, výchozí `true`) – pokud `true`, zastávka je považována za "zpětnou" pouze pokud se shoduje `stop_id` i `stop_name`; pokud `false`, stačí shoda `stop_id`
+    -   `module.pid.vehicle-positions.transferboards.countPreviousStopsToAllow` (integer, výchozí `0`) – kolik předchozích zastávek aktuálního spoje smí kandidátní spoj sdílet ve svých nadcházejících zastávkách, než je považován za zpětný směr a odfiltrován; `0` znamená žádná shoda není povolena
+
 #### _/v3/pid/infotexts_
 
 -  načte aktivní infotexty exportované z aplikace VYMI (JIS) Infotexty
@@ -1458,4 +1535,20 @@ Worker má na starost stahování VYMI (JIS) událostí a infotextů, jejich tra
     - podle názvů linek a jak daleko do budoucnosti se mají odjezdy navracet
     - limitování počtu odjezdů v každé skupině
 -   EP je optimalizován pro vyšší zátěž z mobilní aplikace PID lítačka - požadavek do databáze z OG pouze v případě nutnosti obnovit cache s vehicle descriptory (klimatizace, usb nabíječky), jinak je vše z Redisu
+-   deduplikace odjezdů (pro seskupení "jeden za linka+směr") se provádí podle klíče `route_id + trip_headsign + platform_code`; toto se liší od původního přístupu deduplikace podle `stop_id` a správně pokrývá situace, kdy jeden ASW uzel odpovídá více GTFS `stop_id`
+-   dostupnost pro vozíčkáře (`is_wheelchair_accessible`) se určuje v pořadí priority:
+    1. RT descriptor vozidla (`detailed_info.is_wheelchair_accessible` z vehicle positions)
+    2. GTFS statický příznak `wheelchair_accessible` z `trips.txt` (`1` = přístupné), pokud RT data nejsou k dispozici
 -   je použit `CompressionByDefaultMiddleware` a odpovědi jsou tak na output gateway komprimovány i pokud klient explicitně nepovolí komprimaci vhodnou hodnotou hlavičky `Accept-Encoding` (lze však komprimaci explicitně zakázat hodnotou `identity`)
+
+### JIS v1
+
+#### _/v1/jis/events/custom-format_
+
+-   vrátí seznam publikovaných událostí ve vlastním formátu pro externí konzumenty (fallback endpoint pro webhooky)
+-   parametry
+    -   `displayPeriodStart` / `displayPeriodEnd` – filtrování podle překryvu zobrazovacího okna události s požadovaným rozsahem (ISO 8601)
+    -   `organizationNames` – filtrování podle organizace (pole řetězců)
+    -   `type` – filtrování podle typu události (`INCIDENT`, `DISRUPTION`, `SERVICE_CHANGE`)
+-   zdrojové tabulky: `jis_events`, `jis_events_ropidgtfs_routes`
+-   formát odpovědi: viz schéma `EventCustomFormat` v [openapi-output.yaml](./openapi-output.yaml)

package/docs/jis/index.md

@@ -246,3 +246,20 @@ flowchart TB
 ```
 
 Zdroj a formát dat pro aktivní stahování jsou dále více popsány v implementační dokumentaci ([události](../implementation_documentation.md#jis-events), [infotexty](../implementation_documentation.md#jis-infotexts)), stejně tak jako [worker a tasky](../implementation_documentation.md#jisworker) a popis [uložení dat](../implementation_documentation.md#uložení-dat) včetně databázového schema a popisu retence.
+
+## Datový model událostí — vybraná pole
+
+### `cause_detail`
+
+Volitelné textové upřesnění příčiny události (`cause_detail`). Může být `null`. Dostupné v custom-format exportu (`/v1/jis/events/custom-format`) i v GTFS-RT alert feedu jako rozšíření. Struktura:
+```json
+{ "cs": "Nehoda na křižovatce", "en": null }
+```
+
+### `cause` — anglický překlad
+
+Pole `cause` obsahuje překlad příčiny události do češtiny i do angličtiny. Anglická hodnota je zahrnuta i ve výstupu GTFS-RT alert feedu (pole `Alert.cause` v `pid_feed.pb` i `alerts.pb`).
+
+### `effects` (pole příčin dopadu)
+
+Pole `effects` může obsahovat 1–3 unikátní řetězcové hodnoty. Pouze `effects[0]` se mapuje na standardní GTFS-RT `Alert.effect`; zbývající hodnoty jsou dostupné výhradně v custom-format exportu.

package/docs/processing/input_realtime_data/http_mpvnet.md

@@ -92,6 +92,27 @@
 ```
 
 ## Vlaky
+
+### Parsování stanoviště (`stan`) u vlaků
+
+Atribut `stan` v elementu `<zast>` u vlaků může obsahovat složený řetězec ve formátu `část1/část2` nebo `část1 část2` (např. `5S/22S`, `-/6`, `2/3`). Jako kanonický kód nástupiště se použije **první platný segment** – první token oddělený lomítkem nebo mezerou, pokud není prázdný nebo `-`.
+
+Příklady výsledků po parsování:
+
+| Vstup (`stan`) | Výsledný `platform_code` |
+|---|---|
+| `1/3` | `1` |
+| `-/BUS` | `BUS` |
+| `2/100V` | `2` |
+| `5A/- A C` | `5A` |
+| `5S/22S` | `5S` |
+
+Parsování provádí `MpvStopParser.parsePlatformCode()`. Výsledný kód je uložen jako `cis_stop_platform_code` v tabulce `vehiclepositions_positions` a na výstupu se pro vlaky preferuje před GTFS `platform_code` (viz `PlatformCodeResolver`).
+
+### Zprávy s informací o nástupišti jako syntetická poloha
+
+Pokud MPVNet zpráva vlaku obsahuje informaci o nástupišti (`$.stan`) pro budoucí zastávku a vlak ještě nemá žádnou aktivní RT polohu, vytvoří se syntetická poloha ve stavu `before_track` na základě dat z této zastávky. Díky tomu lze zobrazit kód nástupiště ještě před fyzickým příjezdem vlaku na stanoviště. Kód nástupiště se parsuje stejným způsobem jako výše (`MpvStopParser.parsePlatformCode()`).
+
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
 

package/docs/processing/state_position_tracking/http_mpvnet.md

@@ -13,6 +13,7 @@
     -   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
+    -   **syntetická poloha z informace o nástupišti**: pokud zpráva obsahuje atribut `$.stan` pro budoucí zastávku a vlak ještě nemá aktivní RT polohu, vytvoří se syntetická pozice ve stavu `before_track` pro tuto zastávku – umožňuje zobrazit kód nástupiště před fyzickým příjezdem vlaku
     -   spoje se pošlou do fronty `updateDelay`
 -   updateDelay
     -   opět duplikace vlakových spojů, upsert asociovaných pozic

package/docs/processing/state_position_tracking/tcp_dpp_common.md

@@ -33,6 +33,7 @@
                 -   pokud je pozice duplicitní (existuje pozice se stejným `origin_timestamp`), stav je `duplicate`
                 -   pokud vozidlo jede do garáže, je stav `invisible`
                 -   jinak je stav `after_track`
+            -   **zvláštní případ**: pokud má pozice `cis_last_stop_id = null`, stav se znovu nevyhodnocuje – pozice si zachovává poslední známý stav (zmrazení stavu); to zabraňuje nežádoucímu cyklování zpět do `untracked` pouze kvůli chybějící CIS zastávce
         -   Tracking (`tracking` je `2`)
             -   pokud je vozidlo 200 metrů od nejblizšího bodu na trase, stav je `off_track`
             -   pokud je vozidlo v zastávce, je stav `at_stop`

package/docs/processing/transferboards_filtering.md

@@ -0,0 +1,312 @@
+## v4/pid/transferboards filtering pipeline (newcomer guide)
+
+This section documents every filtering and transformation step executed by the `GET /v4/pid/transferboards` endpoint, in the order they actually run. The goal is to help a developer who is new to the codebase understand **what** each stage does, **why** it exists, and **where** the code lives.
+
+---
+
+### Overview
+
+The endpoint answers the question: _"Given that I am on vehicle X arriving at stop Y, which onward connections should I show on the transfer board?"_
+
+The answer is not simply "all departures from stop Y in the next hour" — many departures must be filtered out because they go back the way the passenger just came, or depart too soon to catch, or are irrelevant in-network transfers. The pipeline also specially handles **guaranteed transfers** (connections the operator has contractually promised to wait for).
+
+**Primary source files:**
+- `src/output-gateway/pid/controllers/v4/V4TransferBoardsController.ts` — orchestrates the full pipeline
+- `src/output-gateway/pid/service/facade/TransferFacade.ts` — fetches the cache, runs line-direction filters
+- `src/output-gateway/pid/helpers/TransferBoardFilter.ts` — static filter methods (time, name, deduplication)
+- `src/output-gateway/pid/helpers/TransferBoardSorter.ts` — sort pipeline
+- `src/output-gateway/pid/service/transformations/TransferDepartureCacheTransformation.ts` — output grouping/capping
+
+---
+
+### Stage 1 — Request validation and parameter parsing
+
+**Where:** `V4PIDRouter.ts` (validation middleware) + `V4TransferBoardsController.ts` (top of `getTransferBoards`)
+
+The endpoint accepts two mutually exclusive identification modes:
+
+- **ASW mode** — `aswId` + `vehicleRegistrationNumber` + `routeType`
+- **CIS mode** — `cisId` + `tripNumber` (returns HTTP 501; not yet implemented)
+
+If neither set of params is provided, or both are, validation rejects the request early. CIS mode always returns `501 Not Implemented`.
+
+---
+
+### Stage 2 — Stop resolution (ASW → GTFS stop IDs)
+
+**Where:** `TransferFacade.getTransferCache()` → `gtfsStopsCache:*`
+
+A single ASW node can map to multiple GTFS `stop_id` values (e.g. platforms A and B at the same tram stop). The facade:
+
+1. Looks up all GTFS `stop_id` values for the given `aswId` from `gtfsStopsCache:{aswId}`.
+2. Fetches the stop names for those `stop_id` values.
+3. Groups them into **same-name clusters** — stops that share a `stop_name` (e.g. both platforms of "Náměstí Míru") are treated as one logical transfer point.
+
+This grouping matters later: only departures from stops in the same cluster pass the same-stop-name filters.
+
+---
+
+### Stage 3 — Current vehicle lookup
+
+**Where:** `V4TransferBoardsController.ts` + `vpPublicStopTimeCache:*`
+
+The controller looks up the arriving vehicle's trip data using `service-{routeType}-{registrationNumber}` as the key into `vpPublicStopTimeCache`. For buses, a fallback to the trolleybus key is tried if the bus key is missing (registration numbers are shared between the two types).
+
+This gives the controller the vehicle's **current `trip_id`** (called `currentTripId` throughout the codebase), which is central to guaranteed transfer detection and direction filtering.
+
+If the vehicle is not found in the stop-time cache, the response is `404 Not Found`.
+
+---
+
+### Stage 4 — Arrival time detection
+
+**Where:** `V4TransferBoardsController.ts` → `gtfsDelayComputation:{tripId}`
+
+The controller reads the vehicle's current trip from `gtfsDelayComputation`, which contains a per-stop array with both planned and predicted (delayed) times. It finds the entry for the target stop and extracts:
+
+- `plannedTimeFrom` — the GTFS scheduled arrival time at this stop
+- `delayedTimeFrom` — the real-time predicted arrival time (may differ due to delays)
+
+Both values are used to set the departure cache query window in the next stage.
+
+---
+
+### Stage 5 — Departure cache fetch
+
+**Where:** `TransferFacade.getTransferCache()` → `gtfsPublicDepartureCache:*`
+
+The facade fetches candidates from `gtfsPublicDepartureCache:{stopId}` (a Redis sorted set, scored by planned departure timestamp) for each GTFS `stop_id` in scope.
+
+**Time window:**
+```
+from  = plannedTimeFrom − 61 minutes
+to    = plannedTimeFrom + 60 minutes + delayMinutes
+```
+
+The 61-minute lookback exists to catch transfer lines whose scheduled departure is in the past but which may still arrive at the stop after the current vehicle due to their own delay of up to 60 minutes.
+
+**Fetch limit:** `max(80, min(120, limit × 10))` items per stop. The wide over-fetch ensures that enough candidates survive later filtering to fill the requested `limit`.
+
+---
+
+### Stage 6 — Self-removal
+
+**Where:** `V4TransferBoardsController.ts`
+
+The current vehicle's own trip (`currentTripId`) is removed from the candidate list. It should never appear as a "transfer option" for itself.
+
+---
+
+### Stage 7 — Pre-filter: bus/tram/trolleybus at wrong-name stops
+
+**Where:** `TransferFacade.getTransferCache()` (inline, before returning)
+
+Before the expensive line-direction filter runs, a cheap pre-filter drops departures that are:
+- Route type **bus, tram, or trolleybus** (metro/train/ferry/funicular pass through unconditionally)
+- From a stop whose `stop_name` differs from the current stop's name
+
+**Exception:** if the departure has a non-empty `connections[]` array (meaning it is a possible guaranteed transfer), it is kept regardless of stop name. This is because a guaranteed transfer bus might legitimately be at a different-named stop.
+
+This pre-filter is a performance optimization — it eliminates obviously irrelevant candidates before the costlier stages.
+
+---
+
+### Stage 8 — Sort + real-time vehicle position join
+
+**Where:** `V4TransferBoardsController.ts`
+
+Remaining candidates are sorted by `departure_datetime` ascending, then each is joined with live vehicle positions from `vpPublicCache` (if the trip has an active vehicle). This enriches each candidate with:
+
+- `predictedDepartureDate` / `predictedDepartureTimestamp` — the RT-adjusted departure time
+- `is_wheelchair_accessible` — resolved from the RT vehicle descriptor if available (see Stage 9)
+
+---
+
+### Stage 9 — Wheelchair accessibility resolution
+
+**Where:** `DepartureBoardMapper.determineWheelchairAccessibility()`
+
+For each candidate departure, accessibility is determined differently by mode:
+
+| Mode | Source |
+|---|---|
+| **Metro** | `wheelchair_boarding` from the GTFS stop (stop-level, static) |
+| **All other** | `real_wheelchair_accessible` from the RT vehicle descriptor (boolean), or if absent: GTFS static `wheelchair_accessible` (trip-level, `GtfsTripWheelchairAccessEnum`) |
+
+The fallback to GTFS static data is the fix introduced in v5.7.1 (item 3 above).
+
+---
+
+### Stage 10 — Guaranteed transfer detection
+
+**Where:** `V4TransferBoardsController.ts` (`havingConnectionFromTripId`)
+
+A departure is a **guaranteed transfer** (Czech: _zaručený přestup_) when:
+
+1. Its `connections[]` array contains an entry where `from_trip_id === currentTripId`, AND
+2. The current vehicle's predicted arrival time is within the wait window:
+   ```
+   vehicleArrivalMs < departurePlannedMs + max_wait_sec × 1000
+   ```
+
+Guaranteed transfers receive special treatment in all subsequent stages — they can bypass nearly every filter and are always shown if time constraints allow.
+
+The result is two sets: `guaranteedTripIds` and `guaranteedConnections`.
+
+---
+
+### Stage 11 — Minimal transfer time filter
+
+**Where:** `TransferBoardFilter.minimalTransferTime()`
+
+Departures whose scheduled time is too close to the vehicle's arrival are dropped — there is not enough time for passengers to board. Thresholds differ by mode:
+
+| Mode | Minimum gap |
+|---|---|
+| Bus, tram, trolleybus | 60 seconds |
+| Metro, train, ferry, funicular | 120 seconds |
+
+**Guaranteed transfers are exempt** from this filter — the operator has guaranteed the connection, so time is irrelevant.
+
+---
+
+### Stage 12 — Same-stop-name filter (Stage 2)
+
+**Where:** `TransferBoardFilter.sameStopNameTransfer()`
+
+A second pass of the stop-name check, applied after guaranteed transfers are identified. Rules:
+
+- Bus/tram/trolleybus at a stop with a different name than the arrival stop → **dropped**
+- Metro/train/ferry/funicular → **kept** (they serve different physical locations by design)
+- Any trip in `guaranteedTripIds` → **kept** (guaranteed transfer exemption)
+- Any trip in `keepAlwaysTripIds` (see Stage 14) → **kept**
+
+This stage is separate from the Stage 7 pre-filter because at Stage 7 we did not yet know which trips were guaranteed.
+
+---
+
+### Stage 13 — Categorise trips for line-direction filter
+
+**Where:** `V4TransferBoardsController.ts`
+
+Before running the expensive direction filter, the controller categorises remaining candidates:
+
+- **Always keep:** guaranteed transfers + "keep always" types (metro, train, ferry, funicular)
+- **Needs filtering:** everything else (bus, tram, trolleybus that are not guaranteed)
+
+Only the "needs filtering" set is passed to `findRelevantTripIdsFromLines`. This avoids running direction analysis on trips that will be kept unconditionally.
+
+---
+
+### Stage 14 — Guaranteed transfer time adjustment
+
+**Where:** `V4TransferBoardsController.ts`
+
+For guaranteed transfers, the displayed departure time is **replaced** with the arriving vehicle's own predicted arrival time. This is the time the bus/tram will actually wait until, so showing the vehicle's arrival time as the "departure" is more useful to passengers than the originally scheduled departure time.
+
+---
+
+### Stage 15 — Sort (pre-output)
+
+**Where:** `TransferBoardSorter.sort()`
+
+A four-criterion stable sort applied before the direction filter:
+
+1. **Metro first** — metro departures before all others
+2. **Metro name ascending** — within metro, sort by `route_short_name` (A before B before C)
+3. **Departure time ascending** — earlier departures first
+4. **`direction_id` ascending** — tiebreaker for trips with identical departure times
+
+---
+
+### Stage 16 — Line-direction filter (`findRelevantTripIdsFromLines`)
+
+**Where:** `TransferFacade.findRelevantTripIdsFromLines()`
+
+This is the most complex stage. It determines whether each candidate trip is going somewhere _new_ for the passenger, or whether it is effectively doubling back along the route the passenger just arrived on.
+
+For each candidate trip, the facade loads its stop sequence from `gtfsDelayComputation` or `vpPublicStopTimeCache`. It then applies two sequential sub-filters:
+
+#### Sub-filter A: Forward-subset check (`filterOutForwardSubgroupOfLine`)
+
+**Question:** Does this candidate trip's future stops form a strict subset of the current vehicle's future stops?
+
+If every stop the candidate will visit is also a future stop on the current vehicle's route, then there is no point transferring — the passenger will get there anyway without changing. Such trips are **dropped**.
+
+**Example:** Current vehicle is bus 207 going A→B→C→D. Candidate bus 150 goes B→C. Since B and C are both future stops of 207, transferring to 150 is redundant → dropped.
+
+#### Sub-filter B: Backtracking conflict check (`filterOutLinesWithBacktrackingConflict`)
+
+**Question:** Do this candidate trip's next N stops overlap with the current vehicle's previous N stops in a way that suggests it is heading back the same way?
+
+Configured by `countPreviousStopsToAllow` (default `0`). The value defines how many of the current vehicle's previous stops the candidate trip is allowed to share in its upcoming stops. If the candidate shares more than that number, it is **dropped** (it's going backwards). `0` means no overlap is permitted at all.
+
+The strictness of the stop matching is controlled by `isOppositeDirectionFilterStopNameStrict` (default `true`): when true, both `stop_id` AND `stop_name` must match; when false, only `stop_id`.
+
+---
+
+### Stage 17 — Combine approved trip IDs
+
+**Where:** `TransferBoardFilter.keepAlwaysLinesAndTripIds()`
+
+The final set of approved trip IDs is the union of:
+- `guaranteedTripIds` (from Stage 10)
+- `keepAlwaysTripIds` (metro/train/ferry/funicular, from Stage 13)
+- Trips that passed the direction filter (from Stage 16)
+
+All other trips are discarded from the candidate list here.
+
+---
+
+### Stage 18 — Output grouping and per-route cap
+
+**Where:** `TransferDepartureCacheTransformation.transform()`
+
+Before the final limit is applied, departures are grouped by route and capped to prevent one line from dominating the board:
+
+| Mode | Grouping key | Cap |
+|---|---|---|
+| **Metro** | `route_short_name + stop_id` | 2 departure times merged into one `departure_timestamp.minutes[]` entry |
+| **Non-metro** | `route_short_name + direction_id` | 2 separate departure entries per group |
+
+For non-metro, `direction_id` is taken from the live vehicle positions cache (keyed by `route_short_name + trip_headsign`), defaulting to `0` when not available.
+
+---
+
+### Stage 19 — Final filter: limit, time window, deduplication
+
+**Where:** `TransferBoardFilter.filterDepartures()`
+
+The last stage applies three rules:
+
+1. **Time window cut:** departures after `arrivalTime + 1 hour` are dropped.
+2. **Trip deduplication:** if two entries share the same `trip_id`, only the first (earliest) is kept.
+3. **Limit:** the result is truncated to the requested `limit` (query parameter, default typically 10).
+
+**Guaranteed transfers are exempt from the time window and limit** — they always appear regardless of how many other results there are, as long as they are still within the `max_wait_sec` window.
+
+---
+
+### Quick reference: which filter each vehicle type is subject to
+
+| Filter | Bus/Tram/Trolleybus | Metro/Train/Ferry/Funicular | Guaranteed transfer |
+|---|---|---|---|
+| Stage 7 pre-filter (wrong stop name) | Yes | No | No (exempt) |
+| Stage 11 min transfer time | Yes (60 s) | Yes (120 s) | **No** |
+| Stage 12 same-stop-name | Yes | No | **No** |
+| Stage 16 direction filter | Yes | **No** | **No** |
+| Stage 17 combine | All types pass via their category | — | — |
+| Stage 18 per-route cap (2 entries) | Yes | Yes (metro grouped differently) | Yes |
+| Stage 19 limit | Yes | Yes | **No** |
+
+---
+
+### Key Redis keys used
+
+| Key pattern | Purpose |
+|---|---|
+| `gtfsStopsCache:{aswId}` | ASW node → GTFS stop_id mapping |
+| `gtfsPublicDepartureCache:{stopId}` | Sorted set of precomputed departures (score = departure Unix timestamp) |
+| `gtfsDelayComputation:{tripId}` | Per-trip RT stop times, delay, shapes |
+| `vpPublicStopTimeCache:{vehicleKey}` | Per-vehicle stop time lookup (used to identify current trip) |
+| `vpPublicCache:*` | Geo-indexed real-time vehicle positions |

package/package.json

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