service-finder/backend/audit_report_vehicle_robots.md

Vehicle Robot Ecosystem - Teljes technikai audit jelentés

Audit dátum: 2026-03-12
Gitea kártya: #69
Auditáló: Főmérnök / Rendszerauditőr

1. Áttekintés

A backend/app/workers/vehicle/ könyvtárban 15 fájl található, melyek egy 5 szintű (0–4) robot‑csővezetéket alkotnak. A pipeline célja a járművek technikai adatainak automatikus felfedezése, gyűjtése, kutatása, AI‑alapú dúsítása és végül a valós eszközök (Asset) VIN‑alapú hitelesítése. A robotok önállóan, aszinkron üzemmódban futnak, és az adatbázis rekordjainak státuszmezőin keresztül kommunikálnak (status‑driven pipeline).

2. Fájllista

Fájl	Szint	Rövid leírás
vehicle_robot_0_discovery_engine.py	0	Őrkutya (watchdog), differenciális RDW szinkron, havonta teljes adatbázis letöltés
vehicle_robot_0_gb_discovery.py	0	Brit (GB) CSV feldolgozás, gb_catalog_discovery tábla feltöltése
vehicle_robot_0_strategist.py	0	Piaci priorítás számítása (RDW darabszám alapján)
vehicle_robot_1_catalog_hunter.py	1	RDW API‑ból technikai adatok kinyerése, vehicle_model_definitions táblába írás
vehicle_robot_1_gb_hunter.py	1	DVLA API (GB) lekérdezés, vehicle_model_definitions táblába írás
vehicle_robot_1_2_nhtsa_fetcher.py	1.2	NHTSA API (USA) – csak EU márkákra szűrve
vehicle_robot_1_4_bike_hunter.py	1.4	NHTSA API – motorok
vehicle_robot_1_5_heavy_eu.py	1.5	RDW API – nehézgépjárművek (teher, busz, lakóautó)
vehicle_robot_2_researcher.py	2	DuckDuckGo keresés, strukturált kontextus előállítása AI számára
vehicle_robot_3_alchemist_pro.py	3	AI‑alapú adategyesítés (RDW + AI), validáció, gold_enriched státusz
vehicle_robot_4_vin_auditor.py	4	Asset VIN hitelesítés AI segítségével
mapping_rules.py	–	Forrásmezők leképezése (jelenleg nincs használatban)
mapping_dictionary.py	–	Szinonimák normalizálása (jelenleg nincs használatban)
vehicle_data_loader.py	–	Külső JSON források betöltése vehicle.reference_lookup táblába
robot_report.py	–	Diagnosztikai dashboard, statisztikák megjelenítése

3. Állapotgép (State Machine) térkép

A következő táblázat a robotok által keresett és beállított státuszokat összegzi. A sorrend a pipeline természetes folyását tükrözi.

3.1. vehicle.catalog_discovery tábla

Robot (fájl)	Keresett státusz (WHERE)	Beállított státusz (SET / INSERT)	Megjegyzés
0_discovery_engine	processing	pending	Őrkutya: beragadt feladatok visszaállítása
0_discovery_engine	–	pending (új rekord)	Differenciális szinkron: csak ha nincs gold_enriched a vehicle_model_definitions‑ben
0_strategist	NOT IN ('processed', 'in_progress')	pending (prioritás frissítés)	Csak még nem feldolgozott rekordok
1_catalog_hunter	pending	processing → processed	Atomizált zárolás (SKIP LOCKED)
1_gb_hunter	pending (gb_catalog_discovery)	processing → processed / invalid_vrm	DVLA API kvótakezeléssel
1_2_nhtsa_fetcher	–	pending (új rekord)	Csak EU márkákhoz, USA_IMPORT piac
1_4_bike_hunter	–	pending (új rekord)	Motorok, USA_IMPORT piac
1_5_heavy_eu	–	pending (új rekord)	Nehézgépjárművek, EU piac

3.2. vehicle.vehicle_model_definitions tábla

Robot (fájl)	Keresett státusz (WHERE)	Beállított státusz (SET / INSERT)	Megjegyzés
0_discovery_engine	research_in_progress, ai_synthesis_in_progress (2 órás timeout)	unverified, awaiting_ai_synthesis	Őrkutya: beragadt AI feladatok visszaállítása
1_catalog_hunter	–	ACTIVE (új rekord)	ON CONFLICT DO NOTHING (make, normalized_name, variant_code, version_code, fuel_type)
1_gb_hunter	–	ACTIVE (új rekord)	ON CONFLICT DO NOTHING
2_researcher	unverified, awaiting_research, ACTIVE	research_in_progress → awaiting_ai_synthesis (siker) / unverified (újra) / suspended_research (max próbálkozás)	Atomizált zárolás, kvótakezelés (DVLA)
3_alchemist_pro	awaiting_ai_synthesis, ACTIVE	ai_synthesis_in_progress → gold_enriched (siker) / manual_review_needed (max próbálkozás) / unverified (vissza)	AI hívás, hibrid merge (RDW + AI), validáció
0_discovery_engine (diff sync)	gold_enriched	–	Védelem: a gold_enriched rekordok kihagyása a felfedezésből

