# Gamification Penalty System — Adatbázis Felderítési Jelentés

**Dátum:** 2026-06-17  
**Cél:** A 3-szintű Büntetési Mátrix (Penalty System) és Árnyéktiltás (Shadowban) bevezetésének adatbázis-struktúra előfeltérképezése

---

## 1. FELADAT: Büntetési Szint (Penalty Level) — Meglévő Struktúra

### ✅ Megállapítás: A büntetési infrastruktúra NAGYRÉSZT KÉSZ

A Vezető Tervező örömére: a rendszer **már tartalmazza** a büntetési pontrendszer alapjait. Az alábbi táblák és mezők **már léteznek** az adatbázisban és a modellekben:

#### backend/app/models/gamification/gamification.py

| Tábla (séma) | Mező | Típus | Státusz |
|---|---|---|---|
| gamification.user_stats | penalty_points | Integer (server_default=0) | ✅ Létezik |
| gamification.user_stats | restriction_level | Integer (server_default=0) | ✅ Létezik |
| gamification.user_stats | penalty_quota_remaining | Integer (default=3) | ✅ Létezik |
| gamification.user_stats | banned_until | DateTime(timezone=True) | ✅ Létezik |
| gamification.user_stats | current_level | Integer (default=1) | ✅ Létezik |
| gamification.level_configs | level_number | Integer (unique) | ✅ Létezik (támogat negatív értékeket!) |
| gamification.level_configs | is_penalty | Boolean (default=False) | ✅ Létezik |
| gamification.level_configs | min_points | Integer | ✅ Létezik |
| gamification.level_configs | rank_name | String | ✅ Létezik |
| gamification.points_ledger | penalty_change | Integer (server_default=0) | ✅ Létezik |
| identity.persons | penalty_points | Integer (default=-1) | ✅ Létezik |
| identity.persons | social_reputation | Numeric(3,2) | ✅ Létezik |
| identity.persons | lifetime_xp | BigInteger (default=-1) | ✅ Létezik |
| identity.user_trust_profiles | trust_score | Integer (default=0) | ✅ Létezik |
| identity.user_trust_profiles | identity_risk_flag | Boolean (default=False) | ✅ Létezik |

### ⚠️ HIÁNYZIK: penalty_level (a 3-szintű büntetési mátrix maga)

A restriction_level mező hasonló koncepció, de jelenleg nincs dedikált penalty_level (Integer, -1 / -2 / -3) mező.

### Javaslat az új mezők helyére

A gamification.user_stats táblába érdemes beilleszteni:

```
PenaltyLevel:          Integer, server_default=0  (-1=Figyelmeztetés, -2=Korlátozás, -3=Árnyéktiltás)
GoodDeedsCount:        Integer, server_default=0  (Jóvátételi cselekedetek számlálója)
ShadowBannedUntil:     DateTime(timezone=True), nullable=True  (Látszólagos tiltás vége)
```

**Indoklás:** A user_stats tábla már most is tartalmazza a penalty_points, restriction_level, penalty_quota_remaining és banned_until mezőket — ez a természetes helye minden büntetési információnak. A Person tábla (identity.persons) szintén rendelkezik penalty_points mezővel, de ott ez a személy szintű, nem a gamification profil része.

---

## 2. FELADAT: Hibajelentés (Report) Tábla

### ❌ Megállapítás: NINCS dedikált report/abuse tábla

Az adatbázisban és a modellek között **NEM található** olyan tábla, amelynek neve report, abuse, flag, ticket, moderation_content vagy data_correction lenne. A PostgreSQL information_schema lekérdezés nulla találatot adott.

### Ami KÖZELÍT

| Tábla | Kapcsolat | Korlát |
|---|---|---|
| marketplace.service_providers | status mező ModerationStatus enumnak | Ez a beküldött szolgáltatók moderálására való, **nem** a visszaélés-jelentésre |
| marketplace.service_profiles | flagged státusz a ServiceStatus enumban | Szolgáltatók flag-elésére |
| gamification.user_contributions | contribution_type = 'report_abuse' | Naplózza, hogy ki jelentett, de **nincs dedikált jelentés adattábla** |

