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

🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)

I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT

Az UX optimalizálása és a banki szintű biztonság érdekében a folyamat két külön fázisra oszlik.

1. Fázis: "Lite" Regisztráció (Step 1)

• Végpont: POST /api/v1/auth/register
• Adatok: Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
• Rendszeresemény:
  • Létrejön a technikai User rekord.
  • Állapot: is_active = False.
  • Szerepkör: Kényszerített kisbetűs user (Postgres Enum fix).
  • Megerősítés: A rendszer kiküld egy aktiváló emailt egy hash kóddal.
  • Válasz: JWT token status: pending_kyc flaggel.

2. Fázis: Banki KYC & Aktiválás (Step 2)

• Végpont: POST /api/v1/auth/complete-kyc (Fejlesztés alatt)
• Kötelező KYC adatok:
  • Anyja születési neve, születési hely/idő.
  • Okmányadatok: Személyi igazolvány és Jogosítvány száma + lejárati idők.
  • Járműkategóriák (pl. A, B, C) és speciális engedélyek (hajó, repülő).
• Finalizálás (Atomi tranzakció):
  1. Person: Identitás rögzítése a JSONB dokumentumtárral.
  2. Wallet: Pénztárca nyitása 0 egyenleggel.
  3. Privát Flotta: Automatikus szervezet létrehozása (is_transferable = False).
  4. Tagság: Felhasználó rögzítése a flotta tulajdonosaként.
  5. Aktiválás: is_active = True és hozzáférés a rendszerhez.

II. TECHNIKAI SZABÁLYOK ÉS FIXEK

• Postgres Enum: Minden szerepkört (role) kisbetűvel kell küldeni az adatbázis felé (user, nem USER).
• Dinamikus Paraméterek: Az auth.reward_days (jutalom napok) és jutalék százalékok a data.system_settings táblából jönnek.
• Audit Trail: Minden regisztrációs fázisról Audit Log készül.

🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4)

I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT

A rendszer a felhasználói élmény optimalizálása (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt.

1. Fázis: "Lite" Regisztráció (Step 1)

• Cél: Gyors belépés és a technikai User fiók létrehozása.
• Kötelező mezők: Email, Jelszó, Vezetéknév, Keresztnév, Régiókód.
• Rendszeresemény:
  • Létrejön a data.users rekord.
  • Állapot: is_active = False.
  • Szerepkör: Kötelezően kisbetűs user (Postgres Enum kényszerítés miatt).
  • Email: A rendszer azonnal kiküld egy ellenőrző emailt egy egyedi hash kóddal/linkkel.
  • Token: Az API egy korlátozott JWT tokent ad vissza, amely csak a Step 2 végpont elérésére jogosít (status: pending_kyc).

2. Fázis: KYC & Aktiválás (Step 2)

• Cél: A valós identitás (Person) rögzítése és a gazdasági egységek inicializálása.
• Kötelező adatok (Identity Verification):
  • Személyes: Anyja születési neve, születési hely, születési 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ély adatai (ha releváns).
• Működés: A felhasználó csak ezen adatok kitöltése és sikeres ellenőrzése után válik teljes jogú taggá.

3. Fázis: Atomi Tranzakció (Finalization)

A KYC adatok beküldésekor a rendszer egyetlen adatbázis-tranzakcióban (Atomic) hajtja végre az alábbiakat:

1. Person létrehozása: A KYC adatok és okmánymásolatok (JSONB) rögzítése.
2. Wallet inicializálás: 0 Coin és 0 XP egyenleggel.
3. Privát Flotta (Private Org): Létrejön a felhasználó saját cége (OrgType.INDIVIDUAL), amely nem átruházható (is_transferable = False).
4. Aktiválás: A User fiók is_active = True állapotba kerül.
5. Audit: Bejegyzés az audit_logs táblába a teljes körű regisztrációról.

II. MEGHÍVÓ ÉS JUTALÉK LOGIKA

• Invite Tokenek:
  • REG_ONLY: Általános meghívó, beköti a felhasználót a 10-5-2% jutalék láncba.
  • COMPANY_JOIN: Meghatározott szervezetbe hív (CEO, Flotta Manager vagy Sofőr szerepkörbe).
• Kredit Jóváírás:
  • Csak az első Prémium csomag befizetésekor történik jutalékfizetés a meghívási láncban.
  • A százalékos mérték (10%, 5% vagy 2%) a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot).

III. TECHNIKAI ÉS BIZTONSÁGI SZABÁLYOK

• Enum Case Sensitivity: A PostgreSQL userrole típusa miatt minden Enum értéket (user, admin, driver, service, fleet_manager) szigorúan kisbetűvel kell kezelni.
• Dinamikus Paraméterezés: Tilos fix értékeket (hardcoded) használni. Az alábbiakat a data.system_settings táblából kell lekérni:
  • auth.reward_days: Regisztrációkor járó prémium napok (alapértelmezett: 14).
  • referral.level1-3: Jutalék szintek mértéke.
