# 🤖 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