### Javaslat: Új user_reports tábla létrehozása

Javasolt séma a gamification sémában (ahol a user_contributions is van):

```
user_reports tábla (gamification séma):
- id                  Integer (PK)
- reporter_id         Integer FK->identity.users.id
- target_type         String(50)  ('service_profile', 'review', 'vehicle', 'user')
- target_id           Integer
- reason_category     String(50)  ('fake_service', 'wrong_data', 'spam', 'abuse', 'other')
- description         Text (nullable)
- evidence_data       JSONB (nullable)
- status              String(20) default='pending' ('pending','verified','dismissed','action_taken')
- reviewed_by         Integer FK->identity.users.id (nullable)
- resolution          Text (nullable)
- created_at          DateTime
- resolved_at         DateTime (nullable)
```

---

## 3. FELADAT: Adminisztrációs Szabályok (System Parameters)

### ✅ Megállapítás: A rendszer RENDELKEZIK dinamikus paraméter táblával

A system.system_parameters tábla **már létezik** és kifejezetten alkalmas a büntetési szabályok adminisztrációjára.

| Oszlop | Típus | Leírás |
|---|---|---|
| key | VARCHAR | Paraméter kulcs (pl. penalty_level_1_quota) |
| category | VARCHAR | Kategorizálás (pl. penalty_system) |
| value | JSONB | A paraméter értéke (JSON, bármi lehet) |
| scope_level | VARCHAR | Hatáskör: global, country, region, organization, user |
| scope_id | VARCHAR | A hatáskör azonosítója |
| is_active | BOOLEAN | Aktív-e |
| description | VARCHAR | Emberi leírás |

### Javasolt paraméterkulcsok a büntetési rendszerhez

| key | category | value (JSON) |
|---|---|---|
| penalty_level_1_threshold | penalty_system | {"min_bad_actions": 2, "quota_reduction": 1} |
| penalty_level_2_threshold | penalty_system | {"min_bad_actions": 5, "xp_multiplier": 0.5} |
| penalty_level_3_threshold | penalty_system | {"min_bad_actions": 10, "shadowban": true, "max_actions_per_day": 1} |
| penalty_action_points | penalty_system | {"fake_service_submission": 10, "fake_review": 15, "spam_comment": 5} |
| penalty_good_deed_recovery | penalty_system | {"points_per_good_deed": -3, "max_recovery_per_day": 1} |

> **Előny:** A scope_level oszlop lehetővé teszi, hogy **ország-specifikus** vagy akár **felhasználó-specifikus** büntetési szabályokat állítsunk be, anélkül hogy a kódot módosítani kellene.

---

## Összefoglaló táblázat

| Feladat | Státusz | Megjegyzés |
|---|---|---|
| **1. Büntetési szint helye** | ✅ **Alap infrastruktúra kész** | user_stats.penalty_points, restriction_level, penalty_quota_remaining, banned_until, level_configs.is_penalty — mind létezik. HIÁNYZIK: dedikált penalty_level és good_deeds_count mező |
| **2. Hibajelentés tábla** | ❌ **NINCS** | Egyetlen dedikált report/abuse tábla sem létezik. A user_contributions.contribution_type = 'report_abuse' csak naplóz, nem tárol jelentéseket. **Teljesen új tábla kell** |
| **3. Adminisztrációs szabályok** | ✅ **Alkalmas** | system.system_parameters JSONB-alapú, scoped paraméter tábla kiválóan megfelel a dinamikus szabályok tárolására. Új paramétereket kell csak beszúrni |

## Következő lépések (ajánlott sorrend)

1. **Új mezők hozzáadása** gamification.user_stats-hoz: penalty_level, good_deeds_count, shadow_banned_until
2. **Új tábla létrehozása:** gamification.user_reports (vagy gamification.content_reports)
3. **Rendszerparaméterek feltöltése:** system.system_parameters büntetési szabályokkal
4. **Penalty Engine service** megírása, ami a level_configs táblából és a system_parameters-ből olvassa a szabályokat, és automatikusan lépteti a penalty_level-et