# 🏛️ 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*