Formáty kurátorovaných datových souborů

Referenční dokumentace ručně kurátorovaných JSON souborů. Scénáře a referenční místa čte js/app.js a validuje tools/test_model.mjs; parkovací souhrny zpracovává tools/parkovani-oblasti.py a validuje tools/test_parkovani.mjs.

data/parkovani-oblasti.json

Kanonický, ručně kontrolovaný vstup pro oblastní mapu parkování. Každý záznam se spojuje s populací a geometrií přes šestimístný textový kodZsj; pořadí záznamů se k párování nikdy nepoužívá.

{
  "schemaVersion": 1,
  "souhrnPublikovany": {
    "mistaLegalni": 5164,
    "mistaTechnicka": 7426,
    "vozidlaNoc": 5340,
    "vozidlaDen": 4680
  },
  "oblasti": [
    {
      "kodZsj": "009075",
      "nazev": "Spořilov",
      "populacniZsj": "Spořilov",
      "mistaLegalni": 257,
      "mistaTechnicka": 577,
      "vozidlaNoc": 551,
      "vozidlaDen": 387
    }
  ],
  "bezPruzkumu": [
    {
      "kodZsj": "009253",
      "nazev": "Popovice",
      "populacniZsj": "Popovice"
    }
  ]
}

• oblasti obsahují 20 souhrnných oblastí tabulky 3.1. Kapacity a vozidla jsou absolutní hodnoty průzkumu; odvozené obsazenosti se do vstupu ručně nezapisují.
• bezPruzkumu obsahuje zbývající čtyři ZSJ města. Generátor jim přidá populaci a geometrii, ale parkovací hodnoty ponechá null.
• populacniZsj je přesný název klíče v mhd-brandys/addr_pop.csv; může se lišit od krátkého názvu oblasti v analýze.
• souhrnPublikovany zachovává publikované celky. Součet zaokrouhlených oblastních řádků se u počtu vozidel nepatrně liší a nesmí potichu přepsat publikovaný souhrn.
• spolehlivostVozidel a poznamkaDat označují oblasti, kde se publikovaný souhrn výrazně liší od agregace dostupných excelových průměrů. Poznámka se zobrazuje ve veřejném detailu oblasti; nejistota se tedy neztrácí při generování GeoJSONu.

Generovaný data/parkovani-oblasti.geojson rozlišuje stavDat hodnotami zmereno, nulova_kapacita a bez_pruzkumu. Nulová kapacita s vozidly má obsazenost null, nikoli nulu nebo nekonečno. Soubor obsahuje také mistaNa1000, noční deficit a příznak rezidentniPriorita.

data/scenare.json

Pole objektů, každý objekt je jeden kurátorovaný dopravní scénář (typicky uzavírka) nabízený v panelu “Scénáře” a přes URL #s=<id>.

[
  {
    "id": "most-svabinskeho",        // string, POVINNÉ, unikátní v rámci souboru
    "nazev": "Uzavírka mostu…",      // string, zobrazený nadpis karty
    "popis": "…",                    // string, volitelný, text karty
    "stav": "hypoteticky",           // "planovano" | "probiha" | "hypoteticky"
    "termin": null,                  // string nebo null, volitelný termín ("🗓️ …")
    "odkaz": null,                   // string (http/https URL) nebo null
    "useky": ["26790228#30127351", …], // pole stabilních klíčů úseků, POVINNÉ
    "cesty": [                       // pole dvojic [odId, doId], VOLITELNÉ
      ["sb-namesti", "br-namesti"],
      ["sb-namesti", "d10-exit14"],
      ["zamek", "sb-namesti"]
    ]
  }
]

Pole

