zv/wtr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add prettier formatting
All checks were successful
CI / Lint, typecheck and build (push) Successful in 9m56s
Details

Browse Source
This commit is contained in:
zv
2026-06-14 20:26:56 +02:00
parent 8bbd9397a1
commit ee55521803
79 changed files with 2451 additions and 969 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/api.md
View File

@@ -4,28 +4,28 @@ Wszystkie zewnętrzne źródła danych są wywoływane przez route handlery Next
## Dane Pogodowe i Lokalizacje
| Metoda | Endpoint | Przeznaczenie |
| --- | --- | --- |
| `GET` | `/api/current-weather?latitude={lat}&longitude={lon}&region={PL\|GLOBAL}` | Zwraca znormalizowane bieżące warunki. Dla `PL` używa IMGW Hybrid, dla `GLOBAL` modelowych warunków Open-Meteo. |
| `GET` | `/api/forecast?latitude={lat}&longitude={lon}&region={PL\|GLOBAL}` | Zwraca 7-dniową prognozę modelową dla współrzędnych. Dla `PL` łączy IMGW ALARO z Open-Meteo, dla `GLOBAL` używa Open-Meteo. Niepoprawne współrzędne zwracają `400`, awaria źródła `502`. |
| `GET` | `/api/imgw-current?latitude={lat}&longitude={lon}` | Pobiera surową lokalną analizę IMGW Hybrid dla współrzędnych. Niepoprawne współrzędne zwracają `400`, awaria źródła `502`. |
| `GET` | `/api/imgw/{path}` | Proxy allowlistowanych endpointów IMGW `danepubliczne.imgw.pl`. Obsługuje kolekcje `synop`, `hydro`, `meteo`, `warningsmeteo`, `warningshydro`, `product` oraz szczegół `synop/id/{id}`. Nieobsługiwana ścieżka zwraca `404`. |
| `GET` | `/api/locations/search?query={query}&language={pl\|en}` | Wyszukuje miejscowości globalnie przez Open-Meteo Geocoding. Wyniki zawierają `countryCode`, `admin1`, `admin2`, `timezone` i region `PL` albo `GLOBAL`. Zapytania krótsze niż 2 znaki albo dłuższe niż 80 znaków zwracają pustą listę. |
| `GET` | `/api/locations/reverse?latitude={lat}&longitude={lon}&language={pl\|en}` | Ustala nazwę miejsca dla pozycji GPS przez Nominatim / OpenStreetMap. Współrzędne są zaokrąglane do trzech miejsc po przecinku. |
| Metoda | Endpoint | Przeznaczenie |
| ------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/api/current-weather?latitude={lat}&longitude={lon}&region={PL\|GLOBAL}` | Zwraca znormalizowane bieżące warunki. Dla `PL` używa IMGW Hybrid, dla `GLOBAL` modelowych warunków Open-Meteo. |
| `GET` | `/api/forecast?latitude={lat}&longitude={lon}&region={PL\|GLOBAL}` | Zwraca 7-dniową prognozę modelową dla współrzędnych. Dla `PL` łączy IMGW ALARO z Open-Meteo, dla `GLOBAL` używa Open-Meteo. Niepoprawne współrzędne zwracają `400`, awaria źródła `502`. |
| `GET` | `/api/imgw-current?latitude={lat}&longitude={lon}` | Pobiera surową lokalną analizę IMGW Hybrid dla współrzędnych. Niepoprawne współrzędne zwracają `400`, awaria źródła `502`. |
| `GET` | `/api/imgw/{path}` | Proxy allowlistowanych endpointów IMGW `danepubliczne.imgw.pl`. Obsługuje kolekcje `synop`, `hydro`, `meteo`, `warningsmeteo`, `warningshydro`, `product` oraz szczegół `synop/id/{id}`. Nieobsługiwana ścieżka zwraca `404`. |
| `GET` | `/api/locations/search?query={query}&language={pl\|en}` | Wyszukuje miejscowości globalnie przez Open-Meteo Geocoding. Wyniki zawierają `countryCode`, `admin1`, `admin2`, `timezone` i region `PL` albo `GLOBAL`. Zapytania krótsze niż 2 znaki albo dłuższe niż 80 znaków zwracają pustą listę. |
| `GET` | `/api/locations/reverse?latitude={lat}&longitude={lon}&language={pl\|en}` | Ustala nazwę miejsca dla pozycji GPS przez Nominatim / OpenStreetMap. Współrzędne są zaokrąglane do trzech miejsc po przecinku. |
## Powiadomienia
Endpointy powiadomień działają w runtime Node.js, bo korzystają z `web-push` i lokalnego magazynu SQLite dla subskrypcji.
| Metoda | Endpoint | Przeznaczenie |
| --- | --- | --- |
| `GET` | `/api/notifications/vapid-key` | Zwraca publiczny klucz VAPID oraz informację, czy Web Push jest skonfigurowany. |
| `POST` | `/api/notifications/subscriptions` | Zapisuje lub aktualizuje subskrypcję Web Push dla urządzenia. Przyjmuje region `PL`/`GLOBAL`, preferencje ostrzeżeń, briefu porannego, briefu wieczornego, lokalizację, język, województwo dla `PL` i opcjonalny powiat TERYT. |
| `DELETE` | `/api/notifications/subscriptions` | Usuwa subskrypcję Web Push po jej endpointcie. |
| `POST` | `/api/notifications/test` | Wysyła powiadomienie testowe na wskazany endpoint subskrypcji. |
| `GET` | `/api/notifications/check` | Endpoint harmonogramu sprawdzający nowe ostrzeżenia meteorologiczne IMGW i wysyłający Web Push do pasujących subskrypcji. |
| `GET` | `/api/notifications/daily-brief` | Endpoint harmonogramu wysyłający raz dziennie poranny brief dla subskrypcji z włączoną opcją i zapisaną lokalizacją. |
| `GET` | `/api/notifications/tomorrow-brief` | Endpoint harmonogramu wysyłający wieczorny brief z prognozą na kolejny dzień. |
| Metoda | Endpoint | Przeznaczenie |
| -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET` | `/api/notifications/vapid-key` | Zwraca publiczny klucz VAPID oraz informację, czy Web Push jest skonfigurowany. |
| `POST` | `/api/notifications/subscriptions` | Zapisuje lub aktualizuje subskrypcję Web Push dla urządzenia. Przyjmuje region `PL`/`GLOBAL`, preferencje ostrzeżeń, briefu porannego, briefu wieczornego, lokalizację, język, województwo dla `PL` i opcjonalny powiat TERYT. |
| `DELETE` | `/api/notifications/subscriptions` | Usuwa subskrypcję Web Push po jej endpointcie. |
| `POST` | `/api/notifications/test` | Wysyła powiadomienie testowe na wskazany endpoint subskrypcji. |
| `GET` | `/api/notifications/check` | Endpoint harmonogramu sprawdzający nowe ostrzeżenia meteorologiczne IMGW i wysyłający Web Push do pasujących subskrypcji. |
| `GET` | `/api/notifications/daily-brief` | Endpoint harmonogramu wysyłający raz dziennie poranny brief dla subskrypcji z włączoną opcją i zapisaną lokalizacją. |
| `GET` | `/api/notifications/tomorrow-brief` | Endpoint harmonogramu wysyłający wieczorny brief z prognozą na kolejny dzień. |
## Autoryzacja Harmonogramu
@@ -46,13 +46,13 @@ Jeśli `NOTIFICATIONS_CRON_SECRET` nie jest ustawiony, endpointy harmonogramu s
## Cache i Odpowiedzi
| Endpoint | Cache |
| --- | --- |
| `/api/forecast` | `s-maxage=900`, `stale-while-revalidate=1800` |
| `/api/current-weather` | `s-maxage=120`, `stale-while-revalidate=300` |
| `/api/imgw-current` | `s-maxage=120`, `stale-while-revalidate=300` |
| `/api/imgw/{path}` | `s-maxage=300`, `stale-while-revalidate=600` |
| `/api/locations/search` | `s-maxage=86400`, `stale-while-revalidate=604800` |
| Endpoint | Cache |
| ------------------------ | ------------------------------------------------- |
| `/api/forecast` | `s-maxage=900`, `stale-while-revalidate=1800` |
| `/api/current-weather` | `s-maxage=120`, `stale-while-revalidate=300` |
| `/api/imgw-current` | `s-maxage=120`, `stale-while-revalidate=300` |
| `/api/imgw/{path}` | `s-maxage=300`, `stale-while-revalidate=600` |
| `/api/locations/search` | `s-maxage=86400`, `stale-while-revalidate=604800` |
| `/api/locations/reverse` | `s-maxage=86400`, `stale-while-revalidate=604800` |
Route handlery zwracają kontrolowane odpowiedzi JSON. Błędy zewnętrznych usług są mapowane na czytelne statusy HTTP, zwykle `400`, `404`, `502` albo `503`.
@@ -62,7 +62,7 @@ Route handlery zwracają kontrolowane odpowiedzi JSON. Błędy zewnętrznych us
Publiczne endpointy ostrzeżeń IMGW potrafią zwrócić HTTP `404` z treścią:
```json
{"status":false,"message":"No products were found"}
{ "status": false, "message": "No products were found" }
```
Dla `warningsmeteo` i `warningshydro` aplikacja traktuje ten wariant jako poprawną pustą listę ostrzeżeń, a nie awarię źródła danych.

