2026.06.04 frontend építés közben

2026-06-04 07:26:22 +00:00
parent 7adf6cc3e3
commit 59a30ac428
3302 changed files with 24091 additions and 1771 deletions
--- a/docs/v02/10_Billing_Credits_Subscriptions_MLM.md
+++ b/docs/v02/10_Billing_Credits_Subscriptions_MLM.md
@@ -0,0 +1,151 @@
+# 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