FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic

docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md

@@ -1,103 +1,94 @@
-# 🔐 AUTHENTICATION & IDENTITY SPECIFICATION (v1.2)
+# 🔐 05_AUTH_AND_IDENTITY_SPEC (v1.3)
 
-## I. AZONOSÍTÁSI STRATÉGIA
-A rendszer szétválasztja a **technikai hozzáférést** (User) és a **valós identitást** (Person).
+## 1. Azonosítási Stratégia
+A rendszer alapelve a **technikai hozzáférés** (User) és a **valós identitás** (Person) szigorú szétválasztása.
 
-### 1. Identitás szintek
-- **User (Login):** Email + Jelszó. Csak a belépéshez és a munkamenethez kell.
-- **Person (Identity):** Vezetéknév, Keresztnév, Anyja neve, Születési adatok, Okmányok.
-- **Azonosító:** Minden Person kap egy globális egyedi azonosítót (UUID).
+### 1.1. Identitás szintek
+- **User (Login):** Email + Jelszó. Kizárólag a belépéshez és a munkamenet (session) kezeléséhez szükséges technikai entitás.
+- **Person (Identity):** A valós személy adatai (Név, anyja neve, születési adatok, okmányok). Minden Person kap egy globális egyedi azonosítót (**UUID**).
 
-### 2. Soft Delete & Re-regisztráció
-- **Nincs fizikai törlés:** A felhasználó csak egy `is_hidden` vagy `deleted_at` flag-et kap.
-- **Ismételt regisztráció:** Ha az email/név/okmány alapján a rendszer felismeri a visszatérőt:
-    - Új technikai User fiók jön létre.
-    - Ez az új fiók a korábbi Person ID-hoz kapcsolódik.
-    - **Adat-izoláció:** A felhasználó csak az új regisztráció dátuma utáni eseményeket látja. A régi adatok a háttérben maradnak (statisztika, sofőr elemzés), de számára rejtettek.
-
-## II. BŐVÍTETT ADATTÁR (KYC & SAFETY)
-A `persons` tábla az alábbi adatcsoportokat tartalmazza (Progresszív feltöltéssel):
-- **Alapadatok:** `last_name`, `first_name`, `birth_place`, `birth_date`, `mothers_name`.
-- **Hivatalos okmányok:** Személyi ig. szám, Jogosítvány (szám + kategóriák + érvényesség), Lakcímkártya, TAJ, Adóazonosító.
-- **Vészhelyzeti adatok (Safety):** Vércsoport, Allergia, Értesítendő személy (ICE) neve és telefonszáma.
-- **Jutalom:** A teljes körű adategyeztetésért 2 hét PRÉMIUM tagság jár.
-
-## III. JUTALÉK ÉS GAZDASÁG
-### 1. Piramis rendszer (3 szint)
-Meghívó lánc alapján számolt jóváírás:
-- **1. szint (Közvetlen):** 10%
-- **2. szint:** 5%
-- **3. szint:** 2%
-*A százalékok a befizetés pillanatában érvényes admin beállítások alapján rögzülnek a tranzakcióban (Snapshot).*
-
-### 2. Wallets
-Minden regisztrációnál létrejön:
-- **Coin Wallet:** Belső fizetőeszköz (Kredit).
-- **XP Ledger:** Tapasztalati pontok (Verseny és rangsor).
-
-## IV. MODERÁCIÓ ÉS VALIDÁLÁS
-- **Validált vélemény:** Csak igazolt ott-tartózkodás (GPS) vagy számlafotó után adható.
-- **Fellebbezés:** A szerviz kérheti a vélemény felülvizsgálatát, amit a Moderátorok/Validátorok bírálnak el.
-
-## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ
-1. **Verifikációs szintek:**
-   - **Unverified (Nem ellenőrzött):** Kézi rögzítés utáni alapállapot. 30 napos türelmi idő.
-   - **Verified (Hitelesített):** Sikeres VIES vagy nemzeti cégnyilvántartó lekérdezés után.
-   - **Suspended (Felfüggesztett):** Ha az automatikus időszakos ellenőrzés során a cég "megszűnt" vagy "inaktív" státuszt kap.
-
-2. **Ellenőrzési logika:**
-   - Elsődleges: **VIES API** (EU-s adószám ellenőrző).
-   - Másodlagos: Nemzeti cégkeresők (robotizált lekérdezés).
-   - Kivételkezelés: Ha a robot nem tud dönteni, a feladat az **Admin/Moderátor** várólistájára kerül.
-
-   ## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ (v1.2)
-
-1. **Verifikációs Státuszok:**
-   - **Unverified (Nem ellenőrzött):** Alapértelmezett állapot kézi rögzítés után. 30 napos türelmi időt biztosít a teljes körű használathoz.
-   - **Verified (Hitelesített):** Automatikus VIES lekérdezés vagy adminisztrátori jóváhagyás utáni állapot.
-   - **Suspended (Felfüggesztett):** Megszűnt cégek vagy le nem igazolt adatok esetén az időszakos (havi) ellenőrzés során.
-
-2. **Ellenőrzési Logika (Robot & Admin):**
-   - **Robot:** A rendszer a `VAT_NUMBER` rögzítésekor azonnal meghívja az EU-s VIES API-t. Egyezőség esetén a státusz azonnal `Verified`.
-   - **Adminisztrátor:** Ha az API nem ad eredményt (pl. friss bejegyzés vagy technikai hiba), az Adminisztrátor kézzel állíthatja át a státuszt a feltöltött dokumentumok alapján.
-   - **Időszakos ellenőrzés:** Egy ütemezett feladat 30 naponta újraellenőrzi a `Verified` cégeket. Ha egy cég megszűntnek tűnik, a rendszer `Suspended` státuszba teszi és értesíti a tulajdonost.
-
-3. **Korlátozások (Suspended/Unverified):**
-   - Nem rögzíthető új jármű a flottába.
-   - Nem generálható meghívó (Invite Token).
-   - Statisztikai kimutatások korlátozása.
-
-   ## I. AZONOSÍTÁSI STRATÉGIA (v1.3)
-...
-### 3. Social Auth (Google / Facebook)
+### 1.2. Social Auth (Google / Facebook)
 - **Működés:** Engedélyezett a gyors belépéshez.
