FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Binary file not shown.
@@ -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
|
||||
# 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"])
|
||||
Binary file not shown.
30
backend/app/api/v1/endpoints/documents.py
Normal file
30
backend/app/api/v1/endpoints/documents.py
Normal file
@@ -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"
|
||||
}
|
||||
@@ -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"}
|
||||
return {
|
||||
"status": "online",
|
||||
"message": "Service Finder Master System v2.0",
|
||||
"features": ["Document Engine", "Asset Vault", "Org Onboarding"]
|
||||
}
|
||||
BIN
backend/app/models/__pycache__/document.cpython-312.pyc
Normal file
BIN
backend/app/models/__pycache__/document.cpython-312.pyc
Normal file
Binary file not shown.
26
backend/app/models/document.py
Normal file
26
backend/app/models/document.py
Normal file
@@ -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())
|
||||
Binary file not shown.
82
backend/app/services/document_service.py
Normal file
82
backend/app/services/document_service.py
Normal file
@@ -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
|
||||
@@ -17,3 +17,4 @@ psycopg[binary]
|
||||
httpx
|
||||
pydantic[email]
|
||||
sendgrid==6.*
|
||||
Pillow
|
||||
@@ -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
|
||||
@@ -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.
|
||||
## 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.
|
||||
@@ -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.
|
||||
- **Átruházhatóság (Transferability):**
|
||||
- `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).
|
||||
|
||||
## 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.
|
||||
## 6. Szervezeti Egységek és CRM
|
||||
A flottákhoz tartozó humán és üzleti kapcsolatok kezelése.
|
||||
|
||||
## Kulcs Táblacsoportok
|
||||
- **`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.
|
||||
|
||||
---
|
||||
|
||||
## 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`.
|
||||
|
||||
## 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.
|
||||
## 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.
|
||||
|
||||
## 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).
|
||||
## 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).
|
||||
|
||||
## 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.
|
||||
|
||||
## 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).
|
||||
|
||||
## 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.
|
||||
## 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.
|
||||
@@ -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
|
||||
### 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 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ó).
|
||||
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.
|
||||
@@ -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.
|
||||
## 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.
|
||||
@@ -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.
|
||||
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.
|
||||
@@ -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.
|
||||
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.
|
||||
@@ -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ú.
|
||||
---
|
||||
|
||||
## 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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Reference in New Issue
Block a user