FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic

docs/V01_gemini/06_Database_Guide.md

@@ -1,109 +1,112 @@
-(Az Adatbázis Bibliája.)
-# 🗄️ DATABASE GUIDE
-# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.4)
+# 🗄️ 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 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.
+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.
 
-## 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):**
+- **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ó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.
+    - `special_permits`: hajó- vagy repülőgép-vezetői engedélyek.
+- **`medical_emergency`**: Vércsoport, allergiák, krónikus betegségek.
 
-## 3. Technikai Integritás (Enum & Séma)
+### 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:** 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.
+- **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. 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ő.
+## 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$$
 
-# 🗄️ DATABASE GUIDE & DATA INTEGRITY (v1.0)
+### 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.
 
-## 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.
+## 5. Flotta és Tulajdonjog Szabályok
+A flották (Organization) és járművek tulajdonjogi logikája:
 
-## 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.
+    - `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).
 
-## 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.
+## 6. Szervezeti Egységek és CRM
+A flottákhoz tartozó humán és üzleti kapcsolatok kezelése.
 
-  ## 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).
+- **`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.
 
-## 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.
+---
+
+## 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.