service-finder/docs/ultimatespecs_integration_audit.md

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.