gemification_admin bekötve

backend/app/api/v1/api.py

@@ -7,6 +7,7 @@ from app.api.v1.endpoints import (
     gamification, translations, users, reports, dictionaries,
     admin_packages, admin_services, admin_organizations, admin_users, admin_persons, constants, providers,
     subscriptions, marketing, admin_permissions, regions,
+    admin_gamification,
 )
 
 api_router = APIRouter()
@@ -43,4 +44,5 @@ api_router.include_router(constants.router, prefix="/constants", tags=["Constant
 api_router.include_router(providers.router, prefix="/providers", tags=["Providers"])
 api_router.include_router(subscriptions.router, prefix="/subscriptions", tags=["Subscriptions"])
 api_router.include_router(marketing.router, prefix="/marketing", tags=["Marketing & Ads"])
-api_router.include_router(admin_permissions.router, prefix="", tags=["Admin Permissions (RBAC)"])
+api_router.include_router(admin_permissions.router, prefix="", tags=["Admin Permissions (RBAC)"])
+api_router.include_router(admin_gamification.router, prefix="/admin/gamification", tags=["Admin Gamification"])

backend/app/api/v1/endpoints/admin.py

@@ -1,4 +1,5 @@
 # /opt/docker/dev/service_finder/backend/app/api/v1/endpoints/admin.py
+import logging
 from fastapi import APIRouter, Depends, HTTPException, status, Body, BackgroundTasks, Query
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, func, text, delete, or_
@@ -6,6 +7,8 @@ from sqlalchemy.orm import selectinload
 from typing import List, Any, Dict, Optional
 from datetime import datetime, timedelta, timezone
 
+logger = logging.getLogger("admin-endpoints")
+
 from app.api import deps
 from app.models.identity import User, UserRole, Person # JAVÍTVA: Központi import
 from app.models.identity.address import Address
@@ -79,7 +82,7 @@ async def approve_action(
     _ = Depends(deps.RequirePermission("settings:edit")),
 ):
     try:
-        await security_service.approve_action(db, admin.id, action_id)
+        await security_service.approve_action(db, current_user.id, action_id)
         return {"status": "success", "message": "Művelet végrehajtva."}
     except Exception as e:
         raise HTTPException(status_code=400, detail=str(e))
@@ -420,8 +423,12 @@ async def apply_gamification_penalty(
     """
     Gamification büntetés kiosztása egy felhasználónak.
     
-    Negatív szintek alkalmazása a frissen létrehozott Gamification rendszerben.
+    REFAKTOR: Most a GamificationService process_activity() metódusát használja
+    is_penalty=True paraméterrel, a direkt level módosítás helyett.
+    A penalty_level (negatív szám) átalakításra kerül penalty_points értékké.
     """
+    from app.services.gamification_service import gamification_service
+    
     # Ellenőrizzük, hogy létezik-e a felhasználó
     user_stmt = select(User).where(User.id == user_id)
     user_result = await db.execute(user_stmt)
@@ -433,50 +440,54 @@ async def apply_gamification_penalty(
             detail=f"User not found with ID: {user_id}"
         )
     
-    # Megkeressük a felhasználó gamification profilját (vagy létrehozzuk)
-    gamification_stmt = select(UserStats).where(UserStats.user_id == user_id)
-    gamification_result = await db.execute(gamification_stmt)
-    gamification = gamification_result.scalar_one_or_none()
+    # A penalty_level (pl. -3) átalakítása penalty_points értékké
+    # A régi rendszerben a penalty_level negatív szint volt (-1, -2, -3)
+    # Az új rendszerben penalty_points-ban mérjük (abs(penalty_level) * 100)
+    penalty_amount = abs(penalty.penalty_level) * 100
     
-    if not gamification:
-        # Ha nincs profil, létrehozzuk alapértelmezett értékekkel
-        gamification = UserStats(
+    try:
+        # GamificationService használata a büntetéshez
+        stats = await gamification_service.process_activity(
+            db=db,
             user_id=user_id,
-            level=0,
-            xp=0,
-            reputation_score=100,
-            created_at=datetime.now(),
-            updated_at=datetime.now()
+            xp_amount=penalty_amount,
+            social_amount=0,
+            reason=f"ADMIN_PENALTY: {penalty.reason}",
+            is_penalty=True,
+            commit=False,  # Ne commitoljon, mert még audit logot is hozzáadunk
+            action_key=None,
+            source_type="admin_penalty",
+            source_id=current_user.id,
+        )
+        
+        # Audit log - SecurityAuditLog has actor_id, target_id, payload_before/payload_after
+        audit_log = SecurityAuditLog(
+            actor_id=current_user.id,
+            action="apply_gamification_penalty",
+            target_id=user_id,
+            payload_before={},
+            payload_after={"penalty_points_added": penalty_amount, "reason": penalty.reason},
+            is_critical=False,
+        )
+        db.add(audit_log)
+        await db.commit()
+        
+        return {
+            "status": "success",
+            "message": f"Gamification penalty applied to user {user_id}",
+            "user_id": user_id,
+            "penalty_points_added": penalty_amount,
+            "total_penalty_points": stats.penalty_points,
+            "restriction_level": stats.restriction_level,
+            "reason": penalty.reason
+        }
+    except Exception as e:
+        await db.rollback()
+        logger.error(f"Failed to apply penalty to user {user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to apply penalty: {str(e)}",
         )
-        db.add(gamification)
-        await db.flush()
-    
-    # Alkalmazzuk a büntetést (negatív szint módosítása)
-    # A level mező lehet negatív is a büntetések miatt
-    new_level = gamification.level + penalty.penalty_level
-    gamification.level = new_level
-    gamification.updated_at = datetime.now()
-    
-    # Audit log
-    audit_log = SecurityAuditLog(
-        user_id=current_user.id,
-        action="apply_gamification_penalty",
-        target_user_id=user_id,
-        details=f"Gamification penalty applied: level change {penalty.penalty_level}, reason: {penalty.reason}",
-        is_critical=False,
-        ip_address="admin_api"
-    )
-    db.add(audit_log)
-    await db.commit()
-    
-    return {
-        "status": "success",
-        "message": f"Gamification penalty applied to user {user_id}",
-        "user_id": user_id,
-        "penalty_level": penalty.penalty_level,
-        "new_level": new_level,
-        "reason": penalty.reason
-    }
 
 
 # ==================== USER MANAGEMENT (EPIC 10: Admin Frontend) ====================

backend/app/api/v1/endpoints/gamification.py

@@ -1,10 +1,13 @@
 # /opt/docker/dev/service_finder/backend/app/api/v1/endpoints/gamification.py
+import logging
 from fastapi import APIRouter, Depends, HTTPException, Body, Query
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, desc, func, and_
 from typing import List, Optional
 from datetime import datetime, timedelta
 
+logger = logging.getLogger("gamification-endpoints")
+
 from app.db.session import get_db
 from app.api.deps import get_current_user
 from app.models.identity import User
@@ -12,6 +15,7 @@ from app.models import UserStats, PointsLedger, LevelConfig, UserContribution, B
 from app.models.system import SystemParameter, ParameterScope
 from app.models.marketplace.service import ServiceStaging
 from app.schemas.gamification import SeasonResponse, UserStatResponse, LeaderboardEntry
+from app.core.i18n import t
 
 router = APIRouter()
 
@@ -140,7 +144,7 @@ async def get_season_standings(
     season = (await db.execute(season_stmt)).scalar_one_or_none()
     
     if not season:
-        raise HTTPException(status_code=404, detail="Season not found")
+        raise HTTPException(status_code=404, detail=t("GAMIFICATION.SEASON.NOT_FOUND"))
     
     # Top hozzájárulók lekérdezése
     stmt = (
@@ -267,36 +271,31 @@ async def get_self_defense_status(
 # --- AZ ÚJ, DINAMIKUS BEKÜLDŐ VÉGPONT (Gamification 2.0 kompatibilis) ---
 @router.post("/submit-service")
 async def submit_new_service(
-    name: str = Body(...), 
-    city: str = Body(...), 
+    name: str = Body(...),
+    city: str = Body(...),
     address: str = Body(...),
     contact_phone: Optional[str] = Body(None),
     website: Optional[str] = Body(None),
     description: Optional[str] = Body(None),
-    db: AsyncSession = Depends(get_db), 
+    db: AsyncSession = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
+    from app.services.gamification_service import gamification_service
+    
     # 1. Önvédelmi státusz ellenőrzése
     defense_status = await get_self_defense_status(db, current_user)
     if not defense_status["can_submit_services"]:
         raise HTTPException(
-            status_code=403, 
-            detail="Önvédelmi korlátozás miatt nem küldhetsz be új szerviz adatokat."
+            status_code=403,
+            detail=t("GAMIFICATION.SUBMIT_SERVICE.SELF_DEFENSE_BLOCKED")
         )
     
     # 2. Beállítások lekérése az Admin által vezérelt táblából
     submission_rewards = await get_system_param(
-        db, "service_submission_rewards", 
+        db, "service_submission_rewards",
         {"points": 50, "xp": 100, "social_credits": 10}
     )
     
-    contribution_config = await get_system_param(
-        db, "contribution_types_config",
-        {
-            "service_submission": {"points": 50, "xp": 100, "weight": 1.0}
-        }
-    )
-    
     # 3. Aktuális szezon lekérdezése
     season_stmt = select(Season).where(
         and_(
@@ -351,50 +350,41 @@ async def submit_new_service(
         points_awarded=submission_rewards.get("points", 50),
         xp_awarded=submission_rewards.get("xp", 100),
         status="pending",  # Robot 5 jóváhagyására vár
-        metadata={
+        provided_fields={
             "service_name": name,
             "city": city,
             "staging_id": new_staging.id
         },
-        created_at=datetime.utcnow()
+        action_type=1,
+        earned_xp=submission_rewards.get("xp", 100),
     )
     db.add(contribution)
     
-    # 8. PointsLedger bejegyzés
-    ledger = PointsLedger(
-        user_id=current_user.id,
-        points=submission_rewards.get("points", 50),
-        xp=submission_rewards.get("xp", 100),
-        source_type="service_submission",
-        source_id=new_staging.id,
-        description=f"Szerviz beküldés: {name}",
-        created_at=datetime.utcnow()
-    )
-    db.add(ledger)
-    
-    # 9. UserStats frissítése
-    if stats:
-        stats.total_points += submission_rewards.get("points", 50)
-        stats.total_xp += submission_rewards.get("xp", 100)
-        stats.services_submitted += 1
-        stats.updated_at = datetime.utcnow()
-    else:
-        # Ha nincs még UserStats, létrehozzuk
-        stats = UserStats(
+    # 8. GamificationService hívás a pontok jóváírásához (a direkt UserStats módosítás helyett)
+    # A GamificationService kezeli a szorzókat, szintlépést, recovery-t és naplózást
+    try:
+        await gamification_service.process_activity(
+            db=db,
             user_id=current_user.id,
-            total_points=submission_rewards.get("points", 50),
-            total_xp=submission_rewards.get("xp", 100),
-            services_submitted=1,
-            created_at=datetime.utcnow(),
-            updated_at=datetime.utcnow()
+            xp_amount=submission_rewards.get("xp", 100),
+            social_amount=submission_rewards.get("social_credits", 10),
+            reason=f"SERVICE_SUBMISSION: {name}",
+            is_penalty=False,
+            commit=False,  # Ne commitoljon, mert a contribution-t is hozzáadjuk
+            action_key="service_submission",
+            source_type="service_submission",
+            source_id=new_staging.id,
         )
-        db.add(stats)
+    except Exception as e:
+        await db.rollback()
+        logger.error(f"GamificationService error during service submission for user {current_user.id}: {e}")
+        raise HTTPException(status_code=400, detail=t("GAMIFICATION.SUBMIT_SERVICE.POINTS_ERROR", error=str(e)))
     
     try:
         await db.commit()
         return {
-            "status": "success", 
-            "message": "Szerviz beküldve a rendszerbe elemzésre!", 
+            "status": "success",
+            "message": t("GAMIFICATION.SUBMIT_SERVICE.SUCCESS"),
             "xp_earned": submission_rewards.get("xp", 100),
             "points_earned": submission_rewards.get("points", 50),
             "staging_id": new_staging.id,
@@ -402,7 +392,7 @@ async def submit_new_service(
         }
     except Exception as e:
         await db.rollback()
-        raise HTTPException(status_code=400, detail=f"Hiba a beküldés során: {str(e)}")
+        raise HTTPException(status_code=400, detail=t("GAMIFICATION.SUBMIT_SERVICE.SUBMIT_ERROR", error=str(e)))
 
 
 # --- Gamification 2.0 API végpontok (Frontend/Mobil) ---
@@ -441,7 +431,7 @@ async def get_active_season(
     stmt = select(Season).where(Season.is_active == True)
     season = (await db.execute(stmt)).scalar_one_or_none()
     if not season:
-        raise HTTPException(status_code=404, detail="No active season found")
+        raise HTTPException(status_code=404, detail=t("GAMIFICATION.SEASON.NO_ACTIVE"))
     return SeasonResponse.from_orm(season)
 
 
@@ -499,33 +489,13 @@ async def get_daily_quiz(
     if already_played:
         raise HTTPException(
             status_code=400,
-            detail="You have already played the daily quiz today. Try again tomorrow."
+            detail=t("GAMIFICATION.QUIZ.ALREADY_PLAYED")
         )
     
-    # Return quiz questions (for now, using mock questions - in production these would come from a database)
-    quiz_questions = [
-        {
-            "id": 1,
-            "question": "Melyik alkatrész felelős a motor levegő‑üzemanyag keverékének szabályozásáért?",
-            "options": ["Generátor", "Lambda‑szonda", "Féktárcsa", "Olajszűrő"],
-            "correctAnswer": 1,
-            "explanation": "A lambda‑szonda méri a kipufogógáz oxigéntartalmát, és ezen alapul a befecskendezés."
-        },
-        {
-            "id": 2,
-            "question": "Mennyi ideig érvényes egy gépjármű műszaki vizsgája Magyarországon?",
-            "options": ["1 év", "2 év", "4 év", "6 év"],
-            "correctAnswer": 1,
-            "explanation": "A személygépkocsik műszaki vizsgája 2 évre érvényes, kivéve az újonnan forgalomba helyezett autókat."
-        },
-        {
-            "id": 3,
-            "question": "Melyik anyag NEM része a hibrid autók akkumulátorának?",
-            "options": ["Lítium", "Nikkel", "Ólom", "Kobalt"],
-            "correctAnswer": 2,
-            "explanation": "A hibrid és elektromos autók akkumulátoraiban általában lítium, nikkel és kobalt található, ólom az ólom‑savas akkukban van."
-        }
-    ]
+    # Load quiz questions from JSON locale files (i18n)
+    from app.core.i18n import get_quiz_data
+    quiz_data = get_quiz_data()
+    quiz_questions = quiz_data.get("questions", [])
     
     return {
         "questions": quiz_questions,
@@ -557,48 +527,50 @@ async def submit_quiz_answer(
     if already_played:
         raise HTTPException(
             status_code=400,
-            detail="You have already played the daily quiz today. Try again tomorrow."
+            detail=t("GAMIFICATION.QUIZ.ALREADY_PLAYED")
         )
     
-    # Mock quiz data - in production this would come from a database
-    quiz_data = {
-        1: {"correct_answer": 1, "points": 10, "explanation": "A lambda‑szonda méri a kipufogógáz oxigéntartalmát, és ezen alapul a befecskendezés."},
-        2: {"correct_answer": 1, "points": 10, "explanation": "A személygépkocsik műszaki vizsgája 2 évre érvényes, kivéve az újonnan forgalomba helyezett autókat."},
-        3: {"correct_answer": 2, "points": 10, "explanation": "A hibrid és elektromos autók akkumulátoraiban általában lítium, nikkel és kobalt található, ólom az ólom‑savas akkukban van."}
-    }
+    # Load quiz data from JSON locale files (i18n)
+    from app.core.i18n import get_quiz_data
+    quiz_locale = get_quiz_data()
+    quiz_questions = quiz_locale.get("questions", [])
     
-    if question_id not in quiz_data:
-        raise HTTPException(status_code=404, detail="Question not found")
+    # Build lookup dict from questions list
+    quiz_lookup = {}
+    for q in quiz_questions:
+        quiz_lookup[q["id"]] = {
+            "correct_answer": q["correctAnswer"],
+            "points": 10,
+            "explanation": q["explanation"]
+        }
     
-    question_info = quiz_data[question_id]
+    if question_id not in quiz_lookup:
+        raise HTTPException(status_code=404, detail=t("GAMIFICATION.QUIZ.QUESTION_NOT_FOUND"))
+    
+    question_info = quiz_lookup[question_id]
     is_correct = selected_option == question_info["correct_answer"]
     
-    # Award points if correct
+    # Award points if correct (GamificationService-en keresztül)
     if is_correct:
-        # Update user stats
-        stats_stmt = select(UserStats).where(UserStats.user_id == current_user.id)
-        stats_result = await db.execute(stats_stmt)
-        user_stats = stats_result.scalar_one_or_none()
+        from app.services.gamification_service import gamification_service
         
-        if not user_stats:
-            # Create user stats if they don't exist
-            user_stats = UserStats(
+        try:
+            await gamification_service.process_activity(
+                db=db,
                 user_id=current_user.id,
-                total_xp=question_info["points"],
-                current_level=1
+                xp_amount=question_info["points"],
+                social_amount=0,
+                reason=f"DAILY_QUIZ: Question {question_id}",
+                is_penalty=False,
+                commit=False,
+                action_key="daily_quiz_correct",
+                source_type="daily_quiz",
+                source_id=question_id,
             )
-            db.add(user_stats)
-        else:
-            user_stats.total_xp += question_info["points"]
-        
-        # Add points ledger entry
-        points_ledger = PointsLedger(
-            user_id=current_user.id,
-            points=question_info["points"],
-            reason=f"Daily quiz correct answer - Question {question_id}",
-            created_at=datetime.now()
-        )
-        db.add(points_ledger)
+        except Exception as e:
+            await db.rollback()
+            logger.error(f"GamificationService error during quiz answer for user {current_user.id}: {e}")
+            raise HTTPException(status_code=500, detail=t("GAMIFICATION.QUIZ.POINTS_FAILED", error=str(e)))
         
         await db.commit()
     
@@ -633,7 +605,7 @@ async def complete_daily_quiz(
     if already_completed:
         raise HTTPException(
             status_code=400,
-            detail="Daily quiz already marked as completed today."
+            detail=t("GAMIFICATION.QUIZ.ALREADY_COMPLETED")
         )
     
     # Add completion entry
@@ -646,7 +618,7 @@ async def complete_daily_quiz(
     db.add(completion_ledger)
     await db.commit()
     
-    return {"message": "Daily quiz marked as completed for today."}
+    return {"message": t("GAMIFICATION.QUIZ.COMPLETED_SUCCESS")}
 
 
 @router.get("/quiz/stats")
@@ -775,7 +747,7 @@ async def award_badge_to_user(
     badge = badge_result.scalar_one_or_none()
     
     if not badge:
-        raise HTTPException(status_code=404, detail="Badge not found")
+        raise HTTPException(status_code=404, detail=t("GAMIFICATION.BADGE.NOT_FOUND"))
     
     # Determine target user (default to current user if not specified)
     target_user_id = user_id if user_id else current_user.id
@@ -789,7 +761,7 @@ async def award_badge_to_user(
     existing = existing_result.scalar_one_or_none()
     
     if existing:
-        raise HTTPException(status_code=400, detail="User already has this badge")
+        raise HTTPException(status_code=400, detail=t("GAMIFICATION.BADGE.ALREADY_AWARDED"))
     
     # Award the badge
     user_badge = UserBadge(
@@ -799,34 +771,31 @@ async def award_badge_to_user(
     )
     db.add(user_badge)
     
-    # Also add points for earning a badge
-    points_ledger = PointsLedger(
-        user_id=target_user_id,
-        points=50,  # Points for earning a badge
-        reason=f"Badge earned: {badge.name}",
-        created_at=datetime.now()
-    )
-    db.add(points_ledger)
+    # Award points via GamificationService (a direkt UserStats módosítás helyett)
+    from app.services.gamification_service import gamification_service
     
-    # Update user stats
-    stats_stmt = select(UserStats).where(UserStats.user_id == target_user_id)
-    stats_result = await db.execute(stats_stmt)
-    user_stats = stats_result.scalar_one_or_none()
-    
-    if user_stats:
-        user_stats.total_xp += 50
-    else:
-        user_stats = UserStats(
+    try:
+        await gamification_service.process_activity(
+            db=db,
             user_id=target_user_id,
-            total_xp=50,
-            current_level=1
+            xp_amount=50,
+            social_amount=0,
+            reason=f"BADGE_EARNED: {badge.name}",
+            is_penalty=False,
+            commit=False,
+            action_key="badge_earned",
+            source_type="badge",
+            source_id=badge_id,
         )
-        db.add(user_stats)
+    except Exception as e:
+        await db.rollback()
+        logger.error(f"GamificationService error during badge award for user {target_user_id}: {e}")
+        raise HTTPException(status_code=500, detail=t("GAMIFICATION.BADGE.POINTS_FAILED", error=str(e)))
     
     await db.commit()
     
     return {
-        "message": f"Badge '{badge.name}' awarded to user",
+        "message": t("GAMIFICATION.BADGE.AWARDED_SUCCESS", badge_name=badge.name),
         "badge_id": badge.id,
         "badge_name": badge.name,
         "points_awarded": 50
@@ -873,10 +842,10 @@ async def get_achievements_progress(
     
     # XP-based achievements
     xp_levels = [
-        {"title": "Novice", "xp_required": 100, "description": "Earn 100 XP"},
-        {"title": "Apprentice", "xp_required": 500, "description": "Earn 500 XP"},
-        {"title": "Expert", "xp_required": 2000, "description": "Earn 2000 XP"},
-        {"title": "Master", "xp_required": 5000, "description": "Earn 5000 XP"},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.XP_NOVICE"), "xp_required": 100, "description": t("GAMIFICATION.ACHIEVEMENTS.XP_NOVICE_DESC")},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.XP_APPRENTICE"), "xp_required": 500, "description": t("GAMIFICATION.ACHIEVEMENTS.XP_APPRENTICE_DESC")},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.XP_EXPERT"), "xp_required": 2000, "description": t("GAMIFICATION.ACHIEVEMENTS.XP_EXPERT_DESC")},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.XP_MASTER"), "xp_required": 5000, "description": t("GAMIFICATION.ACHIEVEMENTS.XP_MASTER_DESC")},
     ]
     
     current_xp = user_stats.total_xp if user_stats else 0
@@ -901,9 +870,9 @@ async def get_achievements_progress(
     quiz_points = quiz_points_result.scalar() or 0
     
     quiz_achievements = [
-        {"title": "Quiz Beginner", "points_required": 50, "description": "Earn 50 quiz points"},
-        {"title": "Quiz Enthusiast", "points_required": 200, "description": "Earn 200 quiz points"},
-        {"title": "Quiz Master", "points_required": 500, "description": "Earn 500 quiz points"},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_BEGINNER"), "points_required": 50, "description": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_BEGINNER_DESC")},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_ENTHUSIAST"), "points_required": 200, "description": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_ENTHUSIAST_DESC")},
+        {"title": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_MASTER"), "points_required": 500, "description": t("GAMIFICATION.ACHIEVEMENTS.QUIZ_MASTER_DESC")},
     ]
     
     for achievement in quiz_achievements:

backend/app/core/i18n.py

@@ -1,53 +1,332 @@
 # /opt/docker/dev/service_finder/backend/app/core/i18n.py
+"""
+Backend i18n helper module.
+
+Loads locale JSON files from backend/static/locales/ into a cached dictionary,
+provides dot-notation key resolution with variable interpolation,
+and integrates with the request-scoped context locale system.
+
+Usage:
+    from app.core.i18n import t, get_locale
+
+    # With explicit language
+    msg = t("AUTH.LOGIN.SUCCESS", lang="en")
+
+    # With variable interpolation
+    msg = t("EMAIL.REG.GREETING", lang="hu", first_name="Péter")
+
+    # Using request context locale (set by I18nMiddleware)
+    msg = t("COMMON.SAVE_SUCCESS")
+
+    # Get full locale dictionary
+    locale_data = get_locale("en")
+"""
 import json
 import os
+import logging
+from typing import Dict, Any, Optional
 
-class LocaleManager:
-    _locales = {}
+logger = logging.getLogger(__name__)
 
-    def get(self, key: str, lang: str = "hu", **kwargs) -> str:
-        if not self._locales:
-            self._load()
-        
-        data = self._locales.get(lang, self._locales.get("hu", {}))
-        # Biztonságos bejárás a pontokkal elválasztott kulcsokhoz
-        for k in key.split("."):
-            if isinstance(data, dict):
-                data = data.get(k, {})
-            else:
-                return key # Ha elakadunk, adjuk vissza magát a kulcsot
-        
-        if isinstance(data, str):
-            return data.format(**kwargs)
-        return key
+# ── Locale file directory ──────────────────────────────────────────────
+# In the Docker container, the static directory is mounted at:
+#   /app/backend/static/locales/
+# We search multiple possible paths to cover both container and local dev.
+_LOCALE_PATHS = [
+    "/app/backend/static/locales",          # Docker container (sf_api)
+    "/opt/docker/dev/service_finder/backend/static/locales",  # Host / dev
+    "backend/static/locales",               # Relative from project root
+    "static/locales",                       # Relative from backend/
+]
 
-    def _load(self):
-        # A konténeren belül ez a biztos útvonal
-        possible_paths = [
-            "/app/app/locales",
-            "app/locales",
-            "backend/app/locales"
-        ]
-        
-        path = ""
-        for p in possible_paths:
-            if os.path.exists(p):
-                path = p
-                break
-        
-        if not path:
-            print("FIGYELEM: Nem található a locales könyvtár!")
-            return
+# ── In-memory cache ────────────────────────────────────────────────────
+_locale_cache: Dict[str, Dict[str, Any]] = {}
+_cache_loaded: bool = False
 
-        for file in os.listdir(path):
-            if file.endswith(".json"):
-                lang = file.split(".")[0]
-                try:
-                    with open(os.path.join(path, file), "r", encoding="utf-8") as f:
-                        self._locales[lang] = json.load(f)
-                except Exception as e:
-                    print(f"Hiba a {file} betöltésekor: {e}")
 
-locale_manager = LocaleManager()
-# Rövid alias a könnyebb használathoz
-t = locale_manager.get
+def _discover_locale_path() -> Optional[str]:
+    """Find the first existing locale directory."""
+    for path in _LOCALE_PATHS:
+        if os.path.isdir(path):
+            logger.debug("i18n locale directory found: %s", path)
+            return path
+    logger.warning("i18n: No locale directory found among %s", _LOCALE_PATHS)
+    return None
+
+
+def _load_locales(force: bool = False) -> None:
+    """
+    Load all JSON locale files from the discovered locale directory
+    into the in-memory cache.
+
+    Args:
+        force: If True, reload even if cache is already populated.
+    """
+    global _cache_loaded
+    if _cache_loaded and not force:
+        return
+
+    path = _discover_locale_path()
+    if not path:
+        _locale_cache.clear()
+        _cache_loaded = True
+        return
+
+    loaded: Dict[str, Dict[str, Any]] = {}
+    for filename in os.listdir(path):
+        if not filename.endswith(".json"):
+            continue
+        lang = filename[:-5]  # strip ".json"
+        filepath = os.path.join(path, filename)
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                loaded[lang] = json.load(f)
+            logger.debug("i18n: Loaded locale '%s' from %s (%d keys)", lang, filepath, _count_keys(loaded[lang]))
+        except Exception as exc:
+            logger.error("i18n: Failed to load locale file %s: %s", filepath, exc)
+
+    _locale_cache.clear()
+    _locale_cache.update(loaded)
+    _cache_loaded = True
+    logger.info("i18n: %d locale(s) loaded into cache: %s", len(loaded), list(loaded.keys()))
+
+
+def _count_keys(data: Any) -> int:
+    """Count leaf string values in a nested dict structure."""
+    if isinstance(data, dict):
+        return sum(_count_keys(v) for v in data.values())
+    return 1 if isinstance(data, str) else 0
+
+
+def _interpolate(text: str, variables: Dict[str, Any]) -> str:
+    """
+    Replace ``{{var_name}}`` placeholders with actual values.
+
+    The JSON locale files use the ``{{variable}}`` syntax (Jinja2/Mustache style),
+    which is different from Python's ``str.format()`` that uses ``{variable}``.
+    """
+    if not variables:
+        return text
+    for var_name, var_value in variables.items():
+        text = text.replace("{{" + var_name + "}}", str(var_value))
+    return text
+
+
+def _resolve_dot_key(data: Dict[str, Any], key: str) -> Any:
+    """
+    Resolve a dot-notation key against a nested dictionary.
+
+    Example:
+        data = {"AUTH": {"LOGIN": {"SUCCESS": "Hello"}}}
+        _resolve_dot_key(data, "AUTH.LOGIN.SUCCESS")  # -> "Hello"
+    """
+    current: Any = data
+    for part in key.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+def get_locale(lang: str) -> Dict[str, Any]:
+    """
+    Return the full locale dictionary for the given language code.
+
+    Falls back to an empty dict if the language is not loaded.
+
+    Args:
+        lang: Language code, e.g. "en", "hu".
+
+    Returns:
+        The nested dictionary of translations for that locale.
+    """
+    _load_locales()
+    return _locale_cache.get(lang, {})
+
+
+def t(key: str, lang: Optional[str] = None, **kwargs: Any) -> str:
+    """
+    Translate a dot-notation key to the localized string.
+
+    Resolution order:
+        1. Explicit ``lang`` parameter.
+        2. Request-scoped locale from ``context.get_current_locale()``
+           (set by I18nMiddleware from Accept-Language header or ?lang=).
+        3. Default locale ``"hu"``.
+
+    If the key is not found in any locale, the key itself is returned
+    as a fallback.
+
+    Variable interpolation:
+        Placeholders in the translation string like ``{{first_name}}``
+        are replaced with the corresponding keyword argument.
+
+    Examples:
+        >>> t("AUTH.LOGIN.SUCCESS", lang="en")
+        "Login successful. Welcome back!"
+
+        >>> t("EMAIL.REG.GREETING", lang="hu", first_name="Péter")
+        "Szia Péter!"
+
+        >>> t("NONEXISTENT.KEY")
+        "NONEXISTENT.KEY"
+    """
+    _load_locales()
+
+    # 1. Determine language
+    if lang is None:
+        try:
+            from app.core.context import get_current_locale
+            lang = get_current_locale()
+        except (ImportError, Exception):
+            lang = "hu"
+
+    # 2. Try requested language
+    locale_data = _locale_cache.get(lang)
+    if locale_data is not None:
+        result = _resolve_dot_key(locale_data, key)
+        if isinstance(result, str):
+            return _interpolate(result, kwargs) if kwargs else result
+
+    # 3. Fallback to English
+    if lang != "en":
+        en_data = _locale_cache.get("en")
+        if en_data is not None:
+            result = _resolve_dot_key(en_data, key)
+            if isinstance(result, str):
+                return _interpolate(result, kwargs) if kwargs else result
+
+    # 4. Fallback to any available locale
+    for fallback_lang, fallback_data in _locale_cache.items():
+        if fallback_lang == lang or fallback_lang == "en":
+            continue
+        result = _resolve_dot_key(fallback_data, key)
+        if isinstance(result, str):
+            return _interpolate(result, kwargs) if kwargs else result
+
+    # 5. Key not found – return the key itself
+    logger.debug("i18n: Key '%s' not found for lang='%s'", key, lang)
+    return key
+
+
+def reload_locales() -> None:
+    """
+    Force-reload all locale files into the cache.
+    Useful after a translation update without restarting the server.
+    """
+    global _cache_loaded
+    _cache_loaded = False
+    _load_locales(force=True)
+    logger.info("i18n: Locales reloaded successfully")
+
+
+# ── Quiz data loader ───────────────────────────────────────────────────
+_QUIZ_PATHS = [
+    "/app/backend/static/quiz",          # Docker container (sf_api)
+    "/opt/docker/dev/service_finder/backend/static/quiz",  # Host / dev
+    "backend/static/quiz",               # Relative from project root
+    "static/quiz",                       # Relative from backend/
+]
+
+_quiz_cache: Dict[str, Dict[str, Any]] = {}
+_quiz_cache_loaded: bool = False
+
+
+def _discover_quiz_path() -> Optional[str]:
+    """Find the first existing quiz directory."""
+    for path in _QUIZ_PATHS:
+        if os.path.isdir(path):
+            logger.debug("Quiz directory found: %s", path)
+            return path
+    logger.warning("Quiz: No quiz directory found among %s", _QUIZ_PATHS)
+    return None
+
+
+def _load_quiz_data(force: bool = False) -> None:
+    """
+    Load all quiz JSON files from the discovered quiz directory
+    into the in-memory cache.
+    """
+    global _quiz_cache_loaded
+    if _quiz_cache_loaded and not force:
+        return
+
+    path = _discover_quiz_path()
+    if not path:
+        _quiz_cache.clear()
+        _quiz_cache_loaded = True
+        return
+
+    loaded: Dict[str, Dict[str, Any]] = {}
+    for filename in os.listdir(path):
+        if not filename.endswith(".json"):
+            continue
+        lang = filename[:-5]  # strip ".json"
+        filepath = os.path.join(path, filename)
+        try:
+            with open(filepath, "r", encoding="utf-8") as f:
+                loaded[lang] = json.load(f)
+            logger.debug("Quiz: Loaded '%s' from %s", lang, filepath)
+        except Exception as exc:
+            logger.error("Quiz: Failed to load file %s: %s", filepath, exc)
+
+    _quiz_cache.clear()
+    _quiz_cache.update(loaded)
+    _quiz_cache_loaded = True
+    logger.info("Quiz: %d language(s) loaded into cache: %s", len(loaded), list(loaded.keys()))
+
+
+def get_quiz_data(lang: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Return the quiz questions for the given language code.
+
+    Resolution order:
+        1. Explicit ``lang`` parameter.
+        2. Request-scoped locale from ``context.get_current_locale()``.
+        3. Default locale ``"hu"``.
+
+    Falls back to English if the requested language is not available,
+    then to any available language, then to an empty dict.
+
+    Returns:
+        A dict with a ``questions`` key containing the list of quiz questions.
+    """
+    _load_quiz_data()
+
+    # 1. Determine language
+    if lang is None:
+        try:
+            from app.core.context import get_current_locale
+            lang = get_current_locale()
+        except (ImportError, Exception):
+            lang = "hu"
+
+    # 2. Try requested language
+    if lang in _quiz_cache:
+        return _quiz_cache[lang]
+
+    # 3. Fallback to English
+    if lang != "en" and "en" in _quiz_cache:
+        return _quiz_cache["en"]
+
+    # 4. Fallback to any available
+    for fallback_lang, fallback_data in _quiz_cache.items():
+        return fallback_data
+
+    # 5. Nothing loaded
+    logger.warning("Quiz: No quiz data available for lang='%s'", lang)
+    return {"questions": []}
+
+
+def reload_quiz_data() -> None:
+    """Force-reload all quiz JSON files into the cache."""
+    global _quiz_cache_loaded
+    _quiz_cache_loaded = False
+    _load_quiz_data(force=True)
+    logger.info("Quiz: Quiz data reloaded successfully")
+
+
+# ── Preload on import ──────────────────────────────────────────────────
+_load_locales()
+_load_quiz_data()

backend/app/models/gamification/gamification.py

@@ -42,6 +42,12 @@ class PointsLedger(Base):
     points: Mapped[int] = mapped_column(Integer, default=0)
     penalty_change: Mapped[int] = mapped_column(Integer, server_default=text("0"), default=0)
     reason: Mapped[str] = mapped_column(String)
+    
+    # HIÁNYZÓ MEZŐK - hozzáadva a gamification.py endpointok és service-ek támogatásához
+    xp: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    source_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
+    source_id: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
     
     user: Mapped["User"] = relationship("User")
@@ -54,6 +60,7 @@ class UserStats(Base):
     user_id: Mapped[int] = mapped_column(Integer, ForeignKey("identity.users.id"), primary_key=True)
     
     total_xp: Mapped[int] = mapped_column(Integer, default=0)
+    total_points: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
     social_points: Mapped[int] = mapped_column(Integer, default=0)
     current_level: Mapped[int] = mapped_column(Integer, default=1)
     
@@ -63,6 +70,7 @@ class UserStats(Base):
     places_discovered: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
     places_validated: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
     providers_added_count: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
+    services_submitted: Mapped[int] = mapped_column(Integer, default=0, server_default=text("0"))
     banned_until: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
     
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

backend/app/services/gamification_service.py

@@ -5,6 +5,7 @@ from decimal import Decimal
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, desc
 from app.models import UserStats, PointsLedger, UserBadge, Badge
+from app.models.gamification.gamification import PointRule
 from app.models.identity import User, Wallet
 from app.models import FinancialLedger
 from app.services.config_service import config # 2.0 Központi konfigurátor
@@ -15,6 +16,9 @@ class GamificationService:
     """
     Gamification Service 2.0 - A 'Jövevény' lelke.
     Felelős a pontozásért, szintekért, büntetésekért és a jutalom-kreditekért.
+    
+    Refaktor: A process_activity() most már a point_rules táblából is olvas,
+    így az admin által definiált pontszabályok elsőbbséget élveznek a master configgal szemben.
     """
 
     @staticmethod
@@ -29,6 +33,22 @@ class GamificationService:
         service = GamificationService()
         return await service.process_activity(db, user_id, xp_amount=amount, social_amount=social_points, reason=reason, commit=commit)
 
+    async def _get_point_rule(self, db: AsyncSession, action_key: str) -> dict | None:
+        """Lekér egy pontszabályt a point_rules táblából action_key alapján.
+        
+        Returns:
+            dict with 'points' and 'description' or None if not found/inactive.
+        """
+        stmt = select(PointRule).where(
+            PointRule.action_key == action_key,
+            PointRule.is_active == True
+        )
+        result = await db.execute(stmt)
+        rule = result.scalar_one_or_none()
+        if rule:
+            return {"points": rule.points, "description": rule.description}
+        return None
+
     async def process_activity(
         self,
         db: AsyncSession,
@@ -37,13 +57,25 @@ class GamificationService:
         social_amount: int,
         reason: str,
         is_penalty: bool = False,
-        commit: bool = True
+        commit: bool = True,
+        action_key: str | None = None,
+        source_type: str | None = None,
+        source_id: int | None = None,
     ):
         """ A fő folyamat: Pontozás -> Büntetés szűrés -> Szintszámítás -> Kifizetés.
         
+        Refaktor 2.0:
+        - Ha action_key meg van adva, a point_rules táblából olvassa a pontértékeket.
+        - A master config csak fallback, ha nincs a point_rules-ben.
+        - Támogatja a source_type és source_id mezőket a PointsLedger naplózáshoz.
+        
         Args:
             commit: If True (default), commits the transaction internally.
                     Set to False when called from within a larger transaction.
+            action_key: Opcionális. Ha meg van adva, a point_rules táblából
+                        olvassa a pontértékeket a master config helyett.
+            source_type: Opcionális. A pontok forrásának típusa (pl. 'service_submission').
+            source_id: Opcionális. A pontok forrásának ID-ja.
         """
         try:
             # 1. ADMIN KONFIGURÁCIÓ BETÖLTÉSE
@@ -59,6 +91,19 @@ class GamificationService:
                 "level_rewards": {"credits_per_10_levels": 50}
             })
 
+            # 1/b. POINT RULES TÁBLA LEKÉRÉSE (ha action_key meg van adva)
+            # A point_rules tábla elsőbbséget élvez a master config-gal szemben!
+            if action_key:
+                rule = await self._get_point_rule(db, action_key)
+                if rule:
+                    # A point_rules-ból jövő pontok felülírják a paraméterként kapott értékeket
+                    xp_amount = rule["points"]
+                    if rule.get("description"):
+                        reason = f"{action_key}: {rule['description']}"
+                    logger.debug(f"Point rule applied: {action_key} -> {xp_amount} XP")
+                else:
+                    logger.debug(f"No active point rule found for action_key='{action_key}', using fallback values.")
+
             # 2. FELHASZNÁLÓ ÉS STATISZTIKA ELLENŐRZÉSE
             stats_stmt = select(UserStats).where(UserStats.user_id == user_id)
             stats = (await db.execute(stats_stmt)).scalar_one_or_none()
@@ -70,7 +115,7 @@ class GamificationService:
 
             # 3. BÜNTETŐ LOGIKA (Ha negatív esemény történik)
             if is_penalty:
-                return await self._apply_penalty(db, stats, xp_amount, reason, cfg)
+                return await self._apply_penalty(db, stats, xp_amount, reason, cfg, source_type=source_type, source_id=source_id)
 
             # 4. SZORZÓK ALKALMAZÁSA (Büntetés alatt állók 'bírsága')
             multiplier = await self._calculate_multiplier(stats, cfg)
@@ -107,8 +152,15 @@ class GamificationService:
                     stats.social_points %= rate # A maradék pont megmarad
                     await self._add_earned_credits(db, user_id, credits_to_add, "SOCIAL_ACTIVITY_CONVERSION")
 
-            # 7. NAPLÓZÁS
-            db.add(PointsLedger(user_id=user_id, points=final_xp, reason=reason))
+            # 7. NAPLÓZÁS (kibővítve xp, source_type, source_id mezőkkel)
+            db.add(PointsLedger(
+                user_id=user_id,
+                points=final_xp,
+                xp=final_xp,
+                reason=reason,
+                source_type=source_type,
+                source_id=source_id,
+            ))
             
             # Only commit if caller wants us to manage the transaction
             if commit:
@@ -124,8 +176,12 @@ class GamificationService:
 
     # --- PRIVÁT SEGÉDFÜGGVÉNYEK ---
 
-    async def _apply_penalty(self, db: AsyncSession, stats: UserStats, amount: int, reason: str, cfg: dict):
-        """Büntetőpontok hozzáadása és korlátozási szintek emelése."""
+    async def _apply_penalty(self, db: AsyncSession, stats: UserStats, amount: int, reason: str, cfg: dict,
+                              source_type: str | None = None, source_id: int | None = None):
+        """Büntetőpontok hozzáadása és korlátozási szintek emelése.
+        
+        Refaktor: Most már támogatja a source_type és source_id mezőket a naplózáshoz.
+        """
         stats.penalty_points += amount
         th = cfg["penalty_logic"]["thresholds"]
         
@@ -133,7 +189,14 @@ class GamificationService:
         elif stats.penalty_points >= th["level_2"]: stats.restriction_level = 2
         elif stats.penalty_points >= th["level_1"]: stats.restriction_level = 1
         
-        db.add(PointsLedger(user_id=stats.user_id, points=0, penalty_change=amount, reason=f"🔴 PENALTY: {reason}"))
+        db.add(PointsLedger(
+            user_id=stats.user_id,
+            points=0,
+            penalty_change=amount,
+            reason=f"🔴 PENALTY: {reason}",
+            source_type=source_type,
+            source_id=source_id,
+        ))
         await db.commit()
         return stats
 
@@ -165,4 +228,4 @@ class GamificationService:
                 details={"reason": reason}
             ))
 
-gamification_service = GamificationService()
+gamification_service = GamificationService()

backend/app/services/system_service.py

@@ -6,7 +6,7 @@ A rendszerparaméterek prioritásos felülbírálást támogatnak: User > Region
 
 import logging
 from typing import Optional, Any, Dict
-from sqlalchemy import select, func  # HOZZÁADVA: func a NOW() híváshoz
+from sqlalchemy import select, func
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
@@ -60,7 +60,7 @@ class SystemService:
         for scope_level, scope_id in scopes:
             stmt = select(SystemParameter).where(
                 SystemParameter.key == key,
-                SystemParameter.scope_level == scope_level,
+                SystemParameter.scope_level == scope_level.value,
                 SystemParameter.is_active == True,
             )
             if scope_id is not None:
@@ -97,42 +97,65 @@ class SystemService:
         """
         Létrehoz vagy frissít egy rendszerparamétert a megadott scope-ban.
         Ha már létezik ugyanazzal a kulccsal, scope_level-lel és scope_id-vel, felülírja.
+
+        Megjegyzés: PostgreSQL-ben a UNIQUE constraint nem blokkolja a NULL scope_id-jű
+        duplikátumokat (mert NULL != NULL). Ezért kétlépéses megközelítést használunk:
+        először megpróbáljuk frissíteni a meglévő rekordot, és ha nem találjuk, beszúrjuk.
         """
         from sqlalchemy.dialects.postgresql import insert
 
-        # UPSERT logika: ON CONFLICT DO UPDATE
-        insert_stmt = insert(SystemParameter).values(
-            key=key,
-            value=value,
-            scope_level=scope_level,
-            scope_id=scope_id,
-            category=category,
-            description=description,
-            last_modified_by=last_modified_by,
-            is_active=True,
+        # 1. lépés: Próbáljuk megkeresni a meglévő rekordot
+        stmt_find = select(SystemParameter).where(
+            SystemParameter.key == key,
+            SystemParameter.scope_level == scope_level.value,
+            SystemParameter.is_active == True,
         )
-        upsert_stmt = insert_stmt.on_conflict_do_update(
-            constraint="uix_param_scope",
-            set_=dict(
+        if scope_id is not None:
+            stmt_find = stmt_find.where(SystemParameter.scope_id == scope_id)
+        else:
+            stmt_find = stmt_find.where(SystemParameter.scope_id.is_(None))
+
+        result = await db.execute(stmt_find)
+        existing = result.scalar_one_or_none()
+
+        if existing:
+            # 2a. lépés: Frissítjük a meglévő rekordot
+            existing.value = value
+            existing.category = category
+            existing.description = description
+            existing.last_modified_by = last_modified_by
+            existing.updated_at = func.now()
+            await db.commit()
+            return existing
+        else:
+            # 2b. lépés: Beszúrunk egy új rekordot
+            insert_stmt = insert(SystemParameter).values(
+                key=key,
                 value=value,
+                scope_level=scope_level.value,
+                scope_id=scope_id,
                 category=category,
                 description=description,
                 last_modified_by=last_modified_by,
-                updated_at=func.now(),
-            ),
-        )
-        await db.execute(upsert_stmt)
-        await db.commit()
+                is_active=True,
+            )
+            await db.execute(insert_stmt)
+            await db.commit()
 
-        # Visszaolvassuk a létrehozott/frissített rekordot
-        stmt = select(SystemParameter).where(
-            SystemParameter.key == key,
-            SystemParameter.scope_level == scope_level,
-            SystemParameter.scope_id == scope_id,
-        )
-        result = await db.execute(stmt)
-        param = result.scalar_one()
-        return param
+            # Visszaolvassuk a létrehozott rekordot
+            stmt_read = select(SystemParameter).where(
+                SystemParameter.key == key,
+                SystemParameter.scope_level == scope_level.value,
+                SystemParameter.is_active == True,
+            )
+            if scope_id is not None:
+                stmt_read = stmt_read.where(SystemParameter.scope_id == scope_id)
+            else:
+                stmt_read = stmt_read.where(SystemParameter.scope_id.is_(None))
+
+            result = await db.execute(stmt_read)
+            param = result.scalar_one()
+            return param
 
 # --- GLOBÁLIS PÉLDÁNY ÉS SEGÉDFÜGGVÉNYEK ---
 # Ezek a fájl legszélén vannak (0-s behúzás), így kívülről importálhatóak!