@golemio/pid 5.8.3 → 5.8.4-dev.2436767567

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.
 
 #### task _EnsureCacheTask_
 
@@ -1086,6 +1105,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:
@@ -1191,6 +1222,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_
 
@@ -1285,7 +1320,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ě
 
@@ -1428,6 +1463,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
 
@@ -1435,6 +1476,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
@@ -1482,4 +1559,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/openapi-output.yaml

@@ -1022,6 +1022,16 @@ paths:
                       type: number
                       format: int64
                       example: 0
+                - name: appendHeadsignsLimit
+                  in: query
+                  description: >-
+                      Number of stops before route switch at which headsign is enriched with continuation info.
+                      When set and a departure has route-switch data, headsign becomes `<headsign> → <next_route> <next_headsign>`.
+                  required: false
+                  schema:
+                      type: integer
+                      minimum: 0
+                      example: 3
 
             responses:
                 "200":
@@ -2644,7 +2654,9 @@ components:
                     example: false
                 origin_timestamp:
                     type: string
-                    description: Time at which the position was sent from the vehicle (UTC)
+                    description: >
+                        Transmission time of the message from the vehicle (UTC).
+                        Corresponds to the lat/lng position reported in the same message.
                     example: "2019-03-18T11:00:00.000Z"
                 speed:
                     type: number
@@ -2766,7 +2778,10 @@ components:
                     example: "top-left"
                 headsign:
                     type: string
-                    description: Trip headsign (usually the final stop).
+                    description: >-
+                        Trip headsign (usually the final stop). When the `appendHeadsignsLimit` parameter is used and the departure
+                        has route-switch data, this field may contain appended continuation info in the form
+                        `<headsign> → <next_route> <next_headsign>`.
                     example: "Chodov"
                 id:
                     type: string
@@ -3175,7 +3190,9 @@ components:
                 origin_timestamp:
                     type: string
                     nullable: true
-                    description: "time when vehicle send last update"
+                    description: >
+                        Transmission time of the last message from the vehicle.
+                        Corresponds to the lat/lng position reported in the same message.
                     example: "2023-12-06T12:00:00+01:00"
 
         ScopeStaticInfo:

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/input_realtime_data/tcp_dpp_bus.md

@@ -15,11 +15,11 @@
 - **lat** - zeměpisná šířka
 - **lng** - zeměpisná délka
 - **akt** - poslední projetá zastávka, nepoužíváme
-- **takt** - timestamp odeslání zprávy z vozidla
+- **takt** - čas události (reálný čas příjezdu/odjezdu vozidla na zastávce); mapuje se na `scheduled_timestamp`
 - **konc** - poslední ASW zastávka spoje, nepoužíváme
-- **tjr** - timestamp odeslání zprávy podle JŘ (v jaký čas mělo vozidlo na daném bodě být)
+- **tjr** - plánovaný čas podle jízdního řádu (v jaký čas mělo vozidlo na daném bodě být); nepoužíváme pro určení pozice
 - **pkt** -  identifikátor zprávy z vozidla/číslo TCP packetu??? Nepoužíváme
-- **tm** - timestamp odeslání zprávy od DPP
+- **tm** - čas přenosu zprávy od DPP (transmission time); odpovídá aktuální zeměpisné poloze vozidla (lat/lng); mapuje se na `origin_timestamp`
 - **events** -  událost asociovaná se zprávou
 	- P - příjezd do zastávky
 	- O - odjezd ze zastávky

package/docs/processing/input_realtime_data/tcp_dpp_tram.md

@@ -14,11 +14,11 @@
 - **lat** - zeměpisná šířka
 - **lng** - zeměpisná délka
 - **akt** - poslední projetá zastávka, nepoužíváme
-- **takt** - timestamp odeslání zprávy z vozidla
+- **takt** - čas události (reálný čas příjezdu/odjezdu vozidla na zastávce); mapuje se na `scheduled_timestamp`
 - **konc** - poslední ASW zastávka spoje, nepoužíváme
-- **tjr** - timestamp odeslání zprávy podle JŘ (v jaký čas mělo vozidlo na daném bodě být)
+- **tjr** - plánovaný čas podle jízdního řádu (v jaký čas mělo vozidlo na daném bodě být); nepoužíváme pro určení pozice
 - **pkt** -  identifikátor zprávy z vozidla/číslo TCP packetu??? Nepoužíváme
-- **tm** - timestamp odeslání zprávy od DPP
+- **tm** - čas přenosu zprávy od DPP (transmission time); odpovídá aktuální zeměpisné poloze vozidla (lat/lng); mapuje se na `origin_timestamp`
 - **events** -  událost asociovaná se zprávou
 	- P - příjezd do zastávky
 	- O - odjezd ze zastávky

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

@@ -14,7 +14,7 @@
         -   pokud je tramvaj, je `tracking 2`
         -   nebo pokud je autobus
             -   pokud vozidlo odeslalo zprávu `O`, je `tracking 2`
-            -   pokud je vozidlo v první zastávce (tjr), nebo pokud vozidlo vyjelo z první zastávky (takt), je `tracking 2`
+            -   pokud je vozidlo v první zastávce (dle `tjr` — plánovaný čas JŘ), nebo pokud vozidlo vyjelo z první zastávky (dle `takt` — čas události), je `tracking 2`
         -   nebo je `tjr` atribut větší než příjezd do první zastávky spoje, je `tracking 2`
         -   jinak je `tracking 0`
     -   Rovněž se podle kmenové linky a oběhu vytvoří následující spoje (stav je `unknown`, `tracking` je vždy 0)
@@ -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`