kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
4e14d57bf6243a5d700d485a7535e524e0a5ca46
service-finder/docs/V01_gemini/06_Database_Guide.md

5.9 KiB
Raw Blame History

🗄️ 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 speciális indexeléssel kezeli a törölt és 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 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ó- vagy repülőgép-vezetői engedélyek.
  • medical_emergency: Vércsoport, allergiák, krónikus betegségek.

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

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.

5. Flotta és Tulajdonjog Szabályok

A flották (Organization) és járművek tulajdonjogi logikája:

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

6. Szervezeti Egységek és CRM

A flottákhoz tartozó humán és üzleti kapcsolatok kezelése.

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

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.

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

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.
Reference in New Issue View Git Blame Copy Permalink