HelpTravel
Polski serwis rezerwacyjny (helptravel.pl): wyszukiwarka i rezerwacja hoteli oraz lotów, wsparta warstwą treści (kierunki, przewodniki, inspiracje) pod SEO.
Rezerwacja odbywa się u nas — nie przez przekierowanie do partnera. Rozliczeniowo merchant of record jest NUITEE TRAVEL (LiteAPI), płatność kartą lub Google Pay.
Stack
- Next.js 16 (App Router) + React 19 + TypeScript + Tailwind CSS
- LiteAPI — jedyny dostawca: hotele (
/data, /hotels/rates, prebook/book) i loty (LiteAPI Flights)
- Upstash Redis — cache stawek, snapshot cen, rate limiting
- Prisma + Postgres — analityka, sesje, zapisane wyjazdy
- OpenRouter — model AI concierge'a (czat doboru wyjazdu)
- Resend (e-mail), Geoapify (geokodowanie), Pexels (zdjęcia)
- Vercel — deployment produkcyjny
Travelpayouts / Hotellook / Aviasales / Stay22 / CJ zostały całkowicie usunięte. Linki kierunkowe prowadzą wyłącznie do naszych własnych ścieżek (/hotele/szukaj, wyszukiwarka lotów).
Uruchomienie lokalne
Menedżer pakietów: pnpm (w repo jest pnpm-lock.yaml).
pnpm install
cp .env.example .env.local # uzupełnij wartości
pnpm db:push
pnpm dev # http://localhost:3000
Weryfikacja
pnpm lint
pnpm test
pnpm build
Pojedynczy plik testowy:
node --import tsx --test src/lib/concierge/tools.test.ts
Testy uruchamiane są z jawnej listy plików w package.json — nowy plik *.test.ts trzeba tam dopisać, inaczej nigdy się nie wykona.
Smoke'i uderzające w prawdziwe API (czytają .env.local):
pnpm smoke:liteapi
pnpm booking:smoke
Zmienne środowiskowe
Źródłem prawdy jest .env.example — zawiera komplet zmiennych z komentarzami (m.in. które klucze LiteAPI idą w X-API-Key, a które są publiczne dla widgetu płatności). Skopiuj go do .env.local; na Vercelu dodaj każdą zmienną osobno.
Minimum do startu lokalnego: DATABASE_URL, NEXT_PUBLIC_SITE_URL, klucze LiteAPI (sand_ wystarczy do wyszukiwania). Bez UPSTASH_* aplikacja działa, tylko bez cache'u i rate limitingu.
Testy płatności obciążają prawdziwą kartę — używaj klucza sand_.
Główne sekcje
Rezerwacje: /hotele (wyszukiwarka, karta hotelu, checkout), /loty (wyniki, rezerwacja), /wyjazdy/[typ], /oferta, /cennik.
Treści i SEO: /kierunki, /najlepsze-kierunki, /inspiracje, /przewodniki, /porownanie, /city-breaki, /cieple-kierunki, /bez-wizy, /tanie-podroze, /weekendowe-wyjazdy.
Zaufanie i formalności: /o-nas, /faq, /jak-pracujemy, /redakcja, /standard-redakcyjny, /regulamin, /polityka-prywatnosci, /dla-partnerow, /mapa-serwisu.
AI concierge (czat doboru wyjazdu) jest montowany w layoucie na każdej stronie; wyłącznik: NEXT_PUBLIC_SHOW_CONCIERGE=false.
Deploy
Vercel, gałąź main idzie prosto na produkcję. Zmienne środowiskowe ustawiane w Project Settings.
Crony (vercel.json) grzeją cache i budują snapshot cen:
/api/cron/warm-rates — co 30 min/api/cron/warm-flights — :15 i :45
Po wdrożeniu: docs/post-deploy-checklist.md.
Zasady produktowe
- Ceny nigdy nie są zmyślane. Każda kwota pochodzi z realnego wyszukania LiteAPI; wpis starszy niż 48 h traktujemy jak brak ceny. Gdy dostawca nic nie zwraca, pokazujemy pusty stan — nie szacunek.
- To samo dotyczy AI concierge'a: kwoty, terminy i oceny wyłącznie z wyników narzędzi, nigdy z „pamięci" modelu.
- Warstwa treści ma wspierać SEO i wiarygodność wydawniczą.
Dokumentacja
CLAUDE.md — architektura, konwencje i pułapki (czytaj przed większą zmianą)docs/booking-flow.md — ścieżka rezerwacji, docs/analytics-events.md — eventy GA4PRODUCT.md — zasady produktowe
