Files

Roo df4a0f07ff admin_users_personels

2026-06-29 14:11:15 +00:00

16 KiB

Raw Blame History

🏗️ 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:

# ==================== 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:

{
  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:

# 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:

# 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

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.
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.
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:

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

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

6. Adatfolyam Diagram

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

Adatbázis migráció: A modell javításokhoz sync_engine futtatása szükséges, ami meglévő adatokat is érinthet.
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.
JSONB konfiguráció: A GAMIFICATION_MASTER_CONFIG JSONB validációja kritikus — hibás JSON letiltja a gamification rendszert.

16 KiB Raw Blame History