# 🏗️ Gamification Admin Integration — Rendszerszintű Terv

## 1. Küldetés és Cél

**Mérföldkő:** Master Book 2.0 — Gamification Pro (MILESTONE_8)
**Cél:** A meglévő Gamification backend (modellek, service-ek, API végpontok) teljes admin felületre történő bekötése, egy új, dedikált **"Gamification"** menüpont alatt az admin Nuxt frontendben.

---

## 2. Jelenlegi Rendszer Állapota (Audit Summary)

### 2.1 Adatbázis Modellek (`gamification` séma)

| Tábla | Státusz | Fejlettség |
|-------|---------|-------------|
| `point_rules` | ✅ Létezik | Alap (action_key, points, description, is_active) |
| `level_configs` | ✅ Létezik | Alap (level_number, min_points, rank_name, is_penalty) |
| `points_ledger` | ✅ Létezik | Teljes (user_id, points, penalty_change, reason) |
| `user_stats` | ✅ Létezik | Teljes (XP, szint, penalty, restriction, quota, helyek) |
| `badges` | ✅ Létezik | Alap (name, description, icon_url) |
| `user_badges` | ✅ Létezik | Kapcsolótábla |
| `user_contributions` | ✅ Létezik | Fejlett (type, entity, status, fingerprint) |
| `seasons` | ✅ Létezik | Alap (name, start, end, is_active) |
| `seasonal_competitions` | ✅ Létezik | Részleges (JSONB rules) |
| `competitions` | ✅ Létezik | `gamification` sémában |
| `user_competition_scores` | ✅ Létezik | Pontszámok |

**Hiányzó mezők a modellekből:**
- `UserStats`-ból hiányzik: `services_submitted`, `total_points` (a gamification.py endpointok használják, de a modellben nincs definiálva!)
- `PointsLedger`-ből hiányzik: `xp` mező, `source_type`, `source_id` (a gamification.py endpoint használja, de a modellben nincs!)

### 2.2 GamificationService

✅ Teljes, jól működő service:
- `process_activity()` — Pontozás + büntetés szűrés + szintszámítás + kifizetés
- `_apply_penalty()` — Büntetőpontok és restriction_level kezelése
- `_calculate_multiplier()` — Dinamikus szorzó L0-L3 között
- `_handle_level_up()` — Kredit jutalom minden 10. szintnél
- `_add_earned_credits()` — Wallet + FinancialLedger integráció

**Figyelem:** A service master configot a `SystemParameter` táblából `GAMIFICATION_MASTER_CONFIG` kulccsal olvassa. Ez már admin által módosítható, de nincs hozzá admin UI!

### 2.3 API Végpontok

| Végpont | Metódus | Státusz | Megjegyzés |
|---------|---------|---------|------------|
| `/gamification/me` | GET | ✅ | UserStatResponse |
| `/gamification/my-stats` | GET | ✅ | Saját statok |
| `/gamification/leaderboard` | GET | ✅ | Top lista |
| `/gamification/seasons` | GET | ✅ | Szezonok |
| `/gamification/seasons/active` | GET | ✅ | Aktív szezon |
| `/gamification/my-contributions` | GET | ✅ | Hozzájárulások |
| `/gamification/season-standings/{id}` | GET | ✅ | Szezon állás |
| `/gamification/self-defense-status` | GET | ✅ | Önvédelmi rendszer |
| `/gamification/submit-service` | POST | ✅ | Szerviz beküldés |
| `/gamification/badges` | GET | ✅ | Összes badge |
| `/gamification/my-badges` | GET | ✅ | Saját badge-ek |
| `/gamification/badges/award/{id}` | POST | ✅ | Badge adományozás |
| `/gamification/achievements` | GET | ✅ | Achievement progress |
| `/gamification/quiz/*` | GET/POST | ✅ | Napi kvíz |
| **`/admin/users/{id}/penalty`** | **PATCH** | ⚠️ | **HIÁNYOS!** Nem használja a GamificationService-t, direktül módosítja a `level` mezőt! |

### 2.4 Admin Frontend

A `layouts/default.vue` menüpontjai:
- Központ → Dashboard
- Felhasználók & Partnerek → Garázsok, Felhasználók, Személyek
- Pénzügyek → Csomagok
- Rendszer → Jogosultságok, Rendszernaplók

**❌ NINCS Gamification menüpont!**

---

## 3. Komplex Terv — Gamification Admin Bekötése

### 3.1 Backend Új Végpontok (Admin API)

