service-finder/docs/V01_gemini/22_ROBOT ÖKOSZISZTÉMA.md

22.1 Robot 1: Catalog Scout (The Library)

    Feladat: Folyamatos, háttérben futó adatgyűjtés (EU-szintű járműspecifikációk).

    Működés: Web-crawling és technikai adatbázisok szinkronizációja. Nem áll le, folyamatosan frissíti a vehicle_catalog táblát.

22.2 Robot 2: Service Hunter & OCR (The Auditor)

    Service Hunting: EU-szintű térképadatok és szaknévsorok (Google, OSM, Yellow Pages) alapján szervizpontok felderítése.

    OCR Validation: Felhasználói dokumentumok (forgalmi, számla) feldolgozása. Ha az OCR szervizadatot talál, keresztellenőrzi a data.organizations táblával.

22.3 Robot 3: RobotScout (The Detective)

    Feladat: Egyedi jármű (Asset) validáció. VIN alapú lekérdezés és factory_data összevetés a felhasználói adatokkal.

    23. SERVICE ONBOARDING & THREE-STEP FLOW

A szolgáltatói (szerviz) regisztráció integrálódik az alap onboarding folyamatba:

    Step 1 (Lite): Alap felhasználói fiók létrehozása.

    Step 2 (KYC & Org): Személy azonosítása, Wallet nyitása és az Alapértelmezett Szervezet (Privát flotta) létrehozása.

    Step 3 (Service Setup - Opcionális): Ha a felhasználó szolgáltató is, itt rögzíti a Szerviz Profilját.

        Létrejön egy második Organization rekord (org_type='service').

        Hozzárendelésre kerülnek az ExpertiseTag-ek (Szakmai szempontok).

        GPS koordináták rögzítése (PostGIS).

24. ROBOT SCOUT & CATALOG STRATEGY (HU -> EU)

A Robot 1 (Catalog Filler) egy rétegelt feltöltési stratégiát követ:

    Layer 1 (Basic Identity): Márka, Típus, Évjárat, Motor (HU piac fókusz).

    Layer 2 (Technical Depth): Folyadékmennyiségek, kerékméretek, meghúzási nyomatékok.

    Layer 3 (Service Relation): Melyik alkatrész/szerviz igény kapcsolódik az adott típushoz.

API Strategy

24. Robot Scout Adatforrások:

    Járművek: A robot a CarQuery API és a NHTSA vPIC API kombinációját használja a 2000 utáni EU-s modellek feltöltéséhez. A ciklusidő: 1 év/5 perc.

    Szervizek: Az OSM Overpass API az elsődleges forrás a lokációkhoz. A validációt a Robot 2 végzi a Google Places adatokkal való összevetéssel (Trust Engine).

    Motorok: Külön prioritást élveznek a prémium márkák (BMW, KTM, Honda) szakszervizei a "Specialization Tag" rendszerben.

    📘 MASTER BOOK KIEGÉSZÍTÉS (v2.4) - 2026.02.13
20.4 Szerviz Életciklus és Automatikus Kivezetés (Soft-Delete)

A Marketplace tisztaságát az automatikus inaktiválási folyamat garantálja:

    Státuszok:

        ghost: Bot által talált, nem hitelesített rekord.

        active: Működő, publikus szerviz.

        flagged: Gyanús (pl. bezártnak jelentett), felülvizsgálatra vár.

        inactive: Megszűnt vagy inaktivált szerviz (Soft-deleted).

    Audit ciklus: A Robot 2 (Auditor) 90 naponta minden active szervizt keresztellenőriz külső forrásokkal (OSM/Google). Ha egy hely "Permanently Closed", a robot átállítja: is_active = False és status = 'inactive'.

22.4 Robot Orchestration (Koordináció)

A robotok az adatbázist használják "jelzőtáblának", így elkerülik az ütközéseket:

    Robot 1 (Catalog Scout): Kizárólag a data.vehicle_catalog táblát írja.

    Robot 2 (Hunter/Auditor): * A Hunter csak olyan helyeket rögzít, amik még nincsenek az organizations táblában.

        Az Auditor csak az is_active=True rekordokat vizsgálja felül.

    Robot 3 (OCR/Detective): Dokumentum-alapú validálást végez. Ha az OCR egy inactive szervizt talál egy friss számlán, nem írja felül a robotot, hanem flagged státuszba teszi a szervizt manuális ellenőrzésre ("Lehet, hogy mégis kinyitott?").

    20.4 Szerviz Állapotok és Láthatóság

    ghost (Alapértelmezett): Bot által talált rekord.

        Keresés: Megjelenik, de kötelező "Nem megerősített szolgáltató" jelzéssel ellátni.

        Gamification: Teljesen nyitott. A felhasználók értékelhetik, fotózhatják. Minden ilyen interakció növeli a trust_score-t.

    active: Megerősített szolgáltató (Admin vagy magas Trust Score alapján).

    flagged: Felülvizsgálat alatt (pl. ellentmondásos adatok).

    inactive: Igazoltan megszűnt. Csak ez az állapot rejtett a keresés elől.

    ## 2.0 Robot 2 (The Detective)
