Refactor: Auth & Identity System v1.4

- Fix: Resolved SQLAlchemy Mapper error for 'UserVehicle' using string-based relationships.
- Fix: Fixed Postgres Enum case sensitivity issue for 'userrole' (forcing lowercase 'user').
- Fix: Resolved ImportError for 'create_access_token' in security module.
- Feature: Implemented 2-step registration protocol (Lite Register -> KYC Step).
- Data: Added bank-level KYC fields (mother's name, ID/Driver/Boat/Pilot license expiry and categories).
- Business: Applied private fleet isolation (is_transferable=False for individual orgs).
- Docs: Updated Grand Master Book to v1.4 and added Developer Pitfalls guide.

docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md

@@ -1,3 +1,88 @@
+# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)
+
+## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT
+Az UX optimalizálása és a banki szintű biztonság érdekében a folyamat két külön fázisra oszlik.
+
+### 1. Fázis: "Lite" Regisztráció (Step 1)
+* **Végpont:** `POST /api/v1/auth/register`
+* **Adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
+* **Rendszeresemény:**
+    * Létrejön a technikai `User` rekord.
+    * **Állapot:** `is_active = False`.
+    * **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum fix).
+    * **Megerősítés:** A rendszer kiküld egy aktiváló emailt egy hash kóddal.
+    * **Válasz:** JWT token `status: pending_kyc` flaggel.
+
+### 2. Fázis: Banki KYC & Aktiválás (Step 2)
+* **Végpont:** `POST /api/v1/auth/complete-kyc` (Fejlesztés alatt)
+* **Kötelező KYC adatok:**
+    * Anyja születési neve, születési hely/idő.
+    * Okmányadatok: Személyi igazolvány és Jogosítvány száma + lejárati idők.
+    * Járműkategóriák (pl. A, B, C) és speciális engedélyek (hajó, repülő).
+* **Finalizálás (Atomi tranzakció):**
+    1. **Person:** Identitás rögzítése a JSONB dokumentumtárral.
+    2. **Wallet:** Pénztárca nyitása 0 egyenleggel.
+    3. **Privát Flotta:** Automatikus szervezet létrehozása (`is_transferable = False`).
+    4. **Tagság:** Felhasználó rögzítése a flotta tulajdonosaként.
+    5. **Aktiválás:** `is_active = True` és hozzáférés a rendszerhez.
+
+## II. TECHNIKAI SZABÁLYOK ÉS FIXEK
+* **Postgres Enum:** Minden szerepkört (role) kisbetűvel kell küldeni az adatbázis felé (`user`, nem `USER`).
+* **Dinamikus Paraméterek:** Az `auth.reward_days` (jutalom napok) és jutalék százalékok a `data.system_settings` táblából jönnek.
+* **Audit Trail:** Minden regisztrációs fázisról Audit Log készül.
+
+# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)
+
+## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT
+A rendszer a felhasználói élmény optimalizálása (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt.
+
+### 1. Fázis: "Lite" Regisztráció (Step 1)
+* **Cél:** Gyors belépés és a technikai User fiók létrehozása.
+* **Kötelező mezők:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
+* **Rendszeresemény:**
+    * Létrejön a `data.users` rekord.
+    * **Állapot:** `is_active = False`.
+    * **Szerepkör:** Kötelezően kisbetűs `user` (Postgres Enum kényszerítés miatt).
+    * **Email:** A rendszer azonnal kiküld egy ellenőrző emailt egy egyedi hash kóddal/linkkel.
+    * **Token:** Az API egy korlátozott JWT tokent ad vissza, amely csak a Step 2 végpont elérésére jogosít (`status: pending_kyc`).
+
+### 2. Fázis: KYC & Aktiválás (Step 2)
+* **Cél:** A valós identitás (Person) rögzítése és a gazdasági egységek inicializálása.
+* **Kötelező adatok (Identity Verification):**
+    * **Személyes:** Anyja születési neve, születési hely, születési idő.
+    * **Okmányok:** Személyi igazolvány száma és lejárati ideje.
+    * **Jogosítvány:** Vezetői engedély száma, lejárata és kategóriák (pl. AM, A, B, C, CE).
+    * **Speciális:** Hajóvezetői és repülőgép-vezetői engedély adatai (ha releváns).
+* **Működés:** A felhasználó csak ezen adatok kitöltése és sikeres ellenőrzése után válik teljes jogú taggá.
+
+### 3. Fázis: Atomi Tranzakció (Finalization)
+A KYC adatok beküldésekor a rendszer egyetlen adatbázis-tranzakcióban (`Atomic`) hajtja végre az alábbiakat:
+1.  **Person létrehozása:** A KYC adatok és okmánymásolatok (JSONB) rögzítése.
+2.  **Wallet inicializálás:** 0 Coin és 0 XP egyenleggel.
+3.  **Privát Flotta (Private Org):** Létrejön a felhasználó saját cége (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`).
+4.  **Aktiválás:** A User fiók `is_active = True` állapotba kerül.
+5.  **Audit:** Bejegyzés az `audit_logs` táblába a teljes körű regisztrációról.
+
+## II. MEGHÍVÓ ÉS JUTALÉK LOGIKA
+* **Invite Tokenek:**
+    * `REG_ONLY`: Általános meghívó, beköti a felhasználót a 10-5-2% jutalék láncba.
+    * `COMPANY_JOIN`: Meghatározott szervezetbe hív (CEO, Flotta Manager vagy Sofőr szerepkörbe).
+* **Kredit Jóváírás:**
+    * Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a meghívási láncban.
+    * A százalékos mérték (10%, 5% vagy 2%) a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot).
+
+## III. TECHNIKAI ÉS BIZTONSÁGI SZABÁLYOK
+* **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden Enum értéket (user, admin, driver, service, fleet_manager) szigorúan **kisbetűvel** kell kezelni.
+* **Dinamikus Paraméterezés:** Tilos fix értékeket (hardcoded) használni. Az alábbiakat a `data.system_settings` táblából kell lekérni:
+    * `auth.reward_days`: Regisztrációkor járó prémium napok (alapértelmezett: 14).
+    * `referral.level1-3`: Jutalék szintek mértéke.
+* **Email Manager:** A `send_email` hívásakor tilos a `subject` paraméter átadása; a szerviz a `template_key` alapján automatikusan generálja azt.
+* **Szigorú Helyreállítás:** A banki szintű KYC után a jelszó-visszaállítás kérhető a Person adatok (Anyja neve, Okmány szám) megadásával is.
+
+## IV. SOCIAL AUTH (GOOGLE / FACEBOOK)
+* Social Auth esetén a Step 1 lerövidül, de a **Step 2 (KYC) kötelező** marad az aktiváláshoz.
+* Amíg a KYC hiányzik, a felhasználó "GUEST" státuszban marad, és nem fér hozzá a flottakezeléshez.
+
 # 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.1)
 
 ## 1. Hibakezelési Jegyzet (TypeError fix)