-- **Kényszerített KYC:** Social Auth esetén a 2. lépésben kötelező a KYC adatok (anyja neve, születési adatok) pótlása.
+- **Kényszerített KYC:** Social Auth esetén a 2. lépésben kötelező a KYC adatok pótlása.
 - **Korlátozás:** Amíg a KYC adatok hiányoznak, a felhasználó "Free User" marad, és nem fér hozzá a regisztrációkor járó extra prémium szolgáltatásokhoz.
 
-## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ
-...
-- **Hibrid Validálás:** Ha a VIES API nem ad eredményt, a rendszer céges dokumentum feltöltését kéri.
-- **Ellenőrzés:** Adminisztrátori jóváhagyás vagy AI-alapú dokumentum-validálás után válik `Verified` státuszúvá.
+### 1.3. Soft Delete & Re-regisztráció
+- **Nincs fizikai törlés:** A felhasználó törléskor `is_hidden` vagy `deleted_at` flag-et kap.
+- **Ismételt regisztráció:** Ha az email/név/okmány alapján a rendszer felismeri a visszatérőt:
+    - Új technikai User fiók jön létre, de a korábbi **Person ID**-hoz kapcsolódik.
+    - **Adat-izoláció:** A felhasználó csak az új regisztráció utáni eseményeket látja, a régi adatok (statisztika, elemzés) csak a háttérben maradnak meg.
 
-# 🆔 Identitás Validációs és Bizalmi Protokoll
+---
 
-A rendszer a fokozatos adatszolgáltatás és a "Tier-based Access Control" (szintezett hozzáférés) elvét alkalmazza.
-
-## 1. Bizalmi Szintek (Trust Tiers)
+## 2. Bizalmi Szintek (Trust Tiers)
+A rendszer a "Tier-based Access Control" (szintezett hozzáférés) elvét alkalmazza az adatszolgáltatás mértékétől függően.
 
 | Szint | Megnevezés | Követelmény | Jogosultságok |
 | :--- | :--- | :--- | :--- |
 | **Tier 0** | Anonymous | Nincs | Csak publikus adatok megtekintése. |
-| **Tier 1** | Verified Email | Step 1 sikeres | Belépés, saját profil megtekintése. |
+| **Tier 1** | Verified Email | Step 1 (Regisztráció) sikeres | Belépés, saját profil megtekintése. |
 | **Tier 2** | KYC Submitted | Step 2 (Személyi adatok + Telefon) | **Privát Széf/Flotta aktiválása**, Wallet használat. |
 | **Tier 3** | AI/OCR Verified | Okmánykép AI általi ellenőrzése | Harmadik fél szolgáltatásainak igénybevétele. |
 