A Robot 2 három fázisban dolgozik:
- **Phase 1 (Discovery):** OSM/Overpass alapú koordináta és név rögzítés.
- **Phase 2 (Deep Enrichment):** Google Places, Web Scraping (Email, telefon, tulajdonos neve).
- **Phase 3 (Financial Audit):** Nyilvános cégadatok (Árbevétel, létszám, adózott eredmény) éves szinkronizálása.

# 22. ROBOT ÖKOSZISZTÉMA

## Robot v1.9.2 (Ghost Commander) & n8n
A robotok és az n8n szoros együttműködésben dolgoznak.

### Funkciók
- **Auto-Heal:** A járműkatalógus hiányos (null) adatainak automatikus pótlása Holland (RDW) és US (NHTSA) forrásokból.
- **Ban-Detection:** Automatikus "Circuit Breaker" logika. Ha a CarQuery vagy más forrás tilt, a robot átvált "Silent Mode"-ba.
- **Event Hunter:** n8n workflow figyeli a motoros/autós találkozókat és eseményeket, majd összeköti őket a helyi szervizpartnerekkel.
- **Gamification Link:** A robot regisztrálja a felhasználói validálásokat és kiosztja a pontokat/krediteket.

# 22. Robot Ökoszisztéma

A rendszer automatizált adatgyűjtő és dúsító ágensei.

## 1. Model Enrichment Robot (Dúsító)
- **Működés:** Hajnali 01:00 - 05:00 között.
- **Logika:** 1. Új `unverified` kódok keresése.
    2. RDW API lekérdezés (Holland alapok).
    3. AI (Gemini) Deep Scraping: Marketing név, felszereltségi lista, szervizintervallumok kinyerése.
    4. Validálás a JSON Sémák alapján.
    5. Master státusz beállítása.

## 2. Resource Management
A robot figyeli a szerver terhelését. Ha a CPU > 70%, az AI lekérdezéseket lassítja (throttle), hogy ne zavarja a hajnali biztonsági mentéseket.

    # 22. Robot Ökoszisztéma Specifikáció

A rendszer autonóm robotok hálózatából áll, amelyek egymásra épülve tisztítják és dúsítják a flottaszintű adatokat.

## 22.1 Robot 1: Catalog Scraper (RDW)
- **Feladata:** Külső API-k (pl. Holland RDW) folyamatos monitorozása és új járművek importálása.
- **Működés:** Nyers adatokat hoz létre `unverified` státusszal.

## 22.2 Robot 2: Technical Enricher & Master Merge (v1.2.6)
Ez a legkomplexebb modul, amely AI-t és webes keresést használ.

### Főbb képességek:
- **Google Search Integration (RAG):** Ha az AI nem ismeri a modellkódot, valós időben keres a gyártói oldalakon.
- **Safe-Merge Technológia:** Megakadályozza a technikai kód nélküli rekordok véletlen összevonását (`N/A-{id}` generálásával).
- **Atomi tranzakciókezelés:** Minden mentés külön tranzakció, így a hiba nem szakítja meg a tömeges feldolgozást.

### Működési folyamat:
1. Rekord kiválasztása (`status = unverified`).
2. RDW kiegészítő adatok lekérése.
3. Gemini 2.0 Flash meghívása keresőeszközzel.
4. JSON parseolás és kód-validáció.
5. Deduplikáció ellenőrzése és mentés.



## 22.3 Robot 3: OCR & Document AI
- **Feladata:** Feltöltött okmányok, számlák és kilométeróra állások felismerése.
- **Technológia:** Multimodális Gemini 2.0 elemzés.
- **Kimenet:** Strukturált JSON, amely azonnal validálható a katalógus (R2) adataival.

## 22.4 Robot 4: Service Hunter (Tervezett)
- **Cél:** A dúsított technikai adatok alapján szervizpartnerek és árak keresése.
- **Input:** Robot 2 által generált szerviz-specifikációk (olaj típus, mennyiség).

## 22.5 Robot Monitoring & Operáció
A robotok állapotát nem csak SQL-ben, hanem az n8n Dashboardon és a logok szintjén is követjük.
- **Hibakezelés:** Automatikus visszalépés és ideiglenes kódgenerálás (`RESET-`, `UNKNOWN-`) az adatbázis kényszerek (Unique, Not Null) betartása érdekében.