Kincses
24d35fe0c1
- Split mother's name in KYC (last/first) - Added mileage_unit and fuel_type to Assets - Expanded AssetCost for international VAT and original currency - Fixed SQLAlchemy IndexError in asset catalog lookup - Added exchange_rate and ratings tables to models
199 lines
9.6 KiB
Markdown
199 lines
9.6 KiB
Markdown
# 🗄️ 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.
|
|
|
|
### 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. | |