service-finder/docs/admin_system_epic.md

🏛️ Admin System Epic: v2.0 - Enterprise Admin & Dynamic Config

Mérföldkő: v2.0 - Enterprise Admin & Dynamic Config
Cél: A Service Finder adminisztrációs rétegének átfogó fejlesztése, amely lehetővé teszi a dinamikus konfigurációk kezelését, szerepköralapú hozzáférés-vezérlést (RBAC), felhasználói és tartalmi moderálást, valamint anomália detektálást a rendszer integritásának védelme érdekében.

Prioritás: Magas
Becsült időtartam: 4 hét (4 fázis)
Felelős: Core Team
Státusz: Tervezés

---

📋 Issue #1 (Phase 1): Hardcode Audit & Config Motor

Cím: Hardcode Audit & Config Motor
Pontszám: 50 XP
Határidő: 2026-04-04
Scope: Backend, Database
Type: Refactor, Infrastructure

Leírás

A kódban található beégetett értékek (pl. 50 XP, limit értékek, API URL-ek) átvizsgálása és kiváltása dinamikus konfigurációs rendszerrel. Létrehozni egy SystemParameter táblát a system sémában, amely kulcs-érték párokat tárol, és egy ConfigService osztályt, amely ezeket az értékeket gyorsítótárazza és szolgáltatja az alkalmazás számára.

🔗 Függőségek (Dependencies)

• Bemenet: Meglévő kódban található hardcode értékek, PostgreSQL adatbázis
• Kimenet: Minden olyan modul, amely hardcode értékeket használ (pl. gamification, billing, robot kvóták)

📝 To-Do List

• Hardcode Audit Script írása, amely végigvizsgálja a backend/ mappát és listázza a potenciális hardcode értékeket
• SystemParameter tábla tervezése (id, key, value, data_type, description, scope, is_encrypted, created_at, updated_at)
• Alembic migráció generálása a tábla létrehozásához
• ConfigService osztály megírása a következőkkel:
  • get(key, default=None) metódus
  • set(key, value) metódus (csak admin)
  • In‑memory cache (TTL 5 perc)
  • Async támogatás
• Hardcode értékek cseréje a ConfigService-re a következő modulokban:
  • gamification.py (XP értékek, szintek)
  • billing_engine.py (díjak, limitek)
  • dvla_service.py (API kvóták)
  • notification_service.py (sablonok)
• Admin API végpont /api/v1/admin/config a konfigurációk kezeléséhez (GET, PUT)
• Tesztelés unit és integrációs tesztekkel

---

📋 Issue #2 (Phase 2): RBAC & Admin Security Layer

Cím: RBAC & Admin Security Layer
Pontszám: 40 XP
Határidő: 2026-04-11
Scope: Backend, Security
Type: Feature, Security

Leírás

Szerepkörök (Superadmin, Moderator, Support) bevezetése és az /api/v1/admin router jogosultság-kezelésének megvalósítása. Minden végpontnak ellenőriznie kell a felhasználó szerepkörét és scope-ját a UserTrustProfile alapján.

🔗 Függőségek (Dependencies)

• Bemenet: identity.user és identity.user_trust_profile táblák, JWT token
• Kimenet: Admin API végpontok, frontend admin felület

📝 To-Do List

• Szerepkör enum definiálása (Superadmin, Moderator, Support, Auditor)
• UserTrustProfile tábla bővítése role és permissions mezőkkel
• Alembic migráció a mezők hozzáadásához
• AdminSecurity dependency létrehozása a következőkkel:
  • require_role(role) dekorátor
  • require_permission(permission) dekorátor
  • Scope ellenőrzés (organization, global)
• /api/v1/admin router védelme a dependency-vel
• Permission matrix dokumentálása (melyik szerepkör mit tehet)
• Teszt felhasználók létrehozása seed scripttel
• Integrációs tesztek a szerepkörökhöz

---

📋 Issue #3 (Phase 3): Core Admin API Végpontok

Cím: Core Admin API Végpontok
Pontszám: 60 XP
Határidő: 2026-04-18
Scope: Backend, API
Type: Feature

Leírás

Felhasználók, KYC, járművek és szervizek kezelését végző admin API végpontok megvalósítása (listázás, szűrés, tiltás, jóváhagyás, törlés). Minden művelet naplózása az audit táblába.

