chore: Backend codebase cleanup and archiving of legacy scripts

docs/audits/audit_report_vehicle_robots.md

@@ -0,0 +1,105 @@
+# 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.*