# 8. Mérföldkő: Gamification 2.0, Verseny és Önvédelmi Rendszer

**Állapot:** Tervezés alatt  
**Kezdés dátuma:** 2026-03-15  
**Befejezés határideje:** 2026-04-15 (becsült)  
**Felelős:** Backend Architekt, Gamification Team

## 🎯 Célok
1. A meglévő Gamification rendszer kibővítése szezonális versenyekkel és önvédelmi mechanizmusokkal.
2. A Service Finder robot pipeline hibáinak kijavítása (Robot 3, sémaeltérés, hiányzó Auditor).
3. A felhasználók által beküldött szervizek biztonságos és ellenőrzött átjuttatása a productionba.
4. Moderációs és büntető rendszer bevezetése a spam és rosszindulatú beküldések kezelésére.

## 📋 Feladatlista

### 1. Adatbázis & Modell Fázis (Foundation)

- [ ] **Season tábla:** Féléves versenyek tárolása.
  - `id`, `name`, `start_date`, `end_date`, `is_active`
  - Séma: `system.seasons`
- [ ] **UserContribution tábla:** Spam védelem és cooldown kezelés.
  - `user_id`, `service_fingerprint`, `action_type`, `earned_xp`, `cooldown_end`
  - Séma: `gamification.user_contributions`
- [ ] **UserStats bővítés:** Restrikciós szintek és büntető kvóták.
  - `restriction_level` (0, -1, -2, -3)
  - `penalty_quota_remaining`
  - `banned_until`
  - Séma: `system.user_stats` (meglévő tábla)
- [ ] **SystemParameter integráció:** Dinamikus küszöbök tárolása.
  - `key`: `promotion_threshold`, `xp_reward_base`, `penalty_multiplier`
  - `value`: JSON konfiguráció
  - Séma: `system.system_parameters` (meglévő)

### 2. Worker Refactoring (The Pipeline)

- [ ] **Robot 3 (Enricher) átírása:** Ne publikáljon! Csak növelje a trust_score-t a stagingben a talált szakmák alapján → státusz: `auditor_ready`.
  - Cél: A jelenlegi `researched` státusz helyett `auditor_ready` legyen, jelezve, hogy az Auditor feldolgozhatja.
  - Függőség: Hiányzó Auditor robot (lásd alább).
- [ ] **Robot 2 (Auditor) implementálása:** Staging → Production átemelés.
  - Olvassa ki a küszöböt a `system_parameters`-ből.
  - Ha a trust_score elég magas:
    - Organization létrehozása (Digital Twin).
    - ServiceProfile létrehozása a staging adatok alapján.
    - Státusz átállítás `active` vagy `pending_validation`.
  - Ha nem igazolható az adat: InternalNotification a moderátoroknak.
  - Audit log rögzítése.
- [ ] **Séma bővítés:** A `service_staging` táblához hiányzó mezők hozzáadása.
  - `contact_phone`, `website`, `external_id`, `contact_email`
  - Migráció: Alembic szkript.

### 3. Gamification API & Verseny (Logic)

- [ ] **POST /submit-service:** User szint ellenőrzés, 90 napos cooldown check, büntetési szorzók.
  - Ellenőrzés: `restriction_level` alapján XP szorzó (-1 szint = 50% XP, -2 szint = 20% XP).
  - Cooldown: `UserContribution` tábla alapján, ugyanazon fingerprint esetén.
  - XP jutalom: `SystemParameter` alapján, korrigálva a büntetési szorzóval.
- [ ] **GET /leaderboard:** Szezonális toplista.
  - Szezon kiválasztása (`is_active = TRUE`).
  - Rangsorolás: Szezonális XP alapján.
  - Adatvédelem: Maszkolt e-mail címek (`a***@domain.com`).
- [ ] **POST /claim-business:** Tulajdonosi igénylés indítása.
  - Feltétel: `trust_score ≥ 100` és `is_verified = TRUE`.
  - Moderátori jóváhagyás szükséges.
  - Jogosultság átadása a kérvényező felhasználónak.

### 4. Moderáció & Admin (Protection)

- [ ] **Büntető mechanizmus:** Ha a Robot 4 vagy moderátor hibás adatot talál → User strike → `restriction_level` csökkentés.
  - Strikes tárolása: `gamification.user_strikes`.
  - Automatikus szintcsökkentés: 3 strikes → `restriction_level -1`.
- [ ] **Admin funkció:** Büntetési kvóták és XP értékek állítása a `SystemParameter` táblán keresztül.
  - Admin UI: Paraméterek szerkesztése (küszöbértékek, szorzók, cooldown idő).
- [ ] **Moderátori értesítések:** InternalNotification rendszer bővítése.
  - Értesítési csatornák: email, in-app, push (opcionális).

## 🗺️ Kapcsolódó Gitea Kártyák
- #76: Hibás Robot 3 (Enricher) – közvetlen publikálás a service_profiles táblába (LEZÁRVA)
- #77: Service Staging tábla hiányzó mezői (contact_phone, website, external_id) (LEZÁRVA)
- #78: Hiányzó Auditor robot a staging -> production átvitelhez (LEZÁRVA)

## 🔗 Függőségek
- **Meglévő rendszer:** Gamification API (`/my-stats`, `/leaderboard`, `/submit-service`), Service robot pipeline (0–4), SystemParameter tábla.
- **Külső rendszerek:** Google Places API (Robot 4), Docker környezet, PostgreSQL adatbázis.

## 🚀 Megvalósítási Lépések
1. **Adatbázis migrációk** (Alembic) – Season, UserContribution, UserStats bővítés, service_staging mezők.
2. **Robot refactoring** – Robot 3 logika finomhangolása, Robot 2 (Auditor) implementálása.
3. **API bővítés** – Új végpontok, meglévők módosítása (submit-service, leaderboard, claim-business).
4. **Moderációs rendszer** – Strikes kezelés, admin felület integráció.
5. **Tesztelés** – Egységtesztek, integrációs tesztek, teljes pipeline teszt.
6. **Dokumentáció** – API dokumentáció, robot leírások, admin útmutató.

## ⚠️ Kockázatok
- **Adatbázis séma változás:** Meglévő adatok migrálása szükséges lehet.
- **Robot függőségek:** Ha az Auditor robot hibás, a staging adatok felhalmozódnak.
- **Teljesítmény:** A leaderboard lekérdezés nagy adatmennyiség esetén lassú lehet (indexelés, gyorsítótárazás).

## ✅ Sikeresség Mérésére
- A staging → production átvitel sikeresen működik (napi X szerviz publikálása).
- A spam beküldések száma csökken (strikes rendszer hatékonysága).
- A felhasználói engagement növekszik (XP, ranglétrák, versenyek).

---
*Ez a dokumentum a projekt gyökerében található, és a 8. mérföldkő tervezési fázisát rögzíti. A tényleges megvalósítás előtt az Architect és a Code csapat felülvizsgálja.*