service-finder/MILESTONE_8_GAMIFICATION_PRO.md

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.