Podchody
🏃 Podchody
Samodzielnie hostowana aplikacja webowa do przygotowywania obrazkowych podchodów dla dzieci. Zamienia zdjęcia charakterystycznych miejsc w punkty na mapie, układa trasę z długimi odcinkami i generuje gotowe materiały do wycięcia oraz plan dla organizatora. Kolejne miejsca są pokazywane zdjęciami i prostymi symbolami, więc grać mogą też dzieci, które jeszcze nie czytają. Wszystkie zdjęcia, projekty i trasy zostają na własnym serwerze.
✨ Funkcjonalność
Zdjęcia i mapa
- Import zdjęć – JPG, PNG, WebP, HEIC i HEIF, również wielu naraz.
- EXIF – automatyczny odczyt współrzędnych GPS i daty wykonania zdjęcia.
- Ręczna korekta – punkt można przesunąć na mapie, kliknąć nowe miejsce albo wpisać współrzędne.
- Schowek na zdjęciu – dokładne miejsce schowania kartki zaznacza się bezpośrednio na fotografii.
- Mapa – OpenStreetMap z miniaturami zdjęć jako znacznikami.
- Projekty – dowolna liczba projektów, np. osobno dla osiedla, parku czy wyjazdu.


Układanie trasy
- Losowanie punktów – wybór liczby punktów; każde zdjęcie ma dokładnie taką samą szansę wejścia do trasy.
- Styl trasy – „dużo biegania”, trasa zrównoważona albo krótsze przejścia. Styl wpływa tylko na kolejność, nie na to, które punkty zostaną wybrane.
- Trasa dla organizatora – osobna, możliwie krótka kolejność chowania kartek.
- Podsumowanie – długość trasy dzieci i trasy chowającego.
- Edycja – ponowne losowanie i ręczna zmiana kolejności.



Zagadki
Opcjonalne zagadki na kartach, które spowalniają dzieci i wydłużają grę:
- liczenie kropek,
- dokończenie obrazkowego wzoru,
- łączenie takich samych kształtów,
- przepisywanie krótkiego słowa pokazanego obok obrazka,
- uzupełnianie brakującej litery,
- dodawanie i odejmowanie do 10 i do 20.
Można wybrać jeden lub kilka rodzajów, a aplikacja rozdziela je równo i losowo między karty. Zadania rozwiązuje się zwykłym ołówkiem i nie opierają się na kolorach, więc działają też na wydruku czarno-białym.

Materiały do druku
karty-do-wyciecia.pdf– cztery karty na stronie A4, do prostego cięcia na krzyż. Każda karta łączy dwa zdjęcia: u góry organizator widzi, gdzie ją schować, a na dole dziecko widzi, dokąd ma pobiec.plan-organizatora.pdf– mapa gry dzieci, chronologia szukania, plan chowania oraz długości obu tras.- Pobieranie – każdy PDF osobno albo cały zestaw jako ZIP.
| Karty do wycięcia | Plan dla organizatora |
|---|---|
![]() | ![]() |
🧱 Architektura
Moduły
apps/web– React 19, TypeScript i Vite; MapLibre GL z kafelkami OpenStreetMap, edycja punktów, tras i generowanie PDF.apps/server– Express, SQLite, ExifTool i Sharp; logowanie, zapis zdjęć, miniatury i algorytm trasy.- Jeden proces – na produkcji serwer udostępnia zbudowany frontend i API pod tym samym adresem, więc nie trzeba konfigurować CORS.
Przepływ danych
- Przeglądarka wysyła zdjęcia do chronionego API.
- Serwer zapisuje oryginał, odczytuje EXIF przez ExifTool i przygotowuje JPEG do podglądu przez Sharp (HEIC ma osobną ścieżkę konwersji).
- Punkt, współrzędne z EXIF, współrzędne poprawione ręcznie i pozycja schowka trafiają do SQLite.
- Generator wybiera zdjęcia i układa kolejność zgodnie ze stylem trasy.
- Przeglądarka składa mapy, zdjęcia, ikony i zagadki w Canvas i zapisuje PDF-y przez jsPDF (ZIP przez JSZip) - bez AI i bez zewnętrznego generatora dokumentów.
Algorytm trasy
- Wybór punktów – wszystkie zdjęcia są tasowane algorytmem Fishera–Yatesa, a do trasy trafia żądana liczba pierwszych punktów.
- Kolejność – odległości liczone są wzorem haversine. Aplikacja tworzy wiele permutacji wybranego zestawu i ocenia je za dużą sumę długości odcinków, dobry najkrótszy odcinek oraz karę za odcinki wyraźnie krótsze od mediany.
- Losowość – wybierany jest losowo jeden z najlepszych układów, a nie zawsze to samo optimum, więc każda gra wygląda trochę inaczej.
Bezpieczeństwo i wdrożenie
- Logowanie – hasło administratora przechowywane jako hash, podpisana sesja; wszystkie endpointy poza logowaniem i
/api/healthwymagają zalogowania. - Prywatność – zdjęcia i baza danych nie opuszczają własnego serwera; pliki są odczytywane po identyfikatorach z bazy, nie po ścieżkach od klienta.
- Docker – pojedynczy obraz i trwały katalog
data/(SQLite, oryginały, miniatury); gotowydocker-composedla Synology z obrazem z GHCR. - Jakość –
npm run checkuruchamia sprawdzanie typów, testy backendu i frontendu oraz produkcyjny build.

