Przejdź do treści
Home Blog Projekty O mnie

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.

Wgrywanie zdjęć punktów

Punkty rozmieszczone na mapie

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.

Generowanie nowej trasy

Trasa dla dzieci

Trasa dla osoby chowającej punkty

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.

Zagadka na karcie

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ęciaPlan dla organizatora
Karty do wycięciaPlan 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

  1. Przeglądarka wysyła zdjęcia do chronionego API.
  2. Serwer zapisuje oryginał, odczytuje EXIF przez ExifTool i przygotowuje JPEG do podglądu przez Sharp (HEIC ma osobną ścieżkę konwersji).
  3. Punkt, współrzędne z EXIF, współrzędne poprawione ręcznie i pozycja schowka trafiają do SQLite.
  4. Generator wybiera zdjęcia i układa kolejność zgodnie ze stylem trasy.
  5. 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/health wymagają 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); gotowy docker-compose dla Synology z obrazem z GHCR.
  • Jakość – npm run check uruchamia sprawdzanie typów, testy backendu i frontendu oraz produkcyjny build.