docs: reorganize project documentation

docs/data-sources.md

@@ -0,0 +1,58 @@
+# Źródła Danych i Cache
+
+`wtr.` korzysta z publicznych źródeł danych pogodowych i lokalizacyjnych. Dane zewnętrzne są pobierane przez route handlery Next.js, a UI pokazuje brak danych jawnie zamiast uzupełniać je estymacją.
+
+## IMGW
+
+| Dane | Źródło |
+| --- | --- |
+| Bieżąca analiza IMGW Hybrid | `https://meteo.imgw.pl/api/v1/forecast/fcapi` |
+| Prognoza godzinowa IMGW ALARO | `https://meteo.imgw.pl/api/v1/forecast/fcapi?m=alaro` |
+| Dane synoptyczne | `https://danepubliczne.imgw.pl/api/data/synop` |
+| Pojedyncza stacja synoptyczna | `https://danepubliczne.imgw.pl/api/data/synop/id/{id}` |
+| Dane hydrologiczne | `https://danepubliczne.imgw.pl/api/data/hydro/` |
+| Ostrzeżenia meteorologiczne | `https://danepubliczne.imgw.pl/api/data/warningsmeteo` |
+| Ostrzeżenia hydrologiczne | `https://danepubliczne.imgw.pl/api/data/warningshydro` |
+| Dane meteorologiczne | `https://danepubliczne.imgw.pl/api/data/meteo/` |
+| Lista produktów | `https://danepubliczne.imgw.pl/api/data/product` |
+
+IMGW jest traktowane jako źródło bieżących pomiarów, hydro i ostrzeżeń. Prognoza modelowa jest w interfejsie rozdzielona od pomiarów.
+
+## Open-Meteo
+
+Open-Meteo Forecast API (`https://api.open-meteo.com/v1/forecast`) dostarcza pełny 7-dniowy horyzont prognozy, prawdopodobieństwo opadu i fallback, jeśli IMGW ALARO nie odpowiada.
+
+Open-Meteo Geocoding API (`https://geocoding-api.open-meteo.com/v1/search`) służy do wyszukiwania miejscowości w Polsce.
+
+Przed większym lub komercyjnym wdrożeniem należy sprawdzić aktualne warunki korzystania z Open-Meteo albo zastąpić usługę własnym dostawcą.
+
+## Nominatim / OpenStreetMap
+
+Opcjonalny reverse geocoding GPS korzysta z publicznego endpointu:
+
+```text
+https://nominatim.openstreetmap.org/reverse
+```
+
+Wywołanie następuje wyłącznie po zgodzie użytkownika. Interfejs pokazuje atrybucję OpenStreetMap. Pozycja GPS jest zaokrąglana do trzech miejsc po przecinku, czyli około 100 metrów.
+
+Przed wdrożeniem o większym ruchu należy sprawdzić aktualną politykę użycia publicznej instancji Nominatim albo użyć własnej usługi.
+
+## Cache
+
+| Dane | Cache |
+| --- | --- |
+| IMGW Hybrid | 120 sekund, `stale-while-revalidate=300` |
+| Prognoza modelowa | 900 sekund, `stale-while-revalidate=1800` |
+| Proxy IMGW `danepubliczne.imgw.pl` | 300 sekund, `stale-while-revalidate=600` |
+| Wyszukiwanie miejscowości | 24 godziny, `stale-while-revalidate=7 dni` |
+| Reverse geocoding | 24 godziny, `stale-while-revalidate=7 dni` |
+
+Service worker dodatkowo może cache'ować odpowiedzi `GET` dla `/api/imgw/*`, `/api/imgw-current` i `/api/forecast`, aby ostatnio pobrane dane były dostępne przy problemach z siecią.
+
+## Ograniczenia Źródeł
+
+- Endpoint IMGW Hybrid jest częścią publicznego frontendu `meteo.imgw.pl`, ale nie jest opisany w stabilnej dokumentacji `danepubliczne.imgw.pl`.
+- Publiczny endpoint synoptyczny IMGW zwraca najnowszy pomiar, a nie historię odczytów.
+- IMGW ALARO zwykle dostarcza krótszy horyzont godzinowy niż 7 dni; Open-Meteo uzupełnia dalszy zakres.
+- `wtr.` nie generuje fikcyjnych danych pogodowych.