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.

## 3. The Triple Wallet System (3-as Pénztárca)

A `wallets` tábla három elkülönített alszámlát kezel a transzparencia érdekében:

| Alszámla | Kód | Forrás | Felhasználás | Átváltható? |
| :--- | :--- | :--- | :--- | :--- |
| **Earned Credits** | `earned_credits` | Munka (validálás), Referral, Jutalék | Prémium funkciók, Szolgáltatás vásárlás | IGEN |
| **Purchased Credits** | `purchased_credits` | Bankkártyás feltöltés (Stripe) | Prémium funkciók, Szolgáltatás vásárlás | IGEN |
| **Service Coins** | `service_coins` | B2B Csomagok, Partneri jóváírás | **Kizárólag** Hirdetés, Kiemelés, Szponzoráció | **NEM** |

## 4. Sales Commission Model (Hunting & Farming)

Az üzletkötők ösztönzése két fázisban történik:

### 4.1 Hunting (Vadász) Jutalék
* **Esemény:** Új fizető ügyfél behozatala (első tranzakció).
* **Mérték:** 10% (Alapértelmezett `system_parameter`).
* **Jóváírás:** Azonnal, `earned_credits` formájában.

### 4.2 Farming (Gazda) Jutalék
* **Esemény:** Meglévő ügyfél havidíj megújítása.
* **Mérték:** 5% (Alapértelmezett `system_parameter`).
* **Átruházhatóság:** A jutalékot nem a User, hanem az `OrganizationSalesAssignment` tábla aktív rekordja határozza meg. Ha az üzletkötő kilép, a portfóliója (és a Farming joga) átruházható egy másik ügynökre.

### 4.3 Financial Ledger (Pénzügyi Napló)
Minden tranzakció (Vásárlás, Jutalék jóváírás, Költés) bekerül a `financial_ledger` táblába, amely megmásíthatatlan (Append-only) és tartalmazza a `related_agent_id`-t a visszakövethetőségért.