• id (string, povinné) – stabilní identifikátor scénáře, používá se v URL (#s=<id>) a jako React/DOM klíč karty. Musí být unikátní napříč souborem; kolize se nekontroluje automaticky, jen vizuálně (dvě karty by splynuly do stejného odkazu).
• nazev (string) – nadpis karty. Chybí-li, vytvorKartuScenare použije id jako fallback.
• popis (string, volitelné) – popisný text pod nadpisem.
• stav (string, volitelné) – jedna z STAVY_SCENARE v js/app.js (planovano/probiha/hypoteticky). Neplatná/chybějící hodnota se tiše normalizuje na hypoteticky (viz normalizujStav), karta nespadne.
• termin (string nebo null, volitelné) – zobrazí se jako 🗓️ termin, pokud je pravdivá hodnota (truthy).
• odkaz (string nebo null, volitelné) – odkaz na dokumentaci/úřední desku. Vykreslí se jen pro http:/https: schéma (viz jeBezpecnyOdkaz) – jiné schéma (javascript:, data:, …) by z klikací karty udělalo vektor útoku, takže se prostě nezobrazí.
• useky (pole stringů, povinné z pohledu smysluplného scénáře) – klíče úseků ve tvaru klicUseku ("<OSM way id>#<OSM node id prvního uzlu>", viz js/graf.js). Při nasazení scénáře se převedou přes graf.osmNaFeatId na uzavírky; klíče, které v aktuální síti neexistují (přegenerovaná síť), se zahodí a v panelu se zobrazí varování (zobrazVarovaniNeznameKlice, zdroj "scenar").
• cesty (pole dvojic [odId, doId], volitelné) – nahradí mista.vychoziCesty v panelu “Typické cesty” po dobu, kdy je scénář aktivní. odId/doId musí odkazovat na id z data/mista.json – odkaz na neznámé id se ve výpočtu tiše přeskočí (spocitejCesty). Slouží k tomu, aby scénář zdůraznil právě ty trasy, které jeho uzavírka nejvíc zasáhne. Chybí-li pole cesty (nebo po validaci nezbyde žádná platná dvojice), panel se vrátí na výchozí dvojice z mista.json – nezůstává viset zvýraznění předchozího scénáře (viz platneCesty a stav.cestyAktivni v js/app.js).

Chování při chybě

• Celý soubor se nenačte / není pole → panel scénářů zůstane prázdný (nactiScenare vrací []), aplikace běží dál.
• Položka pole není objekt nebo nemá string id/pole useky → položka se přeskočí s console.warn, zbytek scénářů se vykreslí normálně.
• Položka pole useky obsahuje neznámý klíč → klíč se zahodí, zbylé klíče scénáře se uzavřou, v UI se zobrazí varování s počtem zahozených úseků.
• Položka pole cesty není dvojice dvou stringů → položka se přeskočí s console.warn (platneCesty v js/app.js), zbylé platné dvojice se použijí; je-li po filtrování pole prázdné, chová se to jako by cesty chybělo (fallback na mista.vychoziCesty).

Konzistence se sítí (kontroluje tools/test_model.mjs)

• Všechny klíče useky všech scénářů musí existovat v aktuální síti (graf.osmNaFeatId) – jinak se scénář po přegenerování sítě tiše rozsype.
• Scénář most-svabinskeho musí obsahovat přesně tytéž úseky jako bbox detekce mostu Maxe Švabinského v testu (množinová rovnost).
• Scénář prutah-stara-boleslav musí obsahovat jen úseky tříd secondary/tertiary tvořící jeden souvislý koridor.

data/mista.json

Objekt s referenčními body dvojměstí pro UI výběr “odkud/kam” a panel “Typické cesty”.

{
  "komentar": "…",           // string, volný popis souboru (nečte kód)
  "zdrojSouradnic": "…",     // string, volný popis zdroje souřadnic (nečte kód)
  "mista": [
    {
      "id": "br-namesti",        // string, POVINNÉ, unikátní v rámci "mista"
      "nazev": "Masarykovo …",   // string, zobrazovaný popisek
      "lon": 14.65958,           // number, WGS84, POVINNÉ, konečné (finite)
      "lat": 50.18596,           // number, WGS84, POVINNÉ, konečné (finite)
      "poznamka": "…"            // string, volitelné, zdroj/ověření souřadnic
    }
  ],
  "vychoziCesty": [
    ["sb-namesti", "br-namesti"]  // dvojice [odId, doId], id musí existovat v "mista"
  ]
}

Pole

• mista (pole, povinné) – referenční body. Každý prvek potřebuje string id (unikátní v rámci pole – při kolizi vyhrává poslední výskyt, protože js/typicke-cesty.js staví id -> uzel mapu) a konečná číselná lon/lat ve stupních WGS84 (EPSG:4326). nazev je zobrazovaný popisek (fallback na id, pokud chybí); poznamka je jen dokumentační text.
• vychoziCesty (pole dvojic, povinné) – výchozí nabídka tras pro panel “Typické cesty”, nahrazovaná stav.cestyAktivni, pokud je aktivní scénář s vlastním polem cesty (viz výše). odId/doId musí odkazovat na id z mista – neznámé id se ve výpočtu tiše přeskočí.

Chování při chybě

• Soubor se nenačte / chybí mista nebo vychoziCesty jako pole → nactiMista vrací null, panel “Typické cesty” zůstane skrytý (stav.mista === null), zbytek aplikace běží dál.
• Prvek mista[i] není objekt, nemá string id, nebo má nekonečné/chybějící lon/lat (NaN, Infinity, null, chybějící pole) → prvek se přeskočí s console.warn (jeValidniMisto v js/app.js), zbytek bodů se načte normálně.
• Prvek vychoziCesty[i] není pole přesně dvou stringů → prvek se přeskočí s console.warn (jeValidniDvojice), zbylé platné dvojice se použijí.
• Dvojice odkazuje na id, které v mista po validaci neexistuje → spocitejCesty (js/typicke-cesty.js) tuto dvojici tiše vynechá z výsledku (žádná chyba, žádný řádek v panelu).

Testy tvaru obou souborů a robustnosti proti vadným datům jsou v tools/test_model.mjs (sekce “robustnost vůči vadným datům” a “typické cesty”).