105 lines
8.6 KiB
Markdown
105 lines
8.6 KiB
Markdown
# 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.* |