54
docs/data-sources.md
View File

@@ -4,17 +4,17 @@
## 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` |
| 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` |
| 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.
@@ -30,15 +30,15 @@ Przed większym, publicznym lub komercyjnym wdrożeniem należy sprawdzić aktua
## Capabilities per Region
| Capability | Polska | Global |
| --- | --- | --- |
| Bieżące warunki | IMGW Hybrid + fallback `synop` | Open-Meteo model |
| Prognoza godzinowa | IMGW ALARO + Open-Meteo | Open-Meteo |
| Prognoza dzienna | IMGW ALARO/Open-Meteo | Open-Meteo |
| Oficjalne ostrzeżenia | IMGW | niedostępne |
| Filtrowanie powiatowe | TERYT | niedostępne |
| Briefy | tak | tak, bez oficjalnych alertów |
| Push alerty oficjalne | IMGW | niedostępne |
| Capability | Polska | Global |
| --------------------- | ------------------------------ | ---------------------------- |
| Bieżące warunki | IMGW Hybrid + fallback `synop` | Open-Meteo model |
| Prognoza godzinowa | IMGW ALARO + Open-Meteo | Open-Meteo |
| Prognoza dzienna | IMGW ALARO/Open-Meteo | Open-Meteo |
| Oficjalne ostrzeżenia | IMGW | niedostępne |
| Filtrowanie powiatowe | TERYT | niedostępne |
| Briefy | tak | tak, bez oficjalnych alertów |
| Push alerty oficjalne | IMGW | niedostępne |
## Nominatim / OpenStreetMap
@@ -54,14 +54,14 @@ Przed wdrożeniem o większym ruchu należy sprawdzić aktualną politykę użyc
## Cache
| Dane | Cache |
| --- | --- |
| IMGW Hybrid | 120 sekund, `stale-while-revalidate=300` |
| Modelowe warunki bieżące Open-Meteo | 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` |
| Dane | Cache |
| ----------------------------------- | ------------------------------------------ |
| IMGW Hybrid | 120 sekund, `stale-while-revalidate=300` |
| Modelowe warunki bieżące Open-Meteo | 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`, `/api/current-weather` i `/api/forecast`, aby ostatnio pobrane dane były dostępne przy problemach z siecią.

4
docs/deployment.md
View File

@@ -77,9 +77,9 @@ Repozytorium używa Gitea Actions jako końcowej bramki jakości po pushu. Lokal
- dokumentacja, teksty i komentarze: przegląd diffu oraz opcjonalnie `git diff --check`,
- drobne zmiany wizualne: bez rutynowego builda; `npm run lint` tylko przy ryzyku błędu składni lub reguł lintingu,
- zmiany w logice, hookach, typach, parserach i danych pogodowych: `npm run typecheck`, a dla TS/TSX także `npm run lint`,
- routing Next.js, config, zależności, `package-lock`, PWA/service worker, API/server code, build config i obsługa env: `npm run lint`, `npm run typecheck` oraz `npm run build`.
- routing Next.js, config, zależności, `package-lock`, PWA/service worker, API/server code, build config i obsługa env: `npm run lint`, `npm run format:check`, `npm run typecheck` oraz `npm run build`.
Repozytorium nie ma obecnie skryptu testów ani formattera.
Repozytorium nie ma obecnie skryptu testów. Formatowanie jest obsługiwane przez Prettier (`npm run format` i `npm run format:check`).
## Bezpieczeństwo Zależności

46
docs/weather-logic.md
View File

@@ -91,17 +91,17 @@ IMGW Hybrid dostarcza m.in. opad 10-minutowy. Ten parametr jest prezentowany odd
Prognoza godzinowa i dzienna rozpoznaje:
| Stan | Opis w interfejsie |
| --- | --- |
| `clear` | Bezchmurnie |
| Stan | Opis w interfejsie |
| -------------- | ---------------------- |
| `clear` | Bezchmurnie |
| `partlyCloudy` | Częściowe zachmurzenie |
| `cloudy` | Pochmurno |
| `fog` | Mgła |
| `drizzle` | Mżawka |
| `rain` | Opady deszczu |
| `snow` | Opady śniegu |
| `thunderstorm` | Burza |
| `unknown` | Brak opisu |
| `cloudy` | Pochmurno |
| `fog` | Mgła |
| `drizzle` | Mżawka |
| `rain` | Opady deszczu |
| `snow` | Opady śniegu |
| `thunderstorm` | Burza |
| `unknown` | Brak opisu |
Bieżąca analiza IMGW Hybrid rozpoznaje bezpośrednio opad deszczu, śnieg i burzę. Dashboard hero używa opisu warunków w następującym priorytecie:
@@ -114,11 +114,11 @@ Bieżąca analiza IMGW Hybrid rozpoznaje bezpośrednio opad deszczu, śnieg i bu
Pole `Cloud` z IMGW Hybrid jest używane jako opis nieba:
| Cloud | Opis w hero |
| --- | --- |
| `>= 75` | Pochmurno |
| `>= 25` | Częściowe zachmurzenie |
| `< 25` | brak osobnego opisu zachmurzenia |
| Cloud | Opis w hero |
| ------- | -------------------------------- |
| `>= 75` | Pochmurno |
| `>= 25` | Częściowe zachmurzenie |
| `< 25` | brak osobnego opisu zachmurzenia |
Jednostki temperatury i wiatru wybierane w `/settings` dotyczą prezentacji w UI, briefach i powiadomieniach. Dane źródłowe oraz progi logiki pogody pozostają liczone w `°C` i `m/s`.
@@ -126,14 +126,14 @@ Jednostki temperatury i wiatru wybierane w `/settings` dotyczą prezentacji w UI
Hero aktualnej pogody używa uproszczonego moodu do wyboru ikony, tekstu i małego akcentu stanu.
| Mood | Reguła |
| --- | --- |
| `night` | godzina przed `06:00` lub od `21:00` |
| `wind` | wiatr od `8 m/s` |
| `cold` | temperatura do `3°C` |
| `cloudy` | wilgotność od `80%` |
| `warm` | temperatura od `20°C` |
| `mild` | pozostałe przypadki |
| Mood | Reguła |
| -------- | ------------------------------------ |
| `night` | godzina przed `06:00` lub od `21:00` |
| `wind` | wiatr od `8 m/s` |
| `cold` | temperatura do `3°C` |
| `cloudy` | wilgotność od `80%` |
| `warm` | temperatura od `20°C` |
| `mild` | pozostałe przypadki |
Warstwa efektów wizualnych jest ograniczona do subtelnych efektów informacyjnych: kropli przy lokalnym opadzie oraz błysku przy burzy. Mood hero jest heurystyką, a nie pełną klasyfikacją sterowaną kodem warunków IMGW Hybrid.