service-finder/docs/V01_gemini/06_Database_Guide.md

(Az Adatbázis Bibliája.)

🗄️ DATABASE GUIDE

🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.4)

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.

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

3. Technikai Integritás (Enum & Séma)

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

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

🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.0)

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.

2. Person (Személyazonosság) - KYC & Safety

A data.persons tábla tárolja a banki szintű azonosításhoz szükséges adatokat:

• Szétválasztott nevek: last_name és first_name a pontos azonosításhoz.
• JSONB mezők: Rugalmas adatszerkezet az okmányokhoz (identity_docs) és vészhelyzeti adatokhoz (medical_emergency).
• Jutalom Trigger: A profil 100%-os kitöltése (név, szül. adatok, okmányok) automatikusan aktiválja a 14 napos PRÉMIUM csomagot.

3. Economy (Pénztárca & Referral)

• Wallet: Minden regisztrációkor létrejön egy rekord a data.wallets táblában (0 Coin, 0 XP).
• Referral Snapshot: A jutalékok kifizetésekor a rendszer rögzíti a tranzakció pillanatában érvényes százalékot (commission_percentage), így a későbbi admin módosítások nem érintik a múltbeli elszámolásokat.

Sémák

• public: Csak technikai táblák (pl. Alembic version).
• data: Az üzleti logika 55 táblája.

Kulcs Táblacsoportok

1. Fleet: vehicles, user_vehicles, vehicle_events, engine_specs.
2. Marketplace: service_providers, service_specialties, organization_locations.
3. Economy: wallets, transactions, shop_items.
4. Identity: users, persons, companies.

Migrációs Állapot

• Eszköz: Alembic.
• Current Head: 10b73fee8967.
• Hiányzó láncszem: A persons tábla létrehozása és a meglévő users tábla migrációja (Ba

4. Regionalizáció és Multi-Currency (EU Scope)

A rendszer fel van készítve az EU-s piacra:

• data.regional_settings: Tárolja az országkódokat (ISO 3166-1), az alapértelmezett nyelvet és a helyi pénznemet.
• data.exchange_rates: Napi frissítésű váltószámok (Base: EUR).
• Valuta Logika: - Minden költséget a rögzítéskori helyi pénznemben (currency_code) és az akkori váltószámmal átszámított EUR-ban is elmentünk.
  • Képlet: Cost_{EUR} = Cost_{Local} \cdot ExchangeRate
  • Ez biztosítja, hogy a nemzetközi flották egységes kimutatást kapjanak.

5. Dinamikus Paraméterezés (System Settings)

• auth.reward_days: Adminból állítható egész szám (alapértelmezett: 14).
• auth.reward_tier: Melyik csomagot kapja (alapértelmezett: PREMIUM).

6. Flotta és Tulajdonjog Szabályok (v1.1)

• Opcionális Járművek: Egy flotta (Organization) létezhet járművek nélkül is. A rendszer nem kényszeríti a jármű rögzítését (pl. Flotta menedzser szerepkör esetén).
• Átruházhatóság (Transferability):
  • INDIVIDUAL flotta: Nem átruházható, a felhasználóhoz kötött.
  • FLEET_OWNER / SERVICE flotta: Átruházható (eladható), új tulajdonos (owner_id) rendelhető hozzá.
• Cég Megszűnése: Soft delete alkalmazása. A cég is_active státusza False lesz, a tulajdonosi viszony megszűnik, de a járművek életútjában (history) az adatok megmaradnak a visszakövethetőség miatt.

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.