🏁 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:

Person létrehozása: Identitás rögzítése JSONB dokumentumtárral a data.persons táblába.
Wallet inicializálás: Pénztárca nyitása 0 Coin és 0 XP egyenleggel.
Privát Flotta (Private Org): Automatikus szervezet létrehozása (OrgType.INDIVIDUAL), amely nem átruházható (is_transferable = False).
Aktiválás: is_active = True státusz beállítása és teljes hozzáférés biztosítása.
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.

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.

5.2 KiB Raw Blame History