# 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
```python
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
```json
{
  "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
```bash
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