# DatováMapa – vize

Datum: 2026-10-06 (nahrazuje původní kontext z 2026-08, ten je v `docs/archiv/`)

## Co je DatováMapa

DatováMapa je **otevřené rozhraní pro vizualizaci dat v mapě**. Definuje otevřené schéma (protokol), přes které může kdokoli zobrazit v mapě libovolná data – body, linie, plochy, hustoty, rastrové vrstvy.

Princip:

1. Poskytovatel dat zveřejní **manifest** (popis sebe a svých datových sad) a **datový endpoint** podle protokolu DatováMapa.
2. Poskytovatel manifest zaregistruje; po schválení provozovatelem se sady objeví v katalogu.
3. Když uživatel sadu zapne, portál se doptá zdroje (pro aktuální výřez mapy a nastavené filtry), odpověď ověří, uloží do cache a vykreslí podle popisu z manifestu.

Portál data nevlastní; zprostředkovává je a vždy uvádí zdroj. Provozovatelem portálu je [vrealmatic.com](https://vrealmatic.com/webove-sluzby).

## Přínos

**Pro uživatele:** na jedné mapě si zkombinuje data z libovolných zdrojů – bez přepínání mezi desítkami mapových portálů.

**Pro poskytovatele:**

- nemusí řešit mapu, styly ani mapový server – stačí JSON endpoint,
- jsou součástí otevřeného datového portálu, jejich data se potkávají s daty ostatních,
- jsou viditelně uvedeni jako zdroj (u dat v mapě, v detailu objektu, v přehledu zdrojů).

## Data připravují AI agenti

Očekáváme, že data u poskytovatelů budou připravovat hlavně AI agenti (na pokyn člověka, který data vlastní). Proto je celý portál stavěný „AI friendly“:

- **Všechno je v markdownu.** Každá stránka dokumentace má markdown verzi (`/dokumentace/{slug}.md`), hlavní stránka `/index.md`, katalog `/zdroje.md`; rozcestník `/llms.txt` a celá dokumentace v jednom souboru `/llms-full.txt`. Zdrojem pravdy jsou soubory v `docs/`, HTML se z nich generuje.
- **Návod pro agenty** s postupem, rozhodovacími tabulkami, šablonami kódu, pravidly (osobní údaje, licence) a kritérii hotové práce.
- **Strojová schémata** generovaná z jednoho zdroje: JSON Schema manifestu a dat, OpenAPI kontrakt poskytovatele (agent z něj vygeneruje server) a OpenAPI portálu.
- **Validátor se zpětnou vazbou**: stabilní kódy nálezů, přesné cesty a rady, jak chybu opravit; živý test celého poskytovatele. Agent iteruje, dokud není `valid: true`.
- **MCP server** `/mcp`: dokumentace, schémata, příklady, validace, katalog a data jako nástroje.
- **Ověřené příklady**: každá ukázka v dokumentaci prochází validátorem (`npm run check:docs`), aby agent nekopíroval chybu.
- **Pole pro dohledatelnost**: `keywords`, `useCases`, `description`, `fields` – podle nich data najdou lidé i asistent portálu.

Data v portálu čtou i AI asistenti běžných lidí a firem. Přes MCP server nebo HTTP API najdou místo (RÚIAN), zeptají se vybraných sad, co je v bodě a okolí (i rastrových map jako záplavy, radon nebo hluk), a dostanou souhrn za obec. Data si vyloží sami a uvedou zdroj. Návod: [Data pro AI asistenty](https://datovamapa.cz/dokumentace/ai-asistenti.md).

## Principy

- **Otevřený protokol.** Schéma je veřejné (`/schema/0.1/manifest.json`, `/schema/0.1/data.json`), založené na GeoJSON (RFC 7946). Skoro vše je volitelné, povinné je jen malé minimum.
- **Záměr, ne knihovna.** Poskytovatel popisuje, *co* chce ukázat (body podle kategorie, kartogram podle hodnoty…), ne konkrétní nastavení mapové knihovny. Portál může vykreslování měnit bez dopadu na poskytovatele.
- **Dopředná kompatibilita.** Neznámá pole se ignorují, neznámý typ vizualizace se vykreslí výchozím stylem. Protokol tak může růst bez rozbíjení existujících zdrojů.
- **Jednoduchá hlavní stránka.** Jen mapa a logo. Na najetí / klik se otevře výběr dat. Žádné panely navíc.
- **Vstupní stránky pro konkrétní data.** Kdo hledá konkrétní metriku, přijde z vyhledávače na stránku sady (`/mapa/{provider}/{dataset}`), sady za obec nebo sestavené mapy (`/mapy/{slug}`): stejná mapa s předvybranými daty a popisem se souhrnem dat. Do mapy si přidá další vrstvy jako na hlavní stránce.
- **Bezpečnost.** Data poskytovatelů se nikdy nevkládají jako HTML, proxy se ptá jen registrovaných zdrojů, s limity na čas a velikost.

## Hlavní stránka

- Celoplošná mapa a logo vlevo nahoře. Mapa se otevře nad celým Českem.
- **Úvod.** Kdo přijde bez výběru a bez odkazu na místo, toho se mapa při načtení zeptá na polohu v prohlížeči, přenese ho do jeho okolí a vedle mapy se otevře úvodní okno „Vaše okolí v datech“ s datovými sadami pro tu oblast: nejdřív místní (např. Brno, Praha), pak vybraná živá a zajímavá data pro celé Česko. Zapnutá vrstva je hned vidět v mapě; „Celý katalog“ otevře velké okno výběru. Kdo polohu nepovolí nebo je mimo Česko, dostane úvod pro celé Česko. Odkaz se zapsanou pozicí nebo výběrem úvod přeskočí.
- Přesnou polohu si uživatel zobrazí tlačítkem „Mé okolí“ vpravo nahoře vedle ovládání mapy – prohlížeč se ptá až po kliknutí; kdo polohu povolil dřív, toho mapa rovnou ukáže v jeho okolí (a úvod použije tuto polohu).
- Najetí myší na logo (nebo klik / tap) otevře velké okno výběru (přes 80 % šířky): vlevo **katalog** jako karty po kategoriích s hledáním, vpravo **Na mapě** – zapnuté vrstvy se stavem, legendou a filtry. Nahoře je ukázka budoucího asistenta – zatím neaktivní. Klik nebo práce v okně ho připne, zavře se křížkem, klávesou Esc nebo klikem mimo.
- Výběr se ukládá do URL, odkaz jde sdílet.

### Zadání v přirozeném jazyce (budoucnost)

Cíl: uživatel napíše např. *„Chci stavět v obci Lipník, zobraz mi všechna relevantní data, co máš pro můj účel“* a portál:

1. pochopí místo (geokódování obce / adresy / parcely) a přesune mapu,
2. pochopí účel (stavba) a vybere relevantní sady podle `useCases`, `keywords` a popisů v manifestech,
3. případně nastaví filtry a shrne, co v datech vidí.

V okně je zatím jen neaktivní ukázka. Kroky 1–3 už ale umí cizí AI asistent přes MCP: `najit_misto` (geokódování RÚIAN), `v_okoli` (výběr sad podle účelu nebo textu a dotaz na bod) a `souhrn`. Výběr sad podle klíčových slov a účelů (`src/lib/search.ts`) používá i hledání v katalogu a MCP nástroj `katalog`. Proto mají manifesty pole `keywords` a `useCases` – připravují data pro asistenta.

## Cache a vlastní datová vrstva

Na začátku jsou zdrojem dat externí API poskytovatelů. Portál odpovědi drží v cache (podle `cache.ttl`), aby se zdroje nezatěžovaly a mapa byla rychlá; při výpadku zdroje může krátce ukázat poslední známá data.

V podmínkách pro poskytovatele si vyhrazujeme, že data můžeme v zájmu **zrychlení, odlehčení zdrojů, udržitelnosti, lepší kombinatoriky, spojování souvislostí a práce s velkými daty** držet ve vlastní cache / datové vrstvě. Poskytovatel to může u sady vypnout (`cache.store: false`).

## Autorská hodnocení (další verze)

Návrh, zatím neimplementováno. Vrstva pro lidi s vlastním názorem a publikem – blogery, recenzenty, kluby –, kteří chtějí ukázat hodnocení míst: „Kavárny podle …“, „Cyklotrasy podle …“, „Dětská hřiště podle …“. Každé místo má hodnocení, krátký verdikt a odkaz na článek.

Dnes to jde jen obecně: autor si vystaví vlastní manifest a GeoJSON s číselným polem a obarví body podle hodnoty. Portál ale neví, že jde o hodnocení, a autor musí data hostovat sám.

Návrh:

- **Hostujeme my.** Autor nahraje CSV nebo GeoJSON, případně body nakliká v mapě. Data ukládá portál (D1 / R2), autor nepotřebuje vlastní web.
- **Hodnocení jako pojem protokolu.** Typ vizualizace `rating` a pole objektu `rating`, `ratingMax` (výchozí 5), `review` (krátký verdikt), `url` (článek) a `visited` (datum návštěvy). Portál ukáže hvězdičky v detailu, nabídne filtr „od N hvězdiček“ a legendu odvodí sám. Typ může použít i poskytovatel s vlastním manifestem.
- **Autor je vidět.** Hodnocení je názor konkrétního člověka, ne údaj portálu. Jméno a odkaz na autora jsou u vrstvy i v detailu každého místa.
- **Schvalování.** Vrstva je mimo katalog, dokud ji provozovatel neschválí, stejně jako u [samoregistrace](https://datovamapa.cz/dokumentace/pro-poskytovatele.md#5-registrace).

Otevřené otázky:

- **Účty.** Portál dnes uživatelské účty nemá. Nahrávání potřebuje přihlášení (např. odkaz e-mailem) a ochranu proti zneužití.
- **Schvalování změn.** Autor bude data průběžně doplňovat. Schvalovat jednou autora, nebo každou změnu?
- **Volné body, nebo existující místa?** Navázání na existující místo (např. podnik z OpenStreetMap) umožní porovnat více autorů u jednoho místa, ale je výrazně složitější.
- **Souhrny.** Průměr z více autorů se blíží recenzním serverům a otevírá riziko manipulace (vymyšlení autoři). Na začátek jen vrstvy vedle sebe.
- **Právo.** Negativní hodnocení pojmenovaného podniku může narazit na ochranu dobré pověsti právnické osoby (§ 135 občanského zákoníku). Potřeba podmínky „autor odpovídá za svůj obsah“, nahlášení místa a rychlé odstranění. Hodnotí se místa, ne soukromé osoby.

## Plán

1. **v0.1 (hotovo):** protokol (manifest + GeoJSON odpověď), katalog, proxy s cache, vizualizace circle / heatmap / line / fill / raster / auto, filtry, detail objektu, přehled zdrojů, ukázkový poskytovatel; dokumentace v markdownu, llms.txt, validátor, MCP server, OpenAPI.
2. **Registrace poskytovatelů:** samoobslužná registrace se schvalováním je hotová (formulář, API, MCP); zbývá monitoring dostupnosti zdrojů.
3. **Asistent:** pro cizí AI asistenty hotové (MCP a API: geokódování RÚIAN, dotaz na bod a okolí včetně rastrových sad, souhrn za obec); zbývá vlastní asistent v okně výběru (LLM nad katalogem).
4. **Další vizualizace a zdroje:** ikony/symboly, 3D vytažení ploch, časová osa, toky, vektorové dlaždice (MVT/PMTiles), OGC API Features a WFS jako typ zdroje.
5. **Vlastní datová vrstva:** trvalé uložení dat (Cloudflare D1/R2, případně PostGIS), prostorové dotazy přes více zdrojů, předpočítané agregace pro velká data.
6. **Autorská hodnocení:** hodnoticí vrstvy blogerů a recenzentů hostované portálem, typ vizualizace `rating` (viz [návrh](https://datovamapa.cz/dokumentace/o-projektu.md#autorska-hodnoceni-dalsi-verze)).