Specyfikacja techniczna — panel webowy

1. Stos technologiczny

Warstwa	Technologia
Framework	Next.js 14 (App Router)
Język	TypeScript (strict mode)
Stylowanie	Tailwind CSS
Pobieranie danych	SWR
Stan klienta	Zustand
Wykresy	Recharts
Mapy	Mapbox GL + react-map-gl
Komponenty UI	Radix UI (primitives)
Formularze	react-hook-form + zod
Powiadomienia	Sonner (toasty)

2. Struktura projektu

busikm-web/
  src/
    app/
      (auth)/             # Logowanie, rejestracja, reset hasła
      (dashboard)/        # Panel chroniony middleware
      (marketing)/        # Landing, cennik, kontakt
      api/proxy/[...path]/ # BFF proxy do backendu
      layout.tsx          # Root layout
    components/
      ui/                 # Button, Input, Dialog, Sheet, Badge
      layout/             # Sidebar, Topbar, Breadcrumb, MobileNav
    lib/                  # Konfiguracja (axios, swr, mapbox, utils)
    hooks/                # useAuth, useClient, useMediaQuery
    stores/               # Zustand (auth, ui, notifications)
    types/                # Typy TS (generowane z OpenAPI + manualne)
  middleware.ts           # Edge middleware (auth guard)

3. Autoryzacja — strategia ciasteczek

Ciasteczko	Typ	Cel
access_token	httpOnly	Token dostępu — niedostępny z JS
refresh_token	httpOnly	Token odświeżania — niedostępny z JS
user_data	non-httpOnly	Dane użytkownika (rola, email) — dostępny z JS

Edge middleware (middleware.ts) sprawdza tokeny na każdym żądaniu i przekierowuje niezalogowanych na /login. Różne role trafiają do różnych dashboardów.

4. BFF Proxy

// app/api/proxy/[...path]/route.ts
// Każde żądanie do /api/proxy/* jest forwardowane do backendu
// z dodaniem access_token z httpOnly cookie
export async function GET(req, { params }) {
  const token = req.cookies.get('access_token');
  const res = await fetch(`${BACKEND_URL}/api/v1/${params.path}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  return Response.json(await res.json());
}

5. Dashboard per rola

Owner Dashboard

• Statystyki — aktywne trasy, łączny przebieg, pojazdy, kierowcy
• Mapa — pozycje kierowców w czasie rzeczywistym (Mapbox + WebSocket)
• Wykresy — przebieg miesięczny, koszty (Recharts)
• Alerty — OC, przegląd techniczny, tachograf, prawo jazdy
• Ostatnie trasy — tabela z sortowaniem i filtrami

Accountant Dashboard

• Raporty do pobrania (PDF, CSV)
• Status eksportów FK
• Dane tylko do odczytu

Accounting Firm Dashboard

• Client Switcher — przełączanie między firmami (nagłówek X-Company-Context)
• Zagregowane statystyki dla wszystkich klientów
• Zbiorczy eksport FK

6. Tabele danych

Wszystkie tabele (pojazdy, trasy, kierowcy, raporty) mają:

• Sortowanie po kolumnach (kliknięcie nagłówka)
• Filtrowanie (data, status, pojazd, kierowca)
• Paginacja (cursor-based z API)
• Bulk actions (zaznacz wiele → eksport, usunięcie)
• Responsywność — na mobile karty zamiast tabeli

7. Mapa w czasie rzeczywistym (Post-MVP)

• Mapbox GL — wizualizacja tras GPS, pozycje kierowców
• WebSocket — aktualizacja pozycji co 5 sekund
• Klastry — grupowanie pojazdów na dużych zoomach
• Heatmapy — intensywność tras na mapie

8. Generowanie klienta API (orval)

# Pipeline:
drf-spectacular → /api/schema/ (OpenAPI 3.0)
                → orval (code generation)
                → typowany klient TS z hookami SWR

# CI sprawdza aktualność:
orval --check