🛡️ Dokumentacja Techniczna: System Kalkulatora Link4

Witamy w dokumentacji technicznej projektu integracji ubezpieczeniowej Link4. System został zaprojektowany jako skalowalna platforma typu Split-Backend, łącząca szybką logikę obliczeniową z elastycznym systemem zarządzania treścią (CMS).

1. Architektura Systemu

System składa się z trzech niezależnych, ale współpracujących warstw. Poniższy diagram przedstawia przepływ danych:

graph TD
    User((Użytkownik)) --> Frontend[Frontend React/Vite]
    Frontend -->|Kalkulacje| Backend[Insurance Engine - FastAPI]
    Frontend -->|Treści/FAQ| CMS[CMS Backend - FastAPI]
    
    subgraph "Infrastruktura Serwerowa"
        Backend -->|SQLite| DB1[(calc.db)]
        CMS -->|SQLite| DB2[(cms.db)]
    end
    
    subgraph "Integracje Zewnętrzne"
        Backend -->|SOAP/XML| Link4[Link4 FullAPI]
    end

Podział odpowiedzialności:

Insurance Engine (Port 8000): Odpowiada za krytyczną komunikację z SOAP API Link4, walidację danych ubezpieczeniowych i przechowywanie ofert.
CMS Backend (Port 8001): Zarządza dynamicznymi elementami strony, artykułami Trivia oraz sekcją FAQ.
Frontend: Nowoczesna aplikacja SPA, która integruje dane z obu backendów w płynny interfejs użytkownika.

2. Integracja Link4 (SOAP fullAPI)

Integracja wykorzystuje zaawansowanego klienta Link4Client opartego na bibliotece zeep oraz httpx.

Kluczowe Procesy:

Short Path (Automatyzacja): Na podstawie numeru rejestracyjnego lub VIN, system odpytuje bazy Link4/UFG w celu automatycznego uzupełnienia danych pojazdu.
Full Calculation: Proces calculate przesyła kompletny profil kierowcy i pojazdu, zwracając listę dostępnych pakietów (OC, AC, Assistance).
Policy Issuance: Proces dwufazowy (prepareSell -> registerPolicy), kończący się wygenerowaniem numeru polisy i harmonogramu wpłat.

Bezpieczeństwo i Komunikacja:

Autoryzacja: Basic Auth wymuszony przez Link4.
IP Whitelisting: Komunikacja z API Link4 wymaga, aby publiczny adres IP serwera był zarejestrowany w ich systemie.

3. Testowanie i Diagnostyka

Wprowadziliśmy rygorystyczny podział na testy automatyczne i narzędzia diagnostyczne.

Testy Automatyczne (pytest)

Służą do weryfikacji logiki biznesowej i stabilności integracji.

docker exec -it insurance-fastapi pytest tests/

Główne pliki testowe:

test_link4.py: Pełny cykl kalkulacji.
test_dictionaries.py: Weryfikacja dostępności słowników API.
test_vehicle_catalog.py: Testowanie ścieżki wyboru marki i modelu.

Narzędzia Diagnostyczne

Do rozwiązywania problemów z łącznością (np. blokady IP):

vps_test_debug.py: Kompleksowy raport stanu połączenia, weryfikacja IP źródłowego i symulacja zapytań SOAP.

4. Standardy Deweloperskie

Branching: Projekt wykorzystuje Git-Flow. Stabilne wersje etapowe znajdują się na gałęzi beta.
Dostęp do Repozytorium: Od wersji Beta 1.0, zalecany jest dostęp przez SSH (git@dev.zarnecki.org:...) dla zwiększenia bezpieczeństwa i wyeliminowania konieczności podawania hasła przy każdej operacji.
Zmienne Środowiskowe: Wszystkie wrażliwe dane (hasła API, klucze JWT) muszą znajdować się wyłącznie w plikach .env (ignorowanych przez Git).

Ostatnia aktualizacja: 2026-05-05 | Wersja: 1.0-beta