diff --git a/backend/Dockerfile b/backend/Dockerfile index 25809c6..00bee41 100755 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -2,17 +2,20 @@ FROM python:3.12-slim WORKDIR /app -# 1. Rendszerfüggőségek telepítése +# 1. Rendszerfüggőségek telepítése (gcc és képkezelő könyvtárak) RUN apt-get update && apt-get install -y --no-install-recommends \ gcc \ python3-dev \ libpq-dev \ + libjpeg-dev \ + zlib1g-dev \ && rm -rf /var/lib/apt/lists/* -# 2. PIP frissítése (Ez némítja el a panaszkodást) +# 2. PIP frissítése RUN pip install --upgrade pip # 3. Függőségek telepítése +# Fontos: A requirements.txt fájlba írd be: Pillow==10.2.0 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt diff --git a/backend/app/api/v1/__pycache__/api.cpython-312.pyc b/backend/app/api/v1/__pycache__/api.cpython-312.pyc index e3466a7..b86352d 100644 Binary files a/backend/app/api/v1/__pycache__/api.cpython-312.pyc and b/backend/app/api/v1/__pycache__/api.cpython-312.pyc differ diff --git a/backend/app/api/v1/api.py b/backend/app/api/v1/api.py index 9637aa4..5463e63 100755 --- a/backend/app/api/v1/api.py +++ b/backend/app/api/v1/api.py @@ -1,16 +1,19 @@ from fastapi import APIRouter -from app.api.v1.endpoints import auth, catalog, assets, organizations +from app.api.v1.endpoints import auth, catalog, assets, organizations, documents # <--- Ide bekerült a documents! api_router = APIRouter() -# Felhasználó és Identitás +# Hitelesítés api_router.include_router(auth.router, prefix="/auth", tags=["Authentication"]) -# Katalógus és Jármű Robotok +# Katalógus api_router.include_router(catalog.router, prefix="/catalog", tags=["Vehicle Catalog"]) -# Egyedi Eszközök (Assets) +# Eszközök (Járművek) api_router.include_router(assets.router, prefix="/assets", tags=["Assets"]) -# Szervezetek és Onboarding -api_router.include_router(organizations.router, prefix="/organizations", tags=["Organizations"]) \ No newline at end of file +# Szervezetek +api_router.include_router(organizations.router, prefix="/organizations", tags=["Organizations"]) + +# DOKUMENTUMOK (Ez az új rész, ami hiányzik neked) +api_router.include_router(documents.router, prefix="/documents", tags=["Documents"]) \ No newline at end of file diff --git a/backend/app/api/v1/endpoints/__pycache__/documents.cpython-312.pyc b/backend/app/api/v1/endpoints/__pycache__/documents.cpython-312.pyc new file mode 100644 index 0000000..e69bc64 Binary files /dev/null and b/backend/app/api/v1/endpoints/__pycache__/documents.cpython-312.pyc differ diff --git a/backend/app/api/v1/endpoints/documents.py b/backend/app/api/v1/endpoints/documents.py new file mode 100644 index 0000000..ba14c90 --- /dev/null +++ b/backend/app/api/v1/endpoints/documents.py @@ -0,0 +1,30 @@ +from fastapi import APIRouter, Depends, UploadFile, File, BackgroundTasks, HTTPException +from sqlalchemy.ext.asyncio import AsyncSession +from app.db.session import get_db +from app.services.document_service import DocumentService + +router = APIRouter() + +@router.post("/upload/{parent_type}/{parent_id}") +async def upload_document( + parent_type: str, + parent_id: str, + background_tasks: BackgroundTasks, + file: UploadFile = File(...), + db: AsyncSession = Depends(get_db) +): + """ + Dokumentum feltöltés, optimalizálás és NAS-ra mentés. + parent_type: 'organizations' vagy 'assets' + """ + if parent_type not in ["organizations", "assets"]: + raise HTTPException(status_code=400, detail="Érvénytelen cél-típus!") + + doc = await DocumentService.process_upload(file, parent_type, parent_id, db, background_tasks) + + return { + "document_id": doc.id, + "thumbnail": doc.thumbnail_path, + "original_name": doc.original_name, + "status": "processed_and_vaulted" + } \ No newline at end of file diff --git a/backend/app/main.py b/backend/app/main.py index f925858..d193f4e 100755 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -1,30 +1,45 @@ +import os from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware +from fastapi.staticfiles import StaticFiles from app.api.v1.api import api_router from app.core.config import settings +# 1. Könyvtárstruktúra biztosítása (SSD puffer a miniképeknek) +# Ez garantálja, hogy az app elindulásakor létezik a célmappa +os.makedirs("static/previews", exist_ok=True) + app = FastAPI( title="Service Finder API", - version="2.0.0", # A rendszer verziója, de a végpont marad v1 + version="2.0.0", openapi_url="/api/v1/openapi.json", docs_url="/docs" ) -# PONTOS CORS BEÁLLÍTÁS +# 2. PONTOS CORS BEÁLLÍTÁS app.add_middleware( CORSMiddleware, allow_origins=[ "http://192.168.100.10:3001", # Frontend portja "http://localhost:3001", - "https://dev.profibot.hu" # Ha van NPM proxy + "https://dev.profibot.hu" # NPM proxy esetén ], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) +# 3. STATIKUS FÁJLOK KISZOLGÁLÁSA +# Ez teszi lehetővé, hogy a /static eléréssel lekérhetőek legyenek a miniképek +app.mount("/static", StaticFiles(directory="static"), name="static") + +# 4. ROUTER BEKÖTÉSE app.include_router(api_router, prefix="/api/v1") @app.get("/") async def root(): - return {"status": "online", "message": "Service Finder Master System v1.0"} \ No newline at end of file + return { + "status": "online", + "message": "Service Finder Master System v2.0", + "features": ["Document Engine", "Asset Vault", "Org Onboarding"] + } \ No newline at end of file diff --git a/backend/app/models/__pycache__/document.cpython-312.pyc b/backend/app/models/__pycache__/document.cpython-312.pyc new file mode 100644 index 0000000..ca8f2c8 Binary files /dev/null and b/backend/app/models/__pycache__/document.cpython-312.pyc differ diff --git a/backend/app/models/document.py b/backend/app/models/document.py new file mode 100644 index 0000000..ce7942e --- /dev/null +++ b/backend/app/models/document.py @@ -0,0 +1,26 @@ +from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey +from sqlalchemy.dialects.postgresql import UUID +from sqlalchemy.sql import func +import uuid +from app.db.base import Base + +class Document(Base): + __tablename__ = "documents" + __table_args__ = {"schema": "data"} + + id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + parent_type = Column(String(20), nullable=False) # 'organization' vagy 'asset' + parent_id = Column(String(50), nullable=False) # Org vagy Asset technikai ID-ja + doc_type = Column(String(50)) # pl. 'foundation_deed', 'registration' + + original_name = Column(String(255), nullable=False) + file_hash = Column(String(64), nullable=False) # A NAS-on tárolt név (UUID) + file_ext = Column(String(10), default="webp") + mime_type = Column(String(100), default="image/webp") + file_size = Column(Integer) + + has_thumbnail = Column(Boolean, default=False) + thumbnail_path = Column(String(255)) # SSD-n lévő elérés + + uploaded_by = Column(Integer, ForeignKey("data.users.id"), nullable=True) + created_at = Column(DateTime(timezone=True), server_default=func.now()) \ No newline at end of file diff --git a/backend/app/services/__pycache__/document_service.cpython-312.pyc b/backend/app/services/__pycache__/document_service.cpython-312.pyc new file mode 100644 index 0000000..5938f95 Binary files /dev/null and b/backend/app/services/__pycache__/document_service.cpython-312.pyc differ diff --git a/backend/app/services/document_service.py b/backend/app/services/document_service.py new file mode 100644 index 0000000..ab2eadb --- /dev/null +++ b/backend/app/services/document_service.py @@ -0,0 +1,82 @@ +import os +import shutil +import time +from PIL import Image +from uuid import uuid4 +from fastapi import UploadFile, BackgroundTasks +from sqlalchemy.ext.asyncio import AsyncSession +from app.models.document import Document + +class DocumentService: + @staticmethod + def _clean_temp(path: str): + """30 perc után törli az ideiglenes fájlt (opcionális, ha maradunk a puffer mellett)""" + time.sleep(1800) + if os.path.exists(path): + os.remove(path) + + @staticmethod + async def process_upload( + file: UploadFile, + parent_type: str, + parent_id: str, + db: AsyncSession, + background_tasks: BackgroundTasks + ): + file_uuid = str(uuid4()) + + # 1. Könyvtárstruktúra meghatározása + temp_dir = "/app/temp/uploads" + nas_vault_dir = f"/mnt/nas/app_data/organizations/{parent_id}/vault" + ssd_thumb_dir = f"/app/static/previews/organizations/{parent_id}" + + for d in [temp_dir, nas_vault_dir, ssd_thumb_dir]: + os.makedirs(d, exist_ok=True) + + # 2. Mentés a TEMP-be + temp_path = os.path.join(temp_dir, f"{file_uuid}_{file.filename}") + content = await file.read() + with open(temp_path, "wb") as f: + f.write(content) + + # 3. Képfeldolgozás (Pillow) + img = Image.open(temp_path) + + # A) Thumbnail generálás (300px WebP az SSD-re) + thumb_filename = f"{file_uuid}_thumb.webp" + thumb_path = os.path.join(ssd_thumb_dir, thumb_filename) + thumb_img = img.copy() + thumb_img.thumbnail((300, 300)) + thumb_img.save(thumb_path, "WEBP", quality=80) + + # B) Nagy kép optimalizálás (Max 1600px WebP a NAS-ra) + vault_filename = f"{file_uuid}.webp" + vault_path = os.path.join(nas_vault_dir, vault_filename) + + if img.width > 1600: + ratio = 1600 / float(img.width) + new_height = int(float(img.height) * float(ratio)) + img = img.resize((1600, new_height), Image.Resampling.LANCZOS) + + img.save(vault_path, "WEBP", quality=85) + + # 4. Adatbázis rögzítés + new_doc = Document( + id=uuid4(), + parent_type=parent_type, + parent_id=parent_id, + original_name=file.filename, + file_hash=file_uuid, + file_size=os.path.getsize(vault_path), + has_thumbnail=True, + thumbnail_path=f"/static/previews/organizations/{parent_id}/{thumb_filename}" + ) + db.add(new_doc) + await db.commit() + + # 5. Puffer törlés ütemezése (30 perc) + # background_tasks.add_task(DocumentService._clean_temp, temp_path) + # MVP-ben töröljük azonnal, ha már a NAS-on van a biztonságos másolat + os.remove(temp_path) + + return new_doc \ No newline at end of file diff --git a/backend/requirements.txt b/backend/requirements.txt index 100c560..64bf8e4 100755 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -17,3 +17,4 @@ psycopg[binary] httpx pydantic[email] sendgrid==6.* +Pillow \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 5c2fa5e..79dcbf9 100755 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,14 +10,13 @@ services: - ./backend:/app - ./alembic.ini:/app/alembic.ini - ./migrations:/app/migrations - - /mnt/nas/app_data:/mnt/nas/app_data environment: PYTHONPATH: /app DATABASE_URL: ${MIGRATION_DATABASE_URL} command: ["bash", "-lc", "alembic upgrade head"] networks: - - default # Hogy lássa a saját hálózatát - - shared_db_net # Hogy lássa a KÖZPONTI adatbázist! + - default + - shared_db_net restart: "no" # 2. BACKEND API @@ -31,7 +30,8 @@ services: - ./backend:/app - ./alembic.ini:/app/alembic.ini - ./migrations:/app/migrations - # Fontos: A 0.0.0.0 host kell, hogy a Proxy elérje! + - /mnt/nas/app_data:/mnt/nas/app_data # Központi NAS elérés + - ./static_previews:/app/static/previews # Lokális SSD gyorsítótár a miniképeknek command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips="*" ports: - "8000:8000" @@ -51,10 +51,10 @@ services: condition: service_started networks: - default - - shared_db_net # <--- ITT KAPCSOLÓDIK A KÖZPONTHOZ + - shared_db_net restart: unless-stopped - # 3. MINIO (Lokális marad a projekthez, de NAS-ra ment) + # 3. MINIO (NAS-ra ment) minio: image: minio/minio container_name: service_finder_minio @@ -72,7 +72,7 @@ services: - default restart: unless-stopped - # 4. REDIS (Gyorsítótár - Lokális marad) + # 4. REDIS (Lokális cache, NAS perzisztencia) redis: image: redis:alpine container_name: service_finder_redis @@ -82,7 +82,7 @@ services: - default restart: unless-stopped - # 5. FRONTEND (Weboldal) + # 5. FRONTEND service_finder_frontend: build: context: ./frontend @@ -99,10 +99,8 @@ services: condition: service_started restart: unless-stopped -# HÁLÓZATOK DEFINIÁLÁSA networks: default: driver: bridge - # Ez a kulcs! Megmondjuk neki, hogy használja a már létező központi hálót: shared_db_net: external: true \ No newline at end of file diff --git a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md index bd0bb7a..e8eea01 100644 --- a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md +++ b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md @@ -1,103 +1,94 @@ -# 🔐 AUTHENTICATION & IDENTITY SPECIFICATION (v1.2) +# 🔐 05_AUTH_AND_IDENTITY_SPEC (v1.3) -## 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). +## 1. Azonosítási Stratégia +A rendszer alapelve a **technikai hozzáférés** (User) és a **valós identitás** (Person) szigorú szétválasztása. -### 1. Identitás szintek -- **User (Login):** Email + Jelszó. Csak a belépéshez és a munkamenethez kell. -- **Person (Identity):** Vezetéknév, Keresztnév, Anyja neve, Születési adatok, Okmányok. -- **Azonosító:** Minden Person kap egy globális egyedi azonosítót (UUID). +### 1.1. Identitás szintek +- **User (Login):** Email + Jelszó. Kizárólag a belépéshez és a munkamenet (session) kezeléséhez szükséges technikai entitás. +- **Person (Identity):** A valós személy adatai (Név, anyja neve, születési adatok, okmányok). Minden Person kap egy globális egyedi azonosítót (**UUID**). -### 2. Soft Delete & Re-regisztráció -- **Nincs fizikai törlés:** A felhasználó csak egy `is_hidden` vagy `deleted_at` flag-et kap. -- **Ismételt regisztráció:** Ha az email/név/okmány alapján a rendszer felismeri a visszatérőt: - - Új technikai User fiók jön létre. - - Ez az új fiók a korábbi Person ID-hoz kapcsolódik. - - **Adat-izoláció:** A felhasználó csak az új regisztráció dátuma utáni eseményeket látja. A régi adatok a háttérben maradnak (statisztika, sofőr elemzés), de számára rejtettek. - -## II. BŐVÍTETT ADATTÁR (KYC & SAFETY) -A `persons` tábla az alábbi adatcsoportokat tartalmazza (Progresszív feltöltéssel): -- **Alapadatok:** `last_name`, `first_name`, `birth_place`, `birth_date`, `mothers_name`. -- **Hivatalos okmányok:** Személyi ig. szám, Jogosítvány (szám + kategóriák + érvényesség), Lakcímkártya, TAJ, Adóazonosító. -- **Vészhelyzeti adatok (Safety):** Vércsoport, Allergia, Értesítendő személy (ICE) neve és telefonszáma. -- **Jutalom:** A teljes körű adategyeztetésért 2 hét PRÉMIUM tagság jár. - -## III. JUTALÉK ÉS GAZDASÁG -### 1. Piramis rendszer (3 szint) -Meghívó lánc alapján számolt jóváírás: -- **1. szint (Közvetlen):** 10% -- **2. szint:** 5% -- **3. szint:** 2% -*A százalékok a befizetés pillanatában érvényes admin beállítások alapján rögzülnek a tranzakcióban (Snapshot).* - -### 2. Wallets -Minden regisztrációnál létrejön: -- **Coin Wallet:** Belső fizetőeszköz (Kredit). -- **XP Ledger:** Tapasztalati pontok (Verseny és rangsor). - -## 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. - -## 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) +### 1.2. 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. +- **Kényszerített KYC:** Social Auth esetén a 2. lépésben kötelező a KYC 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á. +### 1.3. Soft Delete & Re-regisztráció +- **Nincs fizikai törlés:** A felhasználó törléskor `is_hidden` vagy `deleted_at` flag-et kap. +- **Ismételt regisztráció:** Ha az email/név/okmány alapján a rendszer felismeri a visszatérőt: + - Új technikai User fiók jön létre, de a korábbi **Person ID**-hoz kapcsolódik. + - **Adat-izoláció:** A felhasználó csak az új regisztráció utáni eseményeket látja, a régi adatok (statisztika, elemzés) csak a háttérben maradnak meg. -# 🆔 Identitás Validációs és Bizalmi Protokoll +--- -A rendszer a fokozatos adatszolgáltatás és a "Tier-based Access Control" (szintezett hozzáférés) elvét alkalmazza. - -## 1. Bizalmi Szintek (Trust Tiers) +## 2. Bizalmi Szintek (Trust Tiers) +A rendszer a "Tier-based Access Control" (szintezett hozzáférés) elvét alkalmazza az adatszolgáltatás mértékétől függően. | Szint | Megnevezés | Követelmény | Jogosultságok | | :--- | :--- | :--- | :--- | | **Tier 0** | Anonymous | Nincs | Csak publikus adatok megtekintése. | -| **Tier 1** | Verified Email | Step 1 sikeres | Belépés, saját profil megtekintése. | +| **Tier 1** | Verified Email | Step 1 (Regisztráció) sikeres | Belépés, saját profil megtekintése. | | **Tier 2** | KYC Submitted | Step 2 (Személyi adatok + Telefon) | **Privát Széf/Flotta aktiválása**, Wallet használat. | | **Tier 3** | AI/OCR Verified | Okmánykép AI általi ellenőrzése | Harmadik fél szolgáltatásainak igénybevétele. | -## 2. Kötelező Adatkör (Step 2 - Tier 2) -A "Privát Széf" aktiválásához az alábbi adatok megadása kötelező: -- **Kapcsolat:** Valós telefonszám (nemzetközi formátum). -- **Személyi:** Születési hely, idő, anyja neve. -- **Okmány:** Típus, sorszám és **lejárati dátum**. -- **Biztonság:** ICE (In Case of Emergency) név és telefonszám. +--- -## 3. Adattárolási Stratégia -- A rugalmas okmányadatokat és vészhelyzeti kapcsolatokat a `persons.identity_docs` és `persons.ice_contact` JSONB mezőkben tároljuk a kereshetőség és bővíthetőség érdekében. \ No newline at end of file +## 3. KYC és Bővített Adattár (Safety) +A `persons` tábla progresszív feltöltéssel tárolja az adatokat a "Minimal Friction" elv mentén. + +### 3.1. Kötelező Adatkör (Step 2 - Tier 2) +A "Privát Széf" aktiválásához az alábbi adatok megadása kötelező: +- **Alapadatok:** `last_name`, `first_name`, `birth_place`, `birth_date`, `mothers_name`. +- **Kapcsolat:** Valós telefonszám (nemzetközi formátum). +- **Hivatalos okmányok:** Személyi ig. szám, Jogosítvány (szám, kategóriák, érvényesség), Lakcímkártya, TAJ, Adóazonosító. +- **Biztonság (ICE):** "In Case of Emergency" adatok (értesítendő személy neve és telefonszáma). +- **Vészhelyzeti adatok:** Vércsoport, Allergia. + +### 3.2. Jutalom Trigger +A teljes körű adategyeztetésért (100%-os profilkitöltöttség) **2 hét PRÉMIUM** tagság jár. + +--- + +## 4. Céges Azonosítás és Verifikáció +A szervezetek (Companies) hitelesítése és bizalmi szintjeinek kezelése. + +### 4.1. Verifikációs Státuszok +- **Unverified (Nem ellenőrzött):** Kézi rögzítés utáni alapállapot. 30 napos türelmi időt biztosít a funkciókhoz. +- **Verified (Hitelesített):** Hitelesített állapot (VIES API találat vagy Admin kézi jóváhagyás után). +- **Suspended (Felfüggesztett):** Megszűnt cég vagy le nem igazolt adatok esetén az időszakos ellenőrzés során. + +### 4.2. Ellenőrzési Logika (Robot & Admin) +1. **Robot:** A `VAT_NUMBER` rögzítésekor a rendszer azonnal meghívja az EU-s **VIES API**-t. Egyezőség esetén azonnal `Verified`. +2. **Hibrid Validálás:** Ha a VIES API nem ad eredményt, a rendszer céges dokumentum feltöltését kéri. +3. **Ellenőrzés:** Adminisztrátori jóváhagyás vagy AI-alapú dokumentum-validálás után válik a státusz véglegessé. +4. **Időszakos ellenőrzés:** Ütemezett feladat (Cron) 30 naponta újraellenőrzi a cégeket. Megszűnés esetén `Suspended` státusz és értesítés. + +### 4.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. + +--- + +## 5. Jutalék és Gazdasági Rendszer +### 5.1. Piramis rendszer (3 szint) +A meghívó lánc alapján számolt jóváírások (Referral): +- **1. szint (Közvetlen):** 10% +- **2. szint:** 5% +- **3. szint:** 2% +*Megjegyzés: A százalékok a befizetés pillanatában érvényes admin beállítások alapján rögzülnek (Snapshot technika).* + +### 5.2. Wallets +Minden regisztrációnál automatikusan létrejön: +- **Coin Wallet:** Belső fizetőeszköz (Kredit). +- **XP Ledger:** Tapasztalati pontok (Gamification és rangsor). + +--- + +## 6. Moderáció és Validálás +- **Validált vélemény:** Csak igazolt ott-tartózkodás (GPS log) vagy számlafotó (OCR) feltöltése után adható. +- **Fellebbezés:** A szervizek kérhetik a vélemények felülvizsgálatát, amit moderátorok bírálnak el. + +--- + +## 7. Adattárolási Stratégia (Technikai) +- A rugalmas okmányadatokat (`identity_docs`) és a vészhelyzeti kapcsolatokat (`ice_contact`) **JSONB** mezőkben tároljuk a `persons` táblában a kereshetőség és a jövőbeli bővíthetőség érdekében. \ 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 e30cca2..90ca0a5 100644 --- a/docs/V01_gemini/06_Database_Guide.md +++ b/docs/V01_gemini/06_Database_Guide.md @@ -1,109 +1,112 @@ -(Az Adatbázis Bibliája.) -# 🗄️ DATABASE GUIDE -# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.4) +# 🗄️ 06_DATABASE_GUIDE & DATA INTEGRITY (v1.4) + +Ez a dokumentum az adatbázis-architektúra alapelveit és az adatintegritási szabályokat tartalmazza. ## 1. Soft Delete & Újraregisztráció Logika -A rendszerben nincs fizikai törlés. A `data.users` tábla az alábbi módon kezeli a visszatérő felhasználókat: -- **Indexelés:** Az `email` mezőn egy *Partial Unique Index* (`idx_user_email_active_only`) található. -- **Működés:** - Ha a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul. - - Új regisztrációkor, ha a KYC adatok egyeznek, az új technikai User a régi `person_id`-hoz kapcsolódik. +A rendszerben **nincs fizikai törlés**. A `data.users` tábla speciális indexeléssel kezeli a törölt és visszatérő felhasználókat. -## 2. Person (Identitás) - Banki KYC & Safety -A `data.persons` tábla a valós identitást tárolja. A Step 2 regisztráció során az alábbi JSONB struktúra kerül kitöltésre: -- **`identity_docs` (JSONB):** +- **Indexelés:** Az `email` mezőn egy *Partial Unique Index* (`idx_user_email_active_only`) található. +- **Működés:** - Ha `is_deleted = FALSE`, az email foglalt, nem használható újra. + - Ha a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul. +- **Identitás megőrzése:** Új regisztrációkor a rendszer új `user_id`-t generál, de ha a KYC (személyazonosító) adatok egyeznek, az új technikai User a régi `person_id`-hoz kapcsolódik. + +--- + +## 2. Person (Identitás) - KYC & Safety +A `data.persons` tábla a valós, banki szintű személyazonosságot tárolja. + +### 2.1. JSONB struktúrák +Rugalmas adatszerkezet az okmányok és orvosi adatok kezelésére: +- **`identity_docs`**: - `id_card`: szám és lejárati dátum. - `driver_license`: szám, lejárat és kategóriák (pl. ["A", "B", "C"]). - - `special_permits`: hajóvezetői és repülőgép-vezetői engedélyek. -- **`medical_emergency` (JSONB):** Vércsoport, allergiák, krónikus betegségek. -- **Jutalom Trigger:** A profil 100%-os kitöltése után aktiválódik a `system_settings`-ben megadott PRÉMIUM időszak. + - `special_permits`: hajó- vagy repülőgép-vezetői engedélyek. +- **`medical_emergency`**: Vércsoport, allergiák, krónikus betegségek. -## 3. Technikai Integritás (Enum & Séma) +### 2.2. Jutalom Trigger +A profil 100%-os kitöltése (név, születési adatok, okmányok) után automatikusan aktiválódik a `system_settings`-ben meghatározott **PRÉMIUM** időszak (alapértelmezett: 14 nap). + +--- + +## 3. Technikai Integritás és Séma +### 3.1. Adatbázis sémák +- **`public`**: Csak technikai metaadatok (pl. `alembic_version`). +- **`data`**: Az üzleti logika összes táblája (55+ tábla). + +### 3.2. Fejlesztői megjegyzések - **Enum Case Sensitivity:** A Postgres `userrole` típusa **kisbetűérzékeny**. A Python kódból érkező értékeket (pl. `user`, `admin`) kényszerítve kisbetűvel kell rögzíteni. -- **Séma Frissítés:** Mivel a `metadata.create_all` nem frissíti a meglévő táblákat, új oszlopok esetén (pl. `social_provider`, `mothers_name`) manuális `ALTER TABLE` vagy Alembic migráció szükséges. +- **Séma Frissítés:** A `metadata.create_all` nem frissíti a meglévő táblákat. Új oszlopok esetén manuális `ALTER TABLE` vagy Alembic migráció szükséges. +- **Audit:** Minden státuszmódosítás és adatváltozás snapshot-olva kerül az `audit_logs` táblába. -## 4. Dinamikus Paraméterezés (`data.system_settings`) -Minden üzleti változó Admin UI-ról állítható: -- `auth.reward_days`: Regisztrációs prémium hossza (alapértelmezett: 14). -- `referral.l1`: Első szintű jutalék % (alapértelmezett: 10). +--- -## 5. Flotta Tulajdonjog Szabályok (v1.1) -- **`INDIVIDUAL` flotta:** Nem átruházható (`is_transferable = False`), a felhasználóhoz kötött. -- **`FLEET_OWNER / SERVICE` flotta:** Átruházható, új tulajdonoshoz rendelhető. +## 4. Economy, Regionalizáció és Valuta +A rendszer EU-s piacra optimalizált multi-currency logikát használ. +- **`data.regional_settings`**: Országkódok (ISO 3166-1), alapértelmezett nyelvek és pénznemek. +- **`data.exchange_rates`**: Napi frissítésű váltószámok (Bázis: EUR). +- **Valuta Logika:** Minden költséget elmentünk helyi pénznemben (`currency_code`) és a rögzítéskori váltószámmal átszámított EUR-ban is. +- **Képlet:** $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$ -# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.0) +### 4.1. Wallet & Economy +- **Wallets:** Minden regisztrációkor létrejön egy rekord a `data.wallets` táblában (0 Coin, 0 XP). +- **Referral Snapshot:** Jutalék kifizetésekor a rendszer rögzíti a tranzakció pillanatában érvényes `%`-ot (`commission_percentage`), védve az adatot a későbbi módosításoktól. -## 1. Soft Delete & Újraregisztráció Logika -A rendszerben nincs fizikai törlés. A `data.users` tábla az alábbi módon kezeli a visszatérő felhasználókat: +--- -- **Indexelés:** Az `email` mezőn egy *Partial Unique Index* (`idx_user_email_active_only`) található. -- **Működés:** - Ha `is_deleted = FALSE`, az email nem használható újra. - - Ha a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul. - - Új regisztrációkor a rendszer új `user_id`-t generál, de ha a KYC adatok egyeznek, ugyanahhoz a `person_id`-hoz kapcsolja az új fiókot. +## 5. Flotta és Tulajdonjog Szabályok +A flották (Organization) és járművek tulajdonjogi logikája: -## 2. Person (Személyazonosság) - KYC & Safety -A `data.persons` tábla tárolja a banki szintű azonosításhoz szükséges adatokat: -- **Szétválasztott nevek:** `last_name` és `first_name` a pontos azonosításhoz. -- **JSONB mezők:** Rugalmas adatszerkezet az okmányokhoz (`identity_docs`) és vészhelyzeti adatokhoz (`medical_emergency`). -- **Jutalom Trigger:** A profil 100%-os kitöltése (név, szül. adatok, okmányok) automatikusan aktiválja a 14 napos PRÉMIUM csomagot. - -## 3. Economy (Pénztárca & Referral) -- **Wallet:** Minden regisztrációkor létrejön egy rekord a `data.wallets` táblában (0 Coin, 0 XP). -- **Referral Snapshot:** A jutalékok kifizetésekor a rendszer rögzíti a tranzakció pillanatában érvényes százalékot (`commission_percentage`), így a későbbi admin módosítások nem érintik a múltbeli elszámolásokat. - -## Sémák -- `public`: Csak technikai táblák (pl. Alembic version). -- `data`: Az üzleti logika 55 táblája. - -## Kulcs Táblacsoportok -1. **Fleet:** `vehicles`, `user_vehicles`, `vehicle_events`, `engine_specs`. -2. **Marketplace:** `service_providers`, `service_specialties`, `organization_locations`. -3. **Economy:** `wallets`, `transactions`, `shop_items`. -4. **Identity:** `users`, `persons`, `companies`. - -## Migrációs Állapot -- **Eszköz:** Alembic. -- **Current Head:** `10b73fee8967`. -- **Hiányzó láncszem:** A `persons` tábla létrehozása és a meglévő `users` tábla migrációja (Ba - -## 4. Regionalizáció és Multi-Currency (EU Scope) -A rendszer fel van készítve az EU-s piacra: -- **`data.regional_settings`**: Tárolja az országkódokat (ISO 3166-1), az alapértelmezett nyelvet és a helyi pénznemet. -- **`data.exchange_rates`**: Napi frissítésű váltószámok (Base: EUR). -- **Valuta Logika:** - Minden költséget a rögzítéskori **helyi pénznemben** (`currency_code`) és az akkori váltószámmal átszámított **EUR-ban** is elmentünk. - - Képlet: $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$ - - Ez biztosítja, hogy a nemzetközi flották egységes kimutatást kapjanak. - -## 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). - -## 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. + - `INDIVIDUAL` flotta: Nem átruházható, a felhasználóhoz kötött. + - `FLEET_OWNER / SERVICE` flotta: Átruházható, új tulajdonoshoz (`owner_id`) rendelhető. +- **Cég Megszűnése:** Soft delete (`is_active: False`). A járművek életútja (history) megmarad a visszakövethetőség miatt. +- **Opcionális Járművek:** Egy flotta létezhet jármű rögzítése nélkül is (pl. tisztán menedzseri kör). -## 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. +## 6. Szervezeti Egységek és CRM +A flottákhoz tartozó humán és üzleti kapcsolatok kezelése. - ## 4. CRM és Szervezeti Kapcsolattartók -A `data.organization_contacts` tábla felelős a flottákhoz tartozó humán kapcsolattartók kezeléséért. -- **Dinamikus beállítások:** A `data.organizations` tábla `notification_settings` (JSONB) mezője szabályozza, ki és mikor kapjon értesítést. -- **Külső szinkron:** Az `external_crm_id` biztosítja a kapcsolatot külső vállalatirányítási rendszerekkel (API-n keresztül). +- **`data.organizations`**: Bővítve: `tax_number`, `reg_number`, `headquarters_address`, `notification_settings` (JSONB). +- **`data.organization_contacts`**: Mini-CRM funkciók (kapcsolattartók típusai: billing, primary, operational). +- **Kapcsolódás:** `external_crm_id` mező biztosítja az API kapcsolatot külső ERP rendszerekkel. -## 4.1 Szervezeti és CRM Adatmodell -- **data.organizations**: Bővítve `tax_number`, `reg_number`, `headquarters_address` és `is_deleted` mezőkkel. -- **data.organization_contacts**: Új tábla a Mini-CRM funkciókhoz (kapcsolattartók típus szerint: billing, primary, operational). -- **Audit**: Minden státuszmódosítás és adatváltozás snapshot-olva az `audit_logs` táblába. \ No newline at end of file +--- + +## 7. Gazdasági Izoláció és Rating +- **Gamification Korlát:** Csak `INDIVIDUAL` típusú flottákhoz tartozó `Person`-ok gyűjthetnek XP-t. A cégek (`Company`) nem kapnak `XP_Ledger`-t és `Coin_Wallet`-et. +- **Validáció:** Cég nem validálhat szervizpontot, csak a hozzárendelt, azonosított `Person` (technikus). +- **Rating Rendszer:** Külön értékelést kap a **Person** (megbízhatóság), a **Service** (minőség) és a **Vehicle** (műszaki állapot). A cég hírneve ezekből adódik össze. + +--- + +## 8. Dinamikus Paraméterezés (`data.system_settings`) +Minden üzleti változó az Admin UI-ról állítható: +- `auth.reward_days`: Regisztrációs prémium hossza (default: 14). +- `auth.reward_tier`: Kapott csomag típusa (default: PREMIUM). +- `referral.l1`: Első szintű jutalék mértéke (default: 10%). + +--- + +## 9. Kulcs Táblacsoportok +1. **Fleet:** `vehicles`, `user_vehicles`, `vehicle_events`, `engine_specs`. +2. **Marketplace:** `service_providers`, `service_specialties`, `organization_locations`. +3. **Economy:** `wallets`, `transactions`, `shop_items`. +4. **Identity:** `users`, `persons`, `companies`. + +--- + +## 10. Migrációs Állapot (Dev Info) +- **Eszköz:** Alembic +- **Current Head:** `10b73fee8967` +- **Hiányzó láncszem:** A `persons` tábla véglegesítése és a meglévő `users` tábla adatintegrációs migrációja folyamatban. + +## 4.2 Dokumentum és Irattár (Vault Logic) +- **Központi tárolás:** A `data.documents` tábla kezeli az összes csatolmányt (parent_type: 'org', 'asset', 'person'). +- **Metadata:** Tároljuk a dokumentum kibocsátóját (issuer_id) és tárgyát (subject_id) a szervizstatisztikákhoz. +- **Verifikáció:** `status` mező (pending, verified, rejected). + +## 4.3 Crowdsourced Szervezetek +- **Lifecycle:** draft_user -> draft_bot -> community_verified -> official. +- **Gamification:** XP/Kredit jóváírás csak sikeres Bot vagy Owner validáció után. \ No newline at end of file diff --git a/docs/V01_gemini/07_API_Guide.md b/docs/V01_gemini/07_API_Guide.md index 804b5ce..0b1988b 100644 --- a/docs/V01_gemini/07_API_Guide.md +++ b/docs/V01_gemini/07_API_Guide.md @@ -1,56 +1,67 @@ -(API specifikáció.) -# 🔌 API GUIDE +# 🔌 07_API_GUIDE -## Verziózás -- **v1:** Core Fleet funkciók (`/api/v1/vehicles`, `/api/v1/expenses`). -- **v2:** Auth és új modulok (`/api/v2/auth/login`). +## 1. Verziózás (Versioning) +A rendszer támogatja a többszintű verziókezelést a stabilitás és a visszafelé való kompatibilitás érdekében. +- **v1:** Core Fleet funkciók (pl. `/api/v1/vehicles`, `/api/v1/expenses`). +- **v2:** Auth és új generációs modulok (pl. `/api/v2/auth/login`). -## Route Inventory (Kiemelt) -- `POST /api/v2/auth/register` (Regisztráció Person létrehozással) -- `GET /api/v1/fleet/vehicles` (Saját járművek listája) -- `POST /api/v1/search/match` (Szervizkereső algoritmus) -- `POST /api/v1/evidence/upload` (MinIO feltöltés) +--- -## Hiba Kezelés -- **401:** Token lejárt -> Frontend dobjon Loginra. -- **403:** Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" (Tier limit). -- **404:** Resource not found OR Soft Deleted. +## 2. Route Inventory (Kiemelt Végpontok) +Az alábbi táblázat tartalmazza a legfontosabb útvonalakat: -## 🌐 8. Nemzetköziesítés (i18n) és Lokalizáció +| Metódus | Végpont | Leírás | +| :--- | :--- | :--- | +| `POST` | `/api/v2/auth/register` | Regisztráció Person rekord létrehozásával | +| `GET` | `/api/v1/fleet/vehicles` | Felhasználó saját járműveinek listázása | +| `POST` | `/api/v1/search/match` | Szervizkereső algoritmus indítása | +| `POST` | `/api/v1/evidence/upload` | Dokumentum feltöltés (MinIO) | -A rendszer a "Global-Local" elv alapján működik. Tilos a programkódban (hard-coded) szöveges üzeneteket elhelyezni. +--- -### 8.1. Nyelvi fájlok struktúrája +## 3. Hiba Kezelés (Error Handling) +A frontendnek az alábbi HTTP státuszkódok alapján kell lekezelnie a kivételeket: +- **401:** Token lejárt -> Frontendnek automatikusan a Login oldalra kell dobnia a felhasználót. +- **403:** Jogosultság hiba -> "Nincs jogod ehhez a funkcióhoz" üzenet megjelenítése (Tier limit/Role hiba). +- **404:** Resource not found -> Az erőforrás nem található vagy Soft Deleted állapotban van. + +--- + +## 4. Nemzetköziesítés (i18n) és Lokalizáció +A rendszer a "Global-Local" elv alapján működik. **Tilos a programkódban (hard-coded) szöveges üzeneteket elhelyezni.** + +### 4.1. Nyelvi fájlok struktúrája Minden nyelvi fájl a `backend/app/locales/` mappában található, szabványos JSON formátumban. -Példa: `hu.json`, `en.json`, `de.json`. +- **Példa fájlok:** `hu.json`, `en.json`, `de.json`. -### 8.2. Kezelési szabályok +### 4.2. Kezelési szabályok - **Backend:** A rendszerüzeneteket, hibaüzeneteket és az e-mail sablonok tartalmát a `LocaleManager` szolgáltatáson keresztül kéri le. - **Paraméterezés:** A szövegekben használható változók formátuma: `{variable_name}`. - **Sablonkezelés:** Az e-mailek HTML vázát és a JSON-ban tárolt szöveges blokkokat a rendszer a küldés előtt fűzi össze. -### 8.3. Nyelvválasztás logikája +### 4.3. Nyelvválasztás logikája (Prioritás) 1. A kérés fejlécében érkező `Accept-Language` alapján. 2. Bejelentkezett felhasználó esetén a `User.region_code` alapján. 3. Alapértelmezett: `hu`. -# 🛡️ 9. Unified Registration & Security Protocol +--- -A rendszer a "Minimal Friction, Maximum Security" elvét követi. +## 5. Unified Registration & Security Protocol +A rendszer a **"Minimal Friction, Maximum Security"** elvét követi. -### 9.1. Regisztrációs Életciklus -1. **Step 1 (Lite):** `Email`, `Jelszó`, `Név` megadása. Létrejön a `User` és `Person` rekord. Állapot: `is_active: false`. -2. **Verifikáció:** A rendszer UUID alapú tokent generál (48 órás élettartam). A felhasználó e-mailben kap egy gombot/linket. -3. **Step 2 (KYC):** Sikeres verifikáció után a felhasználó megadja az okmányait (rugalmas választó: Személyi/Jogsi/Hajó). -4. **Aktiválás:** Létrejön a **Privát Flotta (Privát Széf)** és a hozzá tartozó `Wallet`. Állapot: `is_active: true`. +### 5.1. Regisztrációs Életciklus +1. **Step 1 (Lite):** `Email`, `Jelszó`, `Név` megadása. Létrejön a `User` és `Person` rekord. Állapot: `is_active: false`. +2. **Verifikáció:** A rendszer UUID alapú tokent generál (48 órás élettartam). A felhasználó e-mailben kap egy aktiváló linket. +3. **Step 2 (KYC):** Sikeres verifikáció után a felhasználó megadja az okmányait (Személyi/Jogsi/Hajó). +4. **Aktiválás:** Létrejön a **Privát Flotta (Privát Széf)** és a hozzá tartozó `Wallet`. Állapot: `is_active: true`. -### 9.2. Token Biztonsági Előírások +### 5.2. Token Biztonsági Előírások - **Regisztrációs Token:** 48 óra élettartam. - **Jelszó-visszaállítási Token:** 1 óra élettartam. -### 9.3. Rate Limiting (Robotvédelem és Költségkontroll) +### 5.3. Rate Limiting (Robotvédelem és Költségkontroll) Az e-mail küldési folyamatokra az alábbi korlátok vonatkoznak: -- **Retry Cooldown:** Újraigénylés (pl. "Nem kaptam meg a kódot") legkorábban 60 másodperc után lehetséges. +- **Retry Cooldown:** Újraigénylés legkorábban 60 másodperc után lehetséges. - **Óránkénti Limit:** Maximum 3 kérelem / e-mail cím. - **Napi Limit:** Maximum 10 kérelem / e-mail cím. - **Zárolás:** A napi limit túllépése esetén a fiók biztonsági okokból 24 órára zárolja a küldési funkciót az adott címre. \ No newline at end of file diff --git a/docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md b/docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md index 77d8336..f02aad8 100644 --- a/docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md +++ b/docs/V01_gemini/07_REGISTRATION_INVITATION_AND_API.md @@ -1,167 +1,101 @@ -# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4) +# 🏁 07_REGISTRATION_INVITATION_AND_API (v1.4) -## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT -Az UX optimalizálása és a banki szintű biztonság érdekében a folyamat két külön fázisra oszlik. +## 1. Kétlépcsős Onboarding Folyamat +A rendszer a felhasználói élmény (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt, amelyet egy atomi tranzakció zár le. -### 1. Fázis: "Lite" Regisztráció (Step 1) +### 1.1. Fázis: "Lite" Regisztráció (Step 1) * **Végpont:** `POST /api/v1/auth/register` -* **Adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód. -* **Rendszeresemény:** - * Létrejön a technikai `User` rekord. - * **Állapot:** `is_active = False`. - * **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum fix). - * **Megerősítés:** A rendszer kiküld egy aktiváló emailt egy hash kóddal. - * **Válasz:** JWT token `status: pending_kyc` flaggel. - -### 2. Fázis: Banki KYC & Aktiválás (Step 2) -* **Végpont:** `POST /api/v1/auth/complete-kyc` (Fejlesztés alatt) -* **Kötelező KYC adatok:** - * Anyja születési neve, születési hely/idő. - * Okmányadatok: Személyi igazolvány és Jogosítvány száma + lejárati idők. - * Járműkategóriák (pl. A, B, C) és speciális engedélyek (hajó, repülő). -* **Finalizálás (Atomi tranzakció):** - 1. **Person:** Identitás rögzítése a JSONB dokumentumtárral. - 2. **Wallet:** Pénztárca nyitása 0 egyenleggel. - 3. **Privát Flotta:** Automatikus szervezet létrehozása (`is_transferable = False`). - 4. **Tagság:** Felhasználó rögzítése a flotta tulajdonosaként. - 5. **Aktiválás:** `is_active = True` és hozzáférés a rendszerhez. - -## II. TECHNIKAI SZABÁLYOK ÉS FIXEK -* **Postgres Enum:** Minden szerepkört (role) kisbetűvel kell küldeni az adatbázis felé (`user`, nem `USER`). -* **Dinamikus Paraméterek:** Az `auth.reward_days` (jutalom napok) és jutalék százalékok a `data.system_settings` táblából jönnek. -* **Audit Trail:** Minden regisztrációs fázisról Audit Log készül. - -# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.4) - -## I. KÉTLÉPCSŐS ONBOARDING FOLYAMAT -A rendszer a felhasználói élmény optimalizálása (UX) és a banki szintű biztonság érdekében két fázisra bontja a regisztrációt. - -### 1. Fázis: "Lite" Regisztráció (Step 1) * **Cél:** Gyors belépés és a technikai User fiók létrehozása. -* **Kötelező mezők:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód. -* **Rendszeresemény:** - * Létrejön a `data.users` rekord. - * **Állapot:** `is_active = False`. - * **Szerepkör:** Kötelezően kisbetűs `user` (Postgres Enum kényszerítés miatt). - * **Email:** A rendszer azonnal kiküld egy ellenőrző emailt egy egyedi hash kóddal/linkkel. - * **Token:** Az API egy korlátozott JWT tokent ad vissza, amely csak a Step 2 végpont elérésére jogosít (`status: pending_kyc`). +* **Kötelező adatok:** Email, Jelszó, Vezetéknév, Keresztnév, Régiókód. +* **Rendszeresemények:** + * Létrejön a `data.users` rekord `is_active = False` állapottal. + * **Szerepkör:** Kényszerített kisbetűs `user` (Postgres Enum kényszer). + * **Megerősítés:** Aktiváló email küldése egyedi hash kóddal. + * **Válasz:** JWT token `status: pending_kyc` flaggel (korlátozott jogosultság). -### 2. Fázis: KYC & Aktiválás (Step 2) -* **Cél:** A valós identitás (Person) rögzítése és a gazdasági egységek inicializálása. -* **Kötelező adatok (Identity Verification):** - * **Személyes:** Anyja születési neve, születési hely, születési idő. +### 1.2. Fázis: Banki KYC & Adatgyűjtés (Step 2) +* **Végpont:** `POST /api/v1/auth/complete-kyc` +* **Kötelező KYC adatok (Identity Verification):** + * **Személyes:** Anyja születési neve, születési hely és idő. * **Okmányok:** Személyi igazolvány száma és lejárati ideje. * **Jogosítvány:** Vezetői engedély száma, lejárata és kategóriák (pl. AM, A, B, C, CE). - * **Speciális:** Hajóvezetői és repülőgép-vezetői engedély adatai (ha releváns). -* **Működés:** A felhasználó csak ezen adatok kitöltése és sikeres ellenőrzése után válik teljes jogú taggá. + * **Speciális:** Hajóvezetői és repülőgép-vezetői engedélyek (ha releváns). -### 3. Fázis: Atomi Tranzakció (Finalization) -A KYC adatok beküldésekor a rendszer egyetlen adatbázis-tranzakcióban (`Atomic`) hajtja végre az alábbiakat: -1. **Person létrehozása:** A KYC adatok és okmánymásolatok (JSONB) rögzítése. -2. **Wallet inicializálás:** 0 Coin és 0 XP egyenleggel. -3. **Privát Flotta (Private Org):** Létrejön a felhasználó saját cége (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`). -4. **Aktiválás:** A User fiók `is_active = True` állapotba kerül. -5. **Audit:** Bejegyzés az `audit_logs` táblába a teljes körű regisztrációról. +### 1.3. Fázis: Atomi Tranzakció (Finalization) +A KYC adatok beküldésekor a rendszer egyetlen megszakíthatatlan folyamatban hajtja végre: +1. **Person létrehozása:** Identitás rögzítése JSONB dokumentumtárral a `data.persons` táblába. +2. **Wallet inicializálás:** Pénztárca nyitása 0 Coin és 0 XP egyenleggel. +3. **Privát Flotta (Private Org):** Automatikus szervezet létrehozása (`OrgType.INDIVIDUAL`), amely **nem átruházható** (`is_transferable = False`). +4. **Aktiválás:** `is_active = True` státusz beállítása és teljes hozzáférés biztosítása. +5. **Audit:** Bejegyzés az `audit_logs` táblába. -## II. MEGHÍVÓ ÉS JUTALÉK LOGIKA -* **Invite Tokenek:** - * `REG_ONLY`: Általános meghívó, beköti a felhasználót a 10-5-2% jutalék láncba. - * `COMPANY_JOIN`: Meghatározott szervezetbe hív (CEO, Flotta Manager vagy Sofőr szerepkörbe). -* **Kredit Jóváírás:** - * Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a meghívási láncban. - * A százalékos mérték (10%, 5% vagy 2%) a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot). +--- -## III. TECHNIKAI ÉS BIZTONSÁGI SZABÁLYOK -* **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden Enum értéket (user, admin, driver, service, fleet_manager) szigorúan **kisbetűvel** kell kezelni. -* **Dinamikus Paraméterezés:** Tilos fix értékeket (hardcoded) használni. Az alábbiakat a `data.system_settings` táblából kell lekérni: - * `auth.reward_days`: Regisztrációkor járó prémium napok (alapértelmezett: 14). - * `referral.level1-3`: Jutalék szintek mértéke. -* **Email Manager:** A `send_email` hívásakor tilos a `subject` paraméter átadása; a szerviz a `template_key` alapján automatikusan generálja azt. -* **Szigorú Helyreállítás:** A banki szintű KYC után a jelszó-visszaállítás kérhető a Person adatok (Anyja neve, Okmány szám) megadásával is. +## 2. Meghívó és Jutalék Logika (Invitation Engine) +A rendszer támogatja a többszintű ajánlói rendszert és a szervezeti meghívókat. -## IV. SOCIAL AUTH (GOOGLE / FACEBOOK) -* Social Auth esetén a Step 1 lerövidül, de a **Step 2 (KYC) kötelező** marad az aktiváláshoz. -* Amíg a KYC hiányzik, a felhasználó "GUEST" státuszban marad, és nem fér hozzá a flottakezeléshez. +### 2.1. Meghívó Típusok +- **`REG_ONLY`**: Általános meghívó, amely beköti az új felhasználót a 10-5-2%-os jutalék láncba. +- **`COMPANY_JOIN`**: Meghatározott szervezetbe hív (pl. CEO, Flotta Manager vagy Sofőr szerepkörbe). -# 🏁 REGISZTRÁCIÓS ÉS AUTH PROTOKOLL (v1.1) +### 2.2. Jutalék Számítás +A százalékos mérték a tranzakció pillanatában érvényes admin beállítások alapján rögzül (Snapshot). A jóváírandó kredit ($C$): -## 1. Hibakezelési Jegyzet (TypeError fix) -A rendszer korábbi verzióiban az `EmailManager` hívása paraméter-eltérést okozott. -- **Megoldás:** A `send_email` hívásakor tilos a `subject` paraméter átadása, mivel azt a szerviz a `template_key` alapján generálja a belső szótárából. +$$C = P_{amount} \cdot \frac{R_{level}}{100}$$ -## 2. Adatbázis Integritás -Az `Organization` tábla bővült az `owner_id` mezővel, amely a magánszemély (Individual) flottájának tulajdonosát jelöli. -- Minden regisztrációkor létrejön egy automatikus flotta. -- A flotta típusa: `OrgType.INDIVIDUAL`. +*Ahol $P$ a befizetett összeg, $R$ pedig az aktuális szint (10, 5 vagy 2) értéke.* +**Szabály:** Csak az **első** Prémium csomag befizetésekor történik jutalékfizetés a láncban. -## 3. Dinamikus Paraméterek -A regisztrációt követő jutalmak (pl. 14 napos prémium) a `data.system_settings` táblából kerülnek kiolvasásra. -Keresett kulcs: `auth.reward_days`. +--- -# 🏁 REGISZTRÁCIÓ, MEGHÍVÓK ÉS API PROTOKOLL (v1.0) +## 3. Technikai és Biztonsági Szabályok +### 3.1. Adatbázis és Enum Kezelés +- **Enum Case Sensitivity:** A PostgreSQL `userrole` típusa miatt minden értéket (pl. `user`, `admin`, `driver`, `service`) szigorúan **kisbetűvel** kell rögzíteni. +- **Dinamikus Paraméterek:** Tilos a hardcoded értékek használata. Az alábbiakat a `data.system_settings` táblából kell lekérni: + - `auth.reward_days`: Regisztrációs prémium hossza (default: 14). + - `referral.level1-3`: Jutalék szintek mértéke. -## 1. Regisztrációs Flow (Atomcsapás-biztos tranzakció) -Minden új regisztráció egyetlen adatbázis-tranzakcióban (`Atomic`) hajtja végre az alábbiakat: -1. **User & Person létrehozása:** Alapidentitás rögzítése. -2. **Wallet inicializálás:** 0 Coin és 0 XP egyenleggel. -3. **Privát Flotta (Private Org):** Létrejön a felhasználó saját cége, ahol ő a tulajdonos. -4. **Meghívó feldolgozása:** - Ha `Personal Invite`: Bekötés a 10-5-2% jutalék láncba. - - Ha `Company Invite`: Másodlagos kapcsolat létrehozása a meghívó céghez (Role: Driver/Admin). +### 3.2. Email Manager Protokoll (TypeError Fix) +- **Szabály:** A `send_email` hívásakor **tilos** a `subject` paraméter kézi átadása. +- **Logika:** A szerviz a `template_key` alapján automatikusan generálja a tárgyat a belső szótárából. -## 2. Meghívó Küldés Logikája (Invitation Engine) -- **Generálás:** Admin vagy jogosult User generál egy egyedi `invite_token`-t. -- **Típusok:** - - `REG_ONLY`: Csak a rendszerbe hív. - - `COMPANY_JOIN`: Meghatározott cégbe és pozícióba hív. -- **Jutalék számítás:** - A jóváírandó kredit $C$: - $$C = P_{amount} \cdot \frac{R_{level}}{100}$$ - *Ahol $P$ a befizetett összeg, $R$ pedig az aktuális szint (10, 5 vagy 2) értéke.* +### 3.3. Social Auth (Google / Facebook) +- A Step 1 lerövidül, de a **Step 2 (KYC) kötelező** marad az aktiváláshoz. +- Amíg a KYC hiányzik, a felhasználó "GUEST" státuszban marad, korlátozott funkciókkal. -## 3. API Végpontok (Baseline v1) -- `POST /api/v1/auth/register`: Komplett onboarding folyamat. -- `POST /api/v1/auth/invite/send`: Meghívó generálása és küldése. -- `GET /api/v1/auth/invite/verify/{token}`: Token ellenőrzése regisztráció előtt. +--- ## 4. Jelszó Helyreállítási Protokoll (Recovery) -A rendszer két szintű helyreállítást biztosít: +A rendszer két biztonsági szintet különít el: -### A) Standard (Email alapú) -- `POST /api/v1/auth/forgot-password` -> Email kiküldése ideiglenes tokennel. +| Szint | Megnevezés | Logika | +| :--- | :--- | :--- | +| **A** | Standard | Email alapú visszaállítás ideiglenes tokennel. | +| **B** | Szigorú (Banki) | Kötelező: Név, Anyja neve, Okmány szám. Ellenőrzés után SMS (telefonszám) vagy Email link. | -### B) Szigorú (Banki szintű / KYC alapú) -- **Végpont:** `POST /api/v1/auth/recover-identity` -- **Kötelező adatok:** Vezetéknév, Keresztnév, Anyja neve, Személyi igazolvány száma. -- **Logika:** 1. A rendszer azonosítja a `Person` rekordot. - 2. Ha sikeres, a rendszer kiküld egy visszaállító linket a Person-höz tartozó **elsődleges telefonszámra (SMS)** vagy a **legutolsó aktív Email címre**. - 3. Sikeres helyreállítás után a felhasználónak kötelezően jelszót kell cserélnie. +--- - ## 🛡️ 10. Kormányozhatóság és Biztonsági Beállítások +## 5. Corporate Onboarding (Céges Regisztráció) +Célja, hogy egy létező Person saját szervezetet (Organization) alapítson. +- **Validáció:** Kötelező adószám ellenőrzés (HU formátum + VIES API lekérdezés). +- **Hierarchia:** A regisztráló automatikusan `owner` rangot kap. +- **Izoláció:** Minden cég saját mappastruktúrát kap a NAS-on az okmányok fizikai elkülönítése érdekében. -A rendszer biztonsági paraméterei központilag, a környezeti változókon keresztül szabályozhatók. Ez lehetővé teszi a biztonsági szint gyors módosítását (pl. támadás esetén szigorítás) a kód módosítása nélkül. +--- -### 10.1. Token Élettartam Szabályok -A `.env` fájlban (vagy a rendszer beállításaiban) az alábbi paraméterekkel szabályozható a hozzáférés: +## 6. Kormányozhatóság és .env Konfiguráció +A biztonsági paraméterek környezeti változókon keresztül szabályozhatók: | Paraméter | Leírás | Alapértelmezett | | :--- | :--- | :--- | -| `REGISTRATION_TOKEN_EXPIRE_HOURS` | Regisztráció megerősítésére álló idő | 48 óra | -| `PASSWORD_RESET_TOKEN_EXPIRE_HOURS` | Jelszó visszaállítására álló idő | 1 óra | +| `REGISTRATION_TOKEN_EXPIRE_HOURS` | Aktiválásra álló idő | 48 óra | +| `PASSWORD_RESET_TOKEN_EXPIRE_HOURS` | Visszaállítási időablak | 1 óra | -### 10.2. Ideiglenes .env Konfiguráció (Példa) -```env -# SECURITY SETTINGS -REGISTRATION_TOKEN_EXPIRE_HOURS=48 -PASSWORD_RESET_TOKEN_EXPIRE_HOURS=1 +--- -# EMAIL SYSTEM -EMAIL_PROVIDER=sendgrid -EMAILS_FROM_EMAIL=info@profibot.hu -EMAILS_FROM_NAME='Profibot Service Finder' -SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxx - -## 4. Corporate Onboarding (Céges regisztráció) -A folyamat célja, hogy egy már létező Person (vagy új User) saját szervezetet (Organization) alapítson. -- **Többszintű validáció:** Kötelező adószám (VAT/Tax ID) ellenőrzés (HU esetén formátum + VIES API). -- **Hierarchia:** A regisztráló automatikusan `owner` rangot kap. -- **Izoláció:** Minden cég saját mappastruktúrát kap a NAS-on az okmányok izolált kezelése érdekében. \ No newline at end of file +## 7. API Végpontok (Baseline v1) +- `POST /api/v1/auth/register`: Komplett onboarding indítása. +- `POST /api/v1/auth/complete-kyc`: KYC adatok beküldése és aktiválás. +- `POST /api/v1/auth/invite/send`: Meghívó generálása. +- `GET /api/v1/auth/invite/verify/{token}`: Token validálása. +- `POST /api/v1/auth/recover-identity`: Szigorú (KYC alapú) helyreállítás. \ 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 972e851..53ee4cb 100644 --- a/docs/V01_gemini/10_Billing_Credits_Subscriptions.md +++ b/docs/V01_gemini/10_Billing_Credits_Subscriptions.md @@ -1,58 +1,76 @@ -# 💰 BILLING, CREDITS & SUBSCRIPTIONS (v1.2) +# 💰 10_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 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. +A rendszer többnyelvű és többvalutás elszámolást alkalmaz. Minden tranzakció kettős értéktárolással valósul meg az adatintegritás érdekében. + +- **Local Cost:** A felhasználó régiója szerinti pénznemben rögzített összeg. +- **Standard Cost (EUR):** A rögzítés pillanatában érvényes árfolyamon számolt alapérték. **Átszámítási képlet:** $$Cost_{EUR} = Cost_{Local} \cdot ExchangeRate$$ -## 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. +--- + +## 2. Előfizetési Csomagok és Business Synergy +A rendszer korlátait a `data.system_settings` tábla szabályozza. A csomagok skálázhatóak a flotta méretétől függően. | Csomag | Jármű Limit | Kiemelt funkciók | | :--- | :--- | :--- | -| **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ó. | +| **FREE** | 1 db | Alap költségnapló, GEO alapú szervizkereső. | +| **PREMIUM** | 3 db | Dokumentumtár, export funkciók, útvonal alapú kereső. | +| **PREMIUM+** | 5 db | Flotta statisztika, TCO (Total Cost of Ownership) elemzés. | | **VIP / VIP+** | 10+ db | Egyedi szervizkezelés, bővíthető slotok, prioritásos support. | -**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. +### 2.1. VIP Synergy Szabályok (Ösztönző rendszer) +- **Synergy Discount:** Ha egy `FLEET_OWNER` aktív **VIP** vagy **VIP+** előfizetéssel rendelkezik, **15% kedvezményt** kap minden vásárlásra a saját privát flottájában is. +- **Ajándék Kredit:** VIP vásárláskor extra kreditek járnak (felhasználható: skinek, medálok, privát Prémium csomag). +- **Időbeli korlát:** A privát kedvezmények időtartama **2-6 hónapra korlátozott**, ösztönözve a folyamatos aktivitást. + +--- ## 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`. +A kedvezmények igénybevétele manuális kódbeíráshoz kötött. Minden felhasználást auditálni kell (`redeemed_at`, `user_id`, `original_price`). + +- **Gift Card (Fix Kredit):** Meghatározott összegű jóváírás (pl. 5000 Ft). +- **Subscription Coupon (%):** Százalékos kedvezmény az előfizetési díjból egy adott időszakra. +- **Lejárat:** Minden kupon rendelkezik fix érvényességi idővel, amely után inaktívvá válik. + +--- + +## 4. MLM Jutalomrendszer (Referral) +A rendszer jutalmazza a sikeres meghívásokat az új tag **első** befizetése után. A százalékos érték a tranzakció pillanatában rögzül (Snapshot). -## 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. +A spam elleni védelem érdekében a meghívók élettartama és mennyisége korlátozott: + +- **Token Lejárati idők:** + - **Felhasználói (User) 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ó. +- **Mennyiségi korlát:** Kezdő keret felhasználónként (alapértelmezett: 10 vagy 20 db). +- **Anti-Spam Logika:** A felhasználó csak sikeres regisztrációk után kap vissza új meghívási lehetőségeket (slotokat). + +--- ## 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`. +A rendszerben a "Verified" (hiteles) státusz eléréséhez bizonyítékok szükségesek. + +- **Kötelező bizonyítékok:** Munkalap fotó, számlakép és kilométeróra-állás fotó. +- **GPS Check-in:** A szerviz eseménykor igazolni kell a helyszíni tartózkodást. +- **Validáció:** Cég mint entitás nem hitelesíthet; a validálást mindig egy azonosított **Person** végzi. + + + +--- ## 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üli visszamenőleges befizetéssel minden funkció és korábbi adat újra aktiválódik. \ No newline at end of file +Ha az előfizetés lejár, a rendszer az alábbi fokozatos korlátozásokat vezeti be: + +1. **Grace Period (30 nap):** Csak adatrögzítés lehetséges, a statisztikai modulok és exportok zárolva vannak. +2. **Zárolás (60 nap):** A fiók írásvédetté válik (Read-only). Nincs új adatrögzítés. +3. **Helyreállítás:** 6 hónapon belüli visszamenőleges befizetés esetén minden korábbi adat és funkció azonnal újraaktiválódik. \ No newline at end of file diff --git a/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md b/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md index 3eaeedb..9687b50 100644 --- a/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md +++ b/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md @@ -1,206 +1,130 @@ -# 🏎️ Asset és Flotta Specifikáció: A Járművek DNS-e +# 🏎️ 18_ASSET_AND_FLEET_SPECIFICATION (v1.2) Ez a dokumentum írja le a rendszer magját képező "széf" logikát, ahol minden közlekedési eszköz (Asset) egyedi életutat és digitális lenyomatot kap. ## 1. Az Alapelv: "Mindenki Flottatulajdonos" -A rendszerben nincs különbség egy magánszemély és egy cég között a technikai rétegben. -- **Privát Flotta:** A regisztráció (Step 2) során automatikusan létrejövő szervezet (Organization). -- **Széf (Safe Deposit):** A flotta része, ahol az eszközök (járművek) és azok bizalmas okmányai laknak. +A rendszerben a technikai réteg nem tesz különbséget magánszemély és cég között. +- **Privát Flotta:** A regisztráció során automatikusan létrejövő szervezet (**Organization**). +- **Széf (Safe Deposit):** A flotta izolált része, ahol az eszközök (járművek) és azok bizalmas okmányai (Vault) találhatók. -## 2. Eszköz Típusok és Speciális Azonosítók -Minden eszköz rendelkezik egy **Univerzális Állandó Azonosítóval (UAI)**, ami az életútja során soha nem változik. +--- -| Típus | Elsődleges Azonosító (UAI) | Speciális Adatpontok | +## 2. Eszköz Típusok és Univerzális Azonosítók (UAI) +Minden eszköz rendelkezik egy **Univerzális Állandó Azonosítóval (UAI)**, amely az életútja során soha nem változik. + +| Kategória | Elsődleges Azonosító (UAI) | Speciális Adatpontok | | :--- | :--- | :--- | -| **Közúti** | VIN (Alvázszám) | Rendszám, Motorkód, Sebességváltó kód | -| **Vízi** | HIN (Hull ID / Testszám) | MMSI kód, IMO szám, Név | -| **Légi** | Serial Number (Gyári szám) | Lajstromjel (Registration), Típusjelzés | -| **Egyéb** | Egyedi sorozatszám | Gyártó, Teljesítmény | +| **Közúti (Car, Bike, Bus)** | **VIN** (Alvázszám) | Rendszám, Motorkód, Sebességváltó kód | +| **Vízi (Boat, Yacht)** | **HIN** (Hull ID) | MMSI kód, IMO szám, Hajó neve | +| **Légi (Aircraft)** | **Serial Number** | Lajstromjel (Registration), Típusjelzés | +| **Heavy Duty / Agri** | Egyedi sorozatszám | Üzemóra, Teljesítmény, Kanál/Vágóasztal típus | +| **Micro-mobility** | Vázszám / UUID | Akkumulátor ciklus, Hatótáv | ### Kiegészítő mérőszámok: - **Futásteljesítmény (Odometer):** Közúti járműveknél (km/mérföld). -- **Üzemóra (Operating Hours):** Hajók, repülők, munkagépek és versenytechnika esetén kritikus. +- **Üzemóra (Operating Hours):** Hajók, repülők és munkagépek esetén az elsődleges szervizintervallum-mérő. +- **VIN Validáció:** Közúti járműveknél kötelező a **VIN Checksum (MOD 11)** ellenőrzése rögzítéskor. + +--- ## 3. A Jármű DNS (Deep Data Structure) -Az adatbázisnak ismernie kell a járművet "gyári" állapotában és annak minden módosítását. +A rendszer két rétegben kezeli a jármű adatait a teljes életút követéséhez. -### A) Gyári Konfiguráció (Factory Specs) -- **Trim Level:** Felszereltségi csomag (pl. S-Line, AMG Pack, Comfortline). -- **Technikai paraméterek:** Motorválaszték, kW/LE, nyomaték, gyári felni- és gumiméret (ET számmal), folyadékmennyiségek. -- **Szervizintervallumok:** Gyártó által előírt periodikus karbantartások (idő vagy távolság alapú). +### 3.1. Gyári Konfiguráció (Factory Specs) +- **Trim Level:** Felszereltségi szint (pl. AMG Pack, S-Line). +- **Technikai paraméterek:** Motorvariációk, kW/LE, nyomaték, gyári felni/gumi méretek (ET számmal), folyadékmennyiségek. +- **Szervizintervallumok:** Gyártói előírások (idő vagy távolság alapú). -### B) Aktuális Állapot és Módosítások (Modifications) -- **Gyári extrák:** Mi az, ami benne maradt? (pl. bőrbelső, napfénytető). -- **Utólagos (Aftermarket):** Mi került bele? (pl. vonóhorog, gázszett). -- **Hiányzó:** Mi került ki belőle? (pl. kiszerelt gyári hifi). +### 3.2. Aktuális Állapot és Módosítások +- **Status Quo:** Gyári extrák, utólagos módosítások (Aftermarket - pl. vonóhorog, gázszett) és hiányzó gyári elemek követése. -## 4. Digitális Szervizkönyv (Digital Service Book) -Nem csak egy lista, hanem egy **Eseményalapú Idővonal (Timeline)**. Minden bejegyzés megváltoztathatatlan (immutable-szerű) logként rögzül. + + +--- + +## 4. Digitális Szervizkönyv és Minősítés +### 4.1. Eseményalapú Idővonal (Timeline) +Minden bejegyzés megváltoztathatatlan (immutable) logként rögzül: - **Típusok:** Karbantartás, Javítás, Műszaki Vizsga, Baleset, Tulajdonosváltás. -- **Csatolmányok:** Fotók az alkatrészekről, számlák PDF-ben, munkalapok. +- **Csatolmányok:** Alkatrész fotók, számlák (OCR), munkalapok. -## 5. Jármű Minősítés és Értékelés -A jármű két különálló, de egymást kiegészítő minősítést kap: +### 4.2. Kettős Értékelési Rendszer +1. **AI Health Score (Technikai):** Algoritmus alapú pontszám a szerviztörténet és a gyári előírások betartása alapján. +2. **Driver Rating (Emocionális):** Szubjektív sofőrértékelés (Komfort, Vezetési élmény, Praktikum). -### A) Technikai Minősítés (AI Health Score) -- **Algoritmus alapú:** A szerviztörténet, az üzemóra/futás aránya és a gyári specifikációk betartása alapján kalkulált pontszám. +--- -### B) Emocionális és Közösségi Értékelés (Driver Rating) -A járművet használó sofőrök értékelhetik az eszközt szubjektív szempontok alapján: -- **Komfort:** Mennyire kényelmes hosszú távon? -- **Vezetési élmény:** "Lelke van", vagy csak egy gép? -- **Praktikum:** Mennyire használható a mindennapokban? -- **Megbízhatóság érzet:** Mennyire érzi magát benne biztonságban a sofőr? +## 5. Multi-Robot Harvester Architektúra +A katalógus feltöltéséért és frissítéséért kategória-specifikus robotok felelnek (`BaseHarvester` alapokon). -Ez a kettős mérőszám adja meg a jármű valós "piaci és használati értékét". +### 5.1. Robot Típusok: +- **Autó / Motor Robot:** Közúti adatokra. +- **Heavy Duty / Agri Robot:** Teherautókra és munkagépekre. +- **Specialty Robot:** Vízi és légi azonosítókra (MMSI, Lajstrom). -## 6. Az Adat-Gondnok (Harvester Robot) -A rendszer integritásáért és az adatok pontosságáért egy automata Robot felel. +### 5.2. Adatgyűjtési Szintek: +- **Initial Load:** A top 1000 európai típus alapfeltöltése. +- **On-Demand Fetch:** Felhasználói "Trigger" hatására indított soron kívüli mélykeresés (Deep Web Scrape). +- **Verification Status:** `verified` (teljes), `incomplete` (részleges), `pending` (ellenőrzésre vár). -### Funkciók: -1. **Initial Load:** A legnépszerűbb 1000 európai járműtípus alapértelmezett feltöltése. -2. **On-Demand Fetch:** Ha egy felhasználó ismeretlen típust keres, a Robot prioritással kutatja fel és rögzíti azt. -3. **Deep Data Scrape:** A Robot nemcsak a típust, hanem a gyári specifikációkat (olajmennyiség, guminyomás, szervizintervallum) is gyűjti. -4. **Maintenance:** Negyedévente frissíti a meglévő adatokat (új modellévek, módosított gyári előírások). -### Adatforrások hierarchiája: -1. Hivatalos gyártói API-k (ahol elérhető). -2. Nyilvános műszaki adatbázisok (Auto-Data, UltimateSpecs). -3. VIN/HIN dekóder algoritmusok. -## 7. Kivételkezelés: Ismeretlen és Egyedi Járművek +--- -Ha egy jármű nem található a globális katalógusban, a rendszer kétlépcsős mentőövet nyújt: +## 6. OCR és Dokumentum Validációs Stratégia +A dokumentumfelismerés (OCR) hibrid technológiát és Tier-alapú prioritást alkalmaz. -### A) On-Demand Harvester (Robot hívása) -1. A felhasználó jelzi, hogy hiányzik a típus. -2. A Robot utasítást kap egy mélyebb keresésre (Deep Web Search). -3. Ha találat van, a Robot rögzíti a katalógusba, és a felhasználó folytathatja a rögzítést. +### 6.1. Feldolgozási Sorrend (Failover Logic) +1. **Tier 1 (External Cloud):** Google Vision / Azure Form Recognizer (ingyenes keret erejéig). +2. **Tier 2 (Saját Fallback):** Helyi szerveren futó **PaddleOCR** modul. -### B) Custom Asset (Egyedi/Sport jármű rögzítése) -Ha a jármű sehol nem szerepel (pl. épített versenyautó, egyedi yacht): -1. **Manuális nyilatkozat:** A felhasználó rögzíti az adatokat. -2. **Dokumentum alapú validáció:** A forgalmi engedély vagy sportigazolvány fotóját kötelező feltölteni. -3. **AI Verifikáció:** A rendszer OCR-rel (szövegfelismerés) kiolvassa az adatokat a fotóról, és összeveti a manuális bevitelével. -4. **"Unverified Model" jelzés:** A katalógusban egyedi azonosítót kap, amíg egy admin vagy a Robot más forrásból meg nem erősíti. +### 6.2. Üzleti Logika és Monetizáció +- **VIP+ / Premium+:** Azonnali (Real-time) OCR feldolgozás (3-5 másodperc). +- **Lite:** Háttérfolyamat (sorban állás), korlátozott havi kvóta (pl. 1 scan/hó). +- **Kreditalapú túllépés:** A kvóta feletti beolvasások a `Wallet`-ből levont kreditért vásárolhatók meg. -## 8. Multi-Robot Harvester Architektúra -A rendszer kategóriánként különálló kutató robotokat használ az erőforrások optimalizálása és az adatok pontossága érdekében. -### A) Működési elv -- **Ütemezett futás:** Minden kategória (Autó, Motor, Teher, Hajó) saját időablakban frissít, elkerülve a szerver túlterhelését. -- **Hiányos adatok kezelése:** A Robot köteles rögzíteni a járművet akkor is, ha csak részleges információt talál (pl. csak márka és típus). -- **Státusz jelölések (`verification_status`):** - - `verified`: Teljes DNS adatsor (Robot által hitelesítve). - - `incomplete`: Alapadatok megvannak, de hiányoznak technikai részletek (pl. guminyomás, olaj). - - `pending`: Felhasználó által felvett, Robot általi ellenőrzésre váró egyedi típus. +--- -### B) On-Demand prioritás -Amikor a felhasználó olyan típust keres, ami nem szerepel a katalógusban, a rendszer egy "Priority Trigger"-t küld az adott kategória Robotjának, amely soron kívül megkezdi a célzott adatgyűjtést. - -## 9. OCR és Dokumentum Validációs Stratégia - -A rendszer a járműokmányok (forgalmi engedély, hajólevél, lajstrom) feldolgozására hibrid OCR (Optical Character Recognition) technológiát alkalmaz. - -### A) Hibrid Feldolgozási Sorrend (Failover Logic) -A költséghatékonyság és a pontosság érdekében a rendszer az alábbi sorrendben próbálkozik: -1. **Tier 1 (External Free/Limited APIs):** Ingyenes keretű felhő szolgáltatások (pl. Google Vision API, Azure Form Recognizer). A rendszer figyeli a havi limiteket, és azok elérésekor automatikusan vált a következő szolgáltatóra. -2. **Tier 2 (Saját Erőforrás - Fallback):** Ha minden ingyenes külső keret elfogyott, a rendszer a saját szerveren futó PaddleOCR (AI alapú) modult használja. - -### B) Monetizáció és Jogosultságok -A dokumentum alapú automata rögzítés és validáció prémium funkció: -- **Free/Lite:** Manuális rögzítés (limitált mezők). -- **VIP:** Automata rögzítés (OCR) 1-2 eszközre. -- **VIP + / Premium +:** Korlátlan okmányfelismerés, automata lejárati figyelmeztetések és hivatalos adat-összevetés. - -## 10. Multi-Robot Harvester (Moduláris Felépítés) - -A járműkatalógus feltöltését egy bázis-osztályra (`BaseHarvester`) épülő, kategória-specifikus robotcsalád végzi. - -- **Autó Robot:** Közúti gépjárművekre optimalizálva. -- **Motor Robot:** Kétkerekű és hobbi járművekre. -- **Heavy Duty Robot:** Teherautók, kamionok és munkagépek specifikációira. -- **Specialty Robot:** Vízi és légi járművek egyedi azonosítóihoz (MMSI, Lajstrom). - -# 🏎️ Asset és Flotta Specifikáció: A Járművek DNS-e (v1.2) - -## 7. Kivételkezelés: Ismeretlen és Egyedi Járművek -- **On-Demand Harvester:** Ha a katalógus hiányos, a Robot kérésre (Trigger) indítja a mélykeresést. -- **Custom Asset:** Egyedi/Sport eszközök rögzítése dokumentum alapú validációval. - -## 8. Multi-Robot Harvester Architektúra -A rendszer kategória-specifikus (Car, Bike, Truck, Specialty) robotokat használ. -- **Ütemezés:** Éjszakai batch-futás a szerver terhelésének minimalizálására. -- **Státuszok:** `verified` (teljes), `incomplete` (részleges), `pending` (ellenőrzésre vár). - -## 9. VIN (Alvázszám) és Validáció -- **Algoritmus:** Minden közúti járműnél kötelező a VIN Checksum (MOD 11) ellenőrzése a beíráskor. -- **Auto-Fill:** Érvényes alvázszám esetén a rendszer felajánlja a gyártói adatok (gyártási év, üzem, motorverzió) automatikus kitöltését. - -## 10. Dokumentum Kezelés és Tárolás (NAS) -Minden eszközhöz csatolt dokumentum (forgalmi, fotók, számlák) központi NAS tárolón kerül rögzítésre. +## 7. Infrastruktúra és Adatkezelés +### 7.1. Dokumentum Tárolás (NAS) - **Elérési út:** `/mnt/nas/app_data/assets/{asset_id}/` -- **Archiválás:** `/mnt/nas/git_vault/` (Adatbázis mentések és konfigurációk). +- **Típusok:** + - **Vault (Tartós):** Kritikus okmányok (Forgalmi, Adásvételi) hash-elt fájlnévvel. + - **Ephemeral (Ideiglenes):** Napi bizonylatok (Parkolójegy), melyek OCR után 90 nappal törlődnek. +- **Képoptimalizálás:** Automata átméretezés (max 1600px) és WebP konverzió (~80-90% megtakarítás). -## 11. OCR és Üzleti Logika (Tier-based) -A dokumentumfelismerés (OCR) prioritása a felhasználói csomagtól függ: -- **VIP+ / Premium+:** Azonnali (Real-time) OCR feldolgozás. A felhasználó a feltöltés után 3-5 másodperccel már látja az előtöltött adatokat. -- **Alap csomag:** Háttérfolyamat (Background task). A feldolgozás sorban állítás után történik, a felhasználó értesítést kap a befejezésről. -- **Failover:** Külső API-k (Google/Azure) és saját erőforrás (PaddleOCR) hibrid használata a költségkontroll érdekében. +### 7.2. Címkezelési Protokoll (v2.0) +Minden címet (székhely, tulajdonos, szerviz) atomizált formában tárolunk a pontos riportáláshoz: +- Irányítószám, Település, Közterület neve, Közterület jellege (utca, út stb.), Házszám (emelet/ajtó kiegészítéssel). -## 12. OCR Monetizáció és Kreditszabályok (Admin Kontroll) +--- -A rendszer az OCR alapú adatbeolvasást kvótákhoz és kreditekhez köti. +## 8. Kivételkezelés: Ismeretlen Járművek +Ha az eszköz nem szerepel a katalógusban: +1. **Custom Asset:** Manuális rögzítés kötelező dokumentum-fotóval. +2. **AI Verifikáció:** OCR-rel összeveti a fotót a bevitt adatokkal. +3. **"Unverified Model" jelzés:** Amíg a Robot vagy egy Admin meg nem erősíti az adatok hitelességét. -### A) Csomag alapú kvóták (Admin beállítás) -Az Admin felületen csomagonként (Lite, VIP, VIP+) meghatározható egy ingyenes havi dokumentum-beolvasási keret: -- **Lite:** 0-1 scan/hó. -- **VIP:** 10 scan/hó. -- **VIP+:** Korlátlan vagy magas limit (pl. 100). +## 3. Document Engine & Optimization +- **Processing:** Feltöltéskor automatikus méretoptimalizálás (max 1600px) és WebP konverzió. +- **Thumbnails:** Minden képből 300px széles WebP előnézet generálódik a gyors UI eléréshez. +- **Supported Formats:** JPG, PNG, WEBP (képek); PDF, DOCX (dokumentumok). +- **OCR Integration:** Számlák és munkalapok esetén automata adatkinyerés (alkatrészek, árak, kilométeróra állás). -### B) Kreditalapú túllépés -Ha a felhasználó kimerítette a keretét, minden további beolvasás kreditért vásárolható meg. -- **Egységár:** Admin felületről állítható (pl. 1 beolvasás = 10 kredit). -- **Tranzakció:** A rendszer levonja a kreditet a felhasználó `Wallet`-jéből a sikeres OCR feldolgozás után. +## 7.4 Dokumentum Életciklus és Pufferelés (v2.2) -### C) Egyedi engedélyek (Permissions) -Lehetőség van egyedi felhasználóknak vagy flottáknak "OCR_Override" jogot adni, amivel a csomagtól függetlenül ingyenes vagy kedvezményes beolvasást kapnak (pl. tesztelők vagy stratégiai partnerek). +A rendszer háromlépcsős tárolási és feldolgozási logikát alkalmaz az optimális hálózati és szerver-teljesítmény érdekében: +1. **Ingestion (TEMP - Helyi SSD):** - Minden feltöltött állomány a `/app/temp/uploads/` mappába érkezik. + - Itt történik az AI/OCR elemzés és a képoptimalizálás (Pillow). + - A nyers forrásfájl a feldolgozás után **30 percig** marad itt (puffer), hogy a felhasználó azonnal visszanézhesse, mielőtt a NAS-ra kerül. -## 13. Kiterjesztett Jármű Kategóriák -A rendszer az alábbi kategóriákat különbözteti meg az életút- és költségkövetéshez: -- **Bus:** Tömegközlekedési és távolsági buszok. -- **Motorhome:** Lakóautók és speciális lakókocsik. -- **Trailer:** Utánfutók, pótkocsik, trélerek. -- **Construction:** Munkagépek (markolók, daruk). -- **Agriculture:** Mezőgazdasági vontatók, kombájnok. -- **Micro-mobility:** E-roller, e-bike flották. +2. **Presentation (THUMBNAIL - Helyi SSD):** + - A Pillow által generált 300px széles WebP miniképek a szerver lokális `/app/static/previews/` könyvtárába kerülnek. + - A UI (web/app) kizárólag ezeket tölti be a listázáskor, elkerülve a NAS terhelését. -# 18. ASSET ÉS FLOTTA SPECIFIKÁCIÓ (v1.1) - -## 1. Dokumentum Tárolási és Feldolgozási Stratégia -A rendszer a tárhelyköltségek optimalizálása és a gyors elérés érdekében hibrid tárolást alkalmaz: - -### A) Tárolási típusok -- **Vault (Tartós):** Jogilag kritikus okmányok (Alapító okirat, Forgalmi, Adásvételi). - - Tárolás: NAS, hash-elt fájlnévvel. - - Elérhetőség: Korlátlan ideig, amíg az Asset/Szervezet aktív. -- **Ephemeral (Ideiglenes):** Napi bizonylatok (Parkolási jegy, Tankolási nyugta). - - Folyamat: Feltöltés -> OCR adatkinyerés -> Adatbázis rögzítés -> Kép törlése (90 nap után). - -### B) Képoptimalizálási Motor -Minden feltöltött dokumentum (JPG/PNG) automata feldolgozáson esik át: -- Átmretezés: Max 1600px szélesség. -- Formátum konverzió: WebP (veszteségmentes tömörítés). -- Eredmény: ~80-90%-os tárhely megtakarítás olvashatóság vesztése nélkül. - -## 2. Címkezelési Protokoll (Atomizált Adatok) -A pontos szűrés és a hivatalos iratok generálása érdekében a címeket az alábbi bontásban tároljuk: -- Irányítószám (IRSZ) -- Település (Város) -- Közterület neve -- Közterület jellege (utca, út, tér, stb. - választható listából) -- Házszám (emelet, ajtó, lépcsőház kiegészítéssel) - - Címkezelés (v2.0): Minden magánszemély és szervezet címét atomizált formában tároljuk (IRSZ, Város, Utca, Házszám, HRSZ). Ez alapfeltétele a későbbi flotta-riportoknak és a pontos térképi megjelenítésnek. \ No newline at end of file +3. **Vault (NAS - Hosszú távú tároló):** + - A feldolgozott, nagyfelbontású (max 1600px) WebP állomány átkerül a NAS-ra: `/mnt/nas/app_data/organizations/{id}/vault/`. + - A NAS-hoz csak akkor fordul a rendszer, ha a felhasználó kifejezetten a dokumentum nagy változatát kéri. \ No newline at end of file diff --git a/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md b/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md index 9e44683..2afe8bb 100644 --- a/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md +++ b/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md @@ -1,7 +1,7 @@ -# 🛠️ ADMIN MANAGEMENT & PERMISSIONS (v1.0) +# 🛠️ 19_ADMIN_AND_PERMISSIONS_SPEC (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). +## 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 | | :--- | :--- | :--- | :--- | @@ -11,56 +11,67 @@ A rendszer többszintű, régió-alapú jogosultságkezelést alkalmaz (RBAC + G | **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. + + +### 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 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. +- **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 -- **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. +### 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. -## 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. +### 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. -## 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. +### 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. -## 6. Értesítési Engine és Lejárati Figyelmeztetések +--- -A rendszer proaktív figyelmeztető rendszert alkalmaz minden előfizetői szinten (Individual és Corporate egyaránt). +## 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). -### A) Előfizetés és Pénzügyi Értesítések -- **Hatókör:** Minden fizetős csomag (Lite+, VIP, VIP+, Corporate). -- **Logika:** Automatikus értesítés küldése 30, 15, 7 és 1 nappal a csomag lejárta előtt. -- **Csatornák:** Push notification, Email és a Mini-CRM kontakt személyek értesítése. +### 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. -### B) Jármű Okmányok és Technikai Lejáratok -A rendszer figyeli az eszközökhöz rögzített metaadatokat: -- **Forgalmi engedély:** Műszaki vizsga lejárata. -- **Biztosítás:** Kötelező (KGFB) és CASCO fordulónapok. -- **Lízing/Szerződés:** Szerződéses futamidő vége. -- **Okmányok:** Hajólevél, lajstrom, emelőgép vizsga stb. +### 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. -### C) CRM Kontaktok és Kapcsolattartás -Minden szervezet (Organization) esetében kötelező megadni legalább egy **Adminisztratív Kontaktot**. -- **Több cég kezelése:** Egy Person több szervezetben is betölthet `owner` vagy `fleet_manager` szerepkört. -- **CRM Mezők:** Név, beosztás, közvetlen elérhetőség (fizetésért felelős, operatív felelős). +--- -## 7. Corporate Onboarding és Validációs Szintek -A cégek rögzítése háromlépcsős ellenőrzésen esik át: -1. **Tier 1 (Automata):** Adószám alapú validáció (HU/VIES API). -2. **Tier 2 (AI/OCR):** Feltöltött dokumentumok (Alapító okirat) intelligens elemzése. -3. **Tier 3 (Human):** Adminisztrátori jóváhagyás (L2/L3 szint), ha az automata folyamat bizonytalan. +## 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). -## 8. B2B Jutalék és MLM Kivételek -- **Direct Referral:** Cég által meghívott másik cég esetén csak 1. szintű (L1) jutalék jár. -- **MLM Korlát:** Szervezetek nem építhetnek többszintű hálózatot, a kifizetés fix üzleti megállapodás alapú. \ No newline at end of file +--- + +## 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. \ No newline at end of file diff --git a/static_previews/organizations/6/067b6c7b-0f4d-4a04-875e-9e85a5621c46_thumb.webp b/static_previews/organizations/6/067b6c7b-0f4d-4a04-875e-9e85a5621c46_thumb.webp new file mode 100644 index 0000000..eb8f0fa Binary files /dev/null and b/static_previews/organizations/6/067b6c7b-0f4d-4a04-875e-9e85a5621c46_thumb.webp differ