átlagos kiegészítséek jó sok

MILESTONE_8_GAMIFICATION_PRO.md

@@ -0,0 +1,104 @@
+# 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.*