# 🗄️ 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.