Kalkulator Ubezpieczeń – Link4 Integration

System do kalkulacji ubezpieczeń komunikacyjnych zbudowany na bazie FastAPI, zintegrowany z zewnętrznym API Link4 (fullAPI / SOAP). Projekt obejmuje backend z logiką kalkulacji, bazę danych do przechowywania wyników oraz frontend w postaci statycznych stron HTML.

---

Stan projektu

Co jest zaimplementowane

• Integracja z Link4 fullAPI – komunikacja przez SOAP/XML z HTTP Basic Auth
• Kalkulator OC / OC+AC – obsługa formuł ubezpieczeniowych (11 = OC, 13 = OC+AC)
• Wyszukiwanie pojazdów z katalogu – endpoint /api/link4/vehicle-models z filtrowaniem po marce/modelu
• Kalkulacja przez VIN / tablicę rejestracyjną – tzw. short path (bez ręcznego podawania modelu)
• Frontend z formularzem – strona /kalkulacja-ubezpieczenia/ z wielokrokowym formularzem HTML/JS
• Strona wyników – /oferty-ubezpieczeniowe/ z prezentacją składki i danych kalkulacji
• Zapis wyników do bazy danych – SQLite (domyślnie), możliwość podmiany na Postgres przez .env
• Endpoint zdrowia – GET /health
• Konteneryzacja – pełna konfiguracja Docker + docker-compose z healthcheckiem i logowaniem

---

Architektura

kalkulator_link4/
├── app/
│   ├── main.py               # Punkt wejścia FastAPI, routing, middleware CORS
│   ├── config.py             # Ustawienia aplikacji (pydantic-settings, .env)
│   ├── api/
│   │   └── link4.py          # Endpointy REST API (/api/link4/...)
│   ├── core/                 # Narzędzia pomocnicze
│   ├── db/
│   │   └── database.py       # Silnik SQLAlchemy, sesje, inicjalizacja tabel
│   ├── models/
│   │   └── calculation.py    # Model ORM – tabela `calculation`
│   ├── schemas/
│   │   └── calculation.py    # Modele Pydantic – walidacja wejścia/wyjścia
│   └── services/
│       └── link4/
│           └── client.py     # Link4Client – komunikacja SOAP z API Link4
├── frontend/
│   ├── index.html                        # Strona główna
│   ├── kalkulacja-ubezpieczenia/         # Formularz kalkulatora
│   │   └── index.html
│   └── oferty-ubezpieczeniowe/           # Strona wyników
│       └── index.html
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env                      # Zmienne środowiskowe (nie wersjonowane)

---

Specyfikacja techniczna

Backend

Element	Technologia / Szczegół
Framework	FastAPI 0.116
Serwer ASGI	Uvicorn
Klient SOAP	Zeep 4.3 + ręczny XML fallback (lxml)
HTTP Client	HTTPX (async)
Baza danych	SQLite (dev) / dowolna baza SQL (prod via .env)
ORM	SQLModel (SQLAlchemy 2.0 + Pydantic)
Walidacja / Schematy	Pydantic v2
Konfiguracja	pydantic-settings + python-dotenv
Testy	pytest + pytest-asyncio

Link4 API

Parametr	Wartość
Protokół	SOAP / XML nad HTTPS
Autentykacja	HTTP Basic Auth (Base64)
Metody	prepareCalculation, calculate
Formuły ubezpieczenia	11 = OC, 13 = OC+AC
Identyfikacja pojazdu	tablicą rej. (short path) lub ID z katalogu
Kontakt – parametry	contact.dateOfBirth, contact.gender, contact.drivingLicenseYear, contact.livingZipCode
Leasing	obsługiwany przez obiekt cession (nie vehicle.leasing)

Frontend

Statyczne strony HTML/CSS/JS serwowane przez FastAPI (StaticFiles). Komunikacja z backendem przez HTML <form> POST oraz fetch do endpointów REST API.

---

Endpointy

