GeoPuzzle Server 2 to backend gry puzzlowej opartej na lokalizacji, stworzony jako moja praca licencjacka. Byłem odpowiedzialny za cały backend — gracze rozwiązują geograficzne zagadki rozmieszczone wzdłuż trasy, zgadując współrzędne mapy dla każdego waypointu. Serwer obsługuje uwierzytelnianie, zarządzanie treścią, rozgrywkę w czasie rzeczywistym i obliczanie wyników.
Gra — WebSocket i protokół komend
Rozgrywka odbywa się przez trwałe połączenie WebSocket. Zamiast pollingu, klient steruje grą wysyłając typowane komendy JSON, a serwer utrzymuje kompletny stan gry per połączenie.
- Komendy:
select,start,next,answer,exit - Stan per połączenie — bieżący etap, skumulowany wynik, czas
- Geograficzny scoring algorytmem Haversine — 100 pkt w promieniu, skalowane 0–100 poza nim
- Automatyczny wpis do scoreboard po zakończeniu gry
- Dwa typy waypointów: zagadki tekstowe i graficzne (upload obrazu)
- Trasa wymaga waypointów i tagów przed aktywacją — wymuszane przez hook pre-save Mongoose
Funkcje API i architektura
Serwer zbudowany na Express.js i TypeScript (ESM), z bazą MongoDB przez Mongoose. Wzorzec factory handler dostarcza generycznych operacji CRUD współdzielonych przez wszystkie modele — kontrolery pozostają zwięzłe i spójne.
- Generyczne factory handlery —
getAll,getOne,addOne,updateOne,deleteOne - Klasa zapytań — filtrowanie, wyszukiwanie pełnotekstowe, sortowanie, ograniczanie pól, paginacja
- Globalny error handler z klasą
AppErrori wrapperemcatchAsync - Dokumentacja Swagger / OpenAPI generowana z komentarzy JSDoc
- Bezpieczeństwo: Helmet, CORS, sanityzacja NoSQL, czyszczenie XSS, ochrona HPP
Uwierzytelnianie i własność zasobów
Użytkownicy logują się przez Google OAuth 2.0 via Passport.js. Po callbacku serwer generuje podpisany JWT używany przy wszystkich chronionych żądaniach. Middleware własności zapewnia, że tylko twórca może edytować lub usuwać swoje zasoby.
- Przepływ logowania i przekierowania Google OAuth 2.0
- Generowanie i walidacja JWT na każdej chronionej trasie
- Middleware własności — mutacje tylko przez twórcę
- Profile użytkowników powiązane z kontami Google przez provider ID
