@golemio/pid 6.4.0 → 6.4.1-dev.3054859807

package/docs/jis/delayed-segments.md

@@ -0,0 +1,241 @@
+# Zpožděné úseky – podklad pro automatické infotexty
+
+Stránka popisuje, jak datová platforma Golemio připravuje pro VYMI podklad pro automatické infotexty o zpožděných úsecích sítě PID ([vymi-general#365](https://gitlab.com/operator-ict/golemio/jis/vymi-alerts/vymi-general/-/work_items/365)): záměr, architekturu řešení, algoritmus zpracování, datový model, výstupní API, výkon, konfiguraci, provoz, známá omezení a klíčová rozhodnutí. Stručný přehled pro odběratele je v [index.md](./index.md#zpožděné-úseky--podklad-pro-automatické-infotexty-get-v1jisdelayed-segments), technické údaje workeru a endpointu v [implementační dokumentaci](../implementation_documentation.md#task-refreshdelayedsegmentstask).
+
+## Záměr
+
+Při velkém zpoždění na úseku sítě (typicky kolona nebo nehoda) mají cestující na odjezdových tabulích dostat informaci, že spoje určitých linek v daném místě nabírají zpoždění. Dispečeři ROPID takové infotexty dnes zadávají ručně. Cílem je, aby je VYMI navrhovalo nebo zakládalo automaticky.
+
+Zpožděné úseky již počítá webová [Mapa PID](https://mapa.pid.cz/) z poloh vozidel Golemia, samotná informace o úseku ale pro infotext nestačí. Je třeba vědět, které linky úsekem jezdí a na kterých zastávkách s odjezdovými tabulemi má smysl infotext zobrazit. Odpovědnosti jsou proto rozděleny takto:
+
+| Kdo | Odpovědnost |
+| --- | --- |
+| Mapa PID | detekce zpožděných úseků a odhad zpoždění |
+| Golemio (modul pid) | pravidelné stažení úseků, obohacení o GTFS data (zastávky úseku, dotčené linky, zastávky s tabulemi a jejich vzdálenost od úseku), uložení a poskytnutí přes interní API |
+| VYMI | párování úseků v čase, rozhodnutí o vzniku, úpravě a ukončení události a infotextů, jejich text a výběr tabulí |
+
+Golemio tedy nerozhoduje o infotextech, poskytuje jen fakta potřebná k rozhodnutí. VYMI si úseky stahuje každých 5 minut a zakládá z nich interní události s infotexty jménem uživatele `OICT_Robot`; ve zkušebním provozu jen u úseků poblíž testovacích zastávek (Vozovna Střešovice B 876/2, U Památníku B 789/2) a za přepínačem v konfiguraci, podrobně viz [dokumentace VYMI](https://gitlab.com/operator-ict/golemio/jis/vymi-alerts/vymi-alerts-backend/-/blob/master/docs/delayed-segments.md). Rozhraní je navrženo nezávisle na zdroji úseků (viz [Kontrakt API](#kontrakt-api)), aby šlo zdroj v budoucnu vyměnit nebo doplnit bez změny pro VYMI.
+
+## Architektura
+
+```mermaid
+flowchart LR
+    mapa["Mapa PID<br/>(detekce zpožděných úseků)"]
+    cron["Cron Tasks<br/>(každých 5 minut)"]
+    rabbit[("RabbitMQ<br/>vehicle-positions.jis.refreshDelayedSegments")]
+    ie["VP Integration Engine<br/>RefreshDelayedSegmentsTask"]
+    pg[("PostgreSQL<br/>jis_delayed_segments<br/>+ GTFS tabulky")]
+    og["VP Output Gateway<br/>GET /v1/jis/delayed-segments"]
+    proxy["Access Proxy<br/>(interní role)"]
+    vymi["VYMI<br/>(automatické infotexty)"]
+
+    cron --> rabbit --> ie
+    mapa -. "HTTP JSON" .-> ie
+    ie <--> pg
+    pg -. "čtení" .-> og
+    vymi -. "HTTP JSON" .-> proxy -.-> og
+```
+
+Plná šipka znamená aktivní posílání, přerušovaná stahování příjemcem. Integration Engine si úseky z Mapy PID stahuje, obohacuje je dotazem nad GTFS daty ve stejné databázi a výsledek ukládá do tabulky `jis_delayed_segments`. Output Gateway tabulku jen čte. VYMI si data stahuje z interního endpointu, přístup je omezen rolí v Access Proxy.
+
+Průběh jednoho běhu:
+
+```mermaid
+sequenceDiagram
+    participant cron as Cron Tasks
+    participant task as RefreshDelayedSegmentsTask
+    participant db as PostgreSQL
+    participant mapa as Mapa PID
+
+    cron->>task: zpráva do fronty (každých 5 minut)
+    task->>task: detectedAt = čas stažení
+    task->>mapa: POST bez vozidel a tvarů úseků
+    mapa-->>task: zpožděné úseky celé sítě
+    task->>task: filtr podle zpoždění, převod krajních zastávek na ASW id
+    task->>db: úseky s obohacením mladším než TTL
+    db-->>task: znovupoužitelná obohacení
+    task->>db: obohacení ostatních úseků (jeden dotaz pro všechny)
+    db-->>task: zastávky, linky, zastávky s tabulemi
+    task->>db: v transakci upsert všech úseků a smazání nedetekovaných
+```
+
+## Zdroj dat: Mapa PID
+
+Mapa PID počítá zpožděné úseky průběžně z poloh vozidel. Úsek vzniká sloučením navazujících zpožděných mezizastávkových úseků, jeho odhadované zpoždění (`expected_delay`, v sekundách) je součtem zpoždění sloučených částí. Úseky se proto v čase prodlužují, zkracují a štěpí.
+
+Golemio volá interní endpoint webové Mapy PID (adresa je jen v konfiguraci, `module.pid.jis.delayedSegments.url`). Endpoint vrací zpožděné úseky vždy pro celou síť bez ohledu na zobrazenou oblast mapy. Požadavek proto posílá prázdnou oblast (`bounds`) a vypnuté tvary úseků (`show_delay_sections: false`), aby odpověď neobsahovala vozidla ani geometrie a byla co nejmenší. Z odpovědi se používá jen pole `delay_shapes`, validované schématem [MapaPidDelayShapesJsonSchema](../../src/schema-definitions/jis/datasources/MapaPidDelayShapesJsonSchema.ts). Krajní zastávky úseku jsou v něm identifikované stop id ve formátu Mapy PID (např. `U1347Z2`, železniční body `T…`).
+
+Endpoint není veřejné API. Úpravy na straně Mapy PID nejsou v naší moci, řešení proto pracuje s jeho současným chováním (viz [Známá omezení](#známá-omezení-a-rizika)).
+
+## Zpracování
+
+Zpracování obstarává [RefreshDelayedSegmentsTask](../../src/integration-engine/jis/workers/tasks/RefreshDelayedSegmentsTask.ts) a [JISDelayedSegmentsDataService](../../src/integration-engine/jis/services/JISDelayedSegmentsDataService.ts):
+
+1. **Čas detekce.** Před stažením se zaznamená `detectedAt`. Všechny úseky jednoho běhu mají stejný čas poslední detekce a od něj se počítá i časové okno obohacení.
+2. **Stažení.** Chyba stažení nebo neplatná odpověď ukončí běh chybou a uložené úseky zůstanou beze změny. Prázdný seznam úseků je platná odpověď a uložené úseky smaže.
+3. **Filtr podle zpoždění.** Úseky se zpožděním pod `minDelaySeconds` (výchozí 300 s) se zahodí. VYMI si minimum zvyšuje parametrem `minDelaySeconds` endpointu (viz [Kontrakt API](#kontrakt-api)).
+4. **Krajní zastávky na ASW id.** Stop id Mapy PID se převede na ASW id (`uzel/sloupek`, např. `U1347Z2` → `1347/2`). Z ASW id krajních zastávek se skládá `id` úseku `{uzel}/{sloupek}-{uzel}/{sloupek}`. Úseky, jejichž krajní zastávky ASW id nemají (železniční body `T…`), se zahodí.
+5. **Obohacení.** Všechny úseky se v každém běhu obohatí jedním dotazem (viz [Obohacení](#obohacení)), každé `id` jen jednou. Obohacené úseky by šly pro optimalizaci cachovat, ale v prvotní implementaci to bylo prozatím vynecháno (bude-li v budoucnu potřeba, lze najít hotovou implementaci v Git historii).
+6. **Vyřazení a duplicity.** Úsek se zahodí, pokud jeho krajní zastávky v GTFS neexistují, pokud ho v časovém okně žádný spoj neprojíždí celý (viz [Známá omezení](#známá-omezení-a-rizika)) nebo pokud nemá dotčené linky. Vyřazené úseky se počítají podle důvodu. Varianty stop id jedné fyzické zastávky mohou vést na stejné `id`; z duplicit se ponechá úsek s největším zpožděním.
+7. **Uložení.** V jedné transakci se všechny úseky upsertují (`updated_at = detectedAt`, `created_at` zůstává z první detekce) a úseky, které v běhu nebyly, se smažou. Úsek, který se později znovu objeví, začíná s novým `created_at`, stejně jako úsek se změněným `id`; `first_detected_at` je proto začátek aktuální nepřerušené detekce.
+
+## Obohacení
+
+Obohacení odvozuje z GTFS dat (předpočítané odjezdy `ropidgtfs_precomputed_departures`, spoje, zastávky a presety odjezdových tabulí) tři údaje. Počítá je dotaz [JISDelayedSegmentEnrichmentQuery](../../src/integration-engine/jis/repositories/helpers/JISDelayedSegmentEnrichmentQuery.ts) najednou pro všechny úseky běhu. Uvažují se jen odjezdy v okně ± `routeTimeWindowMinutes` (výchozí 120 min) od `detectedAt` a jen pravidelné spoje (`exceptional = 0`; výjimečné spoje jsou jednorázové spoje na konkrétní den, např. náhradní doprava). Okno zasahuje i do minulosti, protože zpožděný spoj s odjezdem plánovaným dříve může být v úseku ještě teď (spoj plánovaný na 13:00 může úsekem projíždět ve 13:45).
+
+**Párování podle ASW id.** Jedna fyzická zastávka může mít v GTFS více stop id (zónové a dočasné varianty, např. `U9904Z1P` a `U9904Z1`), presety tabulí přitom bývají přiřazené jen k jedné z nich. Zastávky se proto všude párují podle ASW id, nikoli podle GTFS stop id.
+
+### Zastávky úseku
+
+Zastávky mezi krajními zastávkami (včetně nich) na spojích, které v časovém okně projíždějí celý úsek, sloučené podle ASW id a seřazené podél úseku. Pořadí určuje relativní poloha zastávky na spoji (0 na začátku úseku, 1 na konci), nejmenší ze všech spojů, aby se spoje vynechávající některé zastávky (např. rychlík A→D a zastávkový spoj A→B→C→D) shodly na krajních zastávkách. Pokud dvě větve úseku řadí společnou zastávku různě daleko od začátku, může být pořadí zastávek mezi větvemi přeházené; párování ve VYMI pořadí nepoužívá. Úsek, kterým v okně žádný spoj celý neprojíždí, nemá zastávky ani dotčené linky a zahodí se. Zastávku úseku reprezentuje abecedně první GTFS stop id ze všech jejích variant, nejen z těch, které obsluhují spoje v okně, aby se id mezi běhy neměnilo (VYMI podle něj páruje úseky). Zastávky bez ASW id (např. železniční body `T…`) mezi zastávky úseku nepatří.
+
+### Dotčené linky
+
+Linky, jejichž spoj v časovém okně projede alespoň jeden mezizastávkový úsek mezi dvěma zastávkami úseku, a to ve směru úseku. Směr se neurčuje z pořadí zastávek úseku, ale z dvojic zastávek, které některý spoj jedoucí celým úsekem navštíví v tomto pořadí; platí tak i pro větve, které společnou zastávku řadí různě. Spoj tedy nemusí jet celým úsekem. Linka, která úseku jen dotkne krajní zastávkou nebo jede opačným směrem, dotčená není.
+
+### Zastávky s tabulemi a jejich vzdálenost
+
+Zastávky s presetem odjezdové tabule na dotčených spojích do vzdálenosti `maxInfoPanelDistanceStops` (výchozí 5) zastávek od úseku. Pro každou zastávku se uvádí seznam presetů a pro každou dotčenou linku vzdálenost od úseku ve stanicích se znaménkem:
+
+```text
+spoj linky X:  P0 ─ P1 ─ P2 ─ [A ─ B ─ C ─ D] ─ N1
+vzdálenost:    -3   -2   -1    0   0   0   0    +1
+```
+
+Záporná vzdálenost je před úsekem (tabule, kde cestující nastupují do spojů, které teprve úsekem pojedou), nula v úseku, kladná za úsekem. Pokud spoje jedné linky dávají různé vzdálenosti (např. různé trasy), ponechá se ta nejbližší k úseku. Které tabule dostanou infotext, rozhoduje VYMI: rozsah vzdáleností (výchozí −2 až +2 zastávky) posílá v parametrech `minDistanceStops` a `maxDistanceStops` endpointu a dostane jen tabule v něm.
+
+**Vzdálenost jako rozdíl `stop_sequence`.** Vzdálenost se počítá jako rozdíl pořadí zastávky ve spoji (`stop_sequence`) od první, resp. poslední zastávky spoje na úseku. To předpokládá souvislé číslování zastávek spoje, což platí pro všechny spoje PID (ověřeno na všech 127 635 spojodnech produkčních dat v říjnu 2026). Pokud by číslování mezeru mělo, vzdálenost se zvětší o její délku a tabule může vypadnout z limitu. Přesné pořadí by vyžadovalo seřadit všechny zastávky všech dotčených spojů, což byla nejdražší část dotazu (viz [Výkon](#výkon)).
+
+## Datový model
+
+Tabulka `jis_delayed_segments` (migrace `20261027100000-jis-delayed-segments`), jeden řádek na aktuálně detekovaný úsek:
+
+| Sloupec | Typ | Popis |
+| --- | --- | --- |
+| `id` | `text` | složené z ASW id krajních zastávek `{uzel}/{sloupek}-{uzel}/{sloupek}` |
+| `external_from_stop_id`, `external_to_stop_id` | `varchar(50)` | krajní zastávky ve formátu zdroje, pro dohledání problémů |
+| `from_stop_id`, `from_stop_name`, `to_stop_id`, `to_stop_name` | `varchar(50)`, `text` | krajní zastávky jako GTFS zastávky |
+| `expected_delay_seconds` | `integer` | odhadované zpoždění úseku |
+| `stops`, `routes`, `info_panel_stops` | `jsonb` | obohacení, struktura odpovídá API |
+| `created_at`, `updated_at` | `timestamptz` | začátek aktuální nepřerušené detekce úseku a poslední detekce |
+
+Databázové schéma záměrně nezmiňuje Mapu PID, zdroj je v komentářích sloupců popsán obecně. Úseky se uchovávají jen dokud jsou v posledním úspěšně staženém seznamu.
+
+Pro obohacení byl index `ropidgtfs_precomputed_departures (stop_id)` nahrazen indexem `(stop_id, departure_datetime)`, který stejně dobře slouží dotazům jen podle zastávky (např. odjezdové tabule). Tabulka předpočítaných odjezdů se při každém importu GTFS vytváří znovu jako `LIKE … including all`, index se tedy přenáší automaticky. Názvy indexů se ale při importech mění, migrace proto index hledá podle sloupců, ne podle názvu, a skončí chybou, pokud takový index není právě jeden. Migrace nový index nejdříve vytvoří a starý smaže až na konci: smazání drží výhradní zámek tabulky až do konce migrace a při opačném pořadí by odjezdové tabule čekaly po celou dobu stavby indexu (na produkčních datech ~3 s).
+
+## Kontrakt API
+
+`GET /v1/jis/delayed-segments` (Output Gateway, tag `⚠ JIS (v1) - internal`) vrací uložené úseky seřazené od největšího zpoždění. Volitelné parametry je zužují:
+
+- `minDelaySeconds` – jen úseky se zpožděním alespoň takovým,
+- `minDistanceStops`, `maxDistanceStops` – u zastávek s tabulemi jen linky se vzdáleností (`distance_stops`) v tomto rozsahu včetně; zastávky bez takové linky se vynechají.
+
+Parametry mohou data jen zúžit: úseky se zpožděním pod `minDelaySeconds` a tabule dál než `maxInfoPanelDistanceStops` z konfigurace Integration Engine se vůbec neukládají. Filtrovat v Output Gateway místo ve VYMI znamená, že VYMI nestahuje data, která by zahodilo, a nastavení filtrů zůstává na jednom místě ve VYMI. Schéma je v [openapi-output.yaml](../openapi-output.yaml) (`JISDelayedSegment`). Odpověď je cachovaná 5 s (`s-maxage=5, stale-while-revalidate=5`).
+
+```json
+{
+    "id": "9903/1-9906/1",
+    "from_stop": { "id": "U9903Z1P", "name": "Zastávka A" },
+    "to_stop": { "id": "U9906Z1P", "name": "Zastávka D" },
+    "expected_delay_seconds": 900,
+    "first_detected_at": "2026-10-27T08:50:00.000Z",
+    "last_detected_at": "2026-10-27T09:00:00.000Z",
+    "stops": [{ "id": "U9903Z1P", "name": "Zastávka A" }, "…"],
+    "routes": [{ "id": "L9901", "short_name": "9901", "type": 3 }],
+    "info_panel_stops": [
+        {
+            "stop": { "id": "U9901Z1P", "name": "Zastávka P1" },
+            "preset_route_names": ["preset-p1"],
+            "routes": [{ "id": "L9901", "distance_stops": -2 }]
+        }
+    ]
+}
+```
+
+Zásady kontraktu:
+
+- **Nezávislost na zdroji.** API neobsahuje nic specifického pro Mapu PID (ani její stop id), všechny zastávky a linky jsou GTFS entity. Zdroj úseků lze vyměnit bez změny kontraktu.
+- **`id` není stabilní identifikace.** Úseky v čase rostou, zkracují se a štěpí, `id` se tím mění. VYMI páruje úseky mezi běhy podle `stops`: úsek pokračuje sledovanou kongesci, pokud s ní sdílí alespoň dvě zastávky (dvojice 1:1, větší překryv dřív). Zastávky jsou GTFS stop id abecedně první ze všech variant zastávky v GTFS, nezávisle na tom, které varianty obsluhují spoje v časovém okně; id se tak změní jen se změnou zastávek v GTFS (např. přibude varianta řazená dřív), a i pak jedna změněná zastávka párování podle dvou společných zastávek nerozbije.
+- **Id zastávky s tabulí je id varianty s presetem.** `info_panel_stops[].stop.id` je varianta, ke které je přiřazen preset, a může se lišit od id stejné zastávky ve `stops`. Tabuli v úseku poznáte podle `distance_stops` = 0, ne podle shody id se `stops`.
+- **Aktuálnost podle `last_detected_at`.** Při výpadku zdroje se úseky nemažou. VYMI drží událost platnou do `last_detected_at` + 15 minut (nastavitelné) a při každé další detekci ji prodlouží; když se `last_detected_at` přestane posouvat, událost sama vyprší.
+
+## Výkon
+
+Obohacení byla věnována pozornost, protože běží každých 5 minut nad produkční databází. Měřeno v říjnu 2026 na snímku produkčních dat (2,5 mil. předpočítaných odjezdů), čas dotazu včetně plánování:
+
+| Varianta | 13 úseků | 40 úseků |
+| --- | --- | --- |
+| první verze, dotaz pro každý úsek | až 13 s na úsek | – |
+| dotaz pro každý úsek po optimalizacích | 0,45 s | 1,2 s |
+| jeden dotaz pro všechny úseky | 0,12 s | 0,25 s |
+| současný stav | 0,06–0,08 s | 0,11–0,13 s |
+
+Kontrola směru přes dvojice zastávek přidala ~5–8 %: na stejném snímku 93 → 99 ms pro 13 úseků a 184 → 199 ms pro 40 úseků (medián 7 běhů).
+
+Hlavní kroky:
+
+- **Párování presetů přes malou množinu.** ASW id zastávek nejsou indexovaná, párování všech zastávek dotčených spojů proti všem GTFS zastávkám trvalo sekundy. Dotaz páruje jen proti zastávkám s presetem a jejich variantám.
+- **Jeden dotaz pro všechny úseky.** Plánování (~10 ms) a sdílené části (presety, zastávky) se platí jednou za běh, ne za úsek.
+- **Odolnost vůči odhadům plánovače.** Plánovač u mezivýsledků (CTE) podhodnocuje počty řádků o dva až tři řády a volí vnořené smyčky. Spojení, kde to vedlo k milionům porovnání, nahrazuje vyhledání v malých mapách (`jsonb`) zastávek úseku a dvojic zastávek ve směru úseku.
+- **Vzdálenost z `stop_sequence`** místo řazení všech zastávek všech dotčených spojů (viz výše).
+- **Index `(stop_id, departure_datetime)`** zrychlí hledání odjezdů ze zastávek v časovém okně.
+
+JIT kompilace PostgreSQL by dotaz jen zpomalila: samotná kompilace plánu trvá ~3 s. Odhadovaná cena dotazu (~7 000) je sice hluboko pod výchozím `jit_above_cost` (100 000, nastaveno na rabínu i produkci v říjnu 2026), na rozdíl od prototypu, kterému vypnutí JIT na produkci zrychlilo dotaz zhruba desetkrát. Dotaz přesto běží v transakci s `SET LOCAL jit = off`, aby změna odhadu nebo nastavení nemohla běh zpomalit o sekundy. Nastavení platí jen pro tuto transakci.
+
+## Konfigurace
+
+Klíče modulu pid v konfiguraci Integration Engine:
+
+| Klíč | Výchozí hodnota | Význam |
+| --- | --- | --- |
+| `module.pid.jis.delayedSegments.url` | – (povinný) | adresa endpointu Mapy PID; záměrně jen v konfiguraci nasazení |
+| `module.pid.jis.delayedSegments.minDelaySeconds` | `300` | minimální zpoždění úseku |
+| `module.pid.jis.delayedSegments.routeTimeWindowMinutes` | `120` | časové okno odjezdů pro obohacení (± od detekce) |
+| `module.pid.jis.delayedSegments.maxInfoPanelDistanceStops` | `5` | maximální vzdálenost zastávky s tabulí od úseku |
+
+## Provoz
+
+- **Spouštění:** cron `cron.vehicle-positions.jis.refreshDelayedSegments`, `0 */5 * * * *` (rabín i produkce), fronta `vehicle-positions.jis.refreshDelayedSegments` s TTL 4 minuty (zprávy starší než další běh propadnou). VYMI si úseky stahuje o dvě minuty později (minuta 2, 7, 12, …), aby četl data právě dokončeného běhu; při změně času spouštění je třeba posunout i VYMI.
+- **Předpoklady nasazení:** nastavený `module.pid.jis.delayedSegments.url`, záznam v Cron Tasks a role v Access Proxy pro přístup VYMI k endpointu.
+- **Logování:** každý běh loguje (úroveň info) počet převzatých a nově spočítaných obohacení, počet uložených úseků a počty vyřazených úseků podle důvodu (pod minimálním zpožděním, bez ASW id, krajní zastávky mimo GTFS, úsek neprojíždí celý žádný spoj, bez dotčených linek). Jednotlivé vyřazené úseky se logují jen na úrovni debug, protože se opakují každých 5 minut po celou dobu zpoždění.
+- **Chyby:** chyba stažení, validace nebo databáze ukončí běh chybou a uložená data zůstanou beze změny. Další běh proběhne normálně.
+- **Chybějící jízdní řády:** pokud běh vyřadí všechny úseky s důvodem `no trip runs the whole segment`, pravděpodobně chybí předpočítané odjezdy pro aktuální čas (`ropidgtfs_precomputed_departures`, např. po neúspěšném importu GTFS). Úseky se pak neuloží a VYMI je nedostane.
+
+## Známá omezení a rizika
+
+- **Zaseknutý výpočet Mapy PID nelze rozpoznat.** Odpověď neobsahuje čas výpočtu úseků. Pokud Mapa PID přestane úseky přepočítávat, vrací poslední stav (až 24 hodin) a ten se jeví jako aktuální. Změnu na straně Mapy PID nelze zajistit, riziko je pro zkušební provoz přijaté.
+- **Úseky sloučené přes různé linky se zahodí.** Mapa PID slučuje navazující zpožděné mezizastávkové úseky podle zastávek bez ohledu na linku (úsek A→B jedné linky s úsekem B→C jiné linky). Pokud takový sloučený úsek celý neprojíždí žádný spoj, nelze určit jeho zastávky ani linky a úsek se zahodí. Zpoždění tak může zůstat bez infotextu. Počet těchto úseků je v logu každého běhu (`no trip runs the whole segment`). Řešením by bylo rozdělit úsek na části projížděné jednotlivými spoji; zda je to potřeba, ukáže zkušební provoz.
+- **Mezery v `stop_sequence`** by zvětšily vzdálenosti tabulí (viz [Obohacení](#zastávky-s-tabulemi-a-jejich-vzdálenost)).
+- **Úseky přes železniční body** (krajní zastávka `T…` bez ASW id) se nezpracují.
+- **Chybějící název zastávky nebo linky** v GTFS datech by neprošel validací a běh by skončil chybou; data zůstanou z předchozího běhu.
+- **Souběžné běhy** (např. při zdržení fronty) mohou v krajním případě přepsat novější data staršími, další běh je opraví.
+
+## Klíčová rozhodnutí
+
+| Rozhodnutí | Důvod |
+| --- | --- |
+| Golemio úseky jen obohacuje, o infotextech rozhoduje VYMI | oddělení faktů od pravidel provozu; VYMI vlastní infotexty i jejich životní cyklus |
+| `id` z ASW id krajních zastávek, ale bez stability; párování podle `stops` | Mapa PID úseky slučuje a štěpí, stabilní identita úseku neexistuje |
+| API nezávislé na zdroji, data zdroje jen v DB (`external_*`) | algoritmus Mapy PID se může změnit, zdroj může být vyměněn |
+| Bez nových časových sloupců pro detekci, `created_at` / `updated_at` | první a poslední detekce přirozeně odpovídají vložení a aktualizaci řádku |
+| Neúspěšný běh nemění data, platnost řeší VYMI podle `last_detected_at` | výpadek zdroje nemá smazat informaci o probíhajícím zpoždění |
+| Minimální zpoždění a rozsah vzdáleností tabulí určuje VYMI parametry endpointu, filtruje Output Gateway | jde o provozní rozhodnutí VYMI, Golemio ale posílá jen relevantní data; konfigurace Integration Engine jen omezuje, co se obohacuje a ukládá; testovací zastávky zůstávají filtrem ve VYMI |
+| Vzdálenost tabulí se znaménkem, nejbližší za linku | VYMI rozliší tabule před úsekem, v úseku a za ním |
+| Jedna tabulka s `jsonb` sloupci | data se vždy čtou celá a vyměňují celá, normalizace by nic nepřinesla |
+| Vzdálenost z `stop_sequence` | výkon (viz [Výkon](#výkon)); kompromis je zdokumentovaný výše |
+| Obohacení v každém běhu, bez cache | znovupoužití obohacení přetrvávajících úseků šetřilo jen desetiny sekundy za běh (v listopadu 2026 ~0,1–0,3 s na snímku produkčních dat, ~0,3–0,9 s na rabínu pro 13–40 úseků), za cenu až 30 minut starých zastávek, linek a tabulí po změně jízdních řádů, presetů nebo přechodu mezi denním a nočním provozem |
+| Adresa Mapy PID jen v konfiguraci | endpoint je veřejně dostupný, ale není určen k širokému použití |
+
+## Zdrojový kód a testy
+
+| Část | Soubor |
+| --- | --- |
+| datový zdroj | [JISDelayedSegmentsDataSourceFactory](../../src/integration-engine/jis/datasources/JISDelayedSegmentsDataSourceFactory.ts) |
+| task | [RefreshDelayedSegmentsTask](../../src/integration-engine/jis/workers/tasks/RefreshDelayedSegmentsTask.ts) |
+| zpracování | [JISDelayedSegmentsDataService](../../src/integration-engine/jis/services/JISDelayedSegmentsDataService.ts) |
+| obohacení | [JISDelayedSegmentEnrichmentRepository](../../src/integration-engine/jis/repositories/JISDelayedSegmentEnrichmentRepository.ts), [JISDelayedSegmentEnrichmentQuery](../../src/integration-engine/jis/repositories/helpers/JISDelayedSegmentEnrichmentQuery.ts) |
+| uložení | [JISDelayedSegmentsRepository (IE)](../../src/integration-engine/jis/repositories/JISDelayedSegmentsRepository.ts), [JISDelayedSegmentsModel](../../src/schema-definitions/jis/models/JISDelayedSegmentsModel.ts) |
+| výstup | [V1DelayedSegmentsController](../../src/output-gateway/jis/controllers/v1/V1DelayedSegmentsController.ts), [JISDelayedSegmentsTransformation](../../src/output-gateway/jis/transformations/JISDelayedSegmentsTransformation.ts) |
+| migrace | [20261027100000-jis-delayed-segments](../../db/migrations/postgresql/sqls/20261027100000-jis-delayed-segments-up.sql) |
+| testovací data | [24_jis_delayed_segments.sql](../../db/example/24_jis_delayed_segments.sql) – syntetický koridor s linkami, které úsek projíždějí celý, částečně, jen se ho dotknou, jsou výjimečné, jedou mimo časové okno nebo mají mezeru v `stop_sequence` |
+| testy | `test/integration-engine/jis/**/*DelayedSegment*`, `test/output-gateway/jis/**/*DelayedSegments*` |

package/docs/jis/index.md

@@ -306,3 +306,12 @@ Experimentální feed pro e-paper displeje, generovaný stejným taskem. Obsahuj
 
 - `/v2/pid/departureboards`, `/v3/pid/transferboards` a `/v3/pid/infotexts` čtou infotexty z PostgreSQL; u odjezdových tabulí s parametrem `preset` se vrací jen infotexty navázané na daný preset (`jis_infotexts_presets.route_name`);
 - `/v4/pid/transferboards` čte infotexty z Redis cache `jisCache:*`.
+
+### Zpožděné úseky — podklad pro automatické infotexty (`GET /v1/jis/delayed-segments`)
+
+Endpoint je interní a slouží VYMI k automatickému vytváření interních událostí a infotextů o zpožděných úsecích ([vymi-general#365](https://gitlab.com/operator-ict/golemio/jis/vymi-alerts/vymi-general/-/work_items/365)). Úseky detekuje Mapa PID, Golemio je stahuje, obohacuje a poskytuje, VYMI rozhoduje, zda a jak vytvořit událost/infotext. Záměr, architekturu, algoritmus, výkon a rozhodnutí podrobně popisuje stránka [Zpožděné úseky](./delayed-segments.md).
+
+Úseky každých 5 minut stahuje `RefreshDelayedSegmentsTask` z Mapy PID a obohacuje je o zastávky úseku, dotčené linky a zastávky s panely včetně jejich vzdálenosti od úseku (viz [Zpracování](./delayed-segments.md#zpracování) a [implementační dokumentace](../implementation_documentation.md#task-refreshdelayedsegmentstask)). Pro VYMI platí:
+- úseky v čase rostou a zmenšují se (Mapa PID slučuje navazující zpožděné mezizastávkové úseky), `id` proto není stabilní identifikace; VYMI úseky páruje podle `stops` (alespoň dvě společné zastávky);
+- při chybě stažení zůstávají uložené úseky beze změny a nemažou se; VYMI proto drží událost platnou do `last_detected_at` + 15 minut a nechá ji vypršet, když se `last_detected_at` přestane posouvat; Mapa PID navíc neposílá čas výpočtu úseků, takže zaseknutý výpočet na její straně nelze rozpoznat;
+- minimální zpoždění úseku (`minDelaySeconds`) a rozsah vzdáleností zastávek s panely od úseku (`minDistanceStops`, `maxDistanceStops`) si VYMI určuje parametry endpointu.

package/docs/openapi-output.yaml

@@ -2346,6 +2346,63 @@ paths:
                     $ref: "#/components/responses/BadRequestError"
                 401:
                     $ref: "#/components/responses/UnauthorizedError"
+    /v1/jis/delayed-segments:
+        get:
+            tags:
+                - ⚠ JIS (v1) - internal
+            summary: Get all currently detected delayed segments
+            description: |
+                Returns segments of the network with a significant delay, detected by Mapa PID and enriched with GTFS data:
+                stops of the segment, affected routes and nearby stops with info panels. Refreshed every 5 minutes.
+
+                A segment is a directed corridor of stops. Its `id` is derived from its endpoints; as segments may grow or shrink
+                between refreshes, consumers should match segments by their stops rather than by `id`.
+
+                If fetching the segments fails, the last known segments are kept and their `last_detected_at` stops advancing,
+                so consumers should judge freshness by `last_detected_at`. This does not cover the detection itself stalling:
+                the source provides no time of its calculation, so a stalled detection keeps being fetched and
+                `last_detected_at` keeps advancing.
+
+                Only segments with a delay of at least 5 minutes and info panel stops at most 5 stops from the segment are
+                detected; the query parameters can only narrow them down further.
+            parameters:
+                - name: minDelaySeconds
+                  in: query
+                  required: false
+                  schema:
+                    type: integer
+                    minimum: 0
+                    example: 600
+                  description: Minimum `expected_delay_seconds` of the returned segments.
+                - name: minDistanceStops
+                  in: query
+                  required: false
+                  schema:
+                    type: integer
+                    example: -2
+                  description: |
+                    Minimum `distance_stops` of info panel stop routes. Routes outside the range given by `minDistanceStops`
+                    and `maxDistanceStops` are left out, and so are info panel stops left without a route.
+                - name: maxDistanceStops
+                  in: query
+                  required: false
+                  schema:
+                    type: integer
+                    example: 2
+                  description: Maximum `distance_stops` of info panel stop routes, see `minDistanceStops`.
+            responses:
+                200:
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/JISDelayedSegment"
+                400:
+                    $ref: "#/components/responses/BadRequestError"
+                401:
+                    $ref: "#/components/responses/UnauthorizedError"
 
 
 components:
@@ -4897,3 +4954,122 @@ components:
                     format: date-time
                     example: "2024-02-29T12:22:20.958Z"
                     description: Timestamp from when the event was created in VYMI
+        JISDelayedSegmentStop:
+            type: object
+            required:
+                - id
+                - name
+            properties:
+                id:
+                    type: string
+                    example: U1234Z1P
+                    description: GTFS stop id
+                name:
+                    type: string
+                    example: Vozovna Střešovice
+        JISDelayedSegment:
+            type: object
+            required:
+                - id
+                - from_stop
+                - to_stop
+                - expected_delay_seconds
+                - first_detected_at
+                - last_detected_at
+                - stops
+                - routes
+                - info_panel_stops
+            properties:
+                id:
+                    type: string
+                    example: 1234/1-5678/2
+                    description: Identifier of the segment derived from its endpoints
+                from_stop:
+                    $ref: "#/components/schemas/JISDelayedSegmentStop"
+                to_stop:
+                    $ref: "#/components/schemas/JISDelayedSegmentStop"
+                expected_delay_seconds:
+                    type: integer
+                    example: 900
+                    description: Expected additional delay of a vehicle passing the whole segment
+                first_detected_at:
+                    type: string
+                    format: date-time
+                    example: "2026-10-27T08:50:00.000Z"
+                    description: |
+                        Start of the current continuous detection of the segment; resets when the segment is missing from a successful
+                        refresh or its `id` changes
+                last_detected_at:
+                    type: string
+                    format: date-time
+                    example: "2026-10-27T09:00:00.000Z"
+                    description: Time of the last detection of the segment
+                stops:
+                    type: array
+                    description: |
+                        Stops of the segment, including its endpoints, ordered along the segment. A stop with several GTFS stop ids
+                        (variants) is represented by the alphabetically first of them, so its id stays the same between refreshes
+                        unless the GTFS stops change.
+                    items:
+                        $ref: "#/components/schemas/JISDelayedSegmentStop"
+                routes:
+                    type: array
+                    description: |
+                        Routes with a regular trip travelling at least one hop of the segment within the configured time window
+                        (default 2 hours) before or after the detection
+                    items:
+                        type: object
+                        required:
+                            - id
+                            - short_name
+                            - type
+                        properties:
+                            id:
+                                type: string
+                                example: L119
+                                description: GTFS route id
+                            short_name:
+                                type: string
+                                example: "119"
+                            type:
+                                type: integer
+                                example: 3
+                                description: GTFS route type
+                info_panel_stops:
+                    type: array
+                    description: |
+                        Stops with an info panel (departure preset) in or near the segment along the affected routes. The stop id
+                        is the variant the preset is assigned to, so it may differ from the id of the same stop in `stops`; a stop
+                        inside the segment is recognized by `distance_stops` 0.
+                    items:
+                        type: object
+                        required:
+                            - stop
+                            - preset_route_names
+                            - routes
+                        properties:
+                            stop:
+                                $ref: "#/components/schemas/JISDelayedSegmentStop"
+                            preset_route_names:
+                                type: array
+                                description: Route names of the departure presets assigned to the stop
+                                items:
+                                    type: string
+                                    example: bustec-vozovna_strasovice-876_2
+                            routes:
+                                type: array
+                                description: Affected routes passing the stop
+                                items:
+                                    type: object
+                                    required:
+                                        - id
+                                        - distance_stops
+                                    properties:
+                                        id:
+                                            type: string
+                                            example: L119
+                                            description: GTFS route id
+                                        distance_stops:
+                                            type: integer
+                                            example: -2
+                                            description: Distance of the stop from the segment in stops along the route (negative before the segment, 0 inside, positive after it)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/pid",
-    "version": "6.4.0",
+    "version": "6.4.1-dev.3054859807",
     "description": "Golemio PID Module",
     "type": "module",
     "main": "dist/index.js",
@@ -123,7 +123,7 @@
         "@golemio/core": "^4.0.1-dev.2 || ^4.0.1"
     },
     "dependencies": {
-        "@golemio/ovapi-gtfs-realtime-bindings": "1.4.1",
+        "@golemio/ovapi-gtfs-realtime-bindings": "1.4.1-dev.2464451735",
         "@turf/turf": "^6.5.0",
         "cheap-ruler": "^3.0.2",
         "csv-parser": "^3.0.0",