service-finder/docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md

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

5. Invitation Logic Specifications

5.1 Meghívó Kódok

• Formátum: Véletlenszerű alfanumerikus string (pl. A8B2X9). NEM tartalmazhat személyes adatot.
• Generálás: Minden "Meghívás" gombnyomásra új, egyedi token generálódik.

5.2 Lejárati Idők (TTL)

A meghívók érvényessége a típustól függ:

• Magánszemély (C2C): 72 óra (3 nap). Sürgető érzést kelt.
• Céges / Flotta (B2B): 168 óra (1 hét). Figyelembe veszi a lassabb céges ügymenetet.

5.3 Biztonság

• A meghívó link tartalmaz egy aláírt JWT tokent, amely rögzíti a target_org_id-t (melyik flottába hívjuk) és a role-t (pl. sofőr).
• A kód felhasználása után a link érvénytelenné válik (One-time use).

1. Háromlépcsős Onboarding (v1.5)

1.1 Step 1: Lite Registration

• Technikai User létrehozása (inaktív). Email ellenőrzés indítása.

1.2 Step 2: Individual Setup (Privát Identitás)

• Cél: A természetes személy (Person) és privát szférájának rögzítése.
• Művelet: - Person rögzítése/frissítése.
  • Privát Organization létrehozása (org_type='individual', is_ownership_transferable=False).
  • Központi Telephely (Main Branch) létrehozása a lakcím alapján.
  • Privát Flotta és Wallet inicializálása.

1.3 Step 3: Business Setup (Céges Identitás)

• Cél: Államilag nyilvántartott gazdasági egység rögzítése.
• Művelet:
  • Adószám bekérése + VIES/Cégjegyzék ellenőrzés.
  • Új, különálló Organization létrehozása (org_type='business', is_ownership_transferable=True).
  • Székhely rögzítése mint Main Branch.
  • Opcionális további telephelyek rögzítése.