Metoda	Ścieżka	Opis
GET	/	Strona główna
GET	/kalkulacja-ubezpieczenia/	Formularz kalkulatora
POST	/oferta	Przetworzenie formularza, kalkulacja, wynik
GET	/health	Status aplikacji
GET	/api/link4/vehicle-models	Lista modeli z katalogu Link4
GET	/docs	Swagger UI (automatyczny)
GET	/redoc	ReDoc (automatyczny)

---

Uruchomienie lokalne

Wymagania

• Python 3.11+
• Dostęp do środowiska Link4 (login, hasło, partner ID)

Konfiguracja

Utwórz plik .env w katalogu głównym projektu:

LINK4_BASE_URL=https://api.link4.pl/gate
LINK4_PARTNER_ID=TWOJ_PARTNER_ID
LINK4_LOGIN=TWOJ_LOGIN
LINK4_PASSWORD=TWOJE_HASLO
LINK4_AGENT_ID=            # opcjonalne
LINK4_SOURCE_IP=           # opcjonalne – wymuszenie wychodzącego IP
DATABASE_URL=sqlite:///./calc.db
ENVIRONMENT=development
DEBUG_SOAP=0

Instalacja i uruchomienie

# 1. Utwórz i aktywuj środowisko wirtualne
python -m venv venv
source venv/bin/activate       # Linux/macOS
# lub: venv\Scripts\activate   # Windows

# 2. Zainstaluj zależności
pip install -r requirements.txt

# 3. Uruchom serwer
uvicorn app.main:app --reload --port 8000

Aplikacja będzie dostępna pod adresem: http://localhost:8000

Dokumentacja Swagger: http://localhost:8000/docs

---

Uruchomienie przez Docker

# Zbuduj i uruchom kontener
docker-compose up --build

# Uruchomienie w tle
docker-compose up -d

Aplikacja będzie dostępna na porcie 80 (mapowany z 8000 wewnątrz kontenera).

Zmienne środowiskowe w Docker

Docker Compose ładuje plik .env automatycznie przez dyrektywę env_file. Upewnij się, że plik .env istnieje przed uruchomieniem.

Health check

Docker Compose wykonuje automatyczny health check co 30 sekund:

docker inspect insurance-fastapi --format='{{.State.Health.Status}}'

---

Baza danych

Domyślnie aplikacja używa SQLite (calc.db w katalogu głównym). Tabela calculation przechowuje:

Kolumna	Typ	Opis
id	int PK	Auto-inkrementowane ID
calculation_id	string	Unikalny ID kalkulacji
start_date	date	Data początku polisy
license_plate	string	Numer rejestracyjny
insurance_formula	int	Formuła (11=OC, 13=OC+AC)
premium	float	Składka roczna (PLN)

Aby przełączyć na PostgreSQL, wystarczy zmienić DATABASE_URL w .env:

DATABASE_URL=postgresql://user:password@host:5432/dbname

---

Zmienne środowiskowe – pełna lista

Zmienna	Domyślna wartość	Opis
LINK4_BASE_URL	https://api.link4.pl/gate	Główny URL API Link4
LINK4_VEHICLE_MODELS_URL	https://api.link4.pl/gate/api/ws/VehicleModelsService/v2_2	URL serwisu słownikowego pojazdów
LINK4_PARTNER_ID	–	ID partnera nadane przez Link4
LINK4_LOGIN	–	Login Basic Auth
LINK4_PASSWORD	–	Hasło Basic Auth
LINK4_AGENT_ID	–	ID agenta (dla partnerów MULTI)
LINK4_SOURCE_IP	–	Wymuszenie wychodzącego adresu IP
DATABASE_URL	sqlite:///./calc.db	Connection string bazy danych
ENVIRONMENT	production	Środowisko (development/production)
DEBUG_SOAP	0	Logowanie surowych SOAP XML (1 = włącz)

---

Testy

# Uruchomienie testów
pytest

# Z verbose output
pytest -v

Testy jednostkowe i integracyjne znajdują się w katalogu app/ (pliki test_*.py) oraz tests/.