-## 2. Kötelező Adatkör (Step 2 - Tier 2)
-A "Privát Széf" aktiválásához az alábbi adatok megadása kötelező:
-- **Kapcsolat:** Valós telefonszám (nemzetközi formátum).
-- **Személyi:** Születési hely, idő, anyja neve.
-- **Okmány:** Típus, sorszám és **lejárati dátum**.
-- **Biztonság:** ICE (In Case of Emergency) név és telefonszám.
+---
 
-## 3. Adattárolási Stratégia
-- A rugalmas okmányadatokat és vészhelyzeti kapcsolatokat a `persons.identity_docs` és `persons.ice_contact` JSONB mezőkben tároljuk a kereshetőség és bővíthetőség érdekében.
+## 3. KYC és Bővített Adattár (Safety)
+A `persons` tábla progresszív feltöltéssel tárolja az adatokat a "Minimal Friction" elv mentén.
+
+### 3.1. Kötelező Adatkör (Step 2 - Tier 2)
+A "Privát Széf" aktiválásához az alábbi adatok megadása kötelező:
+- **Alapadatok:** `last_name`, `first_name`, `birth_place`, `birth_date`, `mothers_name`.
+- **Kapcsolat:** Valós telefonszám (nemzetközi formátum).
+- **Hivatalos okmányok:** Személyi ig. szám, Jogosítvány (szám, kategóriák, érvényesség), Lakcímkártya, TAJ, Adóazonosító.
+- **Biztonság (ICE):** "In Case of Emergency" adatok (értesítendő személy neve és telefonszáma).
+- **Vészhelyzeti adatok:** Vércsoport, Allergia.
+
+### 3.2. Jutalom Trigger
+A teljes körű adategyeztetésért (100%-os profilkitöltöttség) **2 hét PRÉMIUM** tagság jár.
+
+---
+
+## 4. Céges Azonosítás és Verifikáció
+A szervezetek (Companies) hitelesítése és bizalmi szintjeinek kezelése.
+
+### 4.1. Verifikációs Státuszok
+- **Unverified (Nem ellenőrzött):** Kézi rögzítés utáni alapállapot. 30 napos türelmi időt biztosít a funkciókhoz.
+- **Verified (Hitelesített):** Hitelesített állapot (VIES API találat vagy Admin kézi jóváhagyás után).
+- **Suspended (Felfüggesztett):** Megszűnt cég vagy le nem igazolt adatok esetén az időszakos ellenőrzés során.
+
+### 4.2. Ellenőrzési Logika (Robot & Admin)
+1. **Robot:** A `VAT_NUMBER` rögzítésekor a rendszer azonnal meghívja az EU-s **VIES API**-t. Egyezőség esetén azonnal `Verified`.
+2. **Hibrid Validálás:** Ha a VIES API nem ad eredményt, a rendszer céges dokumentum feltöltését kéri.
+3. **Ellenőrzés:** Adminisztrátori jóváhagyás vagy AI-alapú dokumentum-validálás után válik a státusz véglegessé.
+4. **Időszakos ellenőrzés:** Ütemezett feladat (Cron) 30 naponta újraellenőrzi a cégeket. Megszűnés esetén `Suspended` státusz és értesítés.
+
+### 4.3. Korlátozások (Suspended/Unverified)
+- Nem rögzíthető új jármű a flottába.
+- Nem generálható meghívó (Invite Token).
+- Statisztikai kimutatások korlátozása.
+
+---
+
+## 5. Jutalék és Gazdasági Rendszer
+### 5.1. Piramis rendszer (3 szint)
+A meghívó lánc alapján számolt jóváírások (Referral):
+- **1. szint (Közvetlen):** 10%
+- **2. szint:** 5%
+- **3. szint:** 2%
+*Megjegyzés: A százalékok a befizetés pillanatában érvényes admin beállítások alapján rögzülnek (Snapshot technika).*
+
+### 5.2. Wallets
+Minden regisztrációnál automatikusan létrejön:
+- **Coin Wallet:** Belső fizetőeszköz (Kredit).
+- **XP Ledger:** Tapasztalati pontok (Gamification és rangsor).
+
+---
+
+## 6. Moderáció és Validálás
+- **Validált vélemény:** Csak igazolt ott-tartózkodás (GPS log) vagy számlafotó (OCR) feltöltése után adható.
+- **Fellebbezés:** A szervizek kérhetik a vélemények felülvizsgálatát, amit moderátorok bírálnak el.
+
+---
+
+## 7. Adattárolási Stratégia (Technikai)
+- A rugalmas okmányadatokat (`identity_docs`) és a vészhelyzeti kapcsolatokat (`ice_contact`) **JSONB** mezőkben tároljuk a `persons` táblában a kereshetőség és a jövőbeli bővíthetőség érdekében.