chore: Archive legacy docs and backup files, prepare for codebase cleanup v2.0

docs/V02/00_README.md

@@ -0,0 +1,92 @@
+# 📘 SERVICE FINDER - MASTER BOOK 2.0 (v2.0)
+**Traffic Ecosystem SuperApp - Single Source of Truth**
+
+Ez a dokumentáció a rendszer véglegesített, konszolidált tudásbázisa. Minden korábbi verziót felülír. A fejlesztés során kizárólag az itt hivatkozott szabályok és struktúrák érvényesek.
+
+## 🚀 1. A Rendszer Alapjai (Core Documentation)
+A teljes tudásbázis 8 db, logikailag elkülönített "könyvbe" (modulba) lett szervezve:
+
+| Fájl | Tartalom / Felelősségi kör |
+| :--- | :--- |
+| **[03_Infrastructure_Operations_2.0](./03_Infrastructure_Operations_2.0.md)** | **DevOps:** Docker Stack, Hálózatok, MinIO, Biztonsági mentés. |
+| **[05_Identity_Auth_MDM](./05_Identity_Auth_MDM.md)** | **Core:** Person vs User, Auth Flow, Master Data Management (Deduplikáció). |
+| **[06_Economy_Fleet_Marketplace_2.0](./06_Economy_Fleet_Marketplace_2.0.md)** | **Business:** Triple Wallet, Csomagok (Tiers), Szerviz Életciklus (Ghost/Active). |
+| **[07_API_Communication_2.0](./07_API_Communication_2.0.md)** | **Interface:** API Végpontok, Admin Panel, i18n, Security (Sentinel). |
+| **[12_Automated_Events_Notifications_2.0](./12_Automated_Events_Notifications_2.0.md)** | **Events:** Értesítési központ, Lejáratok figyelése, Push/Email triggerek. |
+| **[13_Roadmap_Testing_Pitfalls_2.0](./13_Roadmap_Testing_Pitfalls_2.0.md)** | **DevGuide:** Jövőkép, Tech Debt (JSONB), Fejlesztői buktatók. |
+| **[19_Permissions_Tiers_Branches_2.0](./19_Permissions_Tiers_Branches_2.0.md)** | **Access:** RBAC (L0-L3), Sales Agent rendszer, Telephely hierarchia. |
+| **[22_Robot_Ecosystem_2.0](./22_Robot_Ecosystem_2.0.md)** | **AI/Robots:** R1-R4 Robotok specifikációja, AI Search RAG, Safe-Merge logika. |
+
+---
+
+## 🗺️ 2. Kód & Dokumentáció Térkép (Code Mapping)
+Hol találod a kódban azt, amiről a dokumentáció beszél?
+
+### 🤖 Robotok & AI
+| Dokumentáció | Implementáció (File Path) |
+| :--- | :--- |
+| **Robot 1 (Catalog)** | `app/workers/catalog_scout.py` (vagy releváns worker) |
+| **Robot 2 (Enricher)** | `app/workers/technical_enricher.py` (v1.2.6) |
+| **AI Service (RAG)** | `app/services/ai_service.py` (v1.2.5) |
+| **OCR Robot** | `app/workers/ocr_robot.py` (v1.0) |
+
+### 🏢 Üzleti Logika & Modellek
+| Dokumentáció | Implementáció (File Path) |
+| :--- | :--- |
+| **Identity (Person)** | `app/models/identity.py` |
+| **Wallet & Ledger** | `app/models/audit.py` / `app/models/identity.py` |
+| **RBAC & Security** | `app/core/security.py` / `app/services/auth_service.py` |
+| **MDM / Assets** | `app/models/vehicle_definitions.py` / `app/models/asset.py` |
+
+---
+
+## 🧹 3. Archiválási Jegyzőkönyv (Cleanup Log)
+A Master Book 2.0 létrejöttével az alábbi korábbi (v1.0) állományok elavulttá váltak. Javasolt az `_archive/` mappába mozgatásuk vagy törlésük.
+
+- `00_README.md` (Régi index)
+- `01_Project_Overview.md` (Beépült a 05/06-ba)
+- `02_Architecture_System_Context.md` (Beépült a 03-ba)
+- `03_Dev_Environment_Runbook.md` (Beépült a 03-ba)
+- `04_Infrastructure_Docker_Stack.md` (Beépült a 03-ba)
+- `05_AUTH_AND_IDENTITY_SPEC.md` (Beépült a 05-be)
+- `06_Database_Guide.md` (Beépült a 05-be)
+- `07_API_Guide.md` & `07_REGISTRATION...` (Beépült a 07-be)
+- `08_Frontend_Guide.md` (Tartalma elavult, UI refaktorra vár)
+- `09_Admin_API_Guide.md` (Beépült a 07/19-be)
+- `10_Billing_Credits_Subscriptions.md` (Beépült a 06-ba)
+- `11_Gamification_Social.md` (Beépült a 06/19-be)
+- `12_Operations_Backup_Monitoring.md` (Beépült a 03-ba)
+- `13_Roadmap_Tech_Debt.md` (Beépült a 13-ba)
+- `15_Changelog.md` (Beépült a 13-ba / Git history)
+- `16_TESTING...` & `17_DEVELOPER...` (Beépült a 13-ba)
+- `18_ASSET...` & `20_Service_Finder...` (Beépült a 06-ba)
+- `19_ADMIN...` & `23_BRANCH...` (Beépült a 19-be)
+- `21_DEEP_ASSET...` (Beépült a 05-be)
+- `22_ROBOT_ÖKOSZISZTÉMA.md` (Beépült a 22-be)
+
+---
+
+## 🚦 4. Gyorsindítás (Quick Start)
+A rendszer indítása a v2.0 infrastruktúra alapján:
+
+```bash
+# 1. Környezeti változók ellenőrzése
+cat .env
+
+# 2. Konténerek indítása (V2 parancs)
+docker compose up -d --build
+
+# 3. Logok követése (Robot Enricher)
+docker logs -f service_finder_robot_enricher
+
+---
+
+### 🏛️ Architekti Zárszó
+
+Ezzel a lépéssel a projekt átlépett a "Kísérleti" fázisból az **"Ipari"** fázisba.
+1.  A dokumentáció tiszta, nem redundáns.
+2.  A fejlesztők pontosan tudják, hova nyúljanak.
+3.  A robotok logikája "kőbe van vésve".
+
+**Mi legyen a következő technikai lépés?**
+Most, hogy a könyvtár rendben van, javaslom, hogy térjünk vissza a kódhoz és kezdjük el a **Fuzzy Search API** (kereső) fejlesztését, vagy a **Frontend (UI)** felzárkóztatását az új adatokhoz?

docs/V02/03_Infrastructure_Operations.md

@@ -0,0 +1,26 @@
+# 03. Infrastructure, Docker Stack & Operations (v2.0)
+
+Ez a dokumentum a rendszer futtatókörnyezetét, a konténer-architektúrát és a biztonsági mentési protokollokat írja le.
+
+## 3.1 Docker Stack & Hálózati Architektúra
+A rendszer konténerizált, modern Docker Engine-re (Compose V2) optimalizált környezetben fut.
+
+- **Hálózatok:** - `shared_db_net`: Izolált hálózat az adatbázis és a backend modulok között [cite: 2026-02-13].
+    - `bridge`: Külső eléréshez (Nginx, API elérés) [cite: 2026-02-13].
+- **DNS Fallback:** A konténerek a belső névfeloldás mellett Google DNS-t használnak a hálózati beragadások elkerülésére [cite: 2026-02-13].
+
+
+
+## 3.2 Tárolás & Objektumtár (MinIO / NAS)
+Az adatok és médiaállományok szigorúan elkülönített struktúrában tárolódnak:
+- **Objektumtár (MinIO):** `/assets/{uuid}` és `/organizations/{id}` mappaszerkezet az automatikus izolációhoz.
+- **Helyi Tárolás:** `/static/locales` a nyelvi szinkronhoz, Docker jogosultságokkal védve.
+
+## 3.3 Üzemeltetési Runbook
+- **Konfiguráció:** Minden változó a `.env` fájlból töltődik be, a hardkódolt IP-k tilosak.
+- **Dinamikus beállítások:** A `system_configs` tábla JSONB mezői vezérlik a rendszert (pl. jutalékok, árfolyamok) a kód módosítása nélkül.
+- **Monitorozás:** Az n8n Dashboard és a Robot `ProcessLog` táblája biztosítja a valós idejű felügyeletet.
+
+## 3.4 Biztonsági Mentés & Recovery
+- **Adatbázis:** Napi automatikus dump a `shared-postgres` konténerből.
+- **Circuit Breaker:** A robotok automata vészleállítóval rendelkeznek, ha a CPU > 70% vagy külső API tiltás (Ban-Detection) történik.

docs/V02/05_Identity_Auth.md

@@ -0,0 +1,36 @@
+# 05. Identity, Authentication & Master Data Management (v2.0)
+
+Ez a dokumentum a rendszer két legfontosabb oszlopát írja le: ki a felhasználó (Identitás) és hogyan kezeljük az adatokat (MDM).
+
+## 5.1 Az Identitás Filozófiája (The Dual Entity Rule)
+A rendszer megkülönbözteti a hús-vér embert a technikai fióktól.
+
+1.  **Person (A DNS):** A természetes személy, aki "örök". GDPR törlés esetén csak anonimizálódik, de a rendszer integritása miatt megmarad.
+    - **Identity Hash:** SHA256 lenyomat (Anyja neve + Születési hely + Idő) a duplikációk ellen.
+    - **Lifetime XP:** Az egyén életút pontjai, amelyek minden USER fiókján átívelnek.
+2.  **User (A Kulcs):** Technikai belépési fiók (email/jelszó). Bármikor törölhető.
+
+## 5.2 Onboarding Folyamat (3-Step Flow)
+A regisztráció szakaszos, hogy csökkentse a lemorzsolódást:
+- **Step 1 (Lite):** Alap adatok, `is_active=False`.
+- **Step 2 (KYC):** Személyazonosság igazolása (Identity Docs), Wallet nyitása és a Privát Flotta létrehozása.
+- **Step 3 (Service Setup):** Opcionális profilalkotás szolgáltatók (Providers) számára.
+
+## 5.3 Master Data Management (MDM) Logika
+A járműadatok tisztaságát a Robot 2 (Technical Enricher) garantálja.
+
+### A Deduplikáció Szabályai:
+A rendszer csak akkor von össze két járművet (Master-Merge), ha:
+- A gyártó (`make`) egyezik.
+- A technikai kód (`technical_code`) azonos és nem 'N/A'.
+- A hengerűrtartalom (`engine_capacity`) megegyezik.
+
+### Biztonsági kódgenerálás (Fallbacks):
+Ha nem azonosítható a jármű, a rendszer egyedi kódokat generál a `NOT NULL` kényszer miatt:
+- `N/A-{id}`: Ha az AI nem talál kódot.
+- `UNKNOWN-{id}`: Ha az AI lekérdezés sikertelen.
+
+## 5.4 Adatintegritási Szabályok
+- **Soft Delete:** Nincs fizikai törlés. A `data.users` tábla e-mail címe felszabadul törléskor, de az adatok archiválódnak.
+- **Séma Izoláció:** Minden üzleti tábla a `data` sémában található, a `public` csak metaadatokat tartalmaz.
+- **Audit:** Minden pénzügyi mozgás a `financial_ledger` táblába, minden biztonsági esemény a `security_audit_logs` táblába kerül.

docs/V02/06_Database_MDM.md

@@ -0,0 +1,77 @@
+# 06. Economy, Fleet Ecosystem & Marketplace (v2.0)
+
+Ez a dokumentum a rendszer bevételi logikáját, az eszközök (Assets) életútját és a szervizkereső (Service Finder) működési szabályait rögzíti.
+
+## 6.1 A Gazdasági Motor (The Triple Wallet)
+A pénzügyi stabilitást és a B2B/B2C szétválasztást a háromszintű pénztárca-modell biztosítja.
+
+- **Earned Credits:** Validálással, tartalomgyártással vagy Referral jutalékból szerzett kredit. Prémium előfizetésre beváltható.
+- **Purchased Credits:** Valódi pénzért vásárolt egyenleg. Szolgáltatások igénybevételére és Prémiumra fordítható.
+- **Service Coins:** Tisztán B2B egység. Szolgáltatók (Providers) használják kiemelésre és hirdetésre. Nem váltható vissza lakossági Prémiumra.
+
+### Pénzügyi Integritás:
+- **Financial Ledger:** Minden tranzakció (Kredit/Coin/HUF) megmásíthatatlan főkönyvi bejegyzést generál.
+- **Multi-Currency:** A rendszer helyi valutában rögzít, de EUR alapon is tárolja az adatokat a rögzítéskori váltószámmal: $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$.
+
+## 6.2 Flotta és Asset DNS
+A járművek nem egyszerű rekordok, hanem **Digital Twin** entitások, amelyek életútja követhető a tulajdonosváltásokon keresztül is.
+
+- **Asset típusok:** `Individual` (magánszemélyé, nem átruházható flotta) és `Fleet Owner/Service` (céges, átruházható tulajdonjoggal).
+- **Tulajdonjog (Transferability):** Eladáskor a jármű teljes előélete (Evidence Store: fotók, számlák, OCR-ezett adatok) átkerül az új tulajdonoshoz.
+- **Telemetria:** A rendszer kezeli a futásteljesítményt (km/miles/hours) és a technikai eseményeket.
+
+## 6.2.1 Flotta és Asset DNS - Átruházási Szabályok
+A jármű eladásakor a tulajdonjog átruházása **korlátozott**. 
+
+- **Ami átkerül:** A jármű technikai életútja, szerviztörténete és a dúsított MDM adatok (Digital Twin history).
+- **Ami NEM kerül át:** A korábbi tulajdonos által feltöltött privát fotók, dokumentum-állományok és minden pénzügyi/számlázási adat. Ezek az eredeti entitáshoz (Cég vagy Person) maradnak kötve.
+- **Szerviz-kapcsolat:** A szervizbejegyzések és a karbantartási napló elválaszthatatlanul a **járműhöz** (Asset ID) vannak láncolva, függetlenül az aktuális tulajdonostól.
+
+## 6.3 Service Finder & Marketplace
+A Marketplace tisztaságát a Robot 2 (Auditor) és a Trust Engine szimbiózisa adja.
+
+### Szerviz Állapotok (Lifecycle):
+| Állapot | Jelentés | Láthatóság |
+| :--- | :--- | :--- |
+| **Ghost** | Bot által talált, nem hitelesített rekord. | Megjelenik "Nem megerősített" jelzéssel. |
+| **Active** | Validált, hivatalos szolgáltató. | Teljes láthatóság, Trust Badge. |
+| **Flagged** | Gyanús vagy ellentmondásos adatú hely. | Felülvizsgálatig korlátozott. |
+| **Inactive** | Igazoltan megszűnt vagy Soft-deleted. | Rejtett a kereső elől. |
+
+### Audit Ciklus:
+A Robot 2 (Auditor) 90 naponta keresztellenőrzi a szolgáltatók állapotát külső forrásokkal (Google Places/OSM). Ha a hely bezárt, automatikusan `inactive` státuszba helyezi.
+
+## 6.4 Gamifikáció és Jutalomrendszer
+- **XP Korlát:** Csak természetes személyek (`Person`) gyűjthetnek XP-t és social pontokat. Cégek nem kapnak gamifikált jutalmakat.
+- **Social-to-Credit:** Meghatározott XP szint elérésekor a rendszer automatikusan Kreditet ír jóvá a Walletbe.
+- **Referral Szintek:** 10-5-2% jutalékrendszer a meghívottak költései után.
+
+## 6.5 Trust & Evaluation Engine (Az Öt Pillér)
+A rendszerben minden entitás saját, hitelesített értékeléssel rendelkezik a bizalom maximalizálása érdekében.
+
+1. **Person (Sofőr/Tulajdonos):** Megbízhatósági mutató (pl. időpontok betartása, fizetési fegyelem).
+2. **Provider (Szolgáltató):** Szakmai minőségi mutató a felhasználói visszajelzések alapján.
+3. **Vehicle - Technical Rating:** A jármű "egészségügyi" állapota, amely kizárólag a **verifikált szervizelések** és karbantartások alapján kalkulálódik.
+4. **Vehicle - Social Rating:** Közkedveltségi mutató. Azt méri, mennyire népszerű vagy preferált az adott típus/példány a közösségben.
+5. **Validator Rating:** Az adatok ellenőrzését végző szakértők hitelességi pontszáma.
+
+## 6.6 Felhasználói Csomagok (Tiers) és Szolgáltatások
+A rendszer 5+1 szintű csomagstruktúrát alkalmaz, amely meghatározza a járműnyilvántartási kapacitást és az elérhető funkciókat.
+
+| Csomag | Célcsoport | Járműszám | Főbb funkciók |
+| :--- | :--- | :--- | :--- |
+| **FREE** | Magánszemély (Hobby) | 1 db | Alap költségkövetés, szervizkereső. |
+| **PREMIUM** | Aktív autós/motoros | Több (Pl. 3) | OCR dokumentumkezelés, hirdetésmentesség. |
+| **PREMIUM+** | Gyűjtők / Családok | Bővített | Telemetria adatok, részletes szerviznapló. |
+| **VIP** | KKV / Nagyobb flotta | 5-10+ db | Flotta menedzsment, exportok, kimutatások. |
+| **VIP+** | Vállalati flotta | Korlátlan / Egyedi | Több telephely kezelése, egyedi kimutatások. |
+| **SERVICE** | Szolgáltatók | N/A | Ügyfélkezelés, ajánlatadás, profilkiemelés. |
+
+### Kreditalapú skálázás:
+A csomagkorlátokon felül a felhasználóknak lehetőségük van **kreditért** extra járműhelyeket vásárolni a nyilvántartásukhoz, anélkül, hogy teljes csomagot kellene váltaniuk.
+
+## 6.7 VIP és Céges Flottakezelés
+A VIP (céges) előfizetők számára a rendszer dedikált modult biztosít a flotta hatékony üzemeltetéséhez:
+- **Automatizált Kimutatások:** Üzemanyag-fogyasztás, TCO (teljes birtoklási költség) és szervizköltség elemzések.
+- **Csoportos Műveletek:** Adatrögzítés és dokumentumkezelés egyszerre több járműre.
+- **Flotta-Audit:** A járművek műszaki állapotának és vizsgáinak központi felügyelete.

docs/V02/07_API_Service.md

@@ -0,0 +1,34 @@
+# 07. API Architecture, Security & Admin Control (v2.0)
+
+Ez a dokumentum az interfészek felépítését, a jogosultságkezelést (RBAC) és az Admin felügyeleti eszközöket írja le.
+
+## 7.1 API Alapelvek & Biztonság
+- **Standard:** FastAPI v2, aszinkron végpontok.
+- **JWT & RBAC:** A tokenek tartalmazzák a `rank`, `scope_level` és `scope_id` mezőket az azonnali jogosultság-ellenőrzéshez.
+- **Sentinel System (Dual Control):** A kiemelt műveletekhez (pl. pénzügy, VIP státusz) kötelező a "Négy szem elv" (Dual Control) és a `ConfirmedAction` rögzítése.
+
+## 7.2 Moduláris Végpontok (Core Endpoints)
+A korábbi monolitikus struktúrát szétbontottuk a jobb skálázhatóság érdekében:
+1. **Identity API:** `/auth`, `/complete-kyc`.
+2. **Asset API:** `/identity`, `/costs`, `/telemetry` bontásban.
+3. **Marketplace API:** Szervizkeresés (`/search`) és Autocomplete (`/suggest-street`).
+
+
+
+## 7.3 Admin & i18n Szinkronizáció
+Az Adminisztrátori felület nem csupán egy technikai eszköz, hanem a rendszer üzleti és biztonsági felügyeleti központja, amely négy szinten (Globális, Ország, Régió, Egyedi entitás) teszi lehetővé a beavatkozást.
+- **Admin Kontroll Panel:** Központi végpontok a függőben lévő műveletek jóváhagyásához és a vészleállításhoz.
+- **i18n Service:** Adatbázis-alapú fordításkezelés szerveroldali cache-sel. A `/admin/translations/sync` végpont exportálja a JSON fájlokat a Frontend számára.
+
+### 7.3.1 Főbb Adminisztrátori funkciók:
+- **Dinamikus Paraméterezés:** Új rendszerértékek, jutalékok, árfolyamok és globális változók beállítása és ellenőrzése a `system_parameters` táblán keresztül.
+- **Hierarchikus Jogosultságkezelés (RBAC):** A validációs jogok és hozzáférések finomhangolása globális vagy akár egyedi (Individual) szinten is.
+- **Validáció és Audit:** A botok által gyűjtött (Ghost) adatok felülvizsgálata, a `PendingAction` kérések jóváhagyása és a biztonsági riasztások kezelése.
+- **Regionális Kontroll:** Ország- és régióspecifikus szabályok (pl. adózási kulcsok, pénznemek, nyelvi készletek) aktiválása és felügyelete.
+
+### 7.3.2 Sentinel System (Dual Control):
+A kiemelt műveletekhez (pl. pénzügyi keretek módosítása, Admin rang adása) továbbra is kötelező a "Négy szem elv" (Dual Control), ahol a műveletet végző és a jóváhagyó személynek el kell különülnie.
+
+## 7.4 Jövőbeli Interfészek (Roadmap)
+- **Fuzzy Search:** A `synonyms` mezőre épülő `tsvector` alapú intelligens keresőmotor.
+- **Service Hunter API:** A Robot 4 által talált ajánlatok lekérdezése.

docs/V02/12_Automated_Events_Notifications_2.0.md

@@ -0,0 +1,28 @@
+# 12. Automated Events & Notification System (v2.0)
+
+Ez a modul felelős a felhasználók időbeni tájékoztatásáért a járművekkel és az előfizetésekkel kapcsolatos kritikus eseményekről.
+
+## 12.1 Értesítési Típusok és Triggerek
+A rendszer automatikusan figyeli a határidőket és értesítést küld az alábbi esetekben:
+
+### Jármű és Okmány Események:
+- **Lejáró Okmányok:** Személyi igazolvány, jogosítvány vagy útlevél lejárata (Person profil adatai alapján).
+- **Műszaki Vizsga (MOT):** A jármű következő vizsgájának esedékessége.
+- **Biztosítás:** Kötelező vagy CASCO biztosítás fordulónapja és lejárata.
+
+### Karbantartási Értesítések:
+- **Szervizintervallum:** Időalapú (pl. éves szerviz) vagy futásteljesítmény-alapú (pl. 15,000 km-enkénti olajcsere) figyelmeztetések.
+- **Gumiabroncs csere:** Szezonális váltás (téli/nyári) esedékessége.
+
+### Rendszer és Üzleti Értesítések:
+- **Előfizetés:** A választott csomag (Premium, VIP) lejárata vagy a következő számlázási ciklus kezdete.
+- **Kredit egyenleg:** Alacsony egyenleg figyelmeztetés.
+
+## 12.2 Értesítési Csatornák
+Az értesítések prioritástól és beállítástól függően több csatornán érkezhetnek:
+1. **Push Notification:** Azonnali üzenet a mobilalkalmazásban.
+2. **In-App Message:** Értesítési központ a webes felületen.
+3. **E-mail:** Heti összefoglalók vagy kritikus figyelmeztetések.
+
+## 12.3 Értesítési Beállítások (Preference Center)
+A felhasználók a `data.users.notification_settings` mezőben (JSONB) szabályozhatják, hogy mely eseményekről és milyen csatornán kérnek tájékoztatást.

docs/V02/13_Roadmap_Testing_Pitfalls_2.0.md

@@ -0,0 +1,25 @@
+# 13. Roadmap, Testing & Developer Knowledge Base (v2.0)
+
+Ez a dokumentum rögzíti a projekt jövőbeni irányait, a minőségbiztosítási folyamatokat és a fejlesztés során azonosított kritikus hibalehetőségeket (Pitfalls).
+
+## 13.1 Stratégiai Roadmap (Azonnali prioritások)
+A rendszer stabilitása után az alábbi modulok fejlesztése élvez elsőbbséget:
+
+1.  **Intelligens Kereső API (Fuzzy Search):** A `synonyms` mező indexelése PostgreSQL GIN indexekkel a "Google-szerű" találati pontosságért.
+2.  **Média Kezelés & MinIO:** Automata bot fejlesztése gyári járműfotók bányászatára és tárolására.
+3.  **Robot 4 (Service Hunter):** A dúsított `specifications` adatok (olaj, gyertya) alapján szervizajánlatok generálása.
+
+## 13.2 Technikai Adósság (Tech Debt)
+- **JSONB Migráció:** A `JSON` típusú mezők (synonyms, specifications) átállítása `JSONB`-re a gyorsabb szűrés és indexelés érdekében.
+- **N/A Kódok Tisztítása:** Manuális felülvizsgálati felület kialakítása a robot által generált `N/A-{id}` kódok valódi gyári kódokra cseréléséhez.
+- **AI Regex Parsing:** Amint a Gemini API engedi a Search + Controlled JSON használatát, a törékeny Regex tisztítást natív megoldásra kell cserélni.
+
+## 13.3 Tesztelési Protokoll és Telepítés
+- **Automatizált tesztek:** Minden új végpontnál kötelező a Pydantic sémák validációja és az aszinkron adatbázis-kapcsolat ellenőrzése.
+- **CI/CD:** A Docker Compose V2 használata kötelező a ContainerConfig hibák elkerülésére.
+
+## 13.4 Ismert Buktatók (Developer Pitfalls)
+A fejlesztés során azonosított, kerülendő megoldások:
+- **Postgres Enum:** A `userrole` típus kisbetűérzékeny. A Python kódból érkező értékeket (pl. `User`) kényszerítve kisbetűvel kell rögzíteni.
+- **SQLAlchemy Async:** Körkörös importok elkerülése érdekében a modellek közötti kapcsolatokat (relationship) string-alapú hivatkozással kell definiálni.
+- **Database URL:** Alembic migrációkor ellenőrizni kell, hogy az `.env` fájl beolvasása sikeres volt-e, különben "Empty database URL" hiba lép fel.

docs/V02/19_Permissions_Tiers_Branches_2.0.md

@@ -0,0 +1,54 @@
+# 19. Permissions, User Tiers & Branch Hierarchy (v2.0)
+
+Ez a dokumentum a jogosultsági szinteket, a bizalmi rangsorolást és a telephelyek földrajzi-adminisztratív hiearchiáját rögzíti.
+
+## 19.1 Felhasználói Rangok és Előfizetési Tiers
+A rendszer megkülönbözteti a technikai előfizetést (User) és a közösségi megbízhatóságot (Person).
+
+- **Trust Tiers:** - **Tier 1 (Lite):** Csak email verifikált. Korlátozott hozzáférés.
+    - **Tier 2 (Active):** KYC (személyazonosítás) befejezve. Teljes Marketplace hozzáférés, saját flotta kezelése.
+- **Subscription Plans (User szint):** - **FREE:** Alapszintű költségkövetés, hirdetésekkel.
+    - **PREMIUM:** Reklámmentesség, részletes TCO elemzések, prioritásos szervizkeresés.
+    - **VIP:** Egyedi üzleti funkciók, Sales Agent támogatás.
+
+## 19.2 Hierarchikus RBAC (Role-Based Access Control)
+Az adminisztráció és a látókör (Scope) négy szinten különül el:
+
+| Szint (Scope) | Megnevezés | Hatókör |
+| :--- | :--- | :--- |
+| **L0** | **Global Admin** | A teljes ökoszisztéma, rendszerparaméterek és "Kill-switch". |
+| **L1** | **Country Manager** | Adott ország (ISO kód) összes régiója, pénznemek, adókulcsok. |
+| **L2** | **Regional Admin** | Megyei vagy kerületi szintű felügyelet. |
+| **L3** | **Branch Manager** | Konkrét telephely, szervizpont vagy flottaegység irányítása. |
+
+
+
+## 19.3 Bírói Rendszer és Büntetések (Judge & Penalty)
+A közösség tisztaságát a `GamificationService` által vezérelt "Bíró" modul védi.
+
+- **Penalty Points:** Visszaélés vagy hibás validáció esetén 0-3 szintű büntetőpont adható.
+- **Restriction Levels:** A büntetések automatikusan korlátozzák a funkciókat (pl. nem tölthet fel számlát, nem validálhat másokat).
+- **Multipliers:** A büntetett felhasználók kevesebb XP-t és kreditet kapnak ugyanazért a munkáért (Admin-vezérelt szorzók).
+
+## 19.4 Telephelyek és Földrajzi Hierarchia (Branches)
+A rendszer kezeli a multi-tenant telephelyeket, ahol egy címen több jogi entitás is létezhet [cite: 2026-02-13].
+
+- **Normalizált Címek:** Minden telephely az egységes `data.addresses` táblához kapcsolódik (UUID alapú hivatkozás).
+- **PostGIS Integráció:** Minden telephely rendelkezik pontos GPS koordinátával (Point), amely lehetővé teszi a térképi alapú szűrést.
+- **Sales Assignments:** A cégek (Organizations) és telephelyek üzletkötőkhöz (Sales Agents) rendelhetőek "Hunting" vagy "Farming" jutalék céljából.
+
+## 19.5 Biztonsági Protokoll (Sentinel & Four-Eyes)
+A kiemelt műveleteknél (pl. VIP rang kiosztása, büntetés törlése, kifizetés) a rendszer kényszeríti a "Négy szem elvét": egy Admin kezdeményezi, de egy másik L1+ szintű Adminnak kell jóváhagynia a `ConfirmedAction` modulon keresztül.
+
+## 19.6 Üzletkötői és Hirdetésszervezői Rendszer
+A rendszer támogatja a külső értékesítési partnereket a "Hunting & Farming" jutalékmodell alapján.
+
+- **Sales Agents (Üzletkötők):** A `persons` és `users` tábla kapcsolatán keresztül azonosított partnerek, akik szervizeket és cégeket hoznak be a rendszerbe.
+- **Hunting Jutalék:** Egyszeri bónusz egy új szolgáltató vagy céges flotta sikeres regisztrációja és aktiválása után.
+- **Farming Jutalék:** Folyamatos, százalékos bevétel a kezelt partnerek havidíjaiból vagy forgalmából.
+- **Hirdetésszervezés:** Speciális jogosultsági kör a szervizek hirdetéseinek és kiemeléseinek kezelésére.
+
+## 19.7 Rugalmas RBAC Bővíthetőség
+Bár az alaprendszer az L0-L3 hierarchiát követi, a technikai architektúra fel van készítve a jogosultságok dinamikus bővítésére:
+- **Custom Permissions:** A `users` tábla `custom_permissions` (JSONB) mezője lehetővé teszi egyedi engedélyek hozzáadását anélkül, hogy új rangot kellene definiálni.
+- **Bővíthető Szintek:** Az RBAC rendszer úgy lett tervezve, hogy a jövőben új köztes szintek (pl. kistérségi koordinátor) is bevezethetőek legyenek a `scope_level` skálázásával.

docs/V02/22_Robot_Ecosystem.md

@@ -0,0 +1,33 @@
+# 22. Robot Ökoszisztéma & AI Intelligence (v2.0)
+
+Ez a dokumentum az autonóm ágensek technikai specifikációját és koordinációját tartalmazza.
+
+## 22.1 Robot 1: Catalog Scout (The Discovery)
+- **Feladat:** Új járműmodellek importálása külső forrásokból (RDW, NHTSA).
+- **Működés:** `unverified` státuszú alaprekordokat hoz létre. Ha a forrás blokkol (Ban-Detection), a robot automatikusan "Silent Mode"-ba vált.
+
+## 22.2 Robot 2: Technical Enricher (The Detective v1.2.6)
+A legfejlettebb modul, amely a nyers adatokat master-adatokká dúsítja.
+
+### AI Search RAG (Retrieval-Augmented Generation):
+- Mivel a Google Search tool használatakor a Gemini letiltja a kényszerített JSON formátumot, a robot **Regex-alapú JSON bányászatot** alkalmaz a nyers válaszból.
+- **Cél:** Modellkódok, évjáratok és szervizintervallumok kinyerése közvetlenül az internetről.
+
+### Safe-Merge & Not-Null védelem:
+- **Fallback Kódok:** Ha az AI nem talál kódot, a robot `N/A-{id}` vagy `UNKNOWN-{id}` ál-kódokat generál az SQL kényszerek (Unique, Not-Null) betartása érdekében.
+- **Deduplikáció:** Csak akkor von össze rekordokat, ha a technikai kód ÉS a hengerűrtartalom (CCM) is megegyezik.
+
+## 22.3 Robot 3: OCR & Multimodal Document AI
+- **Feladat:** Számlák, forgalmik és kilométerórák elemzése.
+- **Integráció:** A felismerés során kinyert szervizadatokat keresztellenőrzi a `data.organizations` táblával. Ha ellentmondást talál, a szervizt `flagged` státuszba teszi.
+
+## 22.4 Robot 4: Service Hunter (Tervezett)
+- **Cél:** A dúsított technikai adatok alapján szerviz-csomagok és árak automatizált keresése.
+- **Működés:** A `specifications` mezőben tárolt folyadékmennyiségek és alkatrész-típusok alapján generál ajánlat-tervezeteket.
+
+## 22.5 Robot Koordináció (Orchestration)
+A robotok az adatbázist használják "jelzőtáblának", elkerülve az ütközéseket:
+1. **R1** rögzíti az alapot.
+2. **R2** dúsít és validál.
+3. **R3** (OCR) bizonyítékokat csatol a jármű életútjához.
+4. Minden művelet a `ProcessLog` táblában kerül rögzítésre az auditálhatóság érdekében.