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

docs/admin_system_epic.md

@@ -0,0 +1,173 @@
+# 🏛️ 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*