docs: document internal api endpoints

README.md

@@ -76,6 +76,23 @@ Opcjonalny reverse geocoding dla GPS korzysta z publicznego endpointu Nominatim:
 
 Przeglądarka pobiera dane przez route handlery Next.js. Proxy IMGW w `app/api/imgw/[...path]/route.ts` pozwala ujednolicić cache, błędy API i bezpiecznie obsłużyć hydro bez mixed content. Bieżącą analizę pogody obsługuje `app/api/imgw-current/route.ts`, prognozę `app/api/forecast/route.ts`, a reverse geocoding GPS `app/api/locations/reverse/route.ts`.
 
+## Wewnętrzne endpointy API
+
+| Metoda | Endpoint | Przeznaczenie |
+| --- | --- | --- |
+| `GET` | `/api/forecast?latitude={lat}&longitude={lon}` | Zwraca 7-dniową prognozę modelową dla współrzędnych, łącząc IMGW ALARO z fallbackiem Open-Meteo. Odpowiedź ma cache `s-maxage=900`. |
+| `GET` | `/api/imgw-current?latitude={lat}&longitude={lon}` | Pobiera lokalną analizę IMGW Hybrid z oficjalnego portalu IMGW dla współrzędnych. Cache jest krótki, `s-maxage=120`. |
+| `GET` | `/api/imgw/{path}` | Proxy allowlistowanych publicznych endpointów IMGW `danepubliczne.imgw.pl`, m.in. `synop`, `synop/id/{id}`, `hydro`, `meteo`, `warningsmeteo`, `warningshydro` i `product`. Empty `warningsmeteo`/`warningshydro` z komunikatem `No products were found` jest normalizowane do pustej listy. |
+| `GET` | `/api/locations/search?name={query}` | Wyszukuje miejscowości w Polsce przez Open-Meteo Geocoding i zwraca znormalizowane lokalizacje dla wyszukiwarki. Cache `s-maxage=86400`. |
+| `GET` | `/api/locations/reverse?latitude={lat}&longitude={lon}` | Ustala nazwę miejsca dla pozycji GPS przez Nominatim / OpenStreetMap po zgodzie użytkownika. Cache `s-maxage=86400`. |
+| `GET` | `/api/notifications/vapid-key` | Zwraca publiczny klucz VAPID i informację, czy Web Push jest skonfigurowany. Używane przez `/settings`. |
+| `POST` | `/api/notifications/subscriptions` | Zapisuje lub aktualizuje subskrypcję Web Push dla urządzenia, wraz z preferencjami ostrzeżeń, briefu o 7:00, briefu o 18:00, lokalizacją i powiatem TERYT. Wymaga skonfigurowanych kluczy VAPID. |
+| `DELETE` | `/api/notifications/subscriptions` | Usuwa subskrypcję Web Push na podstawie endpointu subskrypcji. |
+| `GET` | `/api/notifications/check` | Endpoint harmonogramu sprawdzający nowe ostrzeżenia meteorologiczne IMGW i wysyłający Web Push do pasujących subskrypcji. W produkcji wymaga `Authorization: Bearer <NOTIFICATIONS_CRON_SECRET>` albo `x-cron-secret`. |
+| `GET` | `/api/notifications/daily-brief` | Endpoint harmonogramu wysyłający raz dziennie poranny brief o 7:00 dla subskrypcji z włączoną opcją i zapisaną lokalizacją. W produkcji wymaga sekretu crona. |
+| `GET` | `/api/notifications/tomorrow-brief` | Endpoint harmonogramu wysyłający wieczorny brief o 18:00 z prognozą na jutro, w tym sygnałami burz z modelu. W produkcji wymaga sekretu crona. |
+| `POST` | `/api/notifications/test` | Wysyła testowe powiadomienie Web Push na konkretny endpoint subskrypcji. Używane wyłącznie z `/settings`. |
+
 ## Ograniczenia API
 
 Dashboard korzysta z publicznego endpointu IMGW Hybrid używanego przez oficjalny portal `meteo.imgw.pl`. Bieżące warunki są wybierane z pierwszego pełnego rekordu analizy Hybrid dla współrzędnych miejscowości, preferując rekord 10-minutowy i wymagając realnych wartości liczbowych. Jeśli pełny rekord 10-minutowy jest wyraźnie starszy niż pełny rekord godzinowy z tej samej odpowiedzi, aplikacja wybiera świeższy rekord godzinowy zamiast nadpisywać aktualny fallback starymi danymi. Dzięki temu `null` z rekordów MERGE nie jest traktowany jako pełny pomiar. Interfejs może dodatkowo pokazać rzeczywisty opad z ostatnich 10 minut, oddzielnie opisuje lokalną analizę Hybrid oraz najbliższą stację pomiarową IMGW. Pokrycie Hybrid może być częściowe: jeśli IMGW publikuje lokalny opad MERGE bez pełnego rekordu parametrów, hero zachowuje lokalny opad, a temperaturę, wiatr, wilgotność i ciśnienie jawnie uzupełnia fallbackiem ze stacji. Jeśli usługa Hybrid nie odpowiada, hero zachowuje cały pomiar `synop` jako oznaczony fallback. Gdy fallback pochodzi ze stacji oddalonej od miejscowości o co najmniej 30 km, interfejs ostrzega o możliwej różnicy warunków lokalnych. Endpoint Hybrid jest częścią publicznego frontendu IMGW, ale nie jest opisany w stabilnej dokumentacji `danepubliczne.imgw.pl`, więc integrację należy monitorować przy zmianach portalu.