🔗 Függőségek (Dependencies)

• Bemenet: Meglévő user, vehicle, service táblák, RBAC layer
• Kimenet: Admin dashboard, moderátori munkafolyamatok

📝 To-Do List

• Felhasználó kezelés:
  • GET /admin/users – listázás, szűrés (email, név, státusz)
  • PUT /admin/users/{user_id}/ban – tiltás (indoklással)
  • PUT /admin/users/{user_id}/approve – KYC jóváhagyás
  • DELETE /admin/users/{user_id} – soft delete
• Jármű kezelés:
  • GET /admin/vehicles – listázás, szűrés (rendszám, márka)
  • PUT /admin/vehicles/{vehicle_id}/flag – gyanúsként megjelölés
  • DELETE /admin/vehicles/{vehicle_id} – törlés (ha hamis adat)
• Szerviz kezelés:
  • GET /admin/services – listázás, szűrés (név, hely, minősítés)
  • PUT /admin/services/{service_id}/verify – kézi ellenőrzés
  • PUT /admin/services/{service_id}/suspend – felfüggesztés
• KYC dokumentumok:
  • GET /admin/kyc/pending – függőben lévő kérelmek
  • PUT /admin/kyc/{request_id}/review – áttekintés és döntés
• Audit naplózás minden admin művelethez (audit.admin_actions tábla)
• Pagination és filter támogatása minden listázó végponthoz
• Swagger dokumentáció frissítése

---

📋 Issue #4 (Phase 4): Anomália Detektálás (Anti-Cheat)

Cím: Anomália Detektálás (Anti-Cheat)
Pontszám: 30 XP
Határidő: 2026-04-25
Scope: Backend, Robot, Security
Type: Feature, Monitoring

Leírás

Robot felügyelő (Cron/Background task) létrehozása, amely figyeli a gyanús tömeges validációkat, helyadatokat és egyéb potenciális csalási kísérleteket. Riasztás generálása és automatikus intézkedések (pl. ideiglenes letiltás).

🔗 Függőségek (Dependencies)

• Bemenet: Audit naplók, vehicle validations, user actions
• Kimenet: Riasztások, automatikus blokkolások, admin értesítések

📝 To-Do List

• Anomália detektálási szabályok definiálása:
  • Túl sok validáció ugyanarról az IP‑ről ( >100/óra)
  • Tömeges helyadat‑módosítás rövid időn belül
  • Gyanús XP farmolás (több account ugyanarról az eszközről)
  • Hamis járműadatok ismételt feltöltése
• AnomalyDetector service létrehozása:
  • Szabályok futtatása időzített ciklusban (pl. 10 percenként)
  • Gyanús események rögzítése audit.suspicious_events táblába
  • Riasztás generálás (email, Slack, in‑app notification)
• Automatikus intézkedések:
  • IP ideiglenes blokkolása (1 óra)
  • Felhasználói account letiltása (manual review required)
  • Validációk visszavonása
• Admin dashboard widget a gyanús tevékenységek megjelenítéséhez
• Tesztadatok generálása és detektálás validálása
• Külső integráció (pl. Fail2ban, Cloudflare) tervezése

---

🗺️ Roadmap & Kapcsolódó Feladatok

1. v2.1 – Admin Dashboard UI (Frontend epic) – a fenti API-k felhasználásával
2. v2.2 – Real‑time Notification System – WebSocket‑alapú értesítések adminoknak
3. v2.3 – Advanced Analytics for Admins – jelentéskészítő, exportálás

📊 Metrikák és Sikerfeltételek

• Hardcode redukció: 90%‑os csökkenés a kódban található magic number‑ek számában
• RBAC teljes lefedettség: Minden admin végpont védett szerepkör‑alapú ellenőrzéssel
• Anomália detektálás pontosság: Legalább 95%‑os recall a csalási kísérleteknél
• Válaszidő: Admin API végpontok átlagos válaszideje < 200 ms

👥 Felelősségek

• Backend Lead: Phase 1 & 2
• Security Engineer: Phase 2 & 4
• API Developer: Phase 3
• QA Engineer: Tesztelés minden fázisban

---

Dokumentum frissítve: 2026‑03‑21
Verzió: 1.0