@golemio/public-transport 0.1.0-dev.2769114834

package/docs/index.md

@@ -0,0 +1,3 @@
+# @golemio/public-transport
+
+This module is intended for use with Golemio services. Refer [here](https://gitlab.com/operator-ict/golemio/code/modules/core/-/blob/development/README.md) for further information on usage, local development and more.

package/docs/jis/diagram_display_start_end.svg

@@ -0,0 +1,169 @@
+<svg id="graph-div-1749736383184" width="2500" height="450" xmlns="http://www.w3.org/2000/svg">
+ <g id="viewport-20250612135303195" class="svg-pan-zoom_viewport">
+ 	<style>
+		#graph-div-1749736383184{
+			font-family:arial,sans-serif;
+			font-size:14px;
+			fill:#000000;}
+			#graph-div-1749736383184 .error-icon{fill:#552222;}
+			#graph-div-1749736383184 .error-text{fill:#552222;stroke:#552222;}
+			#graph-div-1749736383184 .edge-thickness-normal{stroke-width:1px;}
+			#graph-div-1749736383184 .edge-thickness-thick{stroke-width:3.5px;}
+			#graph-div-1749736383184 .edge-pattern-solid{stroke-dasharray:0;}
+			#graph-div-1749736383184 .edge-thickness-invisible{stroke-width:0;fill:none;}
+			#graph-div-1749736383184 .edge-pattern-dashed{stroke-dasharray:3;}
+			#graph-div-1749736383184 .edge-pattern-dotted{stroke-dasharray:2;}
+			#graph-div-1749736383184 .marker{fill:#666;stroke:#666;}
+			#graph-div-1749736383184 .marker.cross{stroke:#666;}
+			#graph-div-1749736383184 svg{font-family:arial,sans-serif;font-size:14px;}
+			#graph-div-1749736383184 p{margin:0;}
+			#graph-div-1749736383184 .mermaid-main-font{font-family:arial,sans-serif;}
+			#graph-div-1749736383184 .exclude-range{fill:#eeeeee;}
+			#graph-div-1749736383184 .section{stroke:none;opacity:0.2;}
+			#graph-div-1749736383184 .section0{fill:hsl(0, 0%, 73.9215686275%);}
+			#graph-div-1749736383184 .section2{fill:hsl(0, 0%, 73.9215686275%);}
+			#graph-div-1749736383184 .section1,#graph-div-1749736383184 .section3{fill:white;opacity:0.2;}
+			#graph-div-1749736383184 .sectionTitle0{fill:#333;}
+			#graph-div-1749736383184 .sectionTitle1{fill:#333;}
+			#graph-div-1749736383184 .sectionTitle2{fill:#333;}
+			#graph-div-1749736383184 .sectionTitle3{fill:#333;}
+			#graph-div-1749736383184 .sectionTitle{text-anchor:start;font-family:arial,sans-serif;}
+			#graph-div-1749736383184 .grid .tick{stroke:hsl(0, 0%, 90%);opacity:0.8;shape-rendering:crispEdges;}
+			#graph-div-1749736383184 .grid .tick text{font-family:arial,sans-serif;fill:#000000;}
+			#graph-div-1749736383184 .grid path{stroke-width:0;}
+			#graph-div-1749736383184 .today{fill:none;stroke:#d42;stroke-width:2px;}
+			#graph-div-1749736383184 .task{stroke-width:2;}
+			#graph-div-1749736383184 .taskText{text-anchor:middle;font-family:arial,sans-serif;}
+			#graph-div-1749736383184 .taskTextOutsideRight{fill:#333;text-anchor:start;font-family:arial,sans-serif;}
+			#graph-div-1749736383184 .taskTextOutsideLeft{fill:#333;text-anchor:end;}
+			#graph-div-1749736383184 .task.clickable{cursor:pointer;}
+			#graph-div-1749736383184 .taskText.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}
+			#graph-div-1749736383184 .taskTextOutsideLeft.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}
+			#graph-div-1749736383184 .taskTextOutsideRight.clickable{cursor:pointer;fill:#003163!important;font-weight:bold;}
+			#graph-div-1749736383184 .taskText0,#graph-div-1749736383184 .taskText1,#graph-div-1749736383184 .taskText2,#graph-div-1749736383184 .taskText3{fill:white;}
+			#graph-div-1749736383184 .task0,#graph-div-1749736383184 .task1,#graph-div-1749736383184 .task2,#graph-div-1749736383184 .task3{fill:#707070;stroke:hsl(0, 0%, 33.9215686275%);}
+			#graph-div-1749736383184 .taskTextOutside0,#graph-div-1749736383184 .taskTextOutside2{fill:#333;}
+			#graph-div-1749736383184 .taskTextOutside1,#graph-div-1749736383184 .taskTextOutside3{fill:#333;}
+			#graph-div-1749736383184 .active0,#graph-div-1749736383184 .active1,#graph-div-1749736383184 .active2,#graph-div-1749736383184 .active3{fill:#eee;stroke:hsl(0, 0%, 33.9215686275%);}
+			#graph-div-1749736383184 .activeText0,#graph-div-1749736383184 .activeText1,#graph-div-1749736383184 .activeText2,#graph-div-1749736383184 .activeText3{fill:#333!important;}
+			#graph-div-1749736383184 .done0,#graph-div-1749736383184 .done1,#graph-div-1749736383184 .done2,#graph-div-1749736383184 .done3{stroke:#666;fill:#bbb;stroke-width:2;}
+			#graph-div-1749736383184 .doneText0,#graph-div-1749736383184 .doneText1,#graph-div-1749736383184 .doneText2,#graph-div-1749736383184 .doneText3{fill:#333!important;}
+			#graph-div-1749736383184 .crit0,#graph-div-1749736383184 .crit1,#graph-div-1749736383184 .crit2,#graph-div-1749736383184 .crit3{stroke:hsl(10.9090909091, 73.3333333333%, 40%);fill:#d42;stroke-width:2;}
+			#graph-div-1749736383184 .activeCrit0,#graph-div-1749736383184 .activeCrit1,#graph-div-1749736383184 .activeCrit2,#graph-div-1749736383184 .activeCrit3{stroke:hsl(10.9090909091, 73.3333333333%, 40%);fill:#eee;stroke-width:2;}
+			#graph-div-1749736383184 .doneCrit0,#graph-div-1749736383184 .doneCrit1,#graph-div-1749736383184 .doneCrit2,#graph-div-1749736383184 .doneCrit3{stroke:hsl(10.9090909091, 73.3333333333%, 40%);fill:#bbb;stroke-width:2;cursor:pointer;shape-rendering:crispEdges;}
+			#graph-div-1749736383184 .milestone{transform:rotate(45deg) scale(0.8,0.8);}
+			#graph-div-1749736383184 .milestoneText{font-style:italic;}
+			#graph-div-1749736383184 .doneCritText0,#graph-div-1749736383184 .doneCritText1,#graph-div-1749736383184 .doneCritText2,#graph-div-1749736383184 .doneCritText3{fill:#333!important;}
+			#graph-div-1749736383184 .activeCritText0,#graph-div-1749736383184 .activeCritText1,#graph-div-1749736383184 .activeCritText2,#graph-div-1749736383184 .activeCritText3{fill:#333!important;}
+			#graph-div-1749736383184 .titleText{text-anchor:middle;font-size:18px;fill:#333;font-family:arial,sans-serif;}
+			#graph-div-1749736383184 .node .neo-node{stroke:#999;}
+			#graph-div-1749736383184 [data-look="neo"].node rect,#graph-div-1749736383184 [data-look="neo"].cluster rect,#graph-div-1749736383184 [data-look="neo"].node polygon{stroke:url(#graph-div-1749736383184-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}
+			#graph-div-1749736383184 [data-look="neo"].node path{stroke:url(#graph-div-1749736383184-gradient);stroke-width:1;}
+			#graph-div-1749736383184 [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}
+			#graph-div-1749736383184 [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}
+			#graph-div-1749736383184 [data-look="neo"].node circle{stroke:url(#graph-div-1749736383184-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}
+			#graph-div-1749736383184 [data-look="neo"].node circle .state-start{fill:#000000;}
+			#graph-div-1749736383184 [data-look="neo"].statediagram-cluster rect{fill:#eee;stroke:url(#graph-div-1749736383184-gradient);stroke-width:1;}
+			#graph-div-1749736383184 [data-look="neo"].icon-shape .icon{fill:url(#graph-div-1749736383184-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}
+			#graph-div-1749736383184 [data-look="neo"].icon-shape .icon-neo path{stroke:url(#graph-div-1749736383184-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}
+			#graph-div-1749736383184 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}
+ </style>
+ 
+ <g class="grid" transform="translate(75, 410)" fill="none" font-size="10" font-family="sans-serif" text-anchor="middle">
+ 	<path class="domain" stroke="currentColor" d="M0.5,-375V0.5H2375.5V-375">
+ 		
+ 	</path>
+ 	<g class="tick" opacity="1" transform="translate(0.5,0)">
+ 		<line stroke="currentColor" y2="-375"></line>
+ 		<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-05-25</text>
+ 	</g>
+ 	<g class="tick" opacity="1" transform="translate(183.5,0)">
+ 		<line stroke="currentColor" y2="-375"></line>
+ 		<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-05-27</text>
+ 	</g>
+	<g class="tick" opacity="1" transform="translate(365.5,0)">
+		<line stroke="currentColor" y2="-375"></line>
+		<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-05-29</text>
+	</g>
+	<g class="tick" opacity="1" transform="translate(548.5,0)">
+		<line stroke="currentColor" y2="-375"></line>
+		<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-05-31</text>
+	</g>
+	<g class="tick" opacity="1" transform="translate(639.5,0)">
+		<line stroke="currentColor" y2="-375"></line>
+		<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-01</text>
+	</g>
+	<g class="tick" opacity="1" transform="translate(822.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-03</text></g>
+	<g class="tick" opacity="1" transform="translate(1005.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-05</text></g>
+	<g class="tick" opacity="1" transform="translate(1188.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-07</text></g>
+	<g class="tick" opacity="1" transform="translate(1370.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-09</text></g>
+	<g class="tick" opacity="1" transform="translate(1553.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-11</text></g>
+	<g class="tick" opacity="1" transform="translate(1736.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-13</text></g>
+	<g class="tick" opacity="1" transform="translate(1918.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-15</text></g>
+	<g class="tick" opacity="1" transform="translate(2101.5,0)"><line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-17</text></g>
+<g class="tick" opacity="1" transform="translate(2284.5,0)">
+	<line stroke="currentColor" y2="-375"></line>
+	<text fill="#000" y="3" dy="1em" stroke="none" font-size="10" style="text-anchor: middle;"> 2024-06-19</text>
+</g>
+</g>
+<g>
+	<rect x="0" y="168" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="120" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="48" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="96" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="336" width="2487.5" height="24" class="section section2"></rect>
+<rect x="0" y="360" width="2487.5" height="24" class="section section2"></rect>
+<rect x="0" y="384" width="2487.5" height="24" class="section section2"></rect>
+<rect x="0" y="192" width="2487.5" height="24" class="section section1"></rect>
+<rect x="0" y="216" width="2487.5" height="24" class="section section1"></rect>
+<rect x="0" y="264" width="2487.5" height="24" class="section section1"></rect>
+<rect x="0" y="240" width="2487.5" height="24" class="section section1"></rect>
+<rect x="0" y="144" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="72" width="2487.5" height="24" class="section section0"></rect>
+<rect x="0" y="288" width="2487.5" height="24" class="section section2"></rect>
+<rect x="0" y="312" width="2487.5" height="24" class="section section2"></rect>
+</g>
+<g>
+	<rect id="e3" rx="3" ry="3" x="75" y="146" width="2375" height="20" transform-origin="1262.5px 155px" class="task done0"></rect>
+	<rect id="e1" rx="3" ry="3" x="532" y="122" width="548" height="20" transform-origin="806px 132px" class="task done0"></rect>
+	<rect id="q1_start" rx="3" ry="3" x="704" y="74" width="20" height="20" transform-origin="714px 84px" class="task milestone  task0"></rect>
+	<rect id="q1" rx="3" ry="3" x="714" y="98" width="823" height="20" transform-origin="1125.5px 108px" class="task crit0"></rect>
+	<rect id="e6" rx="3" ry="3" x="714" y="338" width="731" height="20" transform-origin="1079.5px 348px" class="task done2"></rect>
+	<rect id="e7" rx="3" ry="3" x="806" y="362" width="731" height="20" transform-origin="1171.5px 372px" class="task done2"></rect>
+	<rect id="e8" rx="3" ry="3" x="897" y="386" width="1553" height="20" transform-origin="1673.5px 396px" class="task done2"></rect>
+	<rect id="q2" rx="3" ry="3" x="1080" y="194" width="0" height="20" transform-origin="1080px 204px" class="task active1"></rect>
+	<rect id="q2_marker" rx="3" ry="3" x="1070" y="218" width="20" height="20" transform-origin="1080px 228px" class="task milestone  task1"></rect>
+	<rect id="e5" rx="3" ry="3" x="1080" y="266" width="457" height="20" transform-origin="1308.5px 276px" class="task done1"></rect>
+	<rect id="e4" rx="3" ry="3" x="1171" y="242" width="548" height="20" transform-origin="1445px 252px" class="task done1"></rect>
+	<rect id="e2" rx="3" ry="3" x="1354" y="122" width="639" height="20" transform-origin="1673.5px 136px" class="task done0"></rect>
+	<rect id="q1_end" rx="3" ry="3" x="1527" y="74" width="20" height="20" transform-origin="1537px 84px" class="task milestone  task0"></rect>
+	<rect id="q3" rx="3" ry="3" x="1537" y="290" width="0" height="20" transform-origin="1537px 300px" class="task active2"></rect>
+	<rect id="q3_marker" rx="3" ry="3" x="1527" y="314" width="20" height="20" transform-origin="1537px 324px" class="task milestone  task2"></rect>
+<text id="e3-text" font-size="11" x="1262.5" y="159.5" class="taskText taskText0  doneText0">Event C (Event Starts before, Ends after Interval)  </text>
+<text id="e1-text" font-size="11" x="806" y="135.5" class="taskText taskText0  doneText0">Event A (Event End is inside Interval) </text>
+<text id="q1_start-text" font-size="11" x="729" y="87.5" class="taskTextOutsideRight taskTextOutside0  milestoneText width-84.375">Query Start Point         </text>
+<text id="q1-text" font-size="11" x="1125.5" y="111.5" class="taskText taskText0  critText0 width-69.09375">Query Interval            </text>
+<text id="e6-text" font-size="11" x="1079.5" y="351.5" class="taskText taskText2  doneText2 width-108.828125">Event F (Ends Before)     </text>
+<text id="e7-text" font-size="11" x="1171.5" y="375.5" class="taskText taskText2  doneText2 width-113.71875">Event G (Ends Exactly)    </text>
+<text id="e8-text" font-size="11" x="1673.5" y="399.5" class="taskText taskText2  doneText2 width-112.5">Event H (No End Date)     </text>
+<text id="q2_marker-text" font-size="11" x="1095" y="231.5" class="taskTextOutsideRight taskTextOutside1  milestoneText width-122.28125">Query displayPeriodStart  </text>
+<text id="e5-text" font-size="11" x="1308.5" y="279.5" class="taskText taskText1  doneText1 width-116.15625">Event E (Starts Exactly)  </text>
+<text id="e4-text" font-size="11" x="1445" y="255.5" class="taskText taskText1  doneText1">Event D (Starts After)    </text>
+<text id="e2-text" font-size="11" x="1673.5" y="135.5" class="taskText taskText0  doneText0">Event B (Event Start is inside Interval)   </text>
+<text id="q1_end-text" font-size="11" x="1552" y="87.5" class="taskTextOutsideRight taskTextOutside0  milestoneText width-80.71875">Query End Point           </text>
+<text id="q3_marker-text" font-size="11" x="1552" y="327.5" class="taskTextOutsideRight taskTextOutside2  milestoneText width-118.625">Query displayPeriodEnd    </text></g>
+<g>
+	<text dy="0em" x="10" y="122" font-size="11" class="sectionTitle sectionTitle0"><tspan alignment-baseline="central" x="10">Scenario 1: Both `displayPeriodStart` and `displayPeriodEnd` provided</tspan></text>
+	<text dy="0em" x="10" y="242" font-size="11" class="sectionTitle sectionTitle1"><tspan alignment-baseline="central" x="10">Scenario 2: Only `displayPeriodStart` provided</tspan></text>
+	<text dy="0em" x="10" y="350" font-size="11" class="sectionTitle sectionTitle2"><tspan alignment-baseline="central" x="10">Scenario 3: Only `displayPeriodEnd` provided</tspan></text>
+</g>
+<g class="today"><line x1="35121" x2="35121" y1="25" y2="435" class="today"></line></g>
+<text x="1262.5" y="25" class="titleText">Event Querying Scenarios</text></g></svg>

package/docs/jis/index.md

@@ -0,0 +1,281 @@
+# Dokumentace propisu VYMI (JIS) dat do datové platformy
+
+Data událostí a infotextů jsou z aplikace VYMI aktivně posílána (push) do datové platformy Golemio, vždy ihned po změně v datech. Dále existuje možnost pasivního načtení (pull) dat z VYMI do Golemia, které je provedeno po manuální akci vývojáře a slouží například pro případ, že by došlo k výpadku aktivního posílání. Oba způsoby jsou zjednodušeně znázorněny na následujících dvou sekvenčních diagramech a podrobněji popsány v dalších sekcích.
+
+Sekvenční diagram znázorňující proces aktivního posílání (push) dat:
+
+```mermaid
+sequenceDiagram
+    actor user as Uživatel VYMI
+    participant vymi as Aplikace VYMI
+    participant golemio as Datová platforma Golemio
+
+    user->>vymi: Změna v datech událostí nebo infotextů
+    vymi->>golemio: Aktivní zaslání (push) dat událostí nebo infotextů do Golemia
+```
+
+Sekvenční diagram znázorňující proces pasivního načítání (pull) dat:
+
+```mermaid
+sequenceDiagram
+    participant vymi as Aplikace VYMI
+    participant golemio as Datová platforma Golemio
+    actor developer as Vývojář
+
+    developer->>golemio: Vyžádání načtení dat událostí nebo infotextů
+    golemio->>vymi: Pasivní načtení (pull) dat událostí nebo infotextů z VYMI
+    vymi->>golemio: Data událostí nebo infotextů
+```
+
+## Změny dat ve VYMI
+
+V rámci aplikace VYMI nejprve uživatel provede na front endu změny událostí nebo infotextů, které front end pošle na REST API back endu a ten je zapíše do VYMI PostgreSQL databáze. Mezi front endem a back endem data projdou ještě přes VYMI Ory Oathkeeper proxy (která za pomoci VYMI Ory Kratos a VYMI Ory Keto služeb zajišťuje autentizaci, respektive autorizaci uživatele).
+
+Proces je podrobněji znázorněn na následujícím diagramu (diagram nepopisuje celé VYMI REST API, pouze části nejvíce relevantní pro propisování dat do Golemia; stejně tak jsou vynechány detailnější prvky aplikační struktury).
+
+```mermaid
+flowchart LR
+    subgraph "VYMI"
+        subgraph "VYMI Front End"
+            vymi_create_event("`Vytvoření události`");
+            vymi_update_event("`Úprava události`");
+            vymi_update_event_after_duplicate("`Uložení události po duplikaci`");
+            vymi_create_infotext("`Vytvoření infotextu`");
+            vymi_update_infotext("`Úprava infotextu`");
+            vymi_update_infotext_after_duplicate("`Uložení infotextu po duplikaci`");
+
+            %% invisible unicode char ‎ due to https://github.com/orgs/community/discussions/106690
+            vymi_api_post_event["`HTTP POST s Ory Kratos session tokenem na http‎://api-vymi.golemio.cz/v1/events`"];
+            vymi_api_put_event["`HTTP PUT s Ory Kratos session tokenem na http‎://api-vymi.golemio.cz/v1/events/{eventId}`"];
+            vymi_api_post_infotext["`HTTP POST s Ory Kratos session tokenem na http‎://api-vymi.golemio.cz/v1/events/{eventId}/infotexts`"];
+            vymi_api_put_infotext["`HTTP PUT s Ory Kratos session tokenem na http‎://api-vymi.golemio.cz/v1/events/{eventId}/infotexts/{infotextId}`"];
+        end
+
+        subgraph "VYMI Back End"
+            vymi_events_controller_create["`V1EventsController.createEvent`"];
+            vymi_events_controller_update["`V1EventsController.updateEvent`"];
+            vymi_infotexts_controller_create["`V1EventInfotextsController.createInfotext`"];
+            vymi_infotexts_controller_update["`V1EventInfotextsController.updateInfotext`"];
+        end
+
+        vymi_pg[("`VYMI PostgreSQL`")];
+    end
+
+    vymi_create_event --> vymi_api_post_event;
+    vymi_update_event --> vymi_api_put_event;
+    vymi_update_event_after_duplicate --> vymi_api_put_event;
+    vymi_create_infotext --> vymi_api_post_infotext;
+    vymi_update_infotext --> vymi_api_put_infotext;
+    vymi_update_infotext_after_duplicate --> vymi_api_put_infotext;
+
+    vymi_api_post_event -- "`Přes VYMI Ory Oathkeeper`" --> vymi_events_controller_create;
+    vymi_api_put_event -- "`Přes VYMI Ory Oathkeeper`" --> vymi_events_controller_update;
+    vymi_api_post_infotext -- "`Přes VYMI Ory Oathkeeper`" --> vymi_infotexts_controller_create;
+    vymi_api_put_infotext -- "`Přes VYMI Ory Oathkeeper`" --> vymi_infotexts_controller_update;
+
+    vymi_events_controller_create -- "`UPSERT do tabulek vymi-alerts.public.events a vymi-alerts.public.event_routes`" --> vymi_pg;
+    vymi_events_controller_update -- "`UPSERT do tabulek vymi-alerts.public.events a vymi-alerts.public.event_routes`" --> vymi_pg;
+    vymi_infotexts_controller_create -- "`UPSERT do tabulek vymi-alerts.public.infotexts a vymi-alerts.public.infotext_stops`" --> vymi_pg;
+    vymi_infotexts_controller_update -- "`UPSERT do tabulek vymi-alerts.public.infotexts a vymi-alerts.public.infotext_stops`" --> vymi_pg;
+```
+
+## Aktivní posílání (push) dat
+
+Po uložení změn událostí a infotextů do VYMI PostgreSQL databáze dojde vždy k aktivnímu poslání (push) "aktuálních" dat z VYMI back end služby do Golemia za pomoci HTTP POST dotazu na Golemio Vehicle Positions (VP) Input Gateway (IG).
+- u událostí se posílá pouze konkrétní nově vytvořená nebo upravená událost, nikoliv celý seznam aktuálních událostí.
+- všechny infotexty, které mají `status` `PUBLISHED`, `visibility` `PUBLIC` a zároveň `active_period_end` je `NULL` nebo >= aktuální čas, neboli lidsky všechny aktivní, budoucí a publikované (ne-draft) infotexty.
+
+VP Input Gateway data přijme a zašle do odpovídající RabbitMQ fronty, odkud je převezme VP Integration Engine, který data zapíše do VP PostgreSQL databáze.
+
+Proces je podrobněji znázorněn na následujícím diagramu (detailnější prvky aplikační struktury jsou vynechány).
+
+```mermaid
+flowchart TB
+    subgraph "VYMI"
+        subgraph "VYMI Back End"
+            vymi_events_controller_create["`V1EventsController.createEvent`"];
+            vymi_events_controller_update["`V1EventsController.updateEvent`"];
+            vymi_infotexts_controller_create["`V1EventInfotextsController.createInfotext`"];
+            vymi_infotexts_controller_update["`V1EventInfotextsController.updateInfotext`"];
+
+            vymi_get_events["`EventFacade.getFilteredCustomFormatList`"];
+            vymi_get_infotexts["`InfotextFacade.getFilteredCustomFormatList`"];
+
+            %% invisible unicode char ‎ due to https://github.com/orgs/community/discussions/106690
+            golemio_api_post_events["`HTTPS POST s API klíčem na https‎://api.golemio.cz/input-gateway/v1/jis/events`"];
+            golemio_api_post_infotexts["`HTTPS POST s API klíčem na https‎://api.golemio.cz/input-gateway/v1/jis/infotexts`"];
+        end
+
+        vymi_pg[("`VYMI PostgreSQL`")];
+    end
+
+    subgraph "Golemio"
+        subgraph "Golemio VP Input Gateway"
+            golemio_events_controller["`JISEventsController`"];
+            golemio_infotexts_controller["`JisInfotextsController`"];
+        end
+
+        subgraph "Golemio RabbitMQ"
+            golemio_rabbit_refresh_events["`Fronta vehicle-positions.jis.refreshJISEvents`"];
+            golemio_rabbit_refresh_infotexts["`Fronta vehicle-positions.jis.refreshJISInfotexts`"];
+        end
+
+        subgraph "Golemio VP Integration Engine"
+            golemio_refresh_events_task["`RefreshJISEventsTask`"];
+            golemio_refresh_infotexts_task["`RefreshJISInfotextsTask`"];
+            golemio_refresh_infotexts_cache_task["`RefreshJISInfotextsCacheTask`"];
+        end
+
+        vp_pg[("`VP PostgreSQL`")];
+        vp_redis[("`VP Redis (Valkey)`")];
+    end
+
+    vymi_events_controller_create --> vymi_get_events;
+    vymi_events_controller_update --> vymi_get_events;
+    vymi_events_controller_update --> vymi_get_infotexts;
+    vymi_infotexts_controller_create --> vymi_get_infotexts;
+    vymi_infotexts_controller_update --> vymi_get_infotexts;
+
+    vymi_get_events <-- "`SELECT aktuálních událostí z tabulek vehicle-positions.pid.jis_events a vehicle-positions.pid.jis_events_ropidgtfs_routes`" --> vymi_pg;
+    vymi_get_infotexts <-- "`SELECT aktuálních infotextů z tabulek vehicle-positions.pid.jis_infotexts a vehicle-positions.pid.jis_infotexts_ropidgtfs_stops`" --> vymi_pg;
+
+    vymi_get_events --> golemio_api_post_events;
+    vymi_get_infotexts --> golemio_api_post_infotexts;
+
+    golemio_api_post_events -- "`Přes Golemio Access Proxy`" --> golemio_events_controller;
+    golemio_api_post_infotexts -- "`Přes Golemio Access Proxy`" --> golemio_infotexts_controller;
+
+    golemio_events_controller --> golemio_rabbit_refresh_events;
+    golemio_infotexts_controller --> golemio_rabbit_refresh_infotexts;
+
+    golemio_rabbit_refresh_events --> golemio_refresh_events_task;
+    golemio_rabbit_refresh_infotexts --> golemio_refresh_infotexts_task;
+
+    golemio_refresh_events_task -- "`UPSERT do tabulek vehicle-positions.pid.jis_events a vehicle-positions.pid.jis_events_ropidgtfs_routes`" --> vp_pg;
+    golemio_refresh_infotexts_task -- "`UPSERT do tabulek vehicle-positions.pid.jis_infotexts a vehicle-positions.pid.jis_infotexts_ropidgtfs_stops`" --> vp_pg;
+    golemio_refresh_infotexts_task --> golemio_refresh_infotexts_cache_task;
+
+    golemio_refresh_infotexts_cache_task -- "`Aktualizace cache jisCache:infotexts:* a jisCache:stop-infotexts:*`" --> vp_redis;
+```
+
+Formát zasílaných dat je dále více popsán v implementační dokumentaci ([události](../implementation_documentation.md#jis-events-1), [infotexty](../implementation_documentation.md#jis-infotexts-1)), stejně tak jako odkazy na [Input Gateway OpenAPI](../implementation_documentation.md#input-api) a popis [uložení dat](../implementation_documentation.md#uložení-dat) včetně databázového schema a popisu retence. Data infotextů jsou dále cachovány - tento proces je popsán v dokumentaci [Redis cache](../cache/types/redis.md#cache-pro-api-přestupních-tabulí-transfer-boards).
+
+## Pasivní načítání (pull) dat
+
+V případě potřeby (např. nedojde-li kvůli chybě k aktivnímu poslání dat) lze využít pasivní načtení (pull) dat z VYMI REST API do Golemia. Pro spuštění načtení může vývojář zaslat prázdnou zprávu do správné RabbitMQ fronty, kterou zkonzumuje VP Integration Engine a za pomoci HTTP GET dotazu získá data z VYMI back end služby.
+
+Kromě manuálního spuštění vývojářem je nyní navíc aktivní cron task, který každou minutu automaticky spouští pasivní načítání dat z VYMI do Golemia. Tento mechanismus zajišťuje vyšší odolnost proti výpadkům v aktivním posílání (push) dat.
+
+Při pasivním načítání dat z VYMI do Golemia se využívá mechanismus ETag, který umožňuje rozpoznat, zda se od posledního načtení data změnila. Díky tomu se při opakovaném dotazu přenášejí pouze nová nebo upravená data, zatímco v případě beze změny se vrací pouze informace o tom, že obsah zůstal stejný. Tento přístup zmenšuje objem přenášených dat a snižuje zátěž na databázi a server. ETagy jsou spravovány zvlášť pro události a pro infotexty, aby se změny každého typu vyhodnocovaly nezávisle.
+
+Při pasivním načítání se z VYMI vždy přenačítají pouze aktuální (aktivní) události a infotexty:
+- všechny události, které mají `status` `PUBLISHED`, a zároveň `updated_at` hodnotu z posledních 24 hodin nebo `active_period_end` je `NULL` nebo >= aktuální čas, neboli lidsky všechny publikované (ne-draft) události, které jsou aktivní nebo byly upraveny v posledním dnu;
+- všechny infotexty, které mají `status` `PUBLISHED`, `visibility` `PUBLIC` a zároveň `active_period_end` je `NULL` nebo >= aktuální čas, neboli lidsky všechny aktivní, budoucí a publikované (ne-draft) infotexty.
+
+## Chování databáze v Golemio
+
+Události – v Golemio databázi se uchovávají všechny historické i aktuální události. Staré záznamy se nepromazávají.
+
+Infotexty – v Golemio databázi se uchovávají pouze aktivní infotexty. Neaktivní se při každém přenačtení promazávají.
+
+Proces je podrobněji znázorněn na následujícím diagramu (detailnější prvky aplikační struktury jsou vynechány).
+
+```mermaid
+flowchart TB
+    subgraph "VYMI"
+        subgraph "VYMI Back End"
+            vymi_exports_controller_get_events["`V1ExportsController.getEventListInCustomFormat`"];
+            vymi_exports_controller_get_infotexts["`V1ExportsController.getInfotextListInCustomFormat`"];
+
+            vymi_get_events["`EventFacade.getFilteredCustomFormatList`"];
+            vymi_get_infotexts["`InfotextFacade.getFilteredCustomFormatList`"];
+        end
+
+        vymi_pg[("`VYMI PostgreSQL`")];
+    end
+
+    subgraph "Golemio"
+        subgraph "Golemio RabbitMQ"
+            golemio_rabbit_fetch_events["`Fronta vehicle-positions.jis.fetchJISEvents`"];
+            golemio_rabbit_fetch_infotexts["`Fronta vehicle-positions.jis.fetchJISInfotexts`"];
+            golemio_rabbit_refresh_events["`Fronta vehicle-positions.jis.refreshJISEvents`"];
+            golemio_rabbit_refresh_infotexts["`Fronta vehicle-positions.jis.refreshJISInfotexts`"];
+        end
+
+        subgraph "Golemio VP Integration Engine"
+            golemio_fetch_events_task["`FetchJISEventsTask`"];
+            golemio_fetch_infotexts_task["`FetchJISInfotextsTask`"];
+            golemio_refresh_events_task["`RefreshJISEventsTask`"];
+            golemio_refresh_infotexts_task["`RefreshJISInfotextsTask`"];
+            golemio_refresh_infotexts_cache_task["`RefreshJISInfotextsCacheTask`"];
+
+            %% invisible unicode char ‎ due to https://github.com/orgs/community/discussions/106690
+            golemio_api_get_events["`HTTPS GET s API klíčem na https‎://api-vymi.golemio.cz/v1/exports/events/custom-format`"];
+            golemio_api_get_infotexts["`HTTPS GET s API klíčem na https‎://api-vymi.golemio.cz/v1/exports/infotexts/custom-format`"];
+        end
+
+        vp_pg[("`VP PostgreSQL`")];
+        vp_redis[("`VP Redis (Valkey)`")];
+    end
+
+    vymi_get_events <-- "`SELECT aktuálních událostí z tabulek vehicle-positions.pid.jis_events a vehicle-positions.pid.jis_events_ropidgtfs_routes`" --> vymi_pg;
+    vymi_get_infotexts <-- "`SELECT aktuálních infotextů z tabulek vehicle-positions.pid.jis_infotexts a vehicle-positions.pid.jis_infotexts_ropidgtfs_stops`" --> vymi_pg;
+
+    golemio_rabbit_fetch_events --> golemio_fetch_events_task;
+    golemio_rabbit_fetch_infotexts --> golemio_fetch_infotexts_task;
+    golemio_rabbit_refresh_events --> golemio_refresh_events_task;
+    golemio_rabbit_refresh_infotexts --> golemio_refresh_infotexts_task;
+
+    golemio_fetch_events_task --> golemio_api_get_events;
+    golemio_fetch_infotexts_task --> golemio_api_get_infotexts;
+
+    golemio_api_get_events -- "`Přes VYMI Ory Oathkeeper`" --> vymi_exports_controller_get_events;
+    golemio_api_get_infotexts -- "`Přes VYMI Ory Oathkeeper`" --> vymi_exports_controller_get_infotexts;
+
+    vymi_exports_controller_get_events --> vymi_get_events;
+    vymi_exports_controller_get_infotexts --> vymi_get_infotexts;
+
+    vymi_get_events --> golemio_rabbit_refresh_events;
+    vymi_get_infotexts --> golemio_rabbit_refresh_infotexts;
+
+    golemio_refresh_events_task -- "`UPSERT do tabulek vehicle-positions.pid.jis_events a vehicle-positions.pid.jis_events_ropidgtfs_routes`" --> vp_pg;
+    golemio_refresh_infotexts_task -- "`UPSERT do tabulek vehicle-positions.pid.jis_infotexts a vehicle-positions.pid.jis_infotexts_ropidgtfs_stops`" --> vp_pg;
+    golemio_refresh_infotexts_task --> golemio_refresh_infotexts_cache_task;
+
+    golemio_refresh_infotexts_cache_task -- "`Aktualizace cache jisCache:infotexts:* a jisCache:stop-infotexts:*`" --> vp_redis;
+```
+
+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`).
+
+### Německá jazyková mutace (`de`)
+
+Pole `header_text`, `description_text`, `description_html` a `cause` mají v `/v1/jis/events/custom-format` a v odchozím webhooku i německou mutaci (`de`), kterou VYMI od issue [vymi-general#348](https://gitlab.com/operator-ict/golemio/jis/vymi-alerts/vymi-general/-/work_items/348) propaguje spolu s `cs`/`en`. Německé hodnoty pole `header_text`/`description_text`/`description_html` dodává přímo VYMI; hodnoty pole `cause` jsou naopak — stejně jako `cs`/`en` — mapované staticky v Golemiu (`JISEventTranslationHelper.causeToDe`), zatím jako provizorní překlady s prefixem `TMP:`, než budou nahrazeny finálními hodnotami.
+
+Pole `cause_detail`, `effect_detail`, `url` a jednotlivé `effects` němčinu nemají a nezískají ji — VYMI je vůbec neposílá s `de` hodnotou (validace na VYMI straně to explicitně zakazuje).
+
+Na vstupu (IG, `POST /v1/jis/events`) je pole `de` u `header_text`/`effect_detail`/`description_text`/`description_html`/`url` sice ve schématu obecně povoleno (sdílí jeden validátor), ale v praxi ho VYMI vyplňuje jen u `header_text`/`description_text`/`description_html` — viz předchozí odstavec.
+
+### `attachments` (přílohy)
+
+Pole `attachments` obsahuje dokumenty a odkazy přiložené k události (VYMI `kind: document|link`; vložené obrázky (`inline_image`) se nepropagují). Každá příloha má tvar:
+```json
+{ "url": "https://example.com/doc.pdf", "name": { "cs": "Dokument ke stažení", "en": "Document to download", "de": "Herunterladen" } }
+```
+`name` může chybět i být prázdný objekt, pokud VYMI název přílohy nevyplnila. Pole je dostupné v `/v1/jis/events/custom-format` a v odchozím webhooku; do GTFS-RT alert feedu se nepropaguje.
+
+### `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/jis/missing.md

@@ -0,0 +1,110 @@
+# Kdy je odjezd oznacen jako MISSING
+
+Odjezd je oznacen jako **MISSING**, pokud vozidlo **melo jet**, ale **nejsou k dispozici zadna validni realtime data (delay / poloha)**.
+
+Implementace: `src/output-gateway/pid/models/helpers/SkipHelper.ts` - metoda `isVehicleMissing()`
+
+---
+
+## Konstanty
+
+| Konstanta | Hodnota | Popis |
+|-----------|---------|-------|
+| `START_SOON_MINUTES_THRESHOLD` | 30 min | Prah pro "brzy zacina" (non-metro) |
+| `START_SOON_METRO_MINUTES_THRESHOLD` | 5 min | Prah pro "brzy zacina" (metro) |
+| `DEPARTURED_MINUTES_THRESHOLD` | -2 min | Trip mel zacit pred vice nez 2 minutami |
+| `TRIP_GAP_MINUTES_THRESHOLD` | 60 min | Velka mezera mezi tripy v runu |
+
+---
+
+## MISSING = true (odjezd se nezobrazuje)
+
+Odjezd je **MISSING**, pokud plati nasledujici:
+
+### 1. Zakladni podminky (musi platit vsechny)
+
+- `is_delay_available = false`
+- `trip.start_timestamp` **nebo** `planned_start_timestamp` existuje
+- `run_number` existuje (neni null)
+- `route_id` existuje (neni null)
+
+### 2. Casove podminky
+
+Trip zacina v casovem okne:
+- **Non-metro:** do 30 minut
+- **Metro:** do 5 minut
+
+A zaroven:
+- Trip **uz mel zacit** (`minutesToStart < -2`)
+
+**Vysledek:** odjezd je **MISSING**
+
+---
+
+### 3. Odjezd navazuje na predchozi jizdu bez dat
+
+Pokud trip **jeste uplne nesplnuje bod 2** (nezacal pred 2+ minutami), muze byt stale oznacen jako **MISSING**, pokud:
+
+1. Existuje `runSchedule` pro dany run
+2. Trip **neni prvni v runu**
+3. Mezi aktualnim a predchozim tripem **neni mezera >= 60 minut**
+4. Predchozi trip:
+   - **nema realtime data** (je v `untrackedTrips`)
+   - **uz mel zacit** (`previousMinutesToStart < -2`)
+
+**Vysledek:** odjezd je **MISSING**
+
+---
+
+### 4. Rozsirena kontrola pres predchozi jizdu
+
+Pokud predchozi trip sam **neni prvni v runu** (index > 0) a:
+
+- Mezi jeho startem a koncem jeste starsi jizdy **neni mezera >= 60 minut**
+
+Predchozi jizda je take povazovana za chybejici a **aktualni odjezd je MISSING**.
+
+---
+
+## NOT MISSING = false (odjezd se zobrazi)
+
+Odjezd **neni MISSING**, pokud plati alespon jedna z techto podminek:
+
+### Chybi vstupni data
+
+- `trip.start_timestamp` neexistuje (a `planned_start_timestamp` taky ne)
+- `run_number = null`
+- `route_id = null`
+
+### Ma realtime data
+
+- `is_delay_available = true`
+
+### Je prilis brzy
+
+Trip zacina:
+- **Non-metro:** za >= 30 minut
+- **Metro:** za >= 5 minut
+
+### Nelze overit navaznost jizd
+
+- `runSchedule` pro dany run neexistuje
+- Trip neni nalezen v run schedule
+- Trip je **prvni v runu** (index = 0)
+
+### Mezi jizdami je velka mezera
+
+- Mezera od predchozi jizdy >= 60 minut
+- Mezera pred predchozi jizdou >= 60 minut
+
+### Predchozi jizda ma data nebo jeste nezacala
+
+- Predchozi trip **ma realtime data** (neni v `untrackedTrips`)
+- Predchozi trip **jeste nemel zacit** (`previousMinutesToStart >= -2`)
+
+---
+
+
+## Shrnnuti
+
+> **Odjezd je MISSING, kdyz uz mel jet, nema zadna realtime data a zaroven neni duvod si myslet, ze vozidlo teprve prijede z jine jizdy.**