Weryfikacja specyfikacji: Browser-VPN Product Design

Data: 2026-07-22 | Dokument: 2026-07-22-browser-vpn-product-design.md (738 linii) | Status: Draft

1. Podsumowanie

Specyfikacja Browser-VPN to solidna baza architektoniczna z jasnym zakresem MVP i świadomymi ograniczeniami, ale zawiera krytyczne sprzeczności techniczne w mechanizmie sesji oraz luki operacyjne, które zablokują implementację bez poprawek. Dokument dobrze definiuje "co", ale niedostatecznie "jak".

2. Ocena ogólna

6/10

Dobra struktura, ale brakuje kontraktów API, obsługi błędów i wymagań wydajnościowych. Dwie sprzeczności techniczne wymagają natychmiastowej poprawy.

3. Znalezione problemy

Krytyczne (blokują implementację)

• K1. Sprzeczność: httpOnly cookie + localStorage (sekcja 1.3.8, 10.2). Cytat: "deviceToken stored in httpOnly cookie and localStorage". httpOnly cookie z definicji nie może być odczytany przez JavaScript, więc localStorage nie może zostać z nim zsynchronizowany. Implementator nie wie, który token jest źródłem prawdy.
• K2. Brak mechanizmu dostarczenia numeru zamówienia (sekcja 1.3.4 vs 14.2). Brak emaili, brak kont — jak użytkownik otrzymuje ord-XXXXXX-XXXXXX? Jeśli zamknie kartę przed skopiowaniem, traci dostęp do płatności i sesji. Brak opisu UX dla tego krytycznego kroku.
• K3. Niejasność liczenia czasu sesji (sekcja 1.3.10). Cytat: "Time starts counting from first access, with a 1-hour buffer after container launch". Co jeśli użytkownik nigdy nie otworzy magic link? Kontener działa w nieskończoność? Brak timeoutu na "first access" — zasoby serwera mogą zostać zablokowane.

Ważne (istotne ryzyko)

• W1. Brak kontraktów API (sekcje 7.1, 7.2). 11 modułów backend i 5 stron frontend nie definiują interfejsów między nimi. Brak schematów żądań/odpowiedzi, kodów błędów, typów.
• W2. Brak obsługi błędów (cały dokument). Co gdy Docker nie wystartuje, VPN config jest nieprawidłowy, kontener crashuje? Sekcja 4.3 wspomina "automatic troubleshooting", ale bez procedur.
• W3. Race condition "magic link" (sekcja 1.3.7). Jeśli link jest współdzielony przed pierwszą wizytą, kto jest "first device"? Brak mechanizmu rezerwacji — wyścig przy jednoczesnym otwarciu.
• W4. Brak wymagań wydajnościowych. Brak SLA, czasu startu kontenera, maksymalnego czasu odpowiedzi. Sekcja 3.2 wspomina "CPU < 80%, RAM < 80%", ale bez definicji, jak mierzyć i reagować.
• W5. Realność 50 kontenerów na single server (sekcja 3.2, 13.1.9). 50 jednoczesnych kontenerów z przeglądarką graficzną + WireGuard na jednym serwerze to ekstremalne obciążenie RAM. Brak szacunków zasobów na kontener.

Kosmetyczne

• Ks1. Discount code (sekcja 1.3.2, 6.4). Brak specyfikacji: kto tworzy kody, jak działa walidacja, limity użycia. Tabela istnieje, ale brak opisu logiki.
• Ks2. Browser choice persistence (sekcja 1.3.2). W którym momencie i gdzie jest przechowywany wybór przeglądarki? Kolumna browser jest w orders, ale nie w sessions.

4. Brakujące elementy

Brakuje kontraktów API (OpenAPI/schematy) między modułami, polityki retencji danych poza 30-dniowym summary page, procedur obsługi błędów i recovery, wymagań wydajnościowych (SLA, startup time, response time), szacunków zasobów na kontener i capacity planning, strategii testów (unit, integration, E2E) oraz definicji "first access" z timeoutem na nieodwiedzone sesje.

5. Mocne strony

• Jasny, świadomy zakres MVP z sekcją "Out of Scope" (1.4)
• Świadome ograniczenia z uzasadnieniem (sekcja 14.1)
• Dobre pokrycie modelu danych — 7 tabel pokrywa główne encje
• Przemyślany przepływ zakupu i sesji (sekcja 3)
• Realistyczne podejście do deployment (one-command, migration, domain switching)
• Backup i monitoring wbudowane w MVP, nie odłożone na później
• Priorytetyzacja MoSCoW (Must/Should/Could Have)
• Sekcja "Open Questions" pokazuje dojrzałość procesu

6. Rekomendacje

1. Rozwiąż sprzeczność httpOnly/localStorage — wybierz jedno źródło prawdy dla deviceToken. Rekomendacja: httpOnly cookie jako jedyne, localStorage tylko jako fallback dla SPA routing.
2. Zdefiniuj mechanizm dostarczenia order number — dodaj QR code, pobranie jako plik, lub ostrzeżenie UX przed zamknięciem karty. Rozważ "order recovery" przez discount code jako kompromis anonimowości.
3. Dodaj timeout na first access — np. 1 godzina od aktywacji; jeśli nieodwiedzone, zatrzymaj kontener i zwolnij VPN config.
4. Uzupełnij kontrakty API — dodaj schematy żądań/odpowiedzi dla wszystkich endpointów z sekcji 7.2, z kodami błędów.
5. Dodaj capacity planning — oszacuj RAM/CPU na kontener, zweryfikuj czy 50 jest realistyczne, zdefiniuj plan degradacji.
6. Zdefiniuj procedury obsługi błędów — dla każdego modułu: co, kiedy, jak reagować, kto powiadamiać.
7. Dodaj wymagania wydajnościowe — max startup time (np. 60s), max response time (np. 2s), SLA dostępności (np. 99.5%).
8. Rozwiąż race condition magic link — dodaj mechanizm rezerwacji przy pierwszym kliknięciu (atomic bind).