8.6 KiB
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 UPDATEcsak bizonyos egyedi kulcsokon (pl. make, normalized_name, …).0_discovery_enginedifferenciális szinkronja kihagyja agold_enrichedrekordokat.0_strategistnem módosítprocessedvagyin_progressstátuszú rekordokat.
6. Következtetések
- A robot‑ökoszisztéma jól strukturált, atomizált zárolással, kvótakezeléssel és hibatűréssel.
- A mapping réteg hiányzik – a
mapping_rules.pyésmapping_dictionary.pyfájlok nincsenek használatban. - Kritikus biztonsági rés: nincs
is_manualvédelem. A #27, #28, #29 kártyákhoz kapcsolódó beavatkozásoknál ezt figyelembe kell venni. - Állapotgép áttekinthető, a státuszok logikusan lépnek egymás után. A
gold_enrichedstá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 avehicle_data_loader‑ben, majd terjeszszük ki a hunterekre. - #28 (Manual védelem): Vezessünk be egy
is_manual(boolean) mezőt avehicle_model_definitionstáblában, és a robotok minden írása előtt ellenőrizzük (WHERE is_manual = false). - #29 (Pipeline monitorozás): A
robot_report.pykiegé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.