# 🛠️ 19_ADMIN_AND_PERMISSIONS_SPEC (v1.0)

## 1. Adminisztrátori Hierarchia és Területi Felosztás
A rendszer többszintű, régió-alapú jogosultságkezelést alkalmaz (**RBAC + Geographic Scope**).

| Szint | Megnevezés | Területi hatókör | Jogkörök jellege |
| :--- | :--- | :--- | :--- |
| **L0** | **SuperAdmin** | Globális (Összes ország) | Teljes hozzáférés, Rendszer-paraméterezés, Admin kinevezés. |
| **L1/A** | **Global Director** | Régiós (Több ország) | Országos vezetők felügyelete, aggregált statisztikák. |
| **L1/B** | **National Manager** | Országos (pl. HU) | Saját ország moderátorainak és adatainak teljes kezelése. |
| **L2** | **Staff (Mod/Supp/Fin)** | Lokális / Szakaszolt | Operatív feladatok (VIES, support jegyek, kifizetések). |
| **L3** | **Task Moderator** | Feladat-specifikus | Sablon alapú, korlátozott hozzáférés (pl. csak szerviz validálás). |



### Verseny Logika (Privacy Protection)
Az L1/B szintű vezetők látják más országok aggregált KPI mutatóit (statisztikai összehasonlítás), de **nincs betekintésük** a konkrét személyes vagy céges adatokba.

---

## 2. Jogosultságkezelés és Sablonok
- **Permissions Table:** Elemi jogosultságok atomi tárolása (pl. `approve_vies`, `modify_credits`).
- **Role Templates:** Előre definiált szerepkör-sablonok (pl. "Senior Financial - DE").
- **Regionális Izoláció:** Az adminisztrátorok alapértelmezetten csak a hozzájuk rendelt `ISO_country_code` alá tartozó rekordokat módosíthatják.

---

## 3. Biztonság és "Kill-Switch" Protokoll
### 3.1. Hitelesítés
- **MFA/2FA:** A második bejelentkezéstől kezdve kötelező a **TOTP** (pl. Google Authenticator) használata.
- **Social Auth:** Engedélyezett, de nem váltja ki a kötelező 2FA-t.

### 3.2. Anomaly Score (Fekete Doboz)
- **Audit Logs:** Minden kattintást és módosítást JSON formátumban rögzítünk.
- **Automatikus Felfüggesztés:** Kritikus viselkedés (pl. tömeges adattörlés) esetén a rendszer automatikusan zárolja az admin fiókot és riasztást küld a felette álló szintnek.
- **SuperAdmin Recovery:** Csak egyedi **Offline Kulccsal** és előre regisztrált fizikai eszközzel lehetséges.

### 3.3. State Snapshot (Visszaállíthatóság)
Minden módosítás előtt a rendszer menti a rekord aktuális állapotát. Az L0/L1 szintű adminisztrátorok egy gombnyomással visszaállíthatják az eredeti adatokat károkozás vagy hiba esetén.

---

## 4. Értesítési Engine és Lejárati Figyelmeztetések
A rendszer proaktív módon értesíti az érintetteket a kritikus dátumok előtt (Push, Email, Mini-CRM).

### 4.1. Előfizetési Értesítések
- **Hatókör:** Lite+, VIP, VIP+, Corporate csomagok.
- **Ütemezés:** Automatikus figyelmeztetés **30, 15, 7 és 1** nappal a lejárati dátum előtt.

### 4.2. Technikai és Jármű Okmányok
A rendszer figyeli és jelzi az alábbiak lejáratát:
- **Forgalmi engedély:** Műszaki vizsga érvényessége.
- **Biztosítás:** KGFB és CASCO fordulónapok.
- **Lízing:** Szerződéses futamidő vége.
- **Specialty:** Hajólevél, lajstrom, emelőgép vizsga stb.

---

## 5. CRM és Szervezeti Kontaktok
Minden szervezet (Organization) esetében kötelező legalább egy **Adminisztratív Kontakt** megadása.
- **Multi-Role:** Egy Person több szervezetben is lehet `owner` vagy `fleet_manager`.
- **CRM Mezők:** Név, beosztás, közvetlen elérhetőség (Pénzügyi felelős / Operatív felelős elkülönítve).

---

## 6. Corporate Onboarding és Validáció
A cégek hitelesítése három szinten történik:
1. **Tier 1 (Automata):** Adószám alapú validáció (VIES / Nemzeti API).
2. **Tier 2 (AI/OCR):** Feltöltött dokumentumok (pl. Alapító okirat) intelligens elemzése.
3. **Tier 3 (Human):** L2/L3 szintű adminisztrátori jóváhagyás, ha az automatika bizonytalan.

---

## 7. B2B Jutalék és MLM Korlátok
- **Direct Referral:** Szervezet által meghívott másik szervezet esetén kizárólag az **1. szintű (L1)** jutalék jár.
- **MLM Kivétel:** A szervezetek nem építhetnek többszintű hálózatot; a kifizetés minden esetben fix üzleti megállapodás vagy egyedi szerződés alapján történik.
- **Adminisztrátori Meghívók:** Csak manuálisan generálhatók, és szigorúan **24 órás** lejárati idővel rendelkeznek.

