# DátováMapa – vízia {#datovamapa-vize}

Dátum: 2026-10-06 (nahrádza pôvodný kontext z 2026-08, ten je v `docs/archiv/`)

## Čo je DátováMapa {#co-je-datovamapa}

DátováMapa je **otvorené rozhranie na vizualizáciu dát v mape**. Definuje otvorenú schému (protokol), cez ktorú môže ktokoľvek zobraziť v mape ľubovoľné dáta – body, línie, plochy, hustoty, rastrové vrstvy.

Princíp:

1. Poskytovateľ dát zverejní **manifest** (popis seba a svojich dátových sád) a **dátový endpoint** podľa protokolu DátováMapa.
2. Poskytovateľ manifest zaregistruje; po schválení prevádzkovateľom sa sady objavia v katalógu.
3. Keď používateľ sadu zapne, portál sa dopytuje zdroja (pre aktuálny výrez mapy a nastavené filtre), odpoveď overí, uloží do cache a vykreslí podľa popisu z manifestu.

Portál dáta nevlastní; sprostredkúva ich a vždy uvádza zdroj. Prevádzkovateľom portálu je [vrealmatic.com](https://vrealmatic.com/webove-sluzby).

## Prínos {#prinos}

**Pre používateľov:** na jednej mape si skombinujú dáta z ľubovoľných zdrojov – bez prepínania medzi desiatkami mapových portálov.

**Pre poskytovateľov:**

- nemusia riešiť mapu, štýly ani mapový server – stačí JSON endpoint,
- sú súčasťou otvoreného dátového portálu, ich dáta sa stretávajú s dátami ostatných,
- sú viditeľne uvedení ako zdroj (pri dátach v mape, v detaile objektu, v prehľade zdrojov).

## Dáta pripravujú AI agenti {#data-pripravuji-ai-agenti}

Očakávame, že dáta u poskytovateľov budú pripravovať hlavne AI agenti (na pokyn človeka, ktorý dáta vlastní). Preto je celý portál postavený ako „AI friendly“:

- **Všetko je v markdowne.** Každá stránka dokumentácie má markdown verziu (`/dokumentacia/{slug}.md`), hlavná stránka `/index.md`, katalóg `/zdroje.md`; rozcestník `/llms.txt` a celá dokumentácia v jednom súbore `/llms-full.txt`. Zdrojom pravdy sú súbory v `docs/`, HTML sa z nich generuje.
- **Návod pre agentov** s postupom, rozhodovacími tabuľkami, šablónami kódu, pravidlami (osobné údaje, licencie) a kritériami hotovej práce.
- **Strojové schémy** generované z jedného zdroja: JSON Schema manifestu a dát, OpenAPI kontrakt poskytovateľa (agent z neho vygeneruje server) a OpenAPI portálu.
- **Validátor so spätnou väzbou**: stabilné kódy nálezov, presné cesty a rady, ako chybu opraviť; živý test celého poskytovateľa. Agent iteruje, kým nie je `valid: true`.
- **MCP server** `/mcp`: dokumentácia, schémy, príklady, validácia, katalóg a dáta ako nástroje.
- **Overené príklady**: každá ukážka v dokumentácii prechádza validátorom (`npm run check:docs`), aby agent nekopíroval chybu.
- **Polia na dohľadateľnosť**: `keywords`, `useCases`, `description`, `fields` – podľa nich dáta nájdu ľudia aj asistent portálu.

Dáta v portáli čítajú aj AI asistenti bežných ľudí a firiem. Cez MCP server alebo HTTP API nájdu miesto (register adries), opýtajú sa vybraných sád, čo je v bode a okolí (aj rastrových máp ako záplavy, radón alebo hluk), a dostanú súhrn za obec. Dáta si vyložia sami a uvedú zdroj. Návod: [Dáta pre AI asistentov](https://datovamapa.sk/dokumentacia/ai-asistenti.md).

## Princípy {#principy}

- **Otvorený protokol.** Schéma je verejná (`/schema/0.1/manifest.json`, `/schema/0.1/data.json`), založená na GeoJSON (RFC 7946). Takmer všetko je voliteľné, povinné je len malé minimum.
- **Zámer, nie knižnica.** Poskytovateľ popisuje, *čo* chce ukázať (body podľa kategórie, kartogram podľa hodnoty…), nie konkrétne nastavenie mapovej knižnice. Portál môže vykresľovanie meniť bez dopadu na poskytovateľa.
- **Dopredná kompatibilita.** Neznáme polia sa ignorujú, neznámy typ vizualizácie sa vykreslí predvoleným štýlom. Protokol tak môže rásť bez rozbíjania existujúcich zdrojov.
- **Jednoduchá hlavná stránka.** Len mapa a logo. Na prejdenie myšou / klik sa otvorí výber dát. Žiadne ďalšie panely.
- **Vstupné stránky pre konkrétne dáta.** Kto hľadá konkrétnu metriku, príde z vyhľadávača na stránku sady (`/mapa/{provider}/{dataset}`), sady za obec alebo zostavenej mapy (`/mapy/{slug}`): rovnaká mapa s predvolenými dátami a popisom so súhrnom dát. Do mapy si pridá ďalšie vrstvy ako na hlavnej stránke.
- **Bezpečnosť.** Dáta poskytovateľov sa nikdy nevkladajú ako HTML, proxy sa pýta len registrovaných zdrojov, s limitmi na čas a veľkosť.

## Hlavná stránka {#hlavni-stranka}

- Celoplošná mapa a logo vľavo hore. Mapa sa otvorí nad celým Slovenskom.
- **Úvod.** Kto príde bez výberu a bez odkazu na miesto, toho sa mapa pri načítaní opýta na polohu v prehliadači, prenesie ho do jeho okolia a vedľa mapy sa otvorí úvodné okno „Vaše okolie v dátach“ – rýchly štart: asistent (pripravujeme) s rýchlymi voľbami, teda zostavenými mapami na jedno kliknutie, a odkazmi na práve aktuálne dáta. Jednotlivé vrstvy sa zapínajú v katalógu („Celý katalóg“). Kto polohu nepovolí alebo je mimo Slovenska, dostane úvod pre celé Slovensko. Odkaz s výberom úvod preskočí; úvod sa však vráti, kedykoľvek v mape nič nie je.
- Presnú polohu si používateľ zobrazí tlačidlom „Moje okolie“ vpravo hore vedľa ovládania mapy – prehliadač sa pýta až po kliknutí; kto polohu povolil skôr, toho mapa rovno ukáže v jeho okolí (a úvod použije túto polohu).
- Prejdenie myšou na logo (alebo klik / tap) otvorí veľké okno výberu (cez 80 % šírky): vľavo **katalóg** ako karty podľa kategórií s vyhľadávaním, vpravo **Na mape** – zapnuté vrstvy so stavom, legendou a filtrami. Hore je ukážka budúceho asistenta – zatiaľ neaktívna. Klik alebo práca v okne ho pripne, zatvorí sa krížikom, klávesom Esc alebo klikom mimo.
- Výber sa ukladá do URL, odkaz sa dá zdieľať.

### Zadanie v prirodzenom jazyku (budúcnosť) {#zadani-v-prirozenem-jazyce-budoucnost}

Cieľ: používateľ napíše napr. *„Chcem stavať v obci Lipany, zobraz mi všetky relevantné dáta, čo máš pre môj účel“* a portál:

1. pochopí miesto (geokódovanie obce / adresy / parcely) a presunie mapu,
2. pochopí účel (stavba) a vyberie relevantné sady podľa `useCases`, `keywords` a popisov v manifestoch,
3. prípadne nastaví filtre a zhrnie, čo v dátach vidí.

V okne je zatiaľ len neaktívna ukážka. Kroky 1–3 však už vie cudzí AI asistent cez MCP: `find_place` (geokódovanie registra adries), `nearby` (výber sád podľa účelu alebo textu a dopyt na bod) a `summary`. Výber sád podľa kľúčových slov a účelov (`src/lib/search.ts`) používa aj vyhľadávanie v katalógu a MCP nástroj `catalog`. Preto majú manifesty polia `keywords` a `useCases` – pripravujú dáta pre asistenta.

## Cache a vlastná dátová vrstva {#cache-a-vlastni-datova-vrstva}

Na začiatku sú zdrojom dát externé API poskytovateľov. Portál odpovede drží v cache (podľa `cache.ttl`), aby sa zdroje nezaťažovali a mapa bola rýchla; pri výpadku zdroja môže krátko ukázať posledné známe dáta.

V podmienkach pre poskytovateľov si vyhradzujeme, že dáta môžeme v záujme **zrýchlenia, odľahčenia zdrojov, udržateľnosti, lepšej kombinatoriky, spájania súvislostí a práce s veľkými dátami** držať vo vlastnej cache / dátovej vrstve. Poskytovateľ to môže pri sade vypnúť (`cache.store: false`).

## Autorské hodnotenia (ďalšia verzia) {#autorska-hodnoceni-dalsi-verze}

Návrh, zatiaľ neimplementované. Vrstva pre ľudí s vlastným názorom a publikom – blogerov, recenzentov, kluby –, ktorí chcú ukázať hodnotenia miest: „Kaviarne podľa …“, „Cyklotrasy podľa …“, „Detské ihriská podľa …“. Každé miesto má hodnotenie, krátky verdikt a odkaz na článok.

Dnes to ide len všeobecne: autor si vystaví vlastný manifest a GeoJSON s číselným poľom a zafarbí body podľa hodnoty. Portál však nevie, že ide o hodnotenie, a autor musí dáta hostovať sám.

Návrh:

- **Hostujeme my.** Autor nahrá CSV alebo GeoJSON, prípadne body naklikne v mape. Dáta ukladá portál (D1 / R2), autor nepotrebuje vlastný web.
- **Hodnotenie ako pojem protokolu.** Typ vizualizácie `rating` a polia objektu `rating`, `ratingMax` (predvolene 5), `review` (krátky verdikt), `url` (článok) a `visited` (dátum návštevy). Portál ukáže hviezdičky v detaile, ponúkne filter „od N hviezdičiek“ a legendu odvodí sám. Typ môže použiť aj poskytovateľ s vlastným manifestom.
- **Autor je viditeľný.** Hodnotenie je názor konkrétneho človeka, nie údaj portálu. Meno a odkaz na autora sú pri vrstve aj v detaile každého miesta.
- **Schvaľovanie.** Vrstva je mimo katalógu, kým ju prevádzkovateľ neschváli, rovnako ako pri [samoregistrácii](https://datovamapa.sk/dokumentacia/pre-poskytovatelov.md#5-registrace).

Otvorené otázky:

- **Účty.** Portál dnes používateľské účty nemá. Nahrávanie potrebuje prihlásenie (napr. odkaz e-mailom) a ochranu proti zneužitiu.
- **Schvaľovanie zmien.** Autor bude dáta priebežne dopĺňať. Schvaľovať raz autora, alebo každú zmenu?
- **Voľné body, alebo existujúce miesta?** Naviazanie na existujúce miesto (napr. podnik z OpenStreetMap) umožní porovnať viac autorov pri jednom mieste, ale je výrazne zložitejšie.
- **Súhrny.** Priemer z viacerých autorov sa blíži recenzným serverom a otvára riziko manipulácie (vymyslení autori). Na začiatok len vrstvy vedľa seba.
- **Právo.** Negatívne hodnotenie pomenovaného podniku môže naraziť na ochranu dobrej povesti právnickej osoby (§ 135 Občianskeho zákonníka). Potrebné sú podmienky „autor zodpovedá za svoj obsah“, nahlásenie miesta a rýchle odstránenie. Hodnotia sa miesta, nie súkromné osoby.

## Plán {#plan}

1. **v0.1 (hotovo):** protokol (manifest + GeoJSON odpoveď), katalóg, proxy s cache, vizualizácie circle / heatmap / line / fill / raster / auto, filtre, detail objektu, prehľad zdrojov, ukážkový poskytovateľ; dokumentácia v markdowne, llms.txt, validátor, MCP server, OpenAPI.
2. **Registrácia poskytovateľov:** samoobslužná registrácia so schvaľovaním je hotová (formulár, API, MCP); zostáva monitoring dostupnosti zdrojov.
3. **Asistent:** pre cudzích AI asistentov hotové (MCP a API: geokódovanie registra adries, dopyt na bod a okolie vrátane rastrových sád, súhrn za obec); zostáva vlastný asistent v okne výberu (LLM nad katalógom).
4. **Ďalšie vizualizácie a zdroje:** ikony/symboly, 3D vytiahnutie plôch, časová os, toky, vektorové dlaždice (MVT/PMTiles), OGC API Features a WFS ako typ zdroja.
5. **Vlastná dátová vrstva:** trvalé uloženie dát (Cloudflare D1/R2, prípadne PostGIS), priestorové dopyty cez viac zdrojov, predpočítané agregácie pre veľké dáta.
6. **Autorské hodnotenia:** hodnotiace vrstvy blogerov a recenzentov hostované portálom, typ vizualizácie `rating` (pozri [návrh](https://datovamapa.sk/dokumentacia/o-projekte.md#autorska-hodnoceni-dalsi-verze)).