kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
f38a75a02505d8336fb80f09b15eef476faea5f9
service-finder/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md

7.5 KiB
Raw Blame History

🔐 05_AUTH_AND_IDENTITY_SPEC (v1.3)

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.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).

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 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.

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.

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 (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.

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.

4. Multi-Account & Identity Linking

A felhasználók több e-mail címet is csatolhatnak egyetlen profilhoz, hogy könnyen válthassanak a magánszemély és a céges flotta-menedzser szerepkörök között.

4.1 Szabályrendszer

  • Limit: Egy felhasználói profilhoz maximum 3 másodlagos e-mail cím csatolható.
  • Elsődleges cím: Ez a belépési azonosító és a hivatalos értesítési cím.
  • Context Switching: A felhasználó a fejlécben válthat a "Személyes" és a "Céges" nézetek között (pl. Flotta Manager mód).

4.2 Account Linking Folyamat

  1. User belép az elsődleges fiókba.
  2. Settings -> Linked Accounts -> Add New.
  3. Rendszer küld egy megerősítő linket az új címre.
  4. Ha a linkre kattint, az új cím hozzáadódik a user_identities táblához.
  5. Ha az új címen már volt regisztráció: A rendszer felajánlja az Account Merge (Fiókegyesítés) lehetőségét (biztonsági kérdések után).
# 05. Authentication & Identity Specification

## 5.2. Data Models (Identity)

### 5.2.1. User Entity (`data.users`)
A technikai belépési pont.
- **id**: Integer (PK)
- **email**: String (Unique)
- **hashed_password**: String (Bcrypt)
- **role**: Enum (superadmin, admin, user, service, driver)
- **person_id**: FK -> `data.persons.id` (A TWINS kapcsolat)
- **preferred_language**: String (Default: 'hu') [ÚJ v1.2.5]
- **region_code**: String (Default: 'HU') [ÚJ v1.2.5]
- **is_active**: Boolean

### 5.2.2. TWINS Concept Update
- A `User` (User) és `Person` (Shadow Identity) szétválasztása szigorú.
- Belépéskor a rendszer a `User` táblából olvassa ki a `preferred_language` és `region_code` beállításokat, és ezeket a Token válaszban visszaadja a Frontendnek.

## 1.3 Shadow Identity & Merging Logic
A rendszer támogatja a "Ghost Person" (Árnyék személy) entitásokat.
- **Ghost Person:** Olyan `data.persons` rekord, amelyet a Robot 2 hozott létre nyilvános adatok (pl. cégjegyzék) alapján.
- **Identity Linkage:** Regisztrációkor a `AuthService.complete_kyc` kötelezően ellenőrzi a meglévő Ghost rekordokat (Adószám/Név egyezés).
- **Merge Action:** Találat esetén a rendszer összefűzi a technikai User fiókot a Ghost Person rekorddal, aktiválja a jogosultságokat, és megszünteti a Ghost státuszt.
Reference in New Issue View Git Blame Copy Permalink