Walidacja Planu Implementacji Browser-VPN SaaS

Data: 2026-07-22

Źródła: Plan implementacji (2026-07-22-browser-vpn-implementation-plan.md) vs Specyfikacja v4 (2026-07-22-browser-vpn-v4-design.md)

Ocena ogólna: 7.5/10

Scorecard

Co jest OK ✅

Struktura i podział na taski

• 16 tasków w 5 fazach — właściwy podział, każdy task ma clear objective
• Taski bite-sized (2-5 min) — realny czas wykonania, dobrze zdefiniowane zakresy
• Kolejność faz logiczna — Infrastruktura → Backend → Frontend → Security → Backup → CI/CD
• Każdy task ma verify step — to kluczowe dla TDD i Hermes automation
• Priorytetyzacja MVP — Fazy 0-2 jako Must Have, Fazy 3-4 jako Should Have, Faza 5 jako Could Have

Pokrycie wymagań spec v4

Co brakuje / wymaga poprawy ⚠️

🔴 1. BTCPay Server — brak serwisu w docker-compose (CRITICAL)

Problem: Spec v4 definiuje BTCPay Server jako osobny Docker service z pruned Bitcoin node (10 GB). Plan w Task 1.4 integruje się z BTCPay API, ale nigdzie nie definiuje serwisu BTCPay w docker-compose.yml (Task 0.1). Bez tego serwisu integracja BTCPay nie zadziała — nie ma do czego wysyłać webhooków ani tworzyć invoice'ów.

Rozwiązanie: Dodać serwis btcpayserver do docker-compose.yml (Task 0.1) lub osobny task w Faza 0.

Przykładowa konfiguracja z spec v4:

services:
  btcpayserver:
    image: btcpayserver/btcpayserver:latest
    environment:
      - BTCPAY_CHAIN=BTC
      - BTCPAY_PRUNE=10000
    volumes:
      - btcpay-data:/data
    networks:
      - btcpay-network

🔴 2. Polityka retencji danych — brak implementacji (HIGH)

Problem: Spec v4 definiuje 7 zasad retencji danych:

• Order number: usuwany po 90 dniach
• deviceToken: usuwany po 90 dniach
• IP klienta: NIE przechowywany
• User-Agent: NIE przechowywany
• Logi operacyjne: 7 dni retention
• Tickety support: 90 dni
• Metryki serwera: 30 dni

Plan nie zawiera żadnego taska do implementacji tych zasad. Brak cron joba/schedulera do cleanupu, brak mechanizmu anonimizacji danych.

Rozwiązanie: Dodać task w Faza 1 (backend) lub Faza 3 (security) implementujący scheduler do czyszczenia danych zgodnie z polityką retencji.

🟡 3. SLO Measurement — brak implementacji (MEDIUM)

Problem: Spec v4 definiuje konkretne metody pomiaru SLO:

• Uptime API: curl co 30s do /api/v1/health
• Czas startu kontenera: mierzony w kodzie, zapis do server_metrics
• Response time API: P95 z curl -w "%{time_total}" co 30s
• Streaming latency: heartbeat co 30s

Plan w Task 3.3 (Monitoring) jest ogólny — "Alerty Telegram z progami" — ale nie implementuje tych konkretnych mechanizmów pomiarowych.

Rozwiązanie: Doprecyzować Task 3.3 o implementację SLO measurement zgodnie ze spec v4, lub dodać osobny task.

🟡 4. Brak zadania dla WireGuard config upload (MEDIUM)

Problem: Spec v4 opisuje lifecycle VPN configów (7 kroków), w tym:

• Krok 1: Admin wgrywa plik .conf przez admin panel
• Krok 6: Rotacja configów (disable → upload new)

Plan ma Task 1.5 (VPN pool) i admin panel (Task 2.4), ale nie ma konkretnego taska dla mechanizmu uploadu WireGuard configów przez admin panel ani API endpointu do tego.

Rozwiązanie: Dodać podtask w Task 2.4 (admin panel) lub osobny task w Faza 1 dla API endpointu POST /api/v1/admin/vpn-configs.

🟡 5. Ticket system — brak implementacji (MEDIUM)

Problem: Spec v4 definiuje tabelę tickets w ERD i politykę retencji (90 dni), a plan wspomina tickety w admin panelu (Task 2.4). Brakuje jednak:

• API endpointów do ticketów (create, list, close)
• Formularza tickets na froncie
• Mechanizmu anonimizacji ticketów po 90 dniach

Rozwiązanie: Dodać task w Faza 1 (backend) dla tickets API i w Faza 2 (frontend) dla tickets UI.

🟡 6. Discount codes — brak implementacji (MEDIUM)

Problem: Tabela discount_codes istnieje w migracji SQL (Task 0.2), ale plan nie ma taska dla:

• API do walidacji kodu rabatowego
• Logiki aplikowania rabatu w order flow
• Admin panelu do zarządzania kodami

Rozwiązanie: Dodać walidację discount_code w Task 1.2 (Orders API) i UI w Task 2.4 (admin panel).

🟢 7. DR scenarios — niepełne pokrycie (LOW)

Problem: Spec v4 definiuje 7 scenariuszy DR z RTO/RPO. Plan ma Task 4.2 (restore.sh, switch-domain.sh), ale nie obejmuje wszystkich scenariuszy:

• Brak procedury dla "Container crash >3 razy w 1h" (stop + alert)
• Brak procedury dla "Trocador API down" (jest failover, ale nie ma testu)
• Brak procedury dla "VPN region down" (auto-pomiń, alert)

Rozwiązanie: Dodać te scenariusze do Task 4.2 lub dokumentacji DR.

Analiza szczegółowa

Ocena tasków

Ocena faz

Zalecane poprawki

Must Have (przed implementacją)

1. Dodaj BTCPay Server service do docker-compose.yml (Task 0.1) — bez tego integracja BTCPay nie zadziała
2. Dodaj task dla data retention / cleanup scheduler — w Faza 1 (backend) lub Faza 3 (security)
3. Podziel Task 1.5 na dwa osobne taski: (a) Container orchestration, (b) VPN pool management
4. Podziel Task 2.4 na dwa osobne taski: (a) Admin dashboard + orders, (b) Admin containers + settings
5. Dodaj SLO measurement do Task 3.3 — konkretne skrypty curl, heartbeat, timing

Should Have (przed prod)

1. Dodaj tickets API (Faza 1) + tickets UI (Faza 2)
2. Dodaj discount codes validation w Task 1.2 + admin UI w Task 2.4
3. Dodaj WireGuard config upload endpoint w Faza 1 + admin UI w Task 2.4
4. Uzupełnij DR scenariusze w Task 4.2 — container crash loop, Trocador down test, VPN region down

Could Have (po MVP)

1. Seccomp custom profile (v2) — zgodnie ze spec v4, nie dla MVP

Podsumowanie

Rekomendacja

Plan jest gotowy do implementacji po wprowadzeniu 5 poprawek Must Have. Po ich aplikacji ocena wzrośnie do ~9/10. Główne ryzyko to brak BTCPay serwisu w docker-compose — bez tego nie da się przetestować integracji płatności.

Raport wygenerowany 2026-07-22 przez Hermes Agent na podstawie walidacji planu vs specyfikacji v4.