Initial commit: Robot ökoszisztéma v2.0 - Stabilizált jármű és szerviz robotok

backend/app/workers/README.md

@@ -0,0 +1,221 @@
+# 🤖 Service Finder - Robot Hadsereg (Workers Ecosystem)
+**Verzió:** MB 2.0 Standard  
+**Utolsó frissítés:** 2026. február
+
+Ez a könyvtár tartalmazza a rendszer háttérben futó aszinkron munkásait (workereit). A robotok három logikai "hadosztályra" vannak bontva, hogy a felelősségi körök (Adatgyűjtés, AI Elemzés, Validálás) szigorúan el legyenek választva.
+
+---
+
+## 🏛️ Rendszer Hadosztály (System Division)
+*Ezek a robotok a rendszer általános adatminőségéért és a felhasználói dokumentumokért felelnek.*
+
+### 1. `robot_1_ocr_processor.py` (OCR Dokumentum Elemző)
+* **Miért készült?** A Prémium/VIP felhasználók által feltöltött számlákat és forgalmi engedélyeket dolgozza fel.
+* **Hogyan működik?** Képeket optimalizál (max 1600px), elmenti őket a biztonságos NAS Vault-ba, majd az AI segítségével strukturált adatokat (Gold Data) von ki belőlük.
+* **Docker parancs (Kézi indítás):** `docker compose exec api python -m app.workers.system.robot_1_ocr_processor`
+
+### 2. `system_robot_2_service_auditor.py` (A Bíró)
+* **Miért készült?** Hogy levegye az adminisztrátorok válláról a szervizek élesítésének terhét, és karbantartsa az adatbázist.
+* **Hogyan működik?** Két funkciója van. Egyrészt figyeli a `data.service_staging` táblát, és ha egy szerviz eléri a megadott bizalmi ponthatárt (Trust Score), automatikusan átemeli az éles profilok közé. Másrészt időszakosan inaktiválja a megszűnt szervizeket.
+* **Docker parancs:** `docker compose exec api python -m app.workers.system.system_robot_2_service_auditor`
+
+---
+
+## 🛠️ Szerviz Hadosztály (Service Division)
+*Ezek a robotok a szervizpontok felkutatásáért, dúsításáért és szakmai validálásáért felelnek.*
+
+# 🤖 Service Robot 0: Continental Scout (A Google Rácskereső)
+
+## 🎯 A Modul Célja
+Prémium, fizetős adatbázisokra támaszkodó felderítő. A `data.discovery_parameters` táblában megadott városokat (pl. "Debrecen") dolgozza fel. Egy bounding box-ot (befoglaló téglalapot) kér a Nominatim API-tól, majd azt kis cellákra bontva, mátrix-szerűen végigpásztázza a Google Places API-val.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Olvasás:** `data.discovery_parameters` (Miket kell pásztázni).
+- **Írás:** `data.service_staging` (Várólista). Ha az ujjlenyomat már létezik, csak növeli a `trust_score`-t.
+
+## ⚠️ Biztonsági Figyelmeztetés
+A Google Places API fizetős. A `maxResultCount` és a cellaméret közvetlenül szorozza a költségeket. Ezt a robotot szigorú napi limittel (QuotaManager vagy GCP Console szintű hard-limit) szabad csak futtatni, 30 napos frissítési ciklussal. A mentett adatok magasabb (30) induló bizalmi pontot kapnak, mint az OSM adatok.
+
+# 🤖 Service Robot 0: OSM Scout (A Térképész)
+
+## 🎯 A Modul Célja
+Ingyenes, geolokáció-alapú szerviz-felderítő robot. Az OpenStreetMap (OSM) Overpass API-ját használja, hogy a megadott bounding box (pl. Magyarország) területén lévő autószerelők, gumisok, mosók és benzinkutak POI (Point of Interest) adatait begyűjtse.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Írás:** `data.service_staging` (Várólista).
+- **Zárolás/Szűrés:** A `fingerprint` (név + város MD5 hash-e) alapján szűri a duplikációkat.
+
+## 🧠 Folyamat és Védelem
+1. Külön lekérdezéseket indít a javítóműhelyekre és a kényelmi szolgáltatásokra.
+2. Rate Limit védelem: Beépített exponenciális várakozás, ha az OSM szervere `429 Too Many Requests` hibát ad.
+3. Heti egyszer fut le (86400 * 7 mp), mivel az OSM adatok lassan változnak. A nyers adatokat betölti `pending` státusszal a `ServiceStaging` táblába, alacsony (20) bizalmi pontszámmal.
+* **Docker parancs:** `docker compose exec api python -m app.workers.service.service_robot_1_scout_osm`
+
+### 2. `service_robot_3_enricher.py` (Szakmai Címkéző)
+* **Miért készült?** Hogy a nyers szövegekből (leírások, weboldalak) strukturált szakmai profilokat építsen.
+* **Hogyan működik?** Keresi a projekt hivatalos `ExpertiseTags` kulcsszavait a lekapart szövegekben. Ha egyezést talál, rögzíti a szerviz profiljában, és jóváírja a Gamification felfedezési pontokat.
+* **Docker parancs:** `docker compose exec api python -m app.workers.service.service_robot_3_enricher`
+
+# 🤖 Service Robot 4: Google Validator (A Mesterlövész)
+
+## 🎯 A Modul Célja és Masterbook 2 Illeszkedés
+A Szerviz-ökoszisztéma utolsó minőségbiztosítója. Nem keres vaktában (nincs rácskeresés). Azoknak a szervizeknek, amiket a Robot-1 talált (OSM) és a Robot-3 bedúsított (Szakmák), ez a robot megkeresi a hajszálpontos Google Places ID-ját. Letölti a térképi GPS koordinátákat, a nyitvatartást, a telefonszámot és az értékeléseket.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Zárolás/Olvasás:** `data.service_profiles` (ahol `is_verified = False`).
+- **Írás:** Frissíti a PostGIS `location` geometriát, a JSONB nyitvatartásokat, és a bizalmi pontszámot (`trust_score`). Ha hiteles, beállítja az `is_verified = True` értéket.
+- **Atomi Zárolás:** `FOR UPDATE SKIP LOCKED` védi a race condition hibáktól.
+
+## 🧠 Geo-logika és API Kezelés
+- **Google Places API (New):** Célzott `searchText` alapú keresést futtat a név és a település alapján (`maxResultCount=1`).
+- **QuotaManager (Pénztárcavédelem):** Szigorúan számolja a hívásokat egy fizikai `.quota_google_places.json` fájlban, és megállítja a robotot, ha eléri a `.env`-ben definiált `GOOGLE_DAILY_LIMIT` határt.
+- **Ghosting:** Ha a Google sem ismeri a szervizt, `ghost` státuszba helyezi (fantom szerviz, valószínűleg már bezárt).* **Docker parancs:** `docker compose exec api python -m app.workers.service.service_robot_4_validator_google`
+
+---
+
+## 🚗 Jármű Hadosztály (Vehicle Division)
+*Ezek a robotok a Master Data Management (MDM) járműkatalógusát építik fel nulláról.*
+
+# 🤖 Robot-0: Discovery Engine & Watchdog (A Felderítő)
+
+## 🎯 A Modul Célja és Masterbook 2 Illeszkedés
+A Robot-0 a Service Finder flotta-nyilvántartó ökoszisztémájának "beszállítója" és "gondnoka". Nem végez AI műveleteket és nem gyűjt részletes technikai adatokat. Két fő feladata van, amelyek biztosítják a rendszer skálázhatóságát:
+1. **Differential Sync (Különbözeti Szinkron):** Havonta egyszer letölti az RDW járműlistáját, kiszűri belőle a már kész (gold_enriched) járműveket, és csak az új típusokat helyezi el a `catalog_discovery` várólistán, prioritás (darabszám) szerint rendezve.
+2. **Watchdog (Őrkutya):** Óránként végigfésüli az adatbázist, és megkeresi azokat a feladatokat, amelyekbe a többi robot (Hunter, Researcher, Alchemist) beletört a bicskája vagy lefagyott feldolgozás közben. Ezeket visszaállítja alapállapotba.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Írás:** `data.catalog_discovery` (új modellek felvitele és státusz-visszaállítás).
+- **Olvasás:** `data.vehicle_model_definitions` (létezik-e már a `gold_enriched` rekord?).
+- **Olvasás/Frissítés:** `data.asset_catalog` (manual bootstrap ellenőrzés).
+
+## 🧠 Geo-logika és API Kezelés
+- **Külső API:** `opendata.rdw.nl` (Lapozással, 10.000-es csomagokban).
+- **Hibatűrés:** Exponenciális újrapróbálkozás (Exponential Backoff) Rate Limit (`HTTP 429`) esetén.
+- **Állapotmegőrzés:** A legutolsó sikeres letöltés dátumát a `/app/temp/.last_rdw_sync` fájlban tárolja a felesleges API hívások és a Docker restartból adódó végtelen ciklusok elkerülése végett.
+
+## ⚙️ Logikai Folyamat (Heartbeat Loop)
+A program egy végtelen ciklusban fut az alábbiak szerint:
+1. `run_watchdog()`: Felszabadítja az 1 óránál régebben "processing" vagy "research_in_progress" állapotban lévő rekordokat.
+2. `should_run_rdw_sync()`: Megvizsgálja, eltelt-e 30 nap az utolsó letöltés óta.
+3. **HA IGEN:** Elindítja a `seed_from_rdw()`-t. Az SQL szintű szűrés (`WHERE NOT EXISTS`) biztosítja, hogy a mesteradatok érintetlenek maradjanak.
+4. **Alvás:** A robot 3600 másodpercre (1 óra) elalszik, majd kezdi elölről az Őrkutya futtatásával.
+
+## 🧪 Tesztelési Forgatókönyv a Debugger számára
+- **API Teszt:** A konténer logjában meg kell jelennie a "Lapozás: 0 - 10000 tételek analízise" üzenetnek, API hiba (`429`) esetén pedig a késleltetett újrapróbálkozásnak.
+- **Konzisztencia Teszt:** Ha a `vehicle_model_definitions` táblában van egy "VW GOLF" `gold_enriched` státusszal, a Robot-0 nem szúrhatja be újra a `catalog_discovery` táblába.
+
+### 2. `vehicle_robot_0_strategist.py` (A Stratéga)
+* **Miért készült?** Hogy a rendszer a leggyakoribb autókkal (pl. Suzuki, Toyota) kezdje a munkát, ne a ritka egzotikumokkal.
+* **Hogyan működik?** Elemzi az RDW piacon lévő darabszámokat, és frissíti a várólista `priority_score` mezőjét a valós elterjedtség alapján.
+* **Docker parancs:** `docker compose exec api python -m app.workers.vehicle.vehicle_robot_0_strategist`
+
+### 🤖 Robot-0-GB: GB Discovery Engine (A Brit Felfedező)
+
+## 🎯 Cél
+Az angol piac speciális betöltője. Mivel a DVLA API nem listázható típusok szerint (csak rendszám alapján), ez a robot egy nyílt adathalmazt (CSV) olvas be. A CSV-ből kinyeri az elsődleges rendszámokat (VRM), és egy dedikált `gb_catalog_discovery` várólistára teszi őket, de csak azokat, amelyek még nincsenek a mesterkatalógusunkban!
+
+## 🗄️ Adatbázis Érintettség
+- **Írás:** `data.gb_catalog_discovery` (id, vrm, make, model, status)
+- **Differential Sync:** Szűr a `data.vehicle_model_definitions` tábla `gold_enriched` státusza alapján (meglévő autókat nem tesz a listára).
+
+## ⚙️ Folyamat
+Napi egyszer lefut, végignyálazza a helyi `/mnt/nas/app_data/uk_mot_data.csv` fájlt. Ha új modellt lát, beírja a rendszámát `pending` státusszal.
+
+#### 🤖 Robot-1: Catalog Hunter (A Vadász)
+
+## 🎯 A Modul Célja és Masterbook 2 Illeszkedés
+A Robot-1 az ökoszisztéma első szintű technikai adatbányásza. Feladata, hogy a Robot-0 (Discovery) által kijelölt, `pending` státuszú típusokhoz a lehető legpontosabb műszaki adatokat (köbcenti, lóerő, üzemanyag, motor kód, méretek) gyűjtse be az RDW hivatalos adatbázisából. 
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Olvasás/Írás:** `data.catalog_discovery` (Feladatok átvétele `pending` -> `processing`, majd lezárása `processed` státuszba).
+- **Írás:** `data.vehicle_model_definitions` (Technikai rekordok létrehozása).
+- **Zárolási Stratégia:** Szigorú `FOR UPDATE SKIP LOCKED` használata. Bármennyi példány futhat párhuzamosan, nem fognak összeakadni.
+
+## 🧠 Geo-logika és API Kezelés
+- **Külső API-k:** - Fő adatok: `m9d7-ebf2.json`
+  - Üzemanyag/Károsanyag: `8ys7-d773.json`
+  - Motorblokk: `jh96-v4pq.json`
+- **Hibatűrés:** Exponenciális újrapróbálkozás (Exponential Backoff) beépítve a Rate Limit (`HTTP 429`) és a hálózati szakadások ellen. A robot nem omlik össze, hanem kivár és újra próbálkozik.
+
+## ⚙️ Logikai Folyamat
+1. Keres egy `pending` feladatot a várólistán (prioritás szerint csökkenve) és azonnal `processing`-re állítja.
+2. Lekéri az RDW-ből a típushoz tartozó összes specifikus rendszámot (max 500 db/típus).
+3. A rendszámok alapján lekéri a motor- és üzemanyag-specifikációkat.
+4. `INSERT ... ON CONFLICT DO NOTHING` SQL logikával beszúrja az új technikai variánsokat a mestertáblába. Ha a variáns már létezik, csendben továbblép.
+5. A feladatot `processed` státuszba helyezi, majd folytatja a következóvel.
+* **Docker parancs:** `docker compose exec api python -m app.workers.vehicle.vehicle_robot_1_catalog_hunter`
+
+### 🤖 Robot-1-GB: GB Hunter (A DVLA Mesterlövész)
+
+## 🎯 Cél
+A `gb_catalog_discovery` táblában lévő `pending` rendszámokra küld lekérdezést a hivatalos brit kormányszerver felé (DVLA VES API). Az így kapott 100%-ig hiteles technikai adatokat betölti az európai mestertáblába (`vehicle_model_definitions`) `ACTIVE` státusszal, ahonnan a Robot-3 (Alkimista) befejezi a munkát.
+
+## 🗄️ Adatbázis Érintettség
+- **Atomi zárolás:** `FOR UPDATE SKIP LOCKED` a `gb_catalog_discovery` táblán.
+- **Írás:** `data.vehicle_model_definitions` (`INSERT ... ON CONFLICT DO NOTHING`).
+
+## 🧠 Biztonság és API
+- **API:** `driver-vehicle-licensing.api.gov.uk/vehicle-enquiry/v1/vehicles`
+- **Kvóta Védelem:** A `QuotaManager` szigorúan figyeli a `DVLA_DAILY_LIMIT` változót az `.env` fájlból, megelőzve az API tiltást vagy túlszámlázást.
+
+### 🤖 Robot-2: Vehicle Researcher (A Mesterlövész Adatgyűjtő)
+
+## 🎯 A Modul Célja és Masterbook 2 Illeszkedés
+A Robot-2 az "űrkitöltő" mikroszolgáltatás. Azokra a járművekre specializálódik, amelyeknél az RDW (Robot-1) nem tudott elegendő műszaki adatot biztosítani. Ahelyett, hogy ömlesztett weblapokat olvasna be (ami túlterhelné az AI GPU-t), a Robot-2 célzott "Mesterlövész" kereséseket (Targeted Searches) hajt végre strukturált autós adatbázisokban, és egy zajmentes aktát készít az Alkimista (Robot-3) számára.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Olvasás/Írás:** `data.vehicle_model_definitions`
+- **Állapotátmenetek:** `unverified` / `awaiting_research` -> `research_in_progress` -> `awaiting_ai_synthesis` (vagy `suspended_research` ha 5 próbálkozás után sincs adat).
+- **Zárolási Stratégia:** `FOR UPDATE SKIP LOCKED`, prioritást adva a Toyota modelleknek és a kevesebbet próbált rekordoknak.
+
+## 🧠 Geo-logika és API Kezelés
+- **Tier 1 (Ingyenes):** DuckDuckGo aszinkron burkolóval, `site:ultimatespecs.com` és `site:auto-data.net` operátorokkal.
+- **Tier 2 (Fizetős/Kvótás):** UK DVLA API (Későbbi integrációhoz előkészítve).
+- **Védelmi Rendszerek:** - `QuotaManager`: Szigorúan naplózza a limitált API hívásokat egy lokális fájlba (`.quota_dvla.json`), megakadályozva a túlköltekezést.
+  - **Truncation:** A kontextust maximum 2500 karakterre vágja, megelőzve az LLM Out-of-Memory (OOM) hibáit.
+
+## ⚙️ Logikai Folyamat
+1. Zárolja a megfelelő rekordot.
+2. Párhuzamosan (`asyncio.gather`) indít 3 keresést a neten (Műszaki adatok, Folyadékok, Típushibák).
+3. A kapott "snippeteket" egy strukturált `[SOURCE: XYZ]` formátumú szöveggé fűzi össze.
+4. Ha a szöveg elég hosszú (>150 karakter), átadja az AI-nak. Ha nem, növeli a próbálkozások számát.
+* **Docker parancs:** `docker compose exec api python -m app.workers.vehicle.vehicle_robot_2_researcher`
+
+### 🤖 Robot-3: Alchemist Pro (A Szintetizáló)
+
+## 🎯 A Modul Célja és Masterbook 2 Illeszkedés
+A Robot-3 a rendszer "Agya". Ő az egyetlen, aki drága AI (LLM / Ollama) erőforrásokat használ. Feladata, hogy a Robot-1 (RDW) és Robot-2 (Web) által begyűjtött, sokszor hiányos vagy zajos technikai adatokat egyetlen, tökéletesen tiszta "Arany" (`gold_enriched`) rekorddá olvassza össze a `vehicle_catalog` (Mesterkatalógus) számára.
+
+## 🗄️ Érintett Adatbázis Komponensek
+- **Olvasás/Frissítés:** `data.vehicle_model_definitions` (VMD) tábla.
+- **Írás (Insert):** `data.vehicle_catalog` (Az Aranytábla).
+- **Zárolási Stratégia:** Szigorú `FOR UPDATE SKIP LOCKED`. A `awaiting_ai_synthesis` (Robot-2 által készített) és az `ACTIVE` (Robot-1 által készített) státuszokat veszi fel.
+
+## 🧠 Geo-logika és API Kezelés
+- **AI Hívás:** `AIService.get_clean_vehicle_data` (Helyi Ollama vagy külső LLM).
+- **Költségvetés Védelem:** Beépített `daily_ai_limit` figyeli, hogy ne lépjük túl a megengedett napi hívásszámot. Ha elfogy a keret, a robot alvó módba kapcsol a következő napig.
+- **Sane-Check (Józan ész ellenőrzés):** Beépített fizikai korlátok (pl. max 18000 ccm, max 1500 kW, kivéve teherautók) védik az adatbázist az AI "hallucinációitól".
+
+## ⚙️ Logikai Folyamat
+1. Atomi lakatolással lefoglal egy feladatot és `ai_synthesis_in_progress` státuszba teszi.
+2. Átadja a nyers adatokat (RDW + Web Context) az AI-nak.
+3. Lefuttatja a "Sane Check"-et. Ha az AI hibázott, visszadobja az aktát `unverified` státuszba (hogy a Robot-2 újra megpróbálja).
+4. **Hibrid Merge:** Az RDW hatósági adatai mindig felülírják az AI becsléseit!
+5. Létrehozza a `vehicle_catalog` bejegyzést (`ON CONFLICT DO NOTHING` védelemmel).
+6. Lezárja a VMD rekordot `gold_enriched` státusszal.
+* **Docker parancs:** `docker compose exec api python -m app.workers.vehicle.vehicle_robot_3_alchemist_pro`
+
+### 6. `vehicle_robot_4_vin_auditor.py` (Alvázszám Hitelesítő)
+* **Miért készült?** Hogy a felhasználók által beküldött konkrét járműveket (Assets) pontosan a helyes katalógus-variánshoz kösse.
+* **Hogyan működik?** Dekódolja a VIN (Alváz) számokat az AI segítségével. Ha a megfejtett teljesítmény (kW) eltér a jelenlegitől, új katalógus-variánst hoz létre, és oda köti a járművet.
+* **Docker parancs:** `docker compose exec api python -m app.workers.vehicle.vehicle_robot_4_vin_auditor`
+
+---
+
+## 🚀 Indítási Segédlet (Launch Control)
+
+A robotok önállóan is indíthatók a fenti `docker compose exec ...` parancsokkal hibakeresés céljából, de a végleges működéshez a `docker-compose.yml` fájlban önálló szervizként (container) kell definiálni őket.
+
+**Rendszer újraindítása és a robotok aktiválása a háttérben:**
+```bash
+docker compose up -d --build