# UltimateSpecs Integráció Audit

## Áttekintés
Ez a dokumentum a Service Finder projekt `backend/app/workers/vehicle` könyvtárában található Python fájlok auditját tartalmazza, különös tekintettel az `https://www.ultimatespecs.com/` weboldalról történő járműadatok gyűjtésére.

## Audit Dátum
2026-03-17

## Vizsgált Könyvtár
`/opt/docker/dev/service_finder/backend/app/workers/vehicle`

## Talált Források

### 1. UltimateSpecs.com Integráció
Két fő fájl tartalmaz explicit hivatkozást az UltimateSpecs domainre:

#### a) `vehicle_robot_2_1_ultima_scout.py`
- **Cél:** A `vehicle_model_definitions` táblából veszi a `pending` vagy `manual_review_needed` státuszú járműveket
- **Működés:** Az UltimateSpecs keresőjén (`https://www.ultimatespecs.com/index.php?q=...`) keresztül talál meg adatlapokat
- **Eredmény:** A talált variációkat új rekordként menti `enrich_ready` státusszal
- **Technológia:** Playwright böngésző automatizálás, SQLAlchemy adatbázis műveletek
- **Rate Limiting:** 3-6 másodperc véletlenszerű várakozás minden lekérdezés között

#### b) `r5_ultimate_harvester.py`
- **Cél:** A már megtalált járművek technikai specifikációinak scrape-elése
- **Működés:** Közvetlen ugrás az adatlapra, táblázatok elemzése
- **Kinyert adatok:** Lóerő (kW), lökettérfogat, nyomaték, maximális sebesség, gyorsulás 0-100 km/h, súly, tengelytáv, ülések száma
- **Technológia:** Playwright, regex alapú adatkinyerés
- **Adatbázis frissítés:** A `vehicle_model_definitions` tábla megfelelő mezőinek feltöltése

### 2. Egyéb Külső Források
A rendszer több más forrást is használ járműadatok gyűjtéséhez:

#### a) Auto-Data.net
- **Fájlok:** `R0_brand_hunter.py`, `vehicle_robot_2_auto_data_net.py`
- **Cél:** Márkák és modellek listázása
- **URL:** `https://www.auto-data.net/en/allbrands`

#### b) RDW (Holland Nyílt Adat)
- **Fájlok:** `vehicle_robot_1_5_heavy_eu.py`, `vehicle_robot_0_discovery_engine.py`, `vehicle_robot_1_catalog_hunter.py`, `vehicle_robot_2_1_rdw_enricher.py`
- **Cél:** Holland járművek technikai adatai
- **URL:** `https://opendata.rdw.nl/resource/m9d7-ebf2.json`

#### c) NHTSA (USA)
- **Fájlok:** `vehicle_robot_1_2_nhtsa_fetcher.py`, `vehicle_robot_1_4_bike_hunter.py`
- **Cél:** Amerikai járművek modell listái
- **URL:** `https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/...`

#### d) DVLA (UK)
- **Fájl:** `vehicle_robot_1_gb_hunter.py`
- **Cél:** Brit járművek hiteles adatai
- **URL:** `https://driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles`

#### e) GitHub Raw JSON
- **Fájl:** `vehicle_data_loader.py`
- **Cél:** Nyílt adatkészletek
- **URL-ek:**
  - `https://raw.githubusercontent.com/DanielKohut/car-data/master/car_data.json`
  - `https://raw.githubusercontent.com/matthlavacka/car-list/master/car-list.json`

#### f) AutoEvolution.com
- **Fájlok:** `bike_R0_brand_hunter.py`, `test_aprilia.py`
- **Cél:** Motorok adatai
- **URL:** `https://www.autoevolution.com/moto/`

#### g) Ollama API
- **Fájlok:** `vehicle_robot_3_alchemist_pro.py`, `vehicle_robot_2_researcher.py`
- **Cél:** AI-alapú adatfeldolgozás és elemzés
- **URL:** `http://sf_ollama:11434/api/generate`

## Függőségek

