373 lines
16 KiB
Markdown
373 lines
16 KiB
Markdown
# 🏗️ 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.
|