2026.06.04 frontend építés közben

old_maps/plans/logic_spec_mlm_network.md

@@ -0,0 +1,30 @@
+# MLM Referral, Gamification és Credit Payout Specifikáció
+
+## Modul célja és Masterbook 2 illeszkedés
+P2P Gamification, MLM Referral System, és Credit Wallet kifizetések bevezetése a Masterbook 2 "Triple Wallet" és "Dual Entity" alapelvei szerint. 
+A cél egy 3-szintű meghívásos hálózat (L1, L2, L3) technikai megvalósítása, XP (Social Point) jóváírása az L1 tagnak a meghívott sikeres KYC folyamata után, valamint előfizetési jutalékok (10%, 5%, 3%) automatikus lekönyvelése a CREDIT tárcába (Financial Ledger).
+
+## Adatmodell: Alembic terv, Twin-technika
+- **auth.py (Schema):** `UserLiteRegister` kiegészül a `referred_by_code: Optional[str]` mezővel.
+- **User Modell (Identity):** A `referral_code` (saját kód, pl. 8 karakteres slug) és `referred_by_id` (a meghívó L1 ID-ja, ForeignKey a `users.id`-ra) alapból adott a "Dual Entity" elvek szerint (ellenőrizni kell az identity sémában, ha hiányzik, Alembic-kel hozzáadni, de vélhetően már létezik vagy felvehető a modellbe).
+- **Gamification Service:** KYC végén a `gamification_p2p_invite_xp` beírása a Social Point (XP) részre.
+- **Financial Ledger:** Payout generálásánál `transaction_type=MLM_CREDIT`, `wallet_type=CREDIT` bejegyzések a `finance.ledger` táblában.
+
+## Admin kontroll: Global/Country/Region/User szintű változók
+Az SSoT (`system_parameters`) táblában a következő globális beállítások szükségesek:
+- `mlm_level1_percent`: 10
+- `mlm_level2_percent`: 5
+- `mlm_level3_percent`: 3
+- `gamification_p2p_invite_xp`: 50
+
+Ezeket egy inicializáló szkript tölti fel, hogy Admin felületről később dinamikusan módosíthatók legyenek.
+
+## Logika: P2P Gamification & Payout
+1. **Regisztráció (`register_lite`):** Ha a kérésben szerepel `referred_by_code`, a rendszer felkutatja az ehhez tartozó Usert, majd az új User `referred_by_id`-ját erre a megtalált ID-ra állítja.
+2. **KYC befejezése (`complete_kyc`):** Ha a frissen KYC-zett Usernek van `referred_by_id`-ja, a Gamification Service 50 XP-t ad a szülőnek ("P2P_REFERRAL_SUCCESS").
+3. **MLM Hálózat Lekérdezés (`GET /me/network`):** 
+   - L1: `referred_by_id == current_user.id` (Visszaadva: email, kód, csatlakozás).
+   - L2: Az L1 tagok által meghívottak (Visszaadva: szigorúan csak a kód és dátum adatvédelmi okokból).
+   - L3: Az L2 tagok által meghívottak (szintén csak kód és dátum).
+4. **CREDIT Payout Engine (Mock tesztelés):** Rekurzív/Iteratív szülő-keresés a `referred_by_id` mentén (max 3 szint mélyen). L1 kap 10%-ot, L2 5%-ot, L3 3%-ot a befizetésből, közvetlenül a CREDIT tárcájába.
+