# 🏁 07_REGISTRATION_INVITATION_AND_API (v1.4)

## 1. Kétlépcsős Onboarding Folyamat
A rendszer a felhasználói élmény (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt, amelyet egy atomi tranzakció zár le.

### 1.1. Fázis: "Lite" Regisztráció (Step 1)
* **Végpont:** `POST /api/v1/auth/register`
* **Cél:** Gyors belépés és a technikai User fiók létrehozása.
* **Kötelező adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
* **Rendszeresemények:**
    * Létrejön a `data.users` rekord `is_active = False` állapottal.
    * **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum kényszer).
    * **Megerősítés:** Aktiváló email küldése egyedi hash kóddal.
    * **Válasz:** JWT token `status: pending_kyc` flaggel (korlátozott jogosultság).

### 1.2. Fázis: Banki KYC & Adatgyűjtés (Step 2)
* **Végpont:** `POST /api/v1/auth/complete-kyc`
* **Kötelező KYC adatok (Identity Verification):**
    * **Személyes:** Anyja születési neve, születési hely és 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élyek (ha releváns).

### 1.3. Fázis: Atomi Tranzakció (Finalization)
A KYC adatok beküldésekor a rendszer egyetlen megszakíthatatlan folyamatban hajtja végre:
1.  **Person létrehozása:** Identitás rögzítése JSONB dokumentumtárral a `data.persons` táblába.
2.  **Wallet inicializálás:** Pénztárca nyitása 0 Coin és 0 XP egyenleggel.
3.  **Privát Flotta (Private Org):** Automatikus szervezet létrehozása (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`).
4.  **Aktiválás:** `is_active = True` státusz beállítása és teljes hozzáférés biztosítása.
5.  **Audit:** Bejegyzés az `audit_logs` táblába.

---

## 2. Meghívó és Jutalék Logika (Invitation Engine)
A rendszer támogatja a többszintű ajánlói rendszert és a szervezeti meghívókat.

### 2.1. Meghívó Típusok
-   **`REG_ONLY`**: Általános meghívó, amely beköti az új felhasználót a 10-5-2%-os jutalék láncba.
-   **`COMPANY_JOIN`**: Meghatározott szervezetbe hív (pl. CEO, Flotta Manager vagy Sofőr szerepkörbe).

### 2.2. Jutalék Számítás
A százalékos mérték a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot). A jóváírandó kredit ($C$):

$$C = P_{amount} \cdot \frac{R_{level}}{100}$$

*Ahol $P$ a befizetett összeg, $R$ pedig az aktuális szint (10, 5 vagy 2) értéke.*
**Szabály:** Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a láncban.

---

## 3. Technikai és Biztonsági Szabályok
### 3.1. Adatbázis és Enum Kezelés
-   **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden értéket (pl. `user`, `admin`, `driver`, `service`) szigorúan **kisbetűvel** kell rögzíteni.
-   **Dinamikus Paraméterek:** Tilos a hardcoded értékek használata. Az alábbiakat a `data.system_settings` táblából kell lekérni:
    -   `auth.reward_days`: Regisztrációs prémium hossza (default: 14).
    -   `referral.level1-3`: Jutalék szintek mértéke.

### 3.2. Email Manager Protokoll (TypeError Fix)
-   **Szabály:** A `send_email` hívásakor **tilos** a `subject` paraméter kézi átadása. 
-   **Logika:** A szerviz a `template_key` alapján automatikusan generálja a tárgyat a belső szótárából.

### 3.3. Social Auth (Google / Facebook)
-   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, korlátozott funkciókkal.

---

## 4. Jelszó Helyreállítási Protokoll (Recovery)
A rendszer két biztonsági szintet különít el:

| Szint | Megnevezés | Logika |
| :--- | :--- | :--- |
| **A** | Standard | Email alapú visszaállítás ideiglenes tokennel. |
| **B** | Szigorú (Banki) | Kötelező: Név, Anyja neve, Okmány szám. Ellenőrzés után SMS (telefonszám) vagy Email link. |

---

## 5. Corporate Onboarding (Céges Regisztráció)
Célja, hogy egy létező Person saját szervezetet (Organization) alapítson.
-   **Validáció:** Kötelező adószám ellenőrzés (HU formátum + VIES API lekérdezés).
-   **Hierarchia:** A regisztráló automatikusan `owner` rangot kap.
-   **Izoláció:** Minden cég saját mappastruktúrát kap a NAS-on az okmányok fizikai elkülönítése érdekében.

---

## 6. Kormányozhatóság és .env Konfiguráció
A biztonsági paraméterek környezeti változókon keresztül szabályozhatók:

| Paraméter | Leírás | Alapértelmezett |
| :--- | :--- | :--- |
| `REGISTRATION_TOKEN_EXPIRE_HOURS` | Aktiválásra álló idő | 48 óra |
| `PASSWORD_RESET_TOKEN_EXPIRE_HOURS` | Visszaállítási időablak | 1 óra |

---

## 7. API Végpontok (Baseline v1)
-   `POST /api/v1/auth/register`: Komplett onboarding indítása.
-   `POST /api/v1/auth/complete-kyc`: KYC adatok beküldése és aktiválás.
-   `POST /api/v1/auth/invite/send`: Meghívó generálása.
-   `GET /api/v1/auth/invite/verify/{token}`: Token validálása.
-   `POST /api/v1/auth/recover-identity`: Szigorú (KYC alapú) helyreállítás.