# 🔗 Gamification Point-Rules Admin Kapcsolati Hiányosság Elemzés

**Dátum:** 2026-06-30
**Vizsgálat típusa:** Rendszer-audit
**Vizsgált oldal:** `https://admin.servicefinder.hu/gamification/point-rules`
**Modul:** Gamification Admin Rendszer 2.0
**Gitea Issue:** #364

---

## 🎯 Probléma összefoglalása

A `/gamification/point-rules` admin felületen létrehozott és módosított pontszabályok (action_key -> points) NINCSENEK összekapcsolva a valódi gamification folyamatokkal. Az admin felületen beállított pontértékek csak a folyamatok egy szűk körére (service_submission, daily_quiz_correct) vannak hatással. A többi gamification akció (KYC, költség rögzítés, eszköz regisztráció, fleet esemény, stb.) vagy keménykódolt értékeket, vagy a ConfigService-ből olvasott értékeket használ.

---

## 🔬 Technikai háttér

### 1. Point Rules Adatbázis Tábla (gamification.point_rules)

Az adatbázisban jelenleg **10 aktív pontszabály** található:

| ID | action_key | points | description |
|----|-----------|-------|-------------|
| 3 | ADD_NEW_PROVIDER | 500 | Új szolgáltató rögzítése |
| 1 | ASSET_REGISTER | 100 | - |
| 2 | ASSET_REVIEW | 75 | - |
| 17 | PROVIDER_CONFIRMATION | 150 | Meglévő provider megerősítése |
| 16 | PROVIDER_DISCOVERY | 300 | Új provider felfedezése |
| 18 | PROVIDER_VERIFIED_USE | 100 | Jóváhagyott provider használata |
| 5 | RATE_PROVIDER | 250 | Szolgáltató értékelése |
| 6 | UPDATE_PROVIDER | 100 | Szolgáltató adatainak szerkesztése |
| 4 | USE_UNVERIFIED_PROVIDER | 200 | Nem ellenőrzött szolgáltató használata |
| 7 | TEST_ACTION | 100 | Test rule |

### 2. GAMIFICATION_MASTER_CONFIG Rendszerparaméter

A `system.system_parameters` táblában tárolt konfiguráció:
- xp_logic: base_xp=500, exponent=1.5
- penalty_logic: recovery_rate=0.5, threshold-ok, multiplier-ek
- conversion_logic: social_to_credit_rate=100
- level_rewards: credits_per_10_levels=50

---

## 🚨 A Hiányzó Kapcsolat Részletes Elemzése

### 1. Elsődleges probléma: award_points() nem támogatja az action_key-t

A [`GamificationService.award_points()`](backend/app/services/gamification_service.py:44) statikus metódus definíciója:

```python
@staticmethod
async def award_points(db, user_id, amount, reason, social_points=0, commit=True):
    service = GamificationService()
    return await service.process_activity(
        db, user_id, 
        xp_amount=amount, 
        social_amount=social_points, 
        reason=reason, 
        commit=commit
        # NINCS action_key átadva!
    )
```

A metódus NEM fogad el action_key paramétert, így azt nem is adja át a process_activity()-nak.

### 2. A process_activity() belső logikája

A [`process_activity()`](backend/app/services/gamification_service.py:125-134) metódus:

```python
# 1/b. POINT RULES TÁBLA LEKÉRÉSE (ha action_key meg van adva)
if action_key:
    rule = await self._get_point_rule(db, action_key)
    if rule:
        xp_amount = rule["points"]
```

A logika MŰKÖDIK, de csak akkor indul be, ha az action_key paraméter átadásra kerül.

### 3. Hívások elemzése

#### Helyesen használja az action_key-t (point_rules tábla érvényesül):

| Hívó helye | action_key | Forrás |
|-----------|-----------|--------|
| gamification.py:374 | service_submission | Service beküldés |
| gamification.py:566 | daily_quiz_correct | Napi kvíz |

#### NEM használja az action_key-t (point_rules tábla NEM érvényesül):

