152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
# 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
|