service-finder/docs/gamification_penalty_system_reconnaissance_2026-06-17.md

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