3.3. vehicle.gb_catalog_discovery tábla

Robot (fájl)	Keresett státusz (WHERE)	Beállított státusz (SET / INSERT)
0_gb_discovery	–	pending (új rekord) – csak ha nincs gold_enriched a vehicle_model_definitions‑ben
1_gb_hunter	pending	processing → processed / invalid_vrm

3.4. vehicle.assets tábla

Robot (fájl)	Keresett állapot (WHERE)	Beállított státusz (SET)
4_vin_auditor	is_verified = false AND vin IS NOT NULL	audit_in_progress → active (siker) / audit_failed (hiba)

4. Logikai összefüggések

4.1. Orchestráció

Nincs központi orchestrator. A robotok párhuzamosan futnak, és az adatbázis rekordjainak státuszait közös munka‑memóriaként használják. A folyamat láncolata:

catalog_discovery (pending) 
    → robot 1.x hunter (processed) 
        → vehicle_model_definitions (ACTIVE) 
            → robot 2 researcher (awaiting_ai_synthesis) 
                → robot 3 alchemist (gold_enriched)

A gold_enriched státuszú rekordok védettek: a 0_discovery_engine és 0_gb_discovery nem veszi őket fel újra.

4.2. Mapping réteg

A mapping_rules.py és mapping_dictionary.py fájlok nincsenek integrálva a robotokba. A vehicle_data_loader.py saját, forrásspecifikus leképezést alkalmaz, de a mapping fájlokat nem importálja. Ez a réteg jelenleg kihasználatlan.

4.3. Atomizált zárolás és kvótakezelés

A hunterek és kutatók FOR UPDATE SKIP LOCKED zárolást használnak, így elkerülhető a race condition. A külső API‑k (DVLA, DuckDuckGo) kvótakezeléssel rendelkeznek (QuotaManager osztály).

5. Biztonsági és integritási ellenőrzés

5.1. is_manual védelem hiánya

A teljes kódbázisban egyetlen fájlban sem található is_manual mezőre vagy „manual” kulcsszóra épülő védelem. A robotok csak a gold_enriched státusz alapján kerülik a felülírást. Kockázat: manuálisan bevitt adatok (pl. admin által javított technikai specifikációk) felülírhatók, ha a rekord státusza nem gold_enriched.

5.2. Egyéb védelmi mechanizmusok

• ON CONFLICT DO NOTHING / ON CONFLICT DO UPDATE csak bizonyos egyedi kulcsokon (pl. make, normalized_name, …).
• 0_discovery_engine differenciális szinkronja kihagyja a gold_enriched rekordokat.
• 0_strategist nem módosít processed vagy in_progress státuszú rekordokat.

6. Következtetések

1. A robot‑ökoszisztéma jól strukturált, atomizált zárolással, kvótakezeléssel és hibatűréssel.
2. A mapping réteg hiányzik – a mapping_rules.py és mapping_dictionary.py fájlok nincsenek használatban.
3. Kritikus biztonsági rés: nincs is_manual védelem. A #27, #28, #29 kártyákhoz kapcsolódó beavatkozásoknál ezt figyelembe kell venni.
4. Állapotgép áttekinthető, a státuszok logikusan lépnek egymás után. A gold_enriched státusz jelenti a végső védelmet.

7. Javaslatok a #27, #28, #29 kártyákhoz

• #27 (Mapping integráció): Kapcsoljuk be a mapping_rules.py‑t a vehicle_data_loader‑ben, majd terjeszszük ki a hunterekre.
• #28 (Manual védelem): Vezessünk be egy is_manual (boolean) mezőt a vehicle_model_definitions táblában, és a robotok minden írása előtt ellenőrizzük (WHERE is_manual = false).
• #29 (Pipeline monitorozás): A robot_report.py kiegészítése valós‑idejű státusz‑átmenetek grafikonjával és riasztásokkal.

---

Jelentés készült a backend/app/workers/vehicle/ könyvtár 15 fájljának teljes kódauditja alapján. Minden állítás kódrészletekre támaszkodik.