# MapaDanych – wizja {#datovamapa-vize}

Data: 2026-10-06 (zastępuje pierwotny kontekst z 2026-08, który znajduje się w `docs/archiv/`)

## Czym jest MapaDanych {#co-je-datovamapa}

MapaDanych to **otwarty interfejs do wizualizacji danych na mapie**. Definiuje otwarty schemat (protokół), dzięki któremu każdy może pokazać na mapie dowolne dane – punkty, linie, powierzchnie, gęstości, warstwy rastrowe.

Zasada działania:

1. Dostawca danych publikuje **manifest** (opis siebie i swoich zbiorów danych) oraz **endpoint danych** zgodny z protokołem MapaDanych.
2. Dostawca rejestruje manifest; po zatwierdzeniu przez operatora zbiory pojawiają się w katalogu.
3. Gdy użytkownik włączy zbiór, portal odpytuje źródło (dla bieżącego wycinka mapy i ustawionych filtrów), weryfikuje odpowiedź, zapisuje ją w cache i rysuje zgodnie z opisem z manifestu.

Portal nie jest właścicielem danych; pośredniczy w ich udostępnianiu i zawsze podaje źródło. Operatorem portalu jest [vrealmatic.com](https://vrealmatic.com/web).

## Korzyści {#prinos}

**Dla użytkowników:** na jednej mapie łączą dane z dowolnych źródeł – bez przełączania się między dziesiątkami portali mapowych.

**Dla dostawców:**

- nie muszą zajmować się mapą, stylami ani serwerem map – wystarczy endpoint JSON,
- stają się częścią otwartego portalu danych, a ich dane spotykają się z danymi innych,
- są widocznie wskazani jako źródło (przy danych na mapie, w szczegółach obiektu, w przeglądzie źródeł).

## Dane przygotowują agenci AI {#data-pripravuji-ai-agenti}

Zakładamy, że dane u dostawców będą przygotowywać głównie agenci AI (na polecenie człowieka, do którego dane należą). Dlatego cały portal jest zbudowany jako „AI friendly”:

- **Wszystko jest w markdownie.** Każda strona dokumentacji ma wersję markdown (`/dokumentacja/{slug}.md`), strona główna `/index.md`, katalog `/zrodla.md`; spis treści `/llms.txt` i cała dokumentacja w jednym pliku `/llms-full.txt`. Źródłem prawdy są pliki w `docs/`, HTML jest z nich generowany.
- **Instrukcja dla agentów** z procedurą, tabelami decyzyjnymi, szablonami kodu, zasadami (dane osobowe, licencje) i kryteriami ukończenia pracy.
- **Schematy maszynowe** generowane z jednego źródła: JSON Schema manifestu i danych, kontrakt OpenAPI dostawcy (agent może z niego wygenerować serwer) i OpenAPI portalu.
- **Walidator z informacją zwrotną**: stabilne kody wyników, dokładne ścieżki i wskazówki, jak naprawić błąd; test na żywo całego dostawcy. Agent iteruje, dopóki nie uzyska `valid: true`.
- **Serwer MCP** `/mcp`: dokumentacja, schematy, przykłady, walidacja, katalog i dane jako narzędzia.
- **Sprawdzone przykłady**: każdy przykład w dokumentacji przechodzi przez walidator (`npm run check:docs`), aby agent nie skopiował błędu.
- **Pola ułatwiające wyszukiwanie**: `keywords`, `useCases`, `description`, `fields` – dzięki nim dane znajdą zarówno ludzie, jak i asystent portalu.

Dane z portalu czytają też asystenci AI zwykłych ludzi i firm. Przez serwer MCP lub HTTP API znajdują miejsce (rejestr adresów), pytają wybrane zbiory, co jest w danym punkcie i w okolicy (również mapy rastrowe, takie jak powodzie, radon czy hałas), i otrzymują podsumowanie dla gminy. Sami interpretują dane i podają źródło. Instrukcja: [Dane dla asystentów AI](https://mapadanych.pl/dokumentacja/asystenci-ai.md).

## Zasady {#principy}

- **Otwarty protokół.** Schemat jest publiczny (`/schema/0.1/manifest.json`, `/schema/0.1/data.json`), oparty na GeoJSON (RFC 7946). Prawie wszystko jest opcjonalne, obowiązkowe jest tylko niewielkie minimum.
- **Zamiar, nie biblioteka.** Dostawca opisuje, *co* chce pokazać (punkty według kategorii, kartogram według wartości…), a nie konkretne ustawienia biblioteki mapowej. Portal może zmieniać sposób rysowania bez wpływu na dostawcę.
- **Zgodność w przód.** Nieznane pola są ignorowane, nieznany typ wizualizacji jest rysowany stylem domyślnym. Protokół może więc rosnąć, nie psując istniejących źródeł.
- **Prosta strona główna.** Tylko mapa i logo. Po najechaniu myszą / kliknięciu otwiera się wybór danych. Żadnych dodatkowych paneli.
- **Strony wejściowe dla konkretnych danych.** Kto szuka konkretnego wskaźnika, trafia z wyszukiwarki na stronę zbioru (`/mapa/{provider}/{dataset}`), zbioru dla gminy lub gotowej mapy (`/mapy/{slug}`): ta sama mapa z domyślnie włączonymi danymi i opisem z podsumowaniem danych. Kolejne warstwy dodaje do mapy tak samo jak na stronie głównej.
- **Bezpieczeństwo.** Dane dostawców nigdy nie są wstawiane jako HTML, proxy odpytuje tylko zarejestrowane źródła, z limitami czasu i rozmiaru.

## Strona główna {#hlavni-stranka}

- Mapa na całym ekranie i logo w lewym górnym rogu. Mapa otwiera się z widokiem na całą Polskę.
- **Wprowadzenie.** Kto wchodzi bez wyboru danych i bez odnośnika do miejsca, tego mapa przy ładowaniu poprosi w przeglądarce o lokalizację, przeniesie go w jego okolicę, a obok mapy otworzy się okno powitalne „Twoja okolica w danych” – szybki start: asystent (w przygotowaniu) z szybkimi opcjami, czyli gotowymi mapami na jedno kliknięcie, oraz odnośnikami do aktualnych danych. Poszczególne warstwy włącza się w katalogu („Cały katalog”). Kto nie udostępni lokalizacji albo jest poza Polską, dostaje wprowadzenie dla całej Polski. Odnośnik z wyborem danych pomija wprowadzenie; wraca ono jednak zawsze, gdy na mapie nic nie ma.
- Dokładną lokalizację użytkownik wyświetla przyciskiem „Moja okolica” w prawym górnym rogu obok sterowania mapą – przeglądarka pyta dopiero po kliknięciu; kto udostępnił lokalizację wcześniej, tego mapa od razu pokaże w jego okolicy (a wprowadzenie użyje tej lokalizacji).
- Najechanie myszą na logo (albo kliknięcie / dotknięcie) otwiera duże okno wyboru (ponad 80 % szerokości): po lewej **katalog** w postaci kart według kategorii z wyszukiwaniem, po prawej **Na mapie** – włączone warstwy ze stanem, legendą i filtrami. U góry jest zapowiedź przyszłego asystenta – na razie nieaktywna. Kliknięcie lub praca w oknie przypina je, zamyka się krzyżykiem, klawiszem Esc lub kliknięciem poza oknem.
- Wybór zapisuje się w URL, odnośnik można udostępnić.

### Polecenie w języku naturalnym (przyszłość) {#zadani-v-prirozenem-jazyce-budoucnost}

Cel: użytkownik napisze np. *„Chcę budować dom w gminie Wieliczka, pokaż mi wszystkie dane istotne dla mojego celu”*, a portal:

1. zrozumie miejsce (geokodowanie gminy / adresu / działki) i przesunie mapę,
2. zrozumie cel (budowa) i wybierze odpowiednie zbiory według `useCases`, `keywords` i opisów w manifestach,
3. ewentualnie ustawi filtry i podsumuje, co widzi w danych.

W oknie jest na razie tylko nieaktywna zapowiedź. Kroki 1–3 potrafi już jednak zewnętrzny asystent AI przez MCP: `find_place` (geokodowanie z rejestru adresów), `nearby` (wybór zbiorów według celu lub tekstu i zapytanie o punkt) oraz `summary`. Wyboru zbiorów według słów kluczowych i celów (`src/lib/search.ts`) używa też wyszukiwanie w katalogu i narzędzie MCP `catalog`. Dlatego manifesty mają pola `keywords` i `useCases` – przygotowują dane dla asystenta.

## Cache i własna warstwa danych {#cache-a-vlastni-datova-vrstva}

Na początku źródłem danych są zewnętrzne API dostawców. Portal trzyma odpowiedzi w cache (według `cache.ttl`), aby nie obciążać źródeł i aby mapa była szybka; przy awarii źródła może przez krótki czas pokazywać ostatnie znane dane.

W warunkach dla dostawców zastrzegamy sobie, że w interesie **przyspieszenia, odciążenia źródeł, trwałości, lepszej kombinatoryki, łączenia kontekstów i pracy z dużymi danymi** możemy przechowywać dane we własnym cache / własnej warstwie danych. Dostawca może to wyłączyć dla danego zbioru (`cache.store: false`).

## Oceny autorskie (kolejna wersja) {#autorska-hodnoceni-dalsi-verze}

Propozycja, jeszcze niezaimplementowana. Warstwa dla ludzi z własnym zdaniem i publicznością – blogerów, recenzentów, klubów – którzy chcą pokazać oceny miejsc: „Kawiarnie według …”, „Trasy rowerowe według …”, „Place zabaw według …”. Każde miejsce ma ocenę, krótki werdykt i odnośnik do artykułu.

Dziś da się to zrobić tylko ogólnie: autor publikuje własny manifest i GeoJSON z polem liczbowym i koloruje punkty według wartości. Portal nie wie jednak, że chodzi o ocenę, a autor musi sam hostować dane.

Propozycja:

- **Hostujemy my.** Autor wgrywa CSV lub GeoJSON albo wyklikuje punkty na mapie. Dane przechowuje portal (D1 / R2), autor nie potrzebuje własnej strony.
- **Ocena jako pojęcie protokołu.** Typ wizualizacji `rating` i pola obiektu `rating`, `ratingMax` (domyślnie 5), `review` (krótki werdykt), `url` (artykuł) oraz `visited` (data wizyty). Portal pokaże gwiazdki w szczegółach, zaproponuje filtr „od N gwiazdek” i sam wyprowadzi legendę. Z typu może korzystać także dostawca z własnym manifestem.
- **Autor jest widoczny.** Ocena to opinia konkretnej osoby, a nie informacja portalu. Imię i nazwisko oraz odnośnik do autora są przy warstwie i w szczegółach każdego miejsca.
- **Zatwierdzanie.** Warstwa jest poza katalogiem, dopóki operator jej nie zatwierdzi, tak samo jak przy [samodzielnej rejestracji](https://mapadanych.pl/dokumentacja/dla-dostawcow.md#5-registrace).

Otwarte pytania:

- **Konta.** Portal nie ma dziś kont użytkowników. Wgrywanie wymaga logowania (np. linkiem w e-mailu) i ochrony przed nadużyciami.
- **Zatwierdzanie zmian.** Autor będzie stale uzupełniał dane. Zatwierdzać autora raz, czy każdą zmianę?
- **Wolne punkty czy istniejące miejsca?** Powiązanie z istniejącym miejscem (np. lokalem z OpenStreetMap) pozwoli porównać kilku autorów przy jednym miejscu, ale jest znacznie bardziej złożone.
- **Podsumowania.** Średnia z wielu autorów zbliża się do serwisów z recenzjami i otwiera ryzyko manipulacji (zmyśleni autorzy). Na początek tylko warstwy obok siebie.
- **Prawo.** Negatywna ocena wymienionego z nazwy lokalu może naruszać dobra osobiste osoby prawnej (art. 43 w zw. z art. 23 i 24 Kodeksu cywilnego). Potrzebne są warunki „autor odpowiada za swoje treści”, zgłaszanie miejsc i szybkie usuwanie. Ocenia się miejsca, nie osoby prywatne.

## Plan {#plan}

1. **v0.1 (gotowe):** protokół (manifest + odpowiedź GeoJSON), katalog, proxy z cache, wizualizacje circle / heatmap / line / fill / raster / auto, filtry, szczegóły obiektu, przegląd źródeł, przykładowy dostawca; dokumentacja w markdownie, llms.txt, walidator, serwer MCP, OpenAPI.
2. **Rejestracja dostawców:** samoobsługowa rejestracja z zatwierdzaniem jest gotowa (formularz, API, MCP); pozostaje monitorowanie dostępności źródeł.
3. **Asystent:** dla zewnętrznych asystentów AI gotowe (MCP i API: geokodowanie z rejestru adresów, zapytanie o punkt i okolicę, w tym zbiory rastrowe, podsumowanie dla gminy); pozostaje własny asystent w oknie wyboru (LLM nad katalogiem).
4. **Kolejne wizualizacje i źródła:** ikony/symbole, wyciąganie powierzchni w 3D, oś czasu, przepływy, kafle wektorowe (MVT/PMTiles), OGC API Features i WFS jako typ źródła.
5. **Własna warstwa danych:** trwałe przechowywanie danych (Cloudflare D1/R2, ewentualnie PostGIS), zapytania przestrzenne przez wiele źródeł, wstępnie obliczone agregacje dla dużych danych.
6. **Oceny autorskie:** warstwy z ocenami blogerów i recenzentów hostowane przez portal, typ wizualizacji `rating` (zob. [propozycję](https://mapadanych.pl/dokumentacja/o-projekcie.md#autorska-hodnoceni-dalsi-verze)).