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

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