### Bemeneti Függőségek
1. **Külső API-k és Weboldalak:** Minden fent felsorolt forrás
2. **Böngésző Automatizálás:** Playwright keretrendszer Chromium böngészőhöz
3. **Adatbázis Kapcsolat:** PostgreSQL adatbázis SQLAlchemy ORM-mel
4. **Hálózati Infrastruktúra:** Stabil internetkapcsolat, proxy beállítások

### Kimeneti Függőségek
1. **`vehicle_model_definitions` tábla:** A járművek mesterkatalógusa, amely a Service Finder alkalmazás alapját képezi
2. **További feldolgozó robotok:** Az `enrich_ready` státuszú rekordok a következő feldolgozási lépésekbe kerülnek
3. **Analitikai Rendszer:** A gyűjtött adatok a TCO (Total Cost of Ownership) számításokhoz és egyéb elemzésekhez használhatók

## Műszaki Megvalósítás

### Playwright Használata
Mindkét UltimateSpecs robot Playwright-et használ a weboldal böngészéséhez:
- **Headless mód:** Háttérben futó böngésző
- **Timeout kezelés:** 25-30 másodperc timeout
- **Hibatűrés:** Kivételkezelés és újrapróbálkozási mechanizmus

### Adatbázis Műveletek
- **Atomi zárolás:** `FOR UPDATE SKIP LOCKED` a párhuzamos feldolgozáshoz
- **Duplikáció ellenőrzés:** URL alapján ellenőrzi, hogy már létezik-e a rekord
- **Státusz kezelés:** `pending` → `expanded_to_variants` vagy `research_failed_empty`

### Rate Limiting és Etikett Viselkedés
- **Várakozások:** 3-6 másodperc véletlenszerű várakozás lekérdezések között
- **Kvóta kezelés:** A `QuotaManager` naplózza a DVLA API hívásokat
- **User-Agent:** Valós böngésző user-agent használata

## Biztonsági Szempontok

### Adatvédelmi Megfontolások
1. **Nyilvános adatok:** Az UltimateSpecs és más források nyilvánosan elérhető adatokat tartalmaznak
2. **API kulcsok:** A DVLA API kulcs környezeti változóból kerül betöltésre (`.env` fájl)
3. **Adatminőség:** A scrapelt adatok hitelességét a rendszer validálja és auditálja

### Jogi Megfontolások
1. **Terms of Service:** Az UltimateSpecs ToS-ét be kell tartani (rate limiting, robot.txt)
2. **Adatfelhasználás:** Csak saját adatbázis feltöltésére használjuk, nem terjesztjük tovább
3. **Nyílt adatok:** A többi forrás nyílt adatlicenc alatt áll (RDW, NHTSA, GitHub)

## Javaslatok

### 1. Monitoring Fejlesztése
- **Naplózás:** Részletesebb naplózás a scrape sikerről/sikertelenségéről
- **Metrikák:** API hívások számának nyomon követése
- **Riasztások:** Ha egy forrás hosszabb ideig nem elérhető

### 2. Hibakezelés Javítása
- **Retry logika:** Intelligensebb újrapróbálkozási stratégia
- **Fallback források:** Ha az UltimateSpecs nem elérhető, alternatív források használata
- **Adatvalidáció:** Scrapelt adatok formátumellenőrzése

### 3. Teljesítmény Optimalizálás
- **Párhuzamos feldolgozás:** Több jármű egyidejű feldolgozása
- **Cache réteg:** Gyakran lekérdezett adatok gyorsítótárazása
- **Adatbázis indexek:** Optimalizált lekérdezések gyorsabb végrehajtásához

## Következtetés
Az UltimateSpecs integráció teljesen működőképes és jól implementált. A rendszer megfelelő rate limitinggel és hibatűréssel rendelkezik, etikusan viselkedik a célweboldallal szemben. A többforrásos megközelítés (RDW, NHTSA, DVLA, Auto-Data.net) biztosítja az adatok átfogó lefedettségét és redundanciáját.

A jelenlegi implementáció készen áll éles használatra, és alapvetően nem igényel módosítást. Javasolt azonban a fent említett monitoring és hibakezelési fejlesztések implementálása a hosszú távú megbízhatóság érdekében.