admin_users_personels

2026-06-29 14:11:15 +00:00
parent 383e5511b6
commit df4a0f07ff
237 changed files with 17849 additions and 2934 deletions
--- a/plans/logic_spec_gamification_admin_integration.md
+++ b/plans/logic_spec_gamification_admin_integration.md
@@ -0,0 +1,372 @@
+# 🏗️ 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.