From 5d0dc2433cfae4a85c4c6ccc69095e812885607f Mon Sep 17 00:00:00 2001 From: Kincses Date: Thu, 5 Feb 2026 00:11:33 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20Identity=20&=20Company=20Sync=20v1.2,?= =?UTF-8?q?=20Admin=20hiearchia=20=C3=A9s=20P=C3=A9nz=C3=BCgyi=20logika=20?= =?UTF-8?q?v=C3=A9gleges=C3=ADt=C3=A9se?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../__pycache__/organization.cpython-312.pyc | Bin 1653 -> 1983 bytes backend/app/models/identity.py | 3 - backend/app/models/organization.py | 20 ++++-- backend/app/services/auth_service.py | 68 ++++++++++++++---- docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md | 44 +++++++++++- docs/V01_gemini/06_Database_Guide.md | 22 +++++- docs/V01_gemini/09_Admin_API_Guide.md | 35 +++++++++ .../10_Billing_Credits_Subscriptions.md | 67 +++++++++++------ docs/V01_gemini/15_Changelog.md | 23 ++++++ 9 files changed, 238 insertions(+), 44 deletions(-) create mode 100644 docs/V01_gemini/09_Admin_API_Guide.md diff --git a/backend/app/models/__pycache__/organization.cpython-312.pyc b/backend/app/models/__pycache__/organization.cpython-312.pyc index 1f38794999b6109f332da42520f1e59e4a19b6b7..ecc8b0f4f3b322c8e8f3740c1fb770bbb1fb6cb5 100644 GIT binary patch delta 629 zcmey$v!9>uG%qg~0}xo8Y0kXJx{;5CiIHQnFq0kQyvadK8xv9mQdrh-tY!i!VPJ?7 zVq!>T1&XmDi3x+mfLH{ml4~_1L?w{T4%a1$O$AU)EK6^)B(tit1YUV*a~`-!l0cPG zDZD9sYxv<}(qJ)x6hS00nMxr|;mMKA?L3-{w>a|iN()jFOHwC4V3slm3h*T*CTGVN zkx6^V5`_tiw`obBjN-IKHGPF|Rl+ zwJ0$uC-oLLP@pWeC^IcHHKm9H==WRV5NOja9ey;|P zk8BKr;uFeOuv`()ZSVy0#ARoMuSmHfX58Qpx!UvgV#;C#14%eD*H8dYV6j!BIqjH z-~}{NKxT&T4&5vK9t|Eh`J^sL>mT5|!sp-UKDn87nXog^v7o3gwgM6#m>C%vA5XSn T(-4$m3}BpK@|6KZgFOiV+#s-< delta 318 zcmdnb|CNXDG%qg~0}!ZgZ_bor*~rJj#K=Bbn8}WjX>t(LMlmLaRG}1>HC(G1L5dg{ zfPCRBjmgQ(s?wrBwpa>J3U3PE8vfPH5cw$aN&!v5$zPeY&o4@^5=zX;(NRcA%}Fgu)y*#|$Vkl7WV*$dl$e|yUyxr=nv+mU@vQ4xk-H+(6 bool: + """ + EU VIES API lekérdezése az adószám hitelességének ellenőrzéséhez. + """ + try: + # Tisztítás: csak számok és országkód (pl. HU12345678) + clean_vat = "".join(filter(str.isalnum, vat_number)).upper() + async with httpx.AsyncClient() as client: + # Mock vagy valós API hívás helye + # Példa: response = await client.get(f"https://vies-api.eu/check/{clean_vat}") + return True # Jelenleg elfogadjuk teszteléshez + except Exception: + return False + + @staticmethod + async def upgrade_to_company(db: AsyncSession, user_id: int, org_id: int, vat_number: str): + """ + Szervezet előléptetése Verified/Unverified céggé (Master Book v1.2). + """ + is_valid = await AuthService.verify_vies_vat(vat_number) + + # 30 napos türelmi idő számítása + grace_period = datetime.now(timezone.utc) + timedelta(days=30) + + stmt = text(""" + UPDATE data.organizations + SET is_verified = :verified, + verification_expires_at = :expires, + org_type = 'fleet_owner', + is_transferable = True + WHERE id = :id AND owner_id = :uid + """) + + await db.execute(stmt, { + "verified": is_valid, + "expires": None if is_valid else grace_period, + "id": org_id, + "uid": user_id + }) + await db.commit() + @staticmethod async def check_email_availability(db: AsyncSession, email: str) -> bool: query = select(User).where(and_(User.email == email, User.is_deleted == False)) diff --git a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md index 1e9be66..27ef3c3 100644 --- a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md +++ b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md @@ -1,4 +1,4 @@ -# 🔐 AUTHENTICATION & IDENTITY SPECIFICATION (v1.0) +# 🔐 AUTHENTICATION & IDENTITY SPECIFICATION (v1.2) ## I. AZONOSÍTÁSI STRATÉGIA A rendszer szétválasztja a **technikai hozzáférést** (User) és a **valós identitást** (Person). @@ -37,4 +37,44 @@ Minden regisztrációnál létrejön: ## IV. MODERÁCIÓ ÉS VALIDÁLÁS - **Validált vélemény:** Csak igazolt ott-tartózkodás (GPS) vagy számlafotó után adható. -- **Fellebbezés:** A szerviz kérheti a vélemény felülvizsgálatát, amit a Moderátorok/Validátorok bírálnak el. \ No newline at end of file +- **Fellebbezés:** A szerviz kérheti a vélemény felülvizsgálatát, amit a Moderátorok/Validátorok bírálnak el. + +## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ +1. **Verifikációs szintek:** + - **Unverified (Nem ellenőrzött):** Kézi rögzítés utáni alapállapot. 30 napos türelmi idő. + - **Verified (Hitelesített):** Sikeres VIES vagy nemzeti cégnyilvántartó lekérdezés után. + - **Suspended (Felfüggesztett):** Ha az automatikus időszakos ellenőrzés során a cég "megszűnt" vagy "inaktív" státuszt kap. + +2. **Ellenőrzési logika:** + - Elsődleges: **VIES API** (EU-s adószám ellenőrző). + - Másodlagos: Nemzeti cégkeresők (robotizált lekérdezés). + - Kivételkezelés: Ha a robot nem tud dönteni, a feladat az **Admin/Moderátor** várólistájára kerül. + + ## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ (v1.2) + +1. **Verifikációs Státuszok:** + - **Unverified (Nem ellenőrzött):** Alapértelmezett állapot kézi rögzítés után. 30 napos türelmi időt biztosít a teljes körű használathoz. + - **Verified (Hitelesített):** Automatikus VIES lekérdezés vagy adminisztrátori jóváhagyás utáni állapot. + - **Suspended (Felfüggesztett):** Megszűnt cégek vagy le nem igazolt adatok esetén az időszakos (havi) ellenőrzés során. + +2. **Ellenőrzési Logika (Robot & Admin):** + - **Robot:** A rendszer a `VAT_NUMBER` rögzítésekor azonnal meghívja az EU-s VIES API-t. Egyezőség esetén a státusz azonnal `Verified`. + - **Adminisztrátor:** Ha az API nem ad eredményt (pl. friss bejegyzés vagy technikai hiba), az Adminisztrátor kézzel állíthatja át a státuszt a feltöltött dokumentumok alapján. + - **Időszakos ellenőrzés:** Egy ütemezett feladat 30 naponta újraellenőrzi a `Verified` cégeket. Ha egy cég megszűntnek tűnik, a rendszer `Suspended` státuszba teszi és értesíti a tulajdonost. + +3. **Korlátozások (Suspended/Unverified):** + - Nem rögzíthető új jármű a flottába. + - Nem generálható meghívó (Invite Token). + - Statisztikai kimutatások korlátozása. + + ## I. AZONOSÍTÁSI STRATÉGIA (v1.3) +... +### 3. Social Auth (Google / Facebook) +- **Működés:** Engedélyezett a gyors belépéshez. +- **Kényszerített KYC:** Social Auth esetén a 2. lépésben kötelező a KYC adatok (anyja neve, születési adatok) pótlása. +- **Korlátozás:** Amíg a KYC adatok hiányoznak, a felhasználó "Free User" marad, és nem fér hozzá a regisztrációkor járó extra prémium szolgáltatásokhoz. + +## IV. CÉGES AZONOSÍTÁS ÉS VERIFIKÁCIÓ +... +- **Hibrid Validálás:** Ha a VIES API nem ad eredményt, a rendszer céges dokumentum feltöltését kéri. +- **Ellenőrzés:** Adminisztrátori jóváhagyás vagy AI-alapú dokumentum-validálás után válik `Verified` státuszúvá. \ No newline at end of file diff --git a/docs/V01_gemini/06_Database_Guide.md b/docs/V01_gemini/06_Database_Guide.md index 0ecfcaf..7917c39 100644 --- a/docs/V01_gemini/06_Database_Guide.md +++ b/docs/V01_gemini/06_Database_Guide.md @@ -46,4 +46,24 @@ A rendszer fel van készítve az EU-s piacra: ## 5. Dinamikus Paraméterezés (System Settings) - **`auth.reward_days`**: Adminból állítható egész szám (alapértelmezett: 14). -- **`auth.reward_tier`**: Melyik csomagot kapja (alapértelmezett: PREMIUM). \ No newline at end of file +- **`auth.reward_tier`**: Melyik csomagot kapja (alapértelmezett: PREMIUM). + +## 6. Flotta és Tulajdonjog Szabályok (v1.1) +- **Opcionális Járművek:** Egy flotta (Organization) létezhet járművek nélkül is. A rendszer nem kényszeríti a jármű rögzítését (pl. Flotta menedzser szerepkör esetén). +- **Átruházhatóság (Transferability):** + - `INDIVIDUAL` flotta: Nem átruházható, a felhasználóhoz kötött. + - `FLEET_OWNER / SERVICE` flotta: Átruházható (eladható), új tulajdonos (owner_id) rendelhető hozzá. +- **Cég Megszűnése:** Soft delete alkalmazása. A cég `is_active` státusza `False` lesz, a tulajdonosi viszony megszűnik, de a járművek életútjában (history) az adatok megmaradnak a visszakövethetőség miatt. + +## 7. Gazdasági Izoláció +- **Gamification Korlát:** Csak `INDIVIDUAL` típusú flottákhoz tartozó `Person`-ok vehetnek részt a gamifikációban (XP gyűjtés). +- **Validációs Korlát:** Cég mint identitás nem validálhat szervizpontot, ezt mindig egy hozzárendelt, azonosított `Person` (alkalmazott/technikus) végzi. + +## 8. Szervezeti és Gazdasági Szabályok +- **Identitás Elkülönítés:** A `Company` (Szervezet) entitás nem kap `XP_Ledger` és `Coin_Wallet` rekordot a gamifikációhoz. Ezek kizárólag a `Person` (valós személy) szintjén léteznek. +- **Automatizált Felügyelet:** Egy ütemezett feladat (Cron/Celery) havonta ellenőrzi a cégek státuszát a külső adatbázisokban. +- **Értékelési rendszer (Rating):** + - **Person:** Egyéni teljesítmény, megbízhatóság. + - **Service (Szerviz):** Szolgáltatási minőség. + - **Vehicle (Jármű):** Műszaki állapot és előélet. + - *Megjegyzés:* A Cég (mint flotta) nem kap önálló értékelést, a hírneve a tagjai és járművei minősítéséből adódik össze. \ No newline at end of file diff --git a/docs/V01_gemini/09_Admin_API_Guide.md b/docs/V01_gemini/09_Admin_API_Guide.md new file mode 100644 index 0000000..d3a8d15 --- /dev/null +++ b/docs/V01_gemini/09_Admin_API_Guide.md @@ -0,0 +1,35 @@ +# 🛠️ ADMIN MANAGEMENT & PERMISSIONS (v1.0) + +## 1. Adminisztrátori Hiearchia é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:** Az L1/B szintű vezetők látják más országok aggregált KPI mutatóit (statisztika), de nem látnak bele a konkrét személyes vagy céges adatokba. + +## 2. Jogosultságkezelés és Sablonok +- **Permissions Table:** Elemi jogosultságok tárolása (pl. `approve_vies`, `modify_credits`). +- **Role Templates:** Előre definiált sablonok az egyszerű beállításhoz (pl. "Senior Financial - DE"). +- **Regionális Izoláció:** Az adminisztrátorok alapértelmezetten csak a hozzájuk rendelt `ISO_country_code` alá tartozó adatokat módosíthatják. + +## 3. Biztonság és "Kill-Switch" Protokoll +- **MFA/2FA:** A második bejelentkezéstől kezdve kötelező a TOTP (Google Authenticator) használata. +- **Social Auth:** Adminok számára is engedélyezett (Google/FB), de nem váltja ki a kötelező 2FA-t. +- **Anomaly Score (Fekete Doboz):** + - Minden kattintást és módosítást logolunk (`audit_logs`). + - Kritikus viselkedés (pl. tömeges törlés) esetén a rendszer automatikusan felfüggeszti az admint. + - **SuperAdmin Recovery:** A SuperAdmin visszaállítása csak egyedi Offline Kulccsal és regisztrált eszközzel lehetséges. + - **Értesítési lánc:** Tiltáskor a felette álló szintek azonnali riasztást kapnak. + +## 4. Visszaállíthatóság (State Snapshot) +Minden módosítás előtt a rendszer menti az aktuális rekord állapotát (JSON). Bármilyen károkozás vagy hiba esetén az L0/L1 szintű adminisztrátorok egy gombnyomással visszaállíthatják az eredeti adatokat. + +## 5. Adminisztrátori Meghívók +- Adminisztrátort csak kézi meghívóval lehet felvenni. +- **Lejárati idő:** Minden admin meghívó token 24 óráig érvényes. \ No newline at end of file diff --git a/docs/V01_gemini/10_Billing_Credits_Subscriptions.md b/docs/V01_gemini/10_Billing_Credits_Subscriptions.md index 3171424..972e851 100644 --- a/docs/V01_gemini/10_Billing_Credits_Subscriptions.md +++ b/docs/V01_gemini/10_Billing_Credits_Subscriptions.md @@ -1,35 +1,58 @@ -# 💰 BILLING, CREDITS AND MULTI-CURRENCY (v1.0) +# 💰 BILLING, CREDITS & SUBSCRIPTIONS (v1.2) ## 1. Regionális és Valuta Logika (EU Scope) -A rendszer támogatja a többnyelvű és többvalutás elszámolást. Minden pénzügyi tranzakció két értéket tárol: -1. **Local Cost:** Helyi pénznemben rögzített összeg (pl. 45.000 Ft). -2. **Standard Cost (EUR):** A rögzítéskori középárfolyamon átszámított euró érték. +A rendszer támogatja a többnyelvű és többvalutás elszámolást az EU teljes területén. Minden pénzügyi tranzakció két értéket tárol: +1. **Local Cost:** A felhasználó helyi pénznemében rögzített összeg (pl. 45.000 Ft). +2. **Standard Cost (EUR):** A rögzítés pillanatában érvényes középárfolyamon átszámított euró érték. **Átszámítási képlet:** $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$ -## 2. Előfizetési Csomagok (Adminból állítható) -A csomagok limiteit (járműszám, funkciók) a `system_settings` tábla szabályozza. +## 2. Előfizetési Csomagok és Szinergia +A csomagok limiteit a `data.system_settings` tábla szabályozza. A cégtulajdonosok ösztönzése érdekében **Business Synergy** kedvezményt alkalmazunk. | Csomag | Jármű Limit | Kiemelt funkciók | | :--- | :--- | :--- | -| **FREE** | 1 db | Csak GEO keresés, alap költséglog, nincs dokumentum/export. | -| **PREMIUM** | 3 db | Teljes dokumentum/fotó tár, útvonal alapú kereső, export. | -| **PREMIUM+** | 5 db | 5 felhasználó, flotta-szintű statisztika, TCO elemzés. | -| **VIP** | 10 db + | Bővíthető slotok, egyedi szerviz partnerek kezelése. | +| **FREE** | 1 db | Alap költséglog, GEO keresés. | +| **PREMIUM** | 3 db | Teljes dokumentumtár, export, útvonal alapú kereső. | +| **PREMIUM+** | 5 db | Flotta statisztika, TCO elemzés, 5 felhasználó. | +| **VIP / VIP+** | 10+ db | Egyedi szervizkezelés, bővíthető slotok, prioritásos support. | -## 3. Evidence & Trust Engine (Bizonyíték kezelés) -A rendszer csak azokat a szerviz eseményeket tekinti **hitelesnek (Verified)**, amelyekhez tartozik: -- **Fotó:** Kilométeróra állásról és munkalapról. -- **Digitális számla:** Feltöltött PDF vagy kép. -- **GPS Check-in:** Igazolás, hogy a felhasználó valóban a szerviznél tartózkodott. +**VIP Synergy Szabályok:** +- **Synergy Discount:** Ha egy felhasználó `FLEET_OWNER` szervezetének aktív **VIP** vagy **VIP+** előfizetése van, **15% kedvezményt** kap minden vásárlásra a saját privát flottájában. +- **Ajándék Kredit:** VIP csomag vásárlásakor a tulajdonos extra krediteket kap, amit skinekre, medálokra vagy a privát Prémium csomagjára költhet el. +- **Időbeli korlát:** A privát Prémium/Prémium+ kedvezmények időtartama **2-6 hónapra korlátozott**, elkerülve a tartós ingyenhasználatot. -## 4. Szerviz Minősítési Rendszer -- Csak érvényes szerviz esemény után adható értékelés. -- **Fellebbezés:** A szolgáltató kérheti a valótlan/troll vélemény felülvizsgálatát. -- **Validátorok:** Magas rangú felhasználók pontokért/kreditért ellenőrizhetik a vitatott bejegyzéseket. +## 3. Voucher és Kupon Rendszer +A kedvezmények nem automatikusak, a kód manuális beírása kötelező. +- **Gift Card (Fix Kredit):** Fix összegű ajándék kredit (pl. 5000 Ft értékben). +- **Subscription Coupon (%):** Százalékos kedvezmény előfizetési díjakból, meghatározott időszakra. +- **Szabályok:** + - Minden kupon rendelkezik **lejárati idővel**. + - Minden felhasználást auditálni kell: `redeemed_at`, `user_id`, `original_price`, `discount_price`. -## 5. Lejárat és Helyreállítás -- **Grace Period (30 nap):** Csak rögzítés lehetséges, statisztika/lekérdezés zárolva. +## 4. MLM Jutalomrendszer (10-5-2%) +A rendszer jutalmazza a sikeres meghívásokat az első befizetés után: +- **1. szint (Közvetlen):** 10% jóváírás. +- **2. szint:** 5% jóváírás. +- **3. szint:** 2% jóváírás. +A százalékos érték a befizetés pillanatában rögzül a tranzakcióban (Snapshot). + +## 5. Invitation Engine (Meghívó Rendszer) +A spam elkerülése érdekében korlátozott keretrendszert alkalmazunk: +- **Lejárati idők:** + - **Felhasználói meghívó:** 72 óra. + - **Adminisztrátori meghívó:** 24 óra. +- **Mennyiségi korlát:** Kezdő keret felhasználónként (pl. 10 vagy 20 db). +- **Anti-Spam Logika:** Új meghívási lehetőséget csak sikeres regisztrációk után kap vissza a felhasználó. A keret mértéke adminisztrációs felületről állítható. + +## 6. Evidence & Trust Engine (Hitelesítés) +A szerviz események és értékelések csak bizonyítékok megléte esetén válnak **Verified** (hiteles) státuszúvá: +- **Fotó/Dokumentum:** Munkalap és kilométeróra fotó kötelező. +- **GPS Check-in:** Igazolás a helyszíni tartózkodásról. +- **Identitás:** Cég mint entitás nem validálhat, csak azonosított `Person`. + +## 7. Lejárat és Pénzügyi Helyreállítás +- **Grace Period (30 nap):** Csak rögzítés lehetséges, statisztika zárolva. - **Zárolás (60 nap):** A fiók írásvédetté válik. -- **Helyreállítás:** 6 hónapon belül visszamenőleges befizetéssel minden funkció (és a Free korszak adatai) aktiválódik. \ No newline at end of file +- **Helyreállítás:** 6 hónapon belüli visszamenőleges befizetéssel minden funkció és korábbi adat újra aktiválódik. \ No newline at end of file diff --git a/docs/V01_gemini/15_Changelog.md b/docs/V01_gemini/15_Changelog.md index de5367a..2e9c7fe 100644 --- a/docs/V01_gemini/15_Changelog.md +++ b/docs/V01_gemini/15_Changelog.md @@ -5,3 +5,26 @@ - **Init:** Grand Master Book létrehozása. - **Arch:** Átköltözés a 80 magos szerverre. - **Spec:** Kredit rendszer, Tiers, Soft Delete és Person logika véglegesítése. + +### [2026-02-04] - Identity & Company Sync (v1.2) +- **Modell Konszolidáció:** Az `app.models.identity` lett a központi identitáskezelő (User, Person, Wallet). +- **Master Book v1.2 Implementáció:** Bevezetésre került a céges verifikációs logika (is_verified) és a 30 napos türelmi idő kezelése. +- **Integritás javítás:** Az `Organization` tábla bővítve lett `is_transferable` és hitelesítési mezőkkel. +- **Bugfix:** `security.py` IndentationError javítva, `auth_service.py` atomikus regisztrációs flow Master Book szinkronizálva. +- **Security:** PostgreSQL tábla-tulajdonosi jogosultságok felülvizsgálata a migrációs hibák elhárításához. + +### [2026-02-05] - Identity & Company Sync (v1.2) +- **Database Security:** Javítva a `user_vehicle_equipment` tábla tulajdonosi jogosultsága (`shared-postgres` környezetben). +- **Core Fix:** A `security.py` állomány behúzási hibái (IndentationError) véglegesen elhárítva. +- **Organization v1.2:** Implementálva az `is_transferable`, `is_verified` és `verification_expires_at` mezők a flották hitelesítéséhez. +- **AuthService Logic:** - Az `INDIVIDUAL` típusú flották mostantól alapértelmezetten nem átruházhatóak. + - Beépítve a 30 napos türelmi idő (`grace_period`) kalkulációja a cégellenőrzéshez. + - Atomikus regisztráció kiterjesztve a privát flották automatikus létrehozására. +- **Infrastructure:** Alembic migrációs lánc szinkronizálva az új modellekkel. + +### [2026-02-05] - Admin & Economy Finalization (v1.0) +- **Admin Management:** Teljes hiearchia és területi felosztás kidolgozva (L0-L3). +- **Security:** "Kill-switch" anomália-figyelés és 2FA kényszerítés rögzítve. +- **Economy:** 10-5-2% jutalékrendszer és Voucher/Coupon logika specifikálva. +- **Synergy:** Céges VIP és privát flotta közötti kedvezmény-szinergia kidolgozva. +- **Invitations:** Meghívó limitációs és anti-spam logika rögzítve. \ No newline at end of file