## 6. Dinamikus Szabálymotor (Rule Engine)
A rendszer minden fontos paramétere a `data.system_settings` táblában tárolt JSON objektumokból származik.

### 6.1 Módosítási protokoll
* Az Admin felületen módosított értékek (pl. Kredit jutalom összege) azonnal érvénybe lépnek.
* A módosítás után a Backend Cache-t (`ConfigService`) üríteni kell.

### 6.2 Paraméterezhető modulok
* **Service Hunt:** Távolságok, XP/Kredit szorzók.
* **Fraud Protection:** Strike limitek, kitiltási idők.
* **Billing:** EUR/HUF/USD váltószámok, csomagárak, jármű-slot árak.

## 2026.02.10 FRISSÍTÉS - HIERARCHIKUS RBAC RENDSZER

### 1. Rang-alapú Jogosultság (Rank System)
A rendszer a \`system_parameters\` táblában tárolt \`RBAC_MASTER_CONFIG\` JSON alapján működik.
- **SUPERADMIN (Rank 100):** Globális hatókör, mindent lát.
- **COUNTRY_ADMIN (Rank 80):** Országos felelős.
- **REGION_ADMIN (Rank 60):** Területi vezető (Manage Moderators).
- **MODERATOR (Rank 40):** Adatvalidátor.
- **SALES (Rank 20):** Üzletkötő (Csak saját partnerek).
- **USER (Rank 10):** Végfelhasználó.

### 2. Scope (Hatókör) Védelem
Minden műveletnél ellenőrizzük a \`scope_id\` egyezését:
- Ha a felhasználó \`scope_level = 'region'\`, akkor csak olyan adatot szerkeszthet, ami ugyanahhoz a régióhoz tartozik.
- Kivétel: Impersonation (Megszemélyesítés) - Audit loggal védve.


## 1. Gamification Adminisztráció
A `data.system_parameters` táblában a `GAMIFICATION_MASTER_CONFIG` kulcs alatt az alábbiak állíthatóak:
- `xp_logic`: `base_xp`, `exponent`.
- `penalty_thresholds`: A szintekhez tartozó büntetőpont határok.
- `level_up_rewards`: 10-es szintenkénti Kredit jutalom mértéke.
- `blocked_roles`: [superadmin, service_bot].
- `auto_convert_social`: True/False.

## 2. Gamification Konfiguráció (JSON Schema)
A `GAMIFICATION_MASTER_CONFIG` struktúrája:
- `xp_logic`: Alap XP és kitevő a nehezedő szintezéshez.
- `penalty_logic`: Küszöbértékek, szorzók és ledolgozási ráta.
- `conversion_logic`: Social-to-Credit váltási arány.
- `level_rewards`: Szintlépési bónuszok mértéke.

## 19.1. SuperAdmin Capabilities
A `rank: 100` szintű felhasználó (SuperAdmin) az egyetlen, aki:
1.  **Translation Sync:** Írási joga van a szerver fájlrendszerére a `/api/v1/admin/translations/sync` végponton keresztül.
2.  **Sentinel Override:** Felülbírálhatja az automatikus biztonsági zárolásokat.

## 19.2. Admin API Endpoints
- `POST /admin/translations/sync`:
    - **Trigger:** Manuális (Gombnyomás a Dashboardon).
    - **Action:** `data.translations` -> `static/locales/*.json`.
    - **Permission:** SuperAdmin ONLY.


    ## 5. Security & Audit Logging

A rendszer két szinten naplózza az eseményeket:

### 5.1 Operational Log (Üzemi Napló)
* **Cél:** Hibakeresés, User Activity követés.
* **Tartalom:** Jármű rögzítés, Adatjavítás, Keresés.
* **Hozzáférés:** Moderátor szinttől felfelé.

### 5.2 Security Audit Log (Biztonsági Napló)
* **Cél:** Visszaélések megelőzése, Jogosultságok védelme.
* **Tartalom:** Rang emelés (Role Change), Kredit manuális jóváírása, VIP státusz adása, Admin belépés.
* **Hozzáférés:** Csak Superadmin és Country Admin (Szigorított).

### 5.3 The "Four-Eyes" Principle (4-Szem Elv)
Kritikus műveletek (pl. egy User `is_vip` státuszának kézi átállítása vagy `penalty_points` törlése) esetén a rendszer:
1.  Rögzíti a kérést a `security_audit_logs`-ban.
2.  A státusz "Pending" marad.
3.  A változás **csak akkor lép életbe**, ha egy MÁSIK Adminisztrátor jóváhagyja azt (`confirmed_by_id` kitöltése).
4.  Szuperadmin esetén a `is_critical` flag aktiválódik, és azonnali riasztás megy a többi adminnak.