kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
main
service-finder/backend/app/workers/README.md

17 KiB
Executable File
Raw Permalink Blame History

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

docker compose up -d --build
Reference in New Issue View Git Blame Copy Permalink