#### Új router: `backend/app/api/v1/endpoints/admin_gamification.py`

Létrehozandó végpontok:

```python
# ==================== POINT RULES ====================
GET    /admin/gamification/point-rules          # Összes pontszabály listázása
POST   /admin/gamification/point-rules          # Új pontszabály létrehozása
PUT    /admin/gamification/point-rules/{id}     # Pontszabály módosítása
DELETE /admin/gamification/point-rules/{id}     # Pontszabály törlése (soft)

# ==================== LEVEL CONFIGS ====================
GET    /admin/gamification/level-configs        # Szintkonfigurációk listázása
POST   /admin/gamification/level-configs        # Új szint létrehozása
PUT    /admin/gamification/level-configs/{id}   # Szint módosítása

# ==================== BADGES ====================
GET    /admin/gamification/badges               # Összes badge listázása
POST   /admin/gamification/badges               # Új badge létrehozása
PUT    /admin/gamification/badges/{id}          # Badge módosítása
DELETE /admin/gamification/badges/{id}          # Badge törlése

# ==================== SEASONS ====================
GET    /admin/gamification/seasons              # Szezonok listázása
POST   /admin/gamification/seasons              # Új szezon létrehozása
PUT    /admin/gamification/seasons/{id}         # Szezon módosítása
POST   /admin/gamification/seasons/{id}/activate # Szezon aktiválása

# ==================== COMPETITIONS ====================
GET    /admin/gamification/competitions          # Versenyek listázása
POST   /admin/gamification/competitions          # Új verseny
PUT    /admin/gamification/competitions/{id}     # Verseny módosítása

# ==================== USER STATS ADMIN ====================
GET    /admin/gamification/user-stats           # Összes felhasználói stat (szűrhető)
GET    /admin/gamification/user-stats/{user_id} # Egy felhasználó statjai
PUT    /admin/gamification/user-stats/{user_id} # Statisztika manuális módosítása
POST   /admin/gamification/user-stats/{user_id}/penalty  # Büntetés (GamificationService-en keresztül!)
POST   /admin/gamification/user-stats/{user_id}/reward   # Jutalom (GamificationService-en keresztül!)

# ==================== MASTER CONFIG ====================
GET    /admin/gamification/master-config        # GAMIFICATION_MASTER_CONFIG lekérése
PUT    /admin/gamification/master-config        # GAMIFICATION_MASTER_CONFIG módosítása

# ==================== SYSTEM PARAMETERS (gamification scope) ====================
GET    /admin/gamification/system-params        # Gamification kategóriájú rendszerparaméterek
PUT    /admin/gamification/system-params/{key}  # Rendszerparaméter módosítása

# ==================== AUDIT / HISTORY ====================
GET    /admin/gamification/points-ledger        # Pontnapló (szűrhető user_id, date range)
GET    /admin/gamification/contributions        # Hozzájárulások listája (admin review)
PUT    /admin/gamification/contributions/{id}/review  # Hozzájárulás jóváhagyása/elutasítása
```

### 3.2 Frontend — új Gamification menüpont

#### 3.2.1 Új oldalak

```
frontend_admin/pages/gamification/
├── index.vue              # Gamification Dashboard (áttekintő)
├── point-rules.vue        # Pontszabályok CRUD
├── levels.vue             # Szint konfigurációk
├── badges.vue             # Badge-ek kezelése
├── seasons.vue            # Szezonok kezelése
├── competitions.vue       # Versenyek kezelése
├── users.vue              # Felhasználói statisztikák listája
├── users/[id].vue         # Egy felhasználó részletes gamification adatai
├── leaderboard.vue        # Ranglista admin nézet
├── config.vue             # Master config szerkesztése
├── parameters.vue         # Gamification rendszerparaméterek
└── ledger.vue             # Pontnapló böngészése
```

#### 3.2.2 Menüpont beszúrása

A `frontend_admin/layouts/default.vue` `menuGroups` tömbjébe új csoport:

