🎮 Logic Spec 8: Gamification 2.0, Verseny és Önvédelmi Rendszer
Verzió: 1.0
Dátum: 2026-03-15
Szerző: Rendszer-Architect
Kapcsolódó mérföldkő: MILESTONE_8_GAMIFICATION_PRO.md
🎯 Modul célja és Masterbook 2 illeszkedés
Cél
A Gamification 2.0 modul kiterjeszti a meglévő XP‑ és szintrendszert szezonális versenyekkel, önvédelmi mechanizmusokkal és egy robusztus moderációs keretrendszerrel. A modul biztosítja, hogy a felhasználók által beküldött szervizadatok biztonságosan, ellenőrzött módon kerüljenek a productionba, miközben a spam és rosszindulatú tevékenységeket automatikusan szűri.
Masterbook 2 illeszkedés
- Epic 7: Marketplace & API (A Külvilág felé) – A szervizek publikálása és a marketplace minőségbiztosítása.
- Epic 5: Robot Ecosystem – A service robot pipeline (0–4) hibáinak kijavítása és kiegészítése.
- Epic 3: Identity & Social – Felhasználói reputáció, trust score és büntetési rendszer.
🗄️ Adatmodell
1. Season tábla (system.seasons)
Féléves versenyek tárolása. Minden szezonhoz tartozik egy ranglista, amely a szezonban szerzett XP alapján rangsorol.
| Mező | Típus | Leírás |
|---|---|---|
id |
INTEGER (PK) |
Egyedi azonosító |
name |
VARCHAR(100) |
Szezon neve (pl. "2026 Tavasz") |
start_date |
DATE |
Szezon kezdete |
end_date |
DATE |
Szezon vége |
is_active |
BOOLEAN |
Aktív szezon? (egyidőben legfeljebb egy lehet) |
created_at |
TIMESTAMPTZ |
Létrehozás időbélyege |
Indexek:
idx_seasons_active(is_active) WHEREis_active = TRUEidx_seasons_dates(start_date,end_date)
Alembic terv:
CREATE TABLE system.seasons (
id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
name VARCHAR(100) NOT NULL,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
is_active BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE UNIQUE INDEX idx_seasons_active_unique
ON system.seasons (is_active) WHERE is_active = TRUE;
2. UserContribution tábla (gamification.user_contributions)
Spam védelem: minden felhasználó csak 90 naponként kaphat XP‑t ugyanazon szerviz (fingerprint) beküldéséért.
| Mező | Típus | Leírás |
|---|---|---|
id |
INTEGER (PK) |
Egyedi azonosító |
user_id |
INTEGER |
identity.users.id hivatkozás |
service_fingerprint |
VARCHAR(255) |
A beküldött szerviz hash‑je (MD5) |
action_type |
VARCHAR(30) |
submit_service, claim_business, review |
earned_xp |
INTEGER |
Az adott akcióért kapott XP |
cooldown_end |
TIMESTAMPTZ |
Cooldown vége (90 nap a submit_service esetén) |
created_at |
TIMESTAMPTZ |
Létrehozás időbélyege |
Indexek:
idx_user_contributions_user(user_id,service_fingerprint,action_type)idx_user_contributions_cooldown(cooldown_end) WHEREcooldown_end > NOW()
Alembic terv:
CREATE TABLE gamification.user_contributions (
id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
user_id INTEGER NOT NULL REFERENCES identity.users(id) ON DELETE CASCADE,
service_fingerprint VARCHAR(255) NOT NULL,
action_type VARCHAR(30) NOT NULL,
earned_xp INTEGER NOT NULL DEFAULT 0,
cooldown_end TIMESTAMPTZ NOT NULL,
created_at TIMESTAMPTZ DEFAULT NOW()
);
COMMENT ON TABLE gamification.user_contributions IS
'Spam védelem: felhasználók csak 90 naponként kaphatnak XP‑t ugyanazon szerviz beküldéséért.';
3. UserStats bővítés (system.user_stats)
A meglévő táblához új mezők a restrikciós szintek és büntető kvóták kezeléséhez.
| Mező | Típus | Leírás | Alapérték |
|---|---|---|---|
restriction_level |
INTEGER |
0 (normál), -1 (figyelmeztetés), -2 (korlátozott), -3 (banned) | 0 |
penalty_quota_remaining |
INTEGER |
Hátralévő büntető kvóta (pl. 3 strike) | 3 |
banned_until |
TIMESTAMPTZ |
Kitiltás vége (ha restriction_level = -3) | NULL |
Alembic terv (meglévő tábla módosítása):
ALTER TABLE system.user_stats
ADD COLUMN restriction_level INTEGER NOT NULL DEFAULT 0,
ADD COLUMN penalty_quota_remaining INTEGER NOT NULL DEFAULT 3,
ADD COLUMN banned_until TIMESTAMPTZ;
4. ServiceStaging bővítés (marketplace.service_staging)
Hiányzó mezők hozzáadása a teljes adatátvitel érdekében.
| Mező | Típus | Leírás |
|---|---|---|
contact_phone |
VARCHAR |
Telefonszám (Robot 4 vagy user által megadható) |
website |
VARCHAR |
Weboldal URL |
external_id |
VARCHAR |
Külső rendszer azonosító (pl. Google Place ID) |
contact_email |
VARCHAR |
E‑mail cím |
Alembic terv:
ALTER TABLE marketplace.service_staging
ADD COLUMN contact_phone VARCHAR,
ADD COLUMN website VARCHAR,
ADD COLUMN external_id VARCHAR,
ADD COLUMN contact_email VARCHAR;
5. SystemParameter bővítés (system.system_parameters)
Dinamikus küszöbértékek a gamification és moderáció számára.
| Kulcs | Érték (JSON) | Leírás |
|---|---|---|
service_promotion_threshold |
{"trust_score": 50} |
Minimális trust_score a staging → promotionhoz |
xp_reward_base |
{"submit_service": 50, "claim_business": 200} |
Alap XP jutalmak |
penalty_multiplier |
{"level_-1": 0.5, "level_-2": 0.2} |
XP szorzó restrikciós szint szerint |
strike_policy |
{"max_strikes": 3, "cooldown_days": 90} |
Strike‑ok és cooldown beállítások |
Megjegyzés: A meglévő tábla módosítása nem szükséges, csak új rekordok beszúrása.
🛡️ Admin kontroll: Global/Country/Region/User szintű változók
A system.system_parameters tábla scope mezője (global, country, region, user) lehetővé teszi a különböző szintű beállításokat. A Gamification 2.0 paraméterei alapértelmezetten global scope‑kal rendelkeznek, de felülírhatók country vagy region szinten (pl. különböző országokban eltérő trust_score küszöb).
Példa a hierarchiára:
- Global:
service_promotion_threshold = 50 - Country (HU):
service_promotion_threshold = 40(lazább feltételek Magyarországon) - Region (Budapest):
service_promotion_threshold = 60(szigorúbb Budapesten)
A prioritás: user > region > country > global.
🤖 Robot Refactoring Tervek
1. Robot 3 (Enricher) – Logika finomhangolása
Jelenlegi állapot: enrich_ready → researched (trust_score növelés).
Új állapot: enrich_ready → auditor_ready (trust_score növelés, de nem publikál).
Módosítások:
- A státusz neve
auditor_readylegyen, jelezve, hogy az Auditor feldolgozhatja. - A trust_score számítás változatlan marad.
- A robot továbbra is csak a
service_stagingtáblát módosítja.
2. Robot 2 (Auditor) – Új implementáció
Fájl: service_robot_5_auditor.py (vagy service_robot_2_auditor.py)
Feladat: Atom módon feldolgozza az auditor_ready státuszú staging bejegyzéseket.
Lépések:
- Kiválasztás:
FOR UPDATE SKIP LOCKEDegyauditor_readyrekordra. - Küszöb ellenőrzés: Lekéri a
service_promotion_thresholdértékét asystem_parameters‑ből. - Döntés:
- Ha
trust_score >= küszöb:- Organization létrehozása (ha még nem létezik) a
fleet.organizationstáblában. - ServiceProfile létrehozása a
marketplace.service_profilestáblában, a staging adatokkal. - Státusz beállítása
pending_validation(vagyactive, ha azonnal publikálható). - Audit log rögzítése (
audit.service_audit_log).
- Organization létrehozása (ha még nem létezik) a
- Egyébként:
- Státusz beállítása
needs_moderation. - InternalNotification létrehozása a moderátorok számára.
- Státusz beállítása
- Ha
- Staging frissítés: Státusz
audited,audited_atidőbélyeg.
Technikai részletek:
- Tranzakció használata (minden lépés egy tranzakcióban).
- Hibakezelés: hiba esetén
status = 'error'és logolás. - Időzítés: folyamatos feldolgozás (pl. 30 másodperces ciklus).
3. Robot 4 (Validator) – Integráció
A Validator továbbra is a service_profiles táblán dolgozik, de ha a rekord pending_validation státuszú, a Validator frissítheti a hiányzó mezőket (contact_phone, website) a Google Places API‑ból, majd átállítja active‑ra.
🔧 SystemParameter integráció
A Gamification 2.0 minden dinamikus értékét a system.system_parameters táblából olvassa ki. Ez lehetővé teszi a rendszer finomhangolását anélkül, hogy kódot kellene módosítani.
Példa lekérdezésre:
async def get_promotion_threshold(db):
param = await db.scalar(
select(SystemParameter)
.where(SystemParameter.key == 'service_promotion_threshold')
.where(SystemParameter.scope == 'global')
)
if param:
return param.value.get('trust_score', 50)
return 50
📝 Geo‑logika (Service Finder algoritmus)
A Service Finder alapvetően lokáció‑alapú keresést valósít meg. A Gamification 2.0 nem módosítja a keresési algoritmust, de befolyásolja a találatok minőségét:
- Trust Score súlyozás: Magasabb trust_score‑ú szervizek magasabbra kerülnek a találati listában.
- Szezonális bónusz: Aktív szezonban beküldött szervizek extra láthatóságot kaphatnak.
- Restrikciók:
restriction_level < 0esetén a felhasználó beküldései nem jelennek meg, amíg a korlátozás fennáll.
🚀 Migrációs lépések (Alembic)
- Új táblák létrehozása:
system.seasonsgamification.user_contributions
- Meglévő táblák bővítése:
system.user_stats(új mezők)marketplace.service_staging(hiányzó mezők)
- Alapértelmezett paraméterek beszúrása:
service_promotion_threshold,xp_reward_base,penalty_multiplier,strike_policy
- Robot kód frissítése:
- Robot 3 státusz átnevezése
auditor_ready‑re. - Robot 5 (Auditor) implementálása.
- Robot 4 integrációja a
pending_validationstátusszal.
- Robot 3 státusz átnevezése
✅ Jóváhagyási pont
Ez a logic specifikáció a Modell Fázis (Foundation) teljes tervét tartalmazza. A következő lépés a tervek implementálása a Code módban. Állj meg és kérj jóváhagyást a felhasználótól, mielőtt továbblépsz.
Ez a dokumentum a /plans könyvtárban található, és a 8. mérföldkő technikai specifikációjaként szolgál.
Rendszerszintű adminisztrációs fejlesztések: hierarchikus paraméterek, audit log, konfigurációk, jogosultságok.
Complete integration of Admin Dashboard frontend with backend APIs. Replace mock data with real endpoints, connect all tiles and tables, ensure real-time monitoring works.
Implementing and wiring the backend APIs required for the Epic 11 Public Frontend (Vehicle CRUD, Expenses, Dual-UI preferences, Gamification, and Analytics).