Epic 3: Economy & Billing Engine (Pénzügyi Motor)

docs/v02/07_API_Service.md

@@ -0,0 +1,34 @@
+# 07. API Architecture, Security & Admin Control (v2.0)
+
+Ez a dokumentum az interfészek felépítését, a jogosultságkezelést (RBAC) és az Admin felügyeleti eszközöket írja le.
+
+## 7.1 API Alapelvek & Biztonság
+- **Standard:** FastAPI v2, aszinkron végpontok.
+- **JWT & RBAC:** A tokenek tartalmazzák a `rank`, `scope_level` és `scope_id` mezőket az azonnali jogosultság-ellenőrzéshez.
+- **Sentinel System (Dual Control):** A kiemelt műveletekhez (pl. pénzügy, VIP státusz) kötelező a "Négy szem elv" (Dual Control) és a `ConfirmedAction` rögzítése.
+
+## 7.2 Moduláris Végpontok (Core Endpoints)
+A korábbi monolitikus struktúrát szétbontottuk a jobb skálázhatóság érdekében:
+1. **Identity API:** `/auth`, `/complete-kyc`.
+2. **Asset API:** `/identity`, `/costs`, `/telemetry` bontásban.
+3. **Marketplace API:** Szervizkeresés (`/search`) és Autocomplete (`/suggest-street`).
+
+
+
+## 7.3 Admin & i18n Szinkronizáció
+Az Adminisztrátori felület nem csupán egy technikai eszköz, hanem a rendszer üzleti és biztonsági felügyeleti központja, amely négy szinten (Globális, Ország, Régió, Egyedi entitás) teszi lehetővé a beavatkozást.
+- **Admin Kontroll Panel:** Központi végpontok a függőben lévő műveletek jóváhagyásához és a vészleállításhoz.
+- **i18n Service:** Adatbázis-alapú fordításkezelés szerveroldali cache-sel. A `/admin/translations/sync` végpont exportálja a JSON fájlokat a Frontend számára.
+
+### 7.3.1 Főbb Adminisztrátori funkciók:
+- **Dinamikus Paraméterezés:** Új rendszerértékek, jutalékok, árfolyamok és globális változók beállítása és ellenőrzése a `system_parameters` táblán keresztül.
+- **Hierarchikus Jogosultságkezelés (RBAC):** A validációs jogok és hozzáférések finomhangolása globális vagy akár egyedi (Individual) szinten is.
+- **Validáció és Audit:** A botok által gyűjtött (Ghost) adatok felülvizsgálata, a `PendingAction` kérések jóváhagyása és a biztonsági riasztások kezelése.
+- **Regionális Kontroll:** Ország- és régióspecifikus szabályok (pl. adózási kulcsok, pénznemek, nyelvi készletek) aktiválása és felügyelete.
+
+### 7.3.2 Sentinel System (Dual Control):
+A kiemelt műveletekhez (pl. pénzügyi keretek módosítása, Admin rang adása) továbbra is kötelező a "Négy szem elv" (Dual Control), ahol a műveletet végző és a jóváhagyó személynek el kell különülnie.
+
+## 7.4 Jövőbeli Interfészek (Roadmap)
+- **Fuzzy Search:** A `synonyms` mezőre épülő `tsvector` alapú intelligens keresőmotor.
+- **Service Hunter API:** A Robot 4 által talált ajánlatok lekérdezése.