service-finder/docs/V01_gemini/10_Billing_Credits_Subscriptions.md

💰 10_BILLING_CREDITS_SUBSCRIPTIONS (v1.2)

1. Regionális és Valuta Logika (EU Scope)

A rendszer többnyelvű és többvalutás elszámolást alkalmaz. Minden tranzakció kettős értéktárolással valósul meg az adatintegritás érdekében.

• Local Cost: A felhasználó régiója szerinti pénznemben rögzített összeg.
• Standard Cost (EUR): A rögzítés pillanatában érvényes árfolyamon számolt alapérték.

Átszámítási képlet:

Cost_{EUR} = Cost_{Local} \cdot ExchangeRate

---

2. Előfizetési Csomagok és Business Synergy

A rendszer korlátait a data.system_settings tábla szabályozza. A csomagok skálázhatóak a flotta méretétől függően.

Csomag	Jármű Limit	Kiemelt funkciók
FREE	1 db	Alap költségnapló, GEO alapú szervizkereső.
PREMIUM	3 db	Dokumentumtár, export funkciók, útvonal alapú kereső.
PREMIUM+	5 db	Flotta statisztika, TCO (Total Cost of Ownership) elemzés.
VIP / VIP+	10+ db	Egyedi szervizkezelés, bővíthető slotok, prioritásos support.

2.1. VIP Synergy Szabályok (Ösztönző rendszer)

• Synergy Discount: Ha egy FLEET_OWNER aktív VIP vagy VIP+ előfizetéssel rendelkezik, 15% kedvezményt kap minden vásárlásra a saját privát flottájában is.
• Ajándék Kredit: VIP vásárláskor extra kreditek járnak (felhasználható: skinek, medálok, privát Prémium csomag).
• Időbeli korlát: A privát kedvezmények időtartama 2-6 hónapra korlátozott, ösztönözve a folyamatos aktivitást.

---

3. Voucher és Kupon Rendszer

A kedvezmények igénybevétele manuális kódbeíráshoz kötött. Minden felhasználást auditálni kell (redeemed_at, user_id, original_price).

• Gift Card (Fix Kredit): Meghatározott összegű jóváírás (pl. 5000 Ft).
• Subscription Coupon (%): Százalékos kedvezmény az előfizetési díjból egy adott időszakra.
• Lejárat: Minden kupon rendelkezik fix érvényességi idővel, amely után inaktívvá válik.

---

4. MLM Jutalomrendszer (Referral)

A rendszer jutalmazza a sikeres meghívásokat az új tag első befizetése után. A százalékos érték a tranzakció pillanatában rögzül (Snapshot).

• 1. szint (Közvetlen): 10% jóváírás.
• 2. szint: 5% jóváírás.
• 3. szint: 2% jóváírás.

---

5. Invitation Engine (Meghívó Rendszer)

A spam elleni védelem érdekében a meghívók élettartama és mennyisége korlátozott:

• Token Lejárati idők:
  • Felhasználói (User) meghívó: 72 óra.
  • Adminisztrátori meghívó: 24 óra.
• Mennyiségi korlát: Kezdő keret felhasználónként (alapértelmezett: 10 vagy 20 db).
• Anti-Spam Logika: A felhasználó csak sikeres regisztrációk után kap vissza új meghívási lehetőségeket (slotokat).

---

6. Evidence & Trust Engine (Hitelesítés)

A rendszerben a "Verified" (hiteles) státusz eléréséhez bizonyítékok szükségesek.

• Kötelező bizonyítékok: Munkalap fotó, számlakép és kilométeróra-állás fotó.
• GPS Check-in: A szerviz eseménykor igazolni kell a helyszíni tartózkodást.
• Validáció: Cég mint entitás nem hitelesíthet; a validálást mindig egy azonosított Person végzi.

---

7. Lejárat és Pénzügyi Helyreállítás

Ha az előfizetés lejár, a rendszer az alábbi fokozatos korlátozásokat vezeti be:

1. Grace Period (30 nap): Csak adatrögzítés lehetséges, a statisztikai modulok és exportok zárolva vannak.
2. Zárolás (60 nap): A fiók írásvédetté válik (Read-only). Nincs új adatrögzítés.
3. Helyreállítás: 6 hónapon belüli visszamenőleges befizetés esetén minden korábbi adat és funkció azonnal újraaktiválódik.

4. Economic Model & Exchange Rates

4.1 Dinamikus Árfolyamok (Admin Config)

A rendszer támogatja a többvalutás elszámolást. Az átváltási arányok a system_configs táblából jönnek.

• Példa konfiguráció:
  • 1 HUF = 50 Kredit
  • 1 EUR = 20.000 Kredit (változtatható)
  • 1 USD = 18.500 Kredit

4.2 Referral Commission (Admin Config)

A jutalékrendszer paraméterezhető, alapértelmezett értékei:

• Level 1 (Közvetlen): 10%
• Level 2: 5%
• Level 3: 2%
• Megjegyzés: Adminisztrátori joggal ezek bármikor módosíthatók, visszamenőleges hatály nélkül.

4.3 Kifizetés (Payout)

• Threshold: A kifizetés igénylésének alsó határa alapértelmezetten 1.000.000 Kredit.
• Ez az érték adminisztrátori döntéssel csökkenthető/növelhető a rendszer érettségétől függően.

5. Marketplace & Vanity Items

5.1 Árazási Logika

A rendszer támogatja a dinamikus árazást a kozmetikai elemeknél is.

• Fix áras termékek: Egyszerű levonás a coin_balance-ból vagy credit_balance-ból.
• Időszakos ajánlatok: A katalógusban beállítható sale_price és sale_end_date.

5.2 Vásárlási Folyamat

1. Check: Van-e elég fedezet (Wallet)?
2. Deduct: Tranzakció rögzítése a wallet_transactions táblában (type='purchase_item').
3. Grant: Tétel beírása a user_inventory táblába.
4. Equip: Opcionálisan azonnali beállítás (pl. profilkép keret).

5.3 Bővíthetőség

Új elem hozzáadásához nem kell kódot módosítani, csak a shop_catalog JSON-t kell frissíteni az Admin felületen. A kliens alkalmazás (App/Web) dinamikusan tölti be a kínálatot ebből a JSON-ből.