@golemio/pid 5.7.2 → 5.7.3-dev.2378110705

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,43 @@ 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
+
+## Manuální refresh cache (EnsureCacheTask)
+
+`EnsureCacheTask` slouží jako manuální spouštěč obnovy všech 4 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 4 cílových front. Dvě z nich míří do různých workerů (cross-worker routing přes RabbitMQ exchange), dvě 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 refreshJISInfotextsCache`"]
+
+    trigger --> task
+    task -- cross-worker --> exchange_vp --> q1
+    task -- same-worker --> exchange_self --> q2
+    exchange_self --> q3
+    task -- cross-worker --> exchange_jis --> q4
+```
+

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"]
+}

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,39 @@ 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.
+
+#### task _EnsureCacheTask_
+
+Task slouží jako ruční spouštěč obnovení všech cache. Nespouští se automaticky – pouze manuálním odesláním zprávy do fronty.
+
+-   vstupní rabbitmq fronta
+    -   název: vehicle-positions.ropidgtfs.ensureCache
+    -   TTL: 5 minut
+    -   parametry: žádné
+-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
+    -   název: vehicle-positions.vehiclepositions.refreshGTFSTripData
+    -   název: vehicle-positions.ropidgtfs.refreshPublicGtfsDepartureCache
+    -   název: vehicle-positions.ropidgtfs.refreshGtfsStopsCache
+    -   název: vehicle-positions.jis.refreshJISInfotextsCache
+-   datové zdroje
+    -   žádné
+-   transformace
+    -   žádné
+-   data modely
+    -   žádné
 
 
 
@@ -1062,6 +1101,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 +1218,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 +1316,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 +1459,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 +1472,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 +1555,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`