service-finder/old_maps/plans/logic_spec_mlm_network.md

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.