service-finder/docs/v02/10_Billing_Credits_Subscriptions_MLM.md

10. Billing, Credits, Subscriptions és MLM Referral System

Áttekintés

A Masterbook 2.0 "Triple Wallet" rendszerének kiterjesztése MLM (Multi-Level Marketing) referenciális jutalékokkal és P2P Gamification XP pontokkal. A rendszer lehetővé teszi a felhasználók számára, hogy meghívásos hálózatot építsenek, és jutalékot kapjanak a meghívottak előfizetési befizetéseiből.

MLM Paraméterek (SSoT)

A system_parameters táblában tárolt globális beállítások:

Kulcs	Érték	Leírás
mlm_level1_percent	10	L1 (közvetlen meghívó) jutalék százalék
mlm_level2_percent	5	L2 (második szint) jutalék százalék
mlm_level3_percent	3	L3 (harmadik szint) jutalék százalék
gamification_p2p_invite_xp	50	XP pontok a meghívónak sikeres KYC után

Adatmodell

User Modell kiterjesztések

• referral_code (String, unique): 8 karakteres egyedi kód (pl. "ABC123DE")
• referred_by_id (Integer, ForeignKey): A meghívó User ID-ja (L1)

UserLiteRegister séma

class UserLiteRegister(BaseModel):
    # ... meglévő mezők
    referred_by_code: Optional[str] = None  # Meghívó referral kódja

Regisztrációs folyamat

1. Lite Regisztráció (register_lite)

1. Ha a referred_by_code meg van adva, a rendszer felkutatja a hozzá tartozó Usert
2. Az új User referred_by_id mezőjét a megtalált ID-ra állítja
3. Generál egy egyedi referral_code-ot az új User számára
4. Mentés az adatbázisba

2. KYC Befejezése (complete_kyc)

1. Sikeres KYC után a User kap gamification_kyc_bonus XP-t
2. Ha a Usernek van referred_by_id-ja, a meghívó (L1) kap gamification_p2p_invite_xp XP-t ("P2P_REFERRAL_SUCCESS")

MLM Hálózat API

Végpont: GET /me/network

Visszaadja a felhasználó MLM hálózatát 3 szinten:

Válasz struktúra

{
  "level1": [
    {
      "email": "user1@example.com",
      "referral_code": "ABC123DE",
      "folder_slug": "user1-slug",
      "joined_at": "2026-04-01T10:30:00Z"
    }
  ],
  "level2": [
    {
      "referral_code": "DEF456GH",
      "joined_at": "2026-04-01T11:30:00Z"
    }
  ],
  "level3": [
    {
      "referral_code": "GHI789JK",
      "joined_at": "2026-04-01T12:30:00Z"
    }
  ]
}

Adatvédelmi szabályok

• L1: Teljes információk (email, kód, slug) - közvetlen meghívottak
• L2/L3: Csak referral kód és csatlakozás dátuma - személyes adatok védelme érdekében

CREDIT Wallet Payout Engine

Fizetési esemény feldolgozása

Amikor egy User fizetést hajt végre (pl. előfizetés, szolgáltatás vásárlás):

1. Lánc felépítése: A fizető User referred_by_id mentén max 3 szint mélységig
2. Jutalék számítás:
   • L1: fizetés_összege × mlm_level1_percent / 100
   • L2: fizetés_összege × mlm_level2_percent / 100
   • L3: fizetés_összege × mlm_level3_percent / 100
3. CREDIT Wallet jóváírás:
   • Tranzakció típus: MLM_CREDIT
   • Wallet típus: CREDIT
   • Ledger bejegyzés a finance.ledger táblában

Példa: 10,000 HUF fizetés

• L1 (10%): 1,000 HUF → CREDIT Wallet
• L2 (5%): 500 HUF → CREDIT Wallet
• L3 (3%): 300 HUF → CREDIT Wallet

Admin Kontroll

Paraméterek módosítása

Az Admin felületen keresztül módosíthatók a százalékok és XP értékek:

• /admin/system-parameters végpont
• Dinamikus frissítés - nincs újraindítás szükséges

Naplózás

• Minden MLM tranzakció naplózva a finance.ledger táblában
• Gamification XP tranzakciók naplózva a gamification.point_transactions táblában
• Audit trail a audit.security_events táblában

Tesztelés

E2E Teszt Script

/app/app/scripts/test_mlm_payout_simple.py:

1. MLM paraméterek ellenőrzése
2. Teszt userek létrehozása (L1 → L2 → L3 → L4 fizető)
3. Szimulált fizetés (10,000 HUF)
4. Jutalékok számításának ellenőrzése
5. CREDIT Wallet egyenlegek validálása

Futtatás

docker compose exec sf_api python3 /app/app/scripts/test_mlm_payout_simple.py

Integráció a meglévő rendszerrel

Billing Engine

A meglévő billing_engine.py kiterjesztése MLM payout logikával:

• Payment Success esemény → MLM payout trigger
• Async feldolgozás háttérben

Gamification Service

• P2P_REFERRAL_SUCCESS XP jóváírás
• Social Point (XP) növelése a meghívónak

Frontend

• Referral kód megjelenítése a profilban
• MLM hálózat megtekintése (/me/network)
• CREDIT Wallet egyenleg mutatása

Biztonsági megfontolások

1. Lánc korlát: Maximum 3 szint (L1, L2, L3)
2. Ciklus védelem: Ellenőrzés, hogy a lánc ne tartalmazza a fizetőt
3. Dupla jutalék védelem: Egy fizetésből csak egyszer kaphat jutalékot egy User
4. Adatvédelem: L2/L3 szinteken csak anonymizált adatok

Jövőbeli fejlesztések

1. Dynamic MLM Levels: Admin által konfigurálható szintek száma
2. Tiered Percentages: Szinttől függő változó százalékok
3. Performance Analytics: MLM hálózat teljesítmény metrikák
4. Automated Payout Reports: Havi/havi jutalék kimutatások