```javascript
{
  title: 'Gamification',
  items: [
    {
      path: '/gamification',
      label: 'Gamification HQ',
      icon: '<svg...trophy icon...>',
    },
    {
      label: 'Játékmenet Beállítások',
      icon: '<svg...settings icon...>',
      children: [
        { path: '/gamification/point-rules', label: 'Pontszabályok', icon: '...' },
        { path: '/gamification/levels', label: 'Szintek', icon: '...' },
        { path: '/gamification/badges', label: 'Kitüntetések', icon: '...' },
      ],
    },
    {
      label: 'Események & Szezonok',
      icon: '<svg...calendar icon...>',
      children: [
        { path: '/gamification/seasons', label: 'Szezonok', icon: '...' },
        { path: '/gamification/competitions', label: 'Versenyek', icon: '...' },
      ],
    },
    {
      label: 'Felhasználói Adatok',
      icon: '<svg...users icon...>',
      children: [
        { path: '/gamification/users', label: 'Statisztikák', icon: '...' },
        { path: '/gamification/leaderboard', label: 'Ranglista', icon: '...' },
        { path: '/gamification/ledger', label: 'Pontnapló', icon: '...' },
      ],
    },
    {
      path: '/gamification/config',
      label: 'Rendszer Konfig',
      icon: '<svg...config icon...>',
    },
    {
      path: '/gamification/parameters',
      label: 'Rendszerparaméterek',
      icon: '<svg...params icon...>',
    },
  ],
}
```

### 3.3 Séma Javítások (Adatbázis)

A `UserStats` modellt ki kell egészíteni:

```python
# HIÁNYZÓ MEZŐK - hozzáadandó:
services_submitted: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
total_points: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
```

A `PointsLedger` modellt ki kell egészíteni:

```python
# HIÁNYZÓ MEZŐK - hozzáadandó:
xp: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
source_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
source_id: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
```

### 3.4 Business Logic Javítások

1. **A meglévő `PATCH /admin/users/{user_id}/penalty` végpontot** át kell írni, hogy a `GamificationService` `process_activity()` metódusát használja `is_penalty=True` paraméterrel, ne direkt `level` módosítást végezzen.

2. **A gamification.py endpointok** (`submit-service`, `quiz/answer`, `badges/award`) direktül módosítják a `UserStats` mezőket a GamificationService helyett — ezeket is át kell írni.

3. **A `GamificationService.process_activity()`** jelenleg csak a `GAMIFICATION_MASTER_CONFIG`-ot használja. Ki kell egészíteni, hogy a `point_rules` táblából is olvasson.

---

## 4. UI Komponensek Terve

### 4.1 Gamification Dashboard (`/gamification/index.vue`)
- **Kártyák:** Összes felhasználó (UserStats count), Aktív szezon, Függő contribution-ök, Ma szerzett XP
- **Grafikonok:** Napi XP trend (utolsó 30 nap), Szint eloszlás, Pontszabályok aktivitása
- **Táblák:** Legutóbbi PointsLedger bejegyzések, Top 5 leaderboard

### 4.2 Pontszabályok (`/gamification/point-rules.vue`)
- **DataTable:** action_key, points, description, is_active
- **CRUD:** Inline szerkeszthető sorok, új sor hozzáadása
- **Keresés/Szűrés:** action_key alapján

### 4.3 Szintek (`/gamification/levels.vue`)
- **DataTable:** level_number, min_points, rank_name, is_penalty
- **Vizuális:** Szintlépés fa diagram (Mermaid vagy Vue komponens)

### 4.4 Kitüntetések (`/gamification/badges.vue`)
- **Grid:** Badge kártyák nézet (ikon, név, leírás)
- **CRUD:** Badge létrehozás/szerkesztés, ikon feltöltés
- **Felhasználók:** Badge kiosztása felhasználónak

### 4.5 Szezonok (`/gamification/seasons.vue`)
- **Timeline:** Szezonok idővonal nézetben
- **CRUD:** Új szezon, dátumok, aktív státusz
- **Zárás:** Szezon lezárása automatikus jutalom kiosztással

### 4.6 Felhasználói Statisztikák (`/gamification/users.vue` + `users/[id].vue`)
- **Lista:** UserStats tábla adatai (user, XP, level, penalty)
- **Részletek:** Részletes gamification profil, pontnapló, badge-ek, contribution-ök
- **Műveletek:** Büntetés, Jutalom, Stat reset (auditáltan)

### 4.7 Ranglista (`/gamification/leaderboard.vue`)
- **Tábla:** Top 100 felhasználó ranglétrája
- **Szűrés:** Szezonális / Globális váltás

### 4.8 Master Config (`/gamification/config.vue`)
- **JSON Editor:** `GAMIFICATION_MASTER_CONFIG` szerkesztése validált JSON mezőkkel
  - `xp_logic` — base_xp, exponent
  - `penalty_logic` — recovery_rate, thresholds, multipliers
  - `conversion_logic` — social_to_credit_rate
  - `level_rewards` — credits_per_10_levels