• Email Manager: A send_email hívásakor tilos a subject paraméter átadása; a szerviz a template_key alapján automatikusan generálja azt.
• Szigorú Helyreállítás: A banki szintű KYC után a jelszó-visszaállítás kérhető a Person adatok (Anyja neve, Okmány szám) megadásával is.

IV. SOCIAL AUTH (GOOGLE / FACEBOOK)

• Social Auth esetén 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, és nem fér hozzá a flottakezeléshez.

🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.1)

1. Hibakezelési Jegyzet (TypeError fix)

A rendszer korábbi verzióiban az EmailManager hívása paraméter-eltérést okozott.

• Megoldás: A send_email hívásakor tilos a subject paraméter átadása, mivel azt a szerviz a template_key alapján generálja a belső szótárából.

2. Adatbázis Integritás

Az Organization tábla bővült az owner_id mezővel, amely a magánszemély (Individual) flottájának tulajdonosát jelöli.

• Minden regisztrációkor létrejön egy automatikus flotta.
• A flotta típusa: OrgType.INDIVIDUAL.

3. Dinamikus Paraméterek

A regisztrációt követő jutalmak (pl. 14 napos prémium) a data.system_settings táblából kerülnek kiolvasásra. Keresett kulcs: auth.reward_days.

🏁 REGISZTRÁCIÓ, MEGHÍVÓK ÉS API PROTOKOLL (v1.0)

1. Regisztrációs Flow (Atomcsapás-biztos tranzakció)

Minden új regisztráció egyetlen adatbázis-tranzakcióban (Atomic) hajtja végre az alábbiakat:

1. User & Person létrehozása: Alapidentitás rögzítése.
2. Wallet inicializálás: 0 Coin és 0 XP egyenleggel.
3. Privát Flotta (Private Org): Létrejön a felhasználó saját cége, ahol ő a tulajdonos.
4. Meghívó feldolgozása: - Ha Personal Invite: Bekötés a 10-5-2% jutalék láncba.
   • Ha Company Invite: Másodlagos kapcsolat létrehozása a meghívó céghez (Role: Driver/Admin).

2. Meghívó Küldés Logikája (Invitation Engine)

• Generálás: Admin vagy jogosult User generál egy egyedi invite_token-t.
• Típusok:
  • REG_ONLY: Csak a rendszerbe hív.
  • COMPANY_JOIN: Meghatározott cégbe és pozícióba hív.
• Jutalék számítás: 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.

3. API Végpontok (Baseline v1)

• POST /api/v1/auth/register: Komplett onboarding folyamat.
• POST /api/v1/auth/invite/send: Meghívó generálása és küldése.
• GET /api/v1/auth/invite/verify/{token}: Token ellenőrzése regisztráció előtt.

4. Jelszó Helyreállítási Protokoll (Recovery)

A rendszer két szintű helyreállítást biztosít:

A) Standard (Email alapú)

• POST /api/v1/auth/forgot-password -> Email kiküldése ideiglenes tokennel.

B) Szigorú (Banki szintű / KYC alapú)

• Végpont: POST /api/v1/auth/recover-identity

• Kötelező adatok: Vezetéknév, Keresztnév, Anyja neve, Személyi igazolvány száma.

• Logika: 1. A rendszer azonosítja a Person rekordot. 2. Ha sikeres, a rendszer kiküld egy visszaállító linket a Person-höz tartozó elsődleges telefonszámra (SMS) vagy a legutolsó aktív Email címre. 3. Sikeres helyreállítás után a felhasználónak kötelezően jelszót kell cserélnie.

  🛡️ 10. Kormányozhatóság és Biztonsági Beállítások

A rendszer biztonsági paraméterei központilag, a környezeti változókon keresztül szabályozhatók. Ez lehetővé teszi a biztonsági szint gyors módosítását (pl. támadás esetén szigorítás) a kód módosítása nélkül.

10.1. Token Élettartam Szabályok

A .env fájlban (vagy a rendszer beállításaiban) az alábbi paraméterekkel szabályozható a hozzáférés:

Paraméter	Leírás	Alapértelmezett
REGISTRATION_TOKEN_EXPIRE_HOURS	Regisztráció megerősítésére álló idő	48 óra
PASSWORD_RESET_TOKEN_EXPIRE_HOURS	Jelszó visszaállítására álló idő	1 óra

10.2. Ideiglenes .env Konfiguráció (Példa)

# SECURITY SETTINGS
REGISTRATION_TOKEN_EXPIRE_HOURS=48
PASSWORD_RESET_TOKEN_EXPIRE_HOURS=1

# EMAIL SYSTEM
EMAIL_PROVIDER=sendgrid
EMAILS_FROM_EMAIL=info@profibot.hu
EMAILS_FROM_NAME='Profibot Service Finder'
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxx

## 4. Corporate Onboarding (Céges regisztráció)
A folyamat célja, hogy egy már létező Person (vagy új User) saját szervezetet (Organization) alapítson.
- **Többszintű validáció:** Kötelező adószám (VAT/Tax ID) ellenőrzés (HU esetén formátum + VIES API).
- **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 izolált kezelése érdekében.