# 🗄️ 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. ## 6. Service & Organization Extensions (V2) ### 6.1 `data.system_configs` (Dinamikus Beállítások) Kódba égetett értékek helyett adatbázisból vezérelt működés. * `key` (VARCHAR): Pl. `referral_bonus_L1`, `exchange_rate_EUR`, `payout_threshold`. * `value` (JSONB): Pl. `{"amount": 10, "unit": "percent"}`, `{"rate": 400.0}`. * `is_active` (BOOLEAN). ### 6.2 `data.service_reviews` (Okos Értékelés) * `user_id`, `organization_id`. * `rating` (1-5). * `proof_url` (Számla/Munkalap fotó URL). * `is_active` (BOOLEAN): Csak az aktív számít bele az átlagba (lásd Gamification logika). ### 6.3 `data.wallet_transactions` * `original_currency`: (HUF, EUR, USD). * `exchange_rate`: Az adott pillanatban érvényes váltószám. ## 7. Referrals & Invitations * `data.referrals`: Hierarchikus fa szerkezet (`inviter_id`, `invitee_id`, `level`). * `data.invitations`: * `code`: Random string (pl. `X7K9P2`). * `type`: 'private' (72h) vagy 'company' (168h). * `target_role`: A meghívott jogosultsága (Driver, Manager). ## 8. Virtual Goods & Inventory (Digitális Javak) ### 8.1 `data.user_inventory` Ez a tábla tárolja a felhasználó által megszerzett vagy vásárolt kozmetikai elemeket (NEM jogosultságok, hanem vagyontárgyak). * `id` (UUID): Egyedi azonosító. * `user_id` (FK): A tulajdonos. * `item_id` (VARCHAR): A katalógusban lévő azonosító (pl. `avatar_frame_neon`). * `metadata` (JSONB): Opcionális egyedi tulajdonságok (pl. sorszámozott NFT-szerű elemknél: `{"serial": 42}`). * `acquired_at` (TIMESTAMP): Mikor szerezte. * `is_equipped` (BOOLEAN): Éppen használja-e (pl. ez az aktív avatar kerete). ### 8.2 Shop Catalog Configuration (`system_configs`) A `key = 'shop_catalog'` alatt tároljuk a bolt kínálatát JSON formátumban. **Példa JSON struktúra:** ```json { "categories": ["avatars", "badges", "profile_themes"], "items": { "badge_early_adopter": { "name": "Korai Felfedező", "price": 0, "currency": "free", "condition": "reg_date < '2025-01-01'", "image_url": "/assets/badges/early.png" }, "frame_gold_mechanic": { "name": "Arany Szerelő Keret", "price": 5000, "currency": "credit", "rarity": "legendary", "effect": "shine_animation", "image_url": "/assets/frames/gold.png" } } } ## 5. Geo-Location and Address Master Data A rendszer normalizált címkezelést alkalmaz az adatminőség biztosítása érdekében. ### 5.1 Geo Adattáblák - `data.geo_postal_codes`: ZIP és Település kapcsolata (Unique: country + zip + city). - `data.geo_streets`: Utcanevek listája, ZIP azonosítóhoz kötve. - `data.geo_street_types`: Közterület típusok szótára (út, utca, tér...). ### 5.2 GIS Adatok Minden telephely koordinátája `GEOGRAPHY(POINT, 4326)` típusként van tárolva, amely lehetővé teszi a PostGIS alapú távolságmérést.