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

(Az Adatbázis Bibliája.)

🗄️ DATABASE GUIDE

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