109 lines
7.5 KiB
Markdown
109 lines
7.5 KiB
Markdown
(Az Adatbázis Bibliája.)
|
|
# 🗄️ DATABASE GUIDE
|
|
# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.4)
|
|
|
|
## 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 a felhasználó törli magát (`is_deleted = TRUE`), az email felszabadul.
|
|
- Új regisztrációkor, ha a KYC adatok egyeznek, az új technikai User a régi `person_id`-hoz kapcsolódik.
|
|
|
|
## 2. Person (Identitás) - Banki KYC & Safety
|
|
A `data.persons` tábla a valós identitást tárolja. A Step 2 regisztráció során az alábbi JSONB struktúra kerül kitöltésre:
|
|
- **`identity_docs` (JSONB):**
|
|
- `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óvezetői és repülőgép-vezetői engedélyek.
|
|
- **`medical_emergency` (JSONB):** Vércsoport, allergiák, krónikus betegségek.
|
|
- **Jutalom Trigger:** A profil 100%-os kitöltése után aktiválódik a `system_settings`-ben megadott PRÉMIUM időszak.
|
|
|
|
## 3. Technikai Integritás (Enum & Séma)
|
|
- **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:** Mivel a `metadata.create_all` nem frissíti a meglévő táblákat, új oszlopok esetén (pl. `social_provider`, `mothers_name`) manuális `ALTER TABLE` vagy Alembic migráció szükséges.
|
|
|
|
## 4. Dinamikus Paraméterezés (`data.system_settings`)
|
|
Minden üzleti változó Admin UI-ról állítható:
|
|
- `auth.reward_days`: Regisztrációs prémium hossza (alapértelmezett: 14).
|
|
- `referral.l1`: Első szintű jutalék % (alapértelmezett: 10).
|
|
|
|
## 5. Flotta Tulajdonjog Szabályok (v1.1)
|
|
- **`INDIVIDUAL` flotta:** Nem átruházható (`is_transferable = False`), a felhasználóhoz kötött.
|
|
- **`FLEET_OWNER / SERVICE` flotta:** Átruházható, új tulajdonoshoz rendelhető.
|
|
|
|
|
|
# 🗄️ 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).
|
|
|
|
## 6. Flotta és Tulajdonjog Szabályok (v1.1)
|
|
- **Opcionális Járművek:** Egy flotta (Organization) létezhet járművek nélkül is. A rendszer nem kényszeríti a jármű rögzítését (pl. Flotta menedzser szerepkör esetén).
|
|
- **Átruházhatóság (Transferability):**
|
|
- `INDIVIDUAL` flotta: Nem átruházható, a felhasználóhoz kötött.
|
|
- `FLEET_OWNER / SERVICE` flotta: Átruházható (eladható), új tulajdonos (owner_id) rendelhető hozzá.
|
|
- **Cég Megszűnése:** Soft delete alkalmazása. A cég `is_active` státusza `False` lesz, a tulajdonosi viszony megszűnik, de a járművek életútjában (history) az adatok megmaradnak a visszakövethetőség miatt.
|
|
|
|
## 7. Gazdasági Izoláció
|
|
- **Gamification Korlát:** Csak `INDIVIDUAL` típusú flottákhoz tartozó `Person`-ok vehetnek részt a gamifikációban (XP gyűjtés).
|
|
- **Validációs Korlát:** Cég mint identitás nem validálhat szervizpontot, ezt mindig egy hozzárendelt, azonosított `Person` (alkalmazott/technikus) végzi.
|
|
|
|
## 8. Szervezeti és Gazdasági Szabályok
|
|
- **Identitás Elkülönítés:** A `Company` (Szervezet) entitás nem kap `XP_Ledger` és `Coin_Wallet` rekordot a gamifikációhoz. Ezek kizárólag a `Person` (valós személy) szintjén léteznek.
|
|
- **Automatizált Felügyelet:** Egy ütemezett feladat (Cron/Celery) havonta ellenőrzi a cégek státuszát a külső adatbázisokban.
|
|
- **Értékelési rendszer (Rating):**
|
|
- **Person:** Egyéni teljesítmény, megbízhatóság.
|
|
- **Service (Szerviz):** Szolgáltatási minőség.
|
|
- **Vehicle (Jármű):** Műszaki állapot és előélet.
|
|
- *Megjegyzés:* A Cég (mint flotta) nem kap önálló értékelést, a hírneve a tagjai és járművei minősítéséből adódik össze.
|
|
|
|
## 4. CRM és Szervezeti Kapcsolattartók
|
|
A `data.organization_contacts` tábla felelős a flottákhoz tartozó humán kapcsolattartók kezeléséért.
|
|
- **Dinamikus beállítások:** A `data.organizations` tábla `notification_settings` (JSONB) mezője szabályozza, ki és mikor kapjon értesítést.
|
|
- **Külső szinkron:** Az `external_crm_id` biztosítja a kapcsolatot külső vállalatirányítási rendszerekkel (API-n keresztül).
|
|
|
|
## 4.1 Szervezeti és CRM Adatmodell
|
|
- **data.organizations**: Bővítve `tax_number`, `reg_number`, `headquarters_address` és `is_deleted` mezőkkel.
|
|
- **data.organization_contacts**: Új tábla a Mini-CRM funkciókhoz (kapcsolattartók típus szerint: billing, primary, operational).
|
|
- **Audit**: Minden státuszmódosítás és adatváltozás snapshot-olva az `audit_logs` táblába. |