- **Előnézet:** Hatás kalkulátor (sliderekkel)

---

## 5. Engedélyezés (RBAC)

Minden admin gamification végponthoz `gamification:manage` permission kell:

```python
Depends(deps.RequirePermission("gamification:manage"))
```

A meglévő `fix_phantom_permissions.py` script már tartalmazza ezt a permission-t.

---

## 6. Adatfolyam Diagram

```mermaid
flowchart TD
    A[Admin User] -->|Böngésző| B[Nuxt Admin Frontend]
    B -->|HTTP /admin/gamification/*| C[FastAPI Admin Gateway]
    
    C --> D[admin_gamification.py Router]
    D --> E{GamificationService}
    D --> F[Direct CRUD]
    
    E --> G[(gamification schema)]
    F --> G
    
    G --> H[point_rules]
    G --> I[level_configs]
    G --> J[user_stats]
    G --> K[points_ledger]
    G --> L[badges]
    G --> M[seasons]
    G --> N[seasonal_competitions]
    G --> O[user_contributions]
    
    subgraph "Biztonsági Réteg"
        P[gamification:manage permission]
        Q[SecurityAuditLog minden művelethez]
    end
    
    C --> P
    D --> Q
```

---

## 7. Implementációs Sorrend (Gitea Kártyák)

| # | Kártya Név | Scope | Függőség | Becsült komplexitás |
|---|------------|-------|----------|---------------------|
| 1 | **Adatbázis: Gamification modell javítások (UserStats, PointsLedger)** | Database | Nincs | Közepes |
| 2 | **Backend: Új admin_gamification.py router létrehozása** | Backend | 1 | Magas |
| 3 | **Backend: GamificationService refaktor (point_rules integráció)** | Backend | 1 | Magas |
| 4 | **Backend: Meglévő penalty endpoint javítása** | Backend | 2, 3 | Alacsony |
| 5 | **Backend: gamification.py endpointok GamificationService-re átállítása** | Backend | 3 | Közepes |
| 6 | **Frontend: Gamification menüpont + routing** | Frontend | 2 | Alacsony |
| 7 | **Frontend: Gamification Dashboard oldal** | Frontend | 6 | Közepes |
| 8 | **Frontend: Pontszabályok + Szintek CRUD** | Frontend | 6 | Közepes |
| 9 | **Frontend: Kitüntetések (Badge) kezelő** | Frontend | 6 | Közepes |
| 10 | **Frontend: Szezonok + Versenyek kezelő** | Frontend | 6 | Magas |
| 11 | **Frontend: Felhasználói statisztikák + büntetés/jutalom** | Frontend | 6 | Magas |
| 12 | **Frontend: Ranglista admin nézet** | Frontend | 6 | Alacsony |
| 13 | **Frontend: Master Config szerkesztő** | Frontend | 6 | Közepes |
| 14 | **Frontend: Pontnapló böngésző** | Frontend | 6 | Közepes |
| 15 | **Tesztelés: Gamification admin E2E tesztek** | Backend+Frontend | 2-14 | Magas |

---

## 8. Használt Technológiák

- **Backend:** FastAPI, SQLAlchemy Async, Pydantic v2
- **Frontend:** Nuxt 3, Pinia (state), TailwindCSS, Chart.js (dashboard), vue-json-pretty (config editor)
- **Adatbázis:** PostgreSQL `gamification` séma
- **Auth:** JWT + `gamification:manage` permission

---

## 9. Függőségek

- **Bemenet:** Meglévő `gamification` séma (modellek már készen), `GamificationService`, `SystemParameter` kezelés
- **Kimenet:** Az új admin felület nélkülözhetetlen a gamification rendszer operatív kezeléséhez. Enélkül az admin-ok nem tudják:
  - Módosítani a pontszabályokat
  - Kezelni a büntetéseket (jelenleg direkt SQL/API szinten)
  - Létrehozni szezonokat és versenyeket
  - Felügyelni a felhasználói aktivitást

---

## 10. Kockázatok

1. **Adatbázis migráció:** A modell javításokhoz `sync_engine` futtatása szükséges, ami meglévő adatokat is érinthet.
2. **Kompatibilitás:** A meglévő gamification.py endpointok direktül módosítják a `UserStats` mezőket. Az átállásnál óvatos rollover kell.
3. **JSONB konfiguráció:** A `GAMIFICATION_MASTER_CONFIG` JSONB validációja kritikus — hibás JSON letiltja a gamification rendszert.