service-finder/docs/v02/19_Permissions_Tiers_Branches_2.0.md

# 19. Permissions, User Tiers & Branch Hierarchy (v2.0)

Ez a dokumentum a jogosultsági szinteket, a bizalmi rangsorolást és a telephelyek földrajzi-adminisztratív hiearchiáját rögzíti.

## 19.1 Felhasználói Rangok és Előfizetési Tiers
A rendszer megkülönbözteti a technikai előfizetést (User) és a közösségi megbízhatóságot (Person).

- **Trust Tiers:** - **Tier 1 (Lite):** Csak email verifikált. Korlátozott hozzáférés.
    - **Tier 2 (Active):** KYC (személyazonosítás) befejezve. Teljes Marketplace hozzáférés, saját flotta kezelése.
- **Subscription Plans (User szint):** - **FREE:** Alapszintű költségkövetés, hirdetésekkel.
    - **PREMIUM:** Reklámmentesség, részletes TCO elemzések, prioritásos szervizkeresés.
    - **VIP:** Egyedi üzleti funkciók, Sales Agent támogatás.

## 19.2 Hierarchikus RBAC (Role-Based Access Control)
Az adminisztráció és a látókör (Scope) négy szinten különül el:

| Szint (Scope) | Megnevezés | Hatókör |
| :--- | :--- | :--- |
| **L0** | **Global Admin** | A teljes ökoszisztéma, rendszerparaméterek és "Kill-switch". |
| **L1** | **Country Manager** | Adott ország (ISO kód) összes régiója, pénznemek, adókulcsok. |
| **L2** | **Regional Admin** | Megyei vagy kerületi szintű felügyelet. |
| **L3** | **Branch Manager** | Konkrét telephely, szervizpont vagy flottaegység irányítása. |



## 19.3 Bírói Rendszer és Büntetések (Judge & Penalty)
A közösség tisztaságát a `GamificationService` által vezérelt "Bíró" modul védi.

- **Penalty Points:** Visszaélés vagy hibás validáció esetén 0-3 szintű büntetőpont adható.
- **Restriction Levels:** A büntetések automatikusan korlátozzák a funkciókat (pl. nem tölthet fel számlát, nem validálhat másokat).
- **Multipliers:** A büntetett felhasználók kevesebb XP-t és kreditet kapnak ugyanazért a munkáért (Admin-vezérelt szorzók).

## 19.4 Telephelyek és Földrajzi Hierarchia (Branches)
A rendszer kezeli a multi-tenant telephelyeket, ahol egy címen több jogi entitás is létezhet [cite: 2026-02-13].

- **Normalizált Címek:** Minden telephely az egységes `data.addresses` táblához kapcsolódik (UUID alapú hivatkozás).
- **PostGIS Integráció:** Minden telephely rendelkezik pontos GPS koordinátával (Point), amely lehetővé teszi a térképi alapú szűrést.
- **Sales Assignments:** A cégek (Organizations) és telephelyek üzletkötőkhöz (Sales Agents) rendelhetőek "Hunting" vagy "Farming" jutalék céljából.

## 19.5 Biztonsági Protokoll (Sentinel & Four-Eyes)
A kiemelt műveleteknél (pl. VIP rang kiosztása, büntetés törlése, kifizetés) a rendszer kényszeríti a "Négy szem elvét": egy Admin kezdeményezi, de egy másik L1+ szintű Adminnak kell jóváhagynia a `ConfirmedAction` modulon keresztül.

## 19.6 Üzletkötői és Hirdetésszervezői Rendszer
A rendszer támogatja a külső értékesítési partnereket a "Hunting & Farming" jutalékmodell alapján.

- **Sales Agents (Üzletkötők):** A `persons` és `users` tábla kapcsolatán keresztül azonosított partnerek, akik szervizeket és cégeket hoznak be a rendszerbe.
- **Hunting Jutalék:** Egyszeri bónusz egy új szolgáltató vagy céges flotta sikeres regisztrációja és aktiválása után.
- **Farming Jutalék:** Folyamatos, százalékos bevétel a kezelt partnerek havidíjaiból vagy forgalmából.
- **Hirdetésszervezés:** Speciális jogosultsági kör a szervizek hirdetéseinek és kiemeléseinek kezelésére.

## 19.7 Rugalmas RBAC Bővíthetőség
Bár az alaprendszer az L0-L3 hierarchiát követi, a technikai architektúra fel van készítve a jogosultságok dinamikus bővítésére:
- **Custom Permissions:** A `users` tábla `custom_permissions` (JSONB) mezője lehetővé teszi egyedi engedélyek hozzáadását anélkül, hogy új rangot kellene definiálni.
- **Bővíthető Szintek:** Az RBAC rendszer úgy lett tervezve, hogy a jövőben új köztes szintek (pl. kistérségi koordinátor) is bevezethetőek legyenek a `scope_level` skálázásával.