FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user