11 KiB
Executable File
11 KiB
Executable File
🗄️ 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
emailmező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.
- Ha a felhasználó törli magát (
- 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égiperson_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
userroletí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_allnem frissíti a meglévő táblákat. Új oszlopok esetén manuálisALTER TABLEvagy Alembic migráció szükséges. - Audit: Minden státuszmódosítás és adatváltozás snapshot-olva kerül az
audit_logstá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.walletstá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):
INDIVIDUALflotta: Nem átruházható, a felhasználóhoz kötött.FLEET_OWNER / SERVICEflotta: Á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_idmező biztosítja az API kapcsolatot külső ERP rendszerekkel.
7. Gazdasági Izoláció és Rating
- Gamification Korlát: Csak
INDIVIDUALtípusú flottákhoz tartozóPerson-ok gyűjthetnek XP-t. A cégek (Company) nem kapnakXP_Ledger-t ésCoin_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
- Fleet:
vehicles,user_vehicles,vehicle_events,engine_specs. - Marketplace:
service_providers,service_specialties,organization_locations. - Economy:
wallets,transactions,shop_items. - Identity:
users,persons,companies.
10. Migrációs Állapot (Dev Info)
- Eszköz: Alembic
- Current Head:
10b73fee8967 - Hiányzó láncszem: A
personstábla véglegesítése és a meglévőuserstábla adatintegrációs migrációja folyamatban.
4.2 Dokumentum és Irattár (Vault Logic)
- Központi tárolás: A
data.documentstá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ó:
statusmező (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:
{
"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.
### 5. Hibrid Címkezelési Modell
A rendszer az adatintegritás és a sebesség érdekében hibrid modellt használ.
- **Centralizált adattárolás**: A `data.addresses` tábla tárolja a normalizált címeket (UUID alapú).
- **Öntanuló szótárak**: A `data.geo_postal_codes` és `data.geo_streets` táblák automatikusan bővülnek minden új rögzítésnél.
- **Denormalizált GPS adatok**: Az `organization_locations` tábla közvetlenül tárolja a koordinátákat a JOIN-nélküli PostGIS lekérdezésekhez.
| Tábla | Funkció |
| :--- | :--- |
| `data.addresses` | Konkrét házszám szintű címek (Hibrid hivatkozási pont). |
| `data.geo_postal_codes` | Irányítószám és város kapcsolata (HU/EU támogatás). |
| `data.user_stats` | Felhasználói XP, szintek és strike-ok tárolása. |
## 2.4 Financial & Enrichment Tables
- **data.organization_financials:** Éves gazdasági adatok (árbevétel, profit, létszám) tárolása historikus elemzéshez.
- **data.service_profiles.specialization_tags:** JSONB mező a szigorú szakmai szűréshez (pl. márkák, specifikus javítási típusok).
- **data.service_profiles.google_place_id:** Külső validációs kulcs a Google Places API-hoz.
### Identity & Economy Module (v1.6+)
* **`data.persons`**: Természetes személyek, Identity Hash, Örök XP/Büntetés.
* **`data.users`**: Login fiókok, Előfizetési idő, Sales kapcsolatok.
* **`data.wallets`**: 3-as osztású egyenleg (`earned`, `purchased`, `coins`).
* **`data.financial_ledger`**: Pénzügyi tranzakciók főkönyve.
* **`data.security_audit_logs`**: Biztonsági események és 4-szem jóváhagyások.
* **`data.org_sales_assignments`**: Cég-Üzletkötő kapcsolat (Farming jog).
## 4. MDM és Jármű Katalógus Struktúra
A rendszer hibrid (Relációs + JSONB) modellt használ a skálázhatóság érdekében.
### 4.1 Táblák:
* **data.vehicle_model_definitions**: A "Szent Grál". Tartalmazza a márka, kód, marketing név mellett a fix numerikus adatokat (ccm, kw, weight) a gyors szűréshez.
* **data.feature_definitions**: Globális szótár az összes extráról (ABS, Halradar, Retarder stb.), kategóriákba sorolva.
* **data.model_feature_maps**: Összeköti a modellt az extrákkal.
- `availability`: [STANDARD, OPTIONAL, ACCESSORY]
* **data.vehicle_model_reviews**: Felhasználói vélemények a típusról (1-5 csillag, szöveges).