# 🔐 05_AUTH_AND_IDENTITY_SPEC (v1.3)

## 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.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**).

### 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 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.

### 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.

---

## 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 (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. |

---

## 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.

## 4. Multi-Account & Identity Linking
A felhasználók több e-mail címet is csatolhatnak egyetlen profilhoz, hogy könnyen válthassanak a magánszemély és a céges flotta-menedzser szerepkörök között.

### 4.1 Szabályrendszer
* **Limit:** Egy felhasználói profilhoz maximum **3** másodlagos e-mail cím csatolható.
* **Elsődleges cím:** Ez a belépési azonosító és a hivatalos értesítési cím.
* **Context Switching:** A felhasználó a fejlécben válthat a "Személyes" és a "Céges" nézetek között (pl. Flotta Manager mód).

### 4.2 Account Linking Folyamat
1. User belép az elsődleges fiókba.
2. `Settings -> Linked Accounts -> Add New`.
3. Rendszer küld egy megerősítő linket az új címre.
4. Ha a linkre kattint, az új cím hozzáadódik a `user_identities` táblához.
5. Ha az új címen már volt regisztráció: A rendszer felajánlja az **Account Merge** (Fiókegyesítés) lehetőségét (biztonsági kérdések után).

```markdown
# 05. Authentication & Identity Specification

## 5.2. Data Models (Identity)

### 5.2.1. User Entity (`data.users`)
A technikai belépési pont.
- **id**: Integer (PK)
- **email**: String (Unique)
- **hashed_password**: String (Bcrypt)
- **role**: Enum (superadmin, admin, user, service, driver)
- **person_id**: FK -> `data.persons.id` (A TWINS kapcsolat)
- **preferred_language**: String (Default: 'hu') [ÚJ v1.2.5]
- **region_code**: String (Default: 'HU') [ÚJ v1.2.5]
- **is_active**: Boolean

### 5.2.2. TWINS Concept Update
- A `User` (User) és `Person` (Shadow Identity) szétválasztása szigorú.
- Belépéskor a rendszer a `User` táblából olvassa ki a `preferred_language` és `region_code` beállításokat, és ezeket a Token válaszban visszaadja a Frontendnek.

## 1.3 Shadow Identity & Merging Logic
A rendszer támogatja a "Ghost Person" (Árnyék személy) entitásokat.
- **Ghost Person:** Olyan `data.persons` rekord, amelyet a Robot 2 hozott létre nyilvános adatok (pl. cégjegyzék) alapján.
- **Identity Linkage:** Regisztrációkor a `AuthService.complete_kyc` kötelezően ellenőrzi a meglévő Ghost rekordokat (Adószám/Név egyezés).
- **Merge Action:** Találat esetén a rendszer összefűzi a technikai User fiókot a Ghost Person rekorddal, aktiválja a jogosultságokat, és megszünteti a Ghost státuszt.

## 2. The Dual Entity Model (Person vs. User)

A rendszer alapja a természetes személy (**Person**) és a felhasználói fiók (**User**) szigorú szétválasztása az adatbiztonság és az üzleti folytonosság érdekében.

### 2.1 Person (A DNS - "Az Örök Személy")
A `persons` tábla rekordja soha nem törlődik teljesen (GDPR esetén anonimizálódik), így biztosítva a rendszer memóriáját.
* **Identity Hash:** Egyedi SHA256 lenyomat (`normalized(name + mother + birth_place + birth_date)`), amely megakadályozza a multi-account visszaéléseket és felismeri a visszatérő felhasználókat.
* **Örök Adatok:**
    * `lifetime_xp`: A valaha szerzett összes tapasztalati pont.
    * `penalty_points`: A büntetési szint (0-3). Ez nem nullázódik új regisztrációval!
    * `social_reputation`: A közösségi megbízhatósági index (1.00 = 100%).
    * `is_sales_agent`: Jogosult-e jutalékra.

### 2.2 User (A Kulcs - "A Munkamenet")
A `users` tábla a belépési pont. Törölhető, eldobható, újraregisztrálható.
* **Kapcsolat:** Minden User egyetlen Person-höz tartozik (`person_id`).
* **Időkorlátos Jogok:**
    * `subscription_plan`: FREE / PREMIUM / VIP.
    * `subscription_expires_at`: A prémium funkciók lejárata.
* **Sales Kapcsolat:**
    * `referral_code`: Saját meghívó kód.
    * `current_sales_agent_id`: Ki kapja a "Farming" jutalékot ez után a felhasználó után.

### 2.3 Jogosultsági Szintek (Scope-Based RBAC)
A jogosultság nem csak szerepkör (Role), hanem hatókör (Scope) alapú:
1.  **Global:** Superadmin.
2.  **Country:** Országos Admin (pl. HU).
3.  **Region:** Régiós Admin (pl. Pest megye).
4.  **Entity:** Szerviz Tulajdonos (saját cég).
5.  **Individual:** Átlagfelhasználó (saját adatok).