| Hívó helye | Pontforrás | Probléma |
|-----------|-----------|----------|
| auth_service.py:298 | kyc_reward változó | KYC pontok nem módosíthatók |
| auth_service.py:303 | ConfigService gamification_p2p_invite_xp | P2P referral pontok nem módosíthatók |
| cost_service.py:73 | base_xp * ocr_multiplier | Költség log pontok nem módosíthatók |
| asset_service.py:290 | ConfigService xp_reward_asset_register | Asset reg pontok nem módosíthatók |
| fleet_service.py:88 | event_rewards config dict | Fleet esemény pontok nem módosíthatók |
| social_service.py:73 | Keménykódolt 100 XP, 20 SP | Validáció pontok nem módosíthatók |
| social_service.py:98 | Keménykódolt 50 XP | Elutasítás pontok nem módosíthatók |
| services.py:40 | ConfigService GAMIFICATION_HUNT_REWARD | Service hunt pontok nem módosíthatók |
| services.py:90 | ConfigService GAMIFICATION_VALIDATE_REWARD | Service validation pontok nem módosíthatók |

### 4. Duplikált logika a provider_service-ben

A [`provider_service.py:60-135`](backend/app/services/provider_service.py:60) tartalmaz egy `_award_dynamic_points()` függvényt, ami **saját maga kiolvassa** a point_rules táblát, mielőtt meghívná az award_points()-t.

Ez a logika **MŰKÖDIK**, de:
- **Duplikált**: Ugyanezt a logikát a process_activity() is tartalmazza
- **Feleslegesen komplex**: Ha az award_points() támogatná az action_key-t, ez a függvény leegyszerűsödne

---

## 🔧 Javasolt Javítási Terv

### 1. Közvetlen javítás: award_points() kiegészítése action_key támogatással

Módosítandó fájl: [`backend/app/services/gamification_service.py:44-54`](backend/app/services/gamification_service.py:44)

```python
@staticmethod
async def award_points(
    db: AsyncSession, 
    user_id: int, 
    amount: int, 
    reason: str, 
    social_points: int = 0, 
    commit: bool = True,
    action_key: str | None = None,
):
    service = GamificationService()
    return await service.process_activity(
        db, user_id, 
        xp_amount=amount, 
        social_amount=social_points, 
        reason=reason, 
        commit=commit,
        action_key=action_key,
    )
```

**Hatás:** Minden award_points() hívó automatikusan használhatja a point_rules táblát, ha átadja az action_key-t.

### 2. Hívók átállítása action_key használatára

| Hívó | Javasolt action_key |
|------|-------------------|
| auth_service.py:298 | KYC_VERIFICATION (új) |
| auth_service.py:303 | P2P_REFERRAL_SUCCESS (új) |
| cost_service.py:73 | EXPENSE_LOG (új) |
| asset_service.py:290 | ASSET_REGISTER (mar létezik!) |
| fleet_service.py:88 | FLEET_EVENT (új) |
| social_service.py:73 | PROVIDER_VALIDATED (új) |
| social_service.py:98 | PROVIDER_REJECTED (új) |
| services.py:40 | SERVICE_HUNT (új) |
| services.py:90 | SERVICE_VALIDATION (új) |

### 3. Duplikált logika eltávolítása

A `_award_dynamic_points()` függvény leegyszerűsíthető, ha az award_points() már támogatja az action_key-t.

---

## 📊 Hatáselemzés

### Milyen akciókra van jelenleg hatással a point_rules módosítása?

- Service beküldes - hasznalja (action_key=service_submission)
- Napi kviz - hasznalja (action_key=daily_quiz_correct)
- Provider müveletek - hasznalja (provider_service _award_dynamic_points)

### Milyen akciókra NINCS hatással a point_rules módosítása?

- KYC regisztracio - kemenykodolt
- P2P referral - ConfigService
- Koltség rögzítés - kemenykodolt
- Eszköz regisztracio - ConfigService (bar ASSET_REGISTER letezik!)
- Flotta esemenyek - kemenykodolt
- Szolgaltato validacio/elutasitas - kemenykodolt
- Service hunt/validation - ConfigService

---

## Következtetés

A `/gamification/point-rules` admin felület jelenleg **csak a point_rules adatbazis tabla CRUD kezeleset** teszi lehetove, de a tabla tartalma **nincs hatassal a gamification folyamatok tobbsegere**. A javitashoz a `GamificationService.award_points()` metódust kell kiegesziteni `action_key` parameter tamogatasaval, es a hivokat at kell allitani action_key hasznalatara.