frontend kínlódás

docs/v201/database_schema.md

@@ -0,0 +1,190 @@
+# Database Schema – Version 2.0.1
+
+**Verzió:** 2.0.1  
+**Dátum:** 2026-03-30  
+**Státusz:** Aktív  
+**Kapcsolódó issue:** #179 (Asset Refactor Documentation Sync)
+
+## 1. Áttekintés
+
+A Service Finder 2.0.1 adatbázisa **PostgreSQL 15+** és **SQLAlchemy 2.0+** (asyncpg) alapú. A séma **domain‑driven design (DDD)** elvekre épül, az adatok logikai sémákba vannak csoportosítva:
+
+- **`identity`** – személyazonosság, felhasználók, szerepkörök, bizalomprofilok.
+- **`finance`** – pénzügyi motor (triple wallet, főkönyv, pénznemváltás).
+- **`vehicle`** – járművek, katalógus, szerviznapló, költségek, telemetria.
+- **`fleet`** – flottakezelés, szervezetek, fióktelepek, eszköz‑hozzárendelések.
+- **`marketplace`** – szolgáltatók, szervizprofilok, foglalások, értékelések.
+- **`system`** – rendszerparaméterek, naplók, dokumentumok, fordítások.
+- **`audit`** – auditnaplók, moderálási műveletek.
+
+Ez a dokumentum a **`vehicle` séma aktuális állapotát** részletezi, különös tekintettel a Digital Twin (Asset) refaktor által bevezetett változásokra.
+
+## 2. Vehicle séma – Fő táblák
+
+### 2.1. `vehicle.assets` – A Digital Twin (Thick Asset)
+
+| Mező | Típus | Nullable | Default | Index | Leírás |
+|------|-------|----------|---------|-------|--------|
+| `id` | UUID | ❌ | `uuid_generate_v4()` | ✅ | Elsődleges kulcs |
+| `vin` | VARCHAR(17) | ✅ | NULL | ✅ | Jármű azonosító szám (VIN) |
+| `license_plate` | VARCHAR(20) | ✅ | NULL | ✅ | Rendszám |
+| `name` | VARCHAR | ✅ | NULL | ❌ | Emberi olvasható név (pl. „Kis Piros”) |
+| `catalog_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `vehicle.vehicle_catalog.id`‑re |
+| `vehicle_class` | VARCHAR(50) | ✅ | NULL | ✅ | Járműosztály (VehicleClassEnum) |
+| `brand` | VARCHAR(100) | ✅ | NULL | ✅ | Márka (ha nincs catalog) |
+| `model` | VARCHAR(100) | ✅ | NULL | ✅ | Modell (ha nincs catalog) |
+| `trim_level` | VARCHAR(100) | ✅ | NULL | ❌ | Felszereltségi szint/kivitel |
+| `fuel_type` | VARCHAR(50) | ✅ | NULL | ✅ | Üzemanyag típus (benzin, diesel, elektromos, etanol, gáz) |
+| `engine_capacity` | INTEGER | ✅ | NULL | ✅ | Hengerűrtartalom (cm³) |
+| `power_kw` | INTEGER | ✅ | NULL | ✅ | Teljesítmény (kW) |
+| `torque_nm` | INTEGER | ✅ | NULL | ❌ | Nyomaték (Nm) |
+| `cylinder_layout` | VARCHAR(50) | ✅ | NULL | ❌ | Hengerelrendezés (soros, V, boxer) |
+| `transmission_type` | VARCHAR(50) | ✅ | NULL | ✅ | Sebességváltó típus (kézi, autómata, CVT, DCT) |
+| `drive_type` | VARCHAR(50) | ✅ | NULL | ✅ | Hajtás (első, hátsó, összkerék) |
+| `euro_classification` | VARCHAR(10) | ✅ | NULL | ❌ | EURO besorolás (EURO 1‑6) |
+| `curb_weight` | INTEGER | ✅ | NULL | ❌ | Saját tömeg (kg) |
+| `max_weight` | INTEGER | ✅ | NULL | ❌ | Össztömeg (kg) |
+| `cargo_volume_x` | NUMERIC(10,2) | ✅ | NULL | ❌ | Csomagtartó hossz (cm) |
+| `cargo_volume_y` | NUMERIC(10,2) | ✅ | NULL | ❌ | Csomagtartó szélesség (cm) |
+| `door_count` | INTEGER | ✅ | NULL | ❌ | Ajtók száma |
+| `seat_count` | INTEGER | ✅ | NULL | ❌ | Ülések száma |
+| `roof_type` | VARCHAR(50) | ✅ | NULL | ❌ | Tető típus (RoofTypeEnum) |
+| `audio_system_type` | VARCHAR(100) | ✅ | NULL | ❌ | Hangrendszer típusa |
+| `individual_equipment` | JSONB | ✅ | `'{}'::jsonb` | ❌ | Egyéni felszerelések (JSONB) |
+| `current_mileage` | INTEGER | ❌ | 0 | ✅ | Jelenlegi kilométerállás |
+| `condition_score` | INTEGER | ❌ | 100 | ❌ | Állapotpontszám (0‑100) |
+| `status` | VARCHAR(20) | ❌ | `'active'` | ❌ | Általános státusz (active, inactive, sold) |
+| `data_status` | VARCHAR(20) | ✅ | `'draft'` | ❌ | Adatminőségi státusz (DRAFT, DISCOVERED, ENRICHED, ACTIVE, ARCHIVED) |
+| `year_of_manufacture` | INTEGER | ✅ | NULL | ✅ | Gyártási év |
+| `first_registration_date` | TIMESTAMPTZ | ✅ | NULL | ❌ | Első forgalomba helyezés dátuma |
+| `created_at` | TIMESTAMPTZ | ❌ | `now()` | ❌ | Létrehozás időpontja |
+| `updated_at` | TIMESTAMPTZ | ✅ | NULL | ❌ | Utolsó módosítás időpontja |
+| `is_for_sale` | BOOLEAN | ❌ | `false` | ✅ | Értékesítésre kínálva |
+| `price` | NUMERIC(15,2) | ✅ | NULL | ❌ | Ár |
+| `currency` | VARCHAR(3) | ❌ | `'EUR'` | ❌ | Pénznem |
+| `current_organization_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `fleet.organizations.id`‑re |
+| `branch_id` | UUID | ✅ | NULL | ❌ | Külső kulcs a `fleet.branches.id`‑re |
+| `relocation_performed` | BOOLEAN | ❌ | `false` | ❌ | Áthelyezés történt‑e |
+| `owner_person_id` | BIGINT | ✅ | NULL | ❌ | Külső kulcs a `identity.persons.id`‑re |
+| `owner_org_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `fleet.organizations.id`‑re |
+| `operator_person_id` | BIGINT | ✅ | NULL | ❌ | Külső kulcs a `identity.persons.id`‑re |
+| `operator_org_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `fleet.organizations.id`‑re |
+
+**Megjegyzések:**
+- A `vin` egyedi index (`UNIQUE`), de lehet NULL.
+- A `catalog_id` opcionális; ha nincs megadva, a `brand` és `model` mezők használhatók.
+- A `data_status` a profil kitöltöttségét tükrözi; a `system_data_completion_weights` tábla alapján számolt `profile_completion_percentage`‑al összefügg.
+- A `current_organization_id` és `branch_id` a flotta‑kezeléshez szükséges.
+
+### 2.2. `vehicle.asset_events` – Digitális Szervizkönyv
+
+| Mező | Típus | Nullable | Default | Index | Leírás |
+|------|-------|----------|---------|-------|--------|
+| `id` | UUID | ❌ | `uuid_generate_v4()` | ✅ | Elsődleges kulcs |
+| `asset_id` | UUID | ❌ | – | ✅ | Külső kulcs a `vehicle.assets.id`‑re |
+| `user_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `identity.users.id`‑re |
+| `organization_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `fleet.organizations.id`‑re |
+| `event_type` | VARCHAR(50) | ❌ | – | ❌ | Esemény típus (AssetEventTypeEnum) |
+| `odometer_reading` | INTEGER | ✅ | NULL | ❌ | Km óra állás az eseménykor |
+| `description` | TEXT | ✅ | NULL | ❌ | Szabad szöveges leírás |
+| `cost_id` | UUID | ✅ | NULL | ❌ | Külső kulcs a `vehicle.asset_costs.id`‑re |
+| `event_date` | TIMESTAMPTZ | ❌ | `now()` | ❌ | Az esemény dátuma |
+| `created_at` | TIMESTAMPTZ | ❌ | `now()` | ❌ | Rögzítés időpontja |
+| `updated_at` | TIMESTAMPTZ | ✅ | NULL | ❌ | Utolsó módosítás időpontja |
+
+**Megjegyzések:**
+- A `cost_id` kapcsolja össze a költségekkel; ha NULL, az esemény nem köthető konkrét kiadáshoz.
+- Az `event_type` a felsorolt 8 típus egyike (SERVICE, REPAIR, ACCIDENT, INSPECTION, TIRE_CHANGE, MAINTENANCE, UPGRADE, RECALL).
+
+### 2.3. `vehicle.vehicle_catalog` – Katalógus mesteradatok
+
+| Mező | Típus | Nullable | Default | Index | Leírás |
+|------|-------|----------|---------|-------|--------|
+| `id` | INTEGER | ❌ | – | ✅ | Elsődleges kulcs |
+| `master_definition_id` | INTEGER | ✅ | NULL | ❌ | Külső kulcs a `vehicle.vehicle_model_definitions.id`‑re |
+| `make` | VARCHAR | ❌ | – | ✅ | Márka |
+| `model` | VARCHAR | ❌ | – | ✅ | Modell |
+| `generation` | VARCHAR | ✅ | NULL | ✅ | Generáció |
+| `year_from` | INTEGER | ✅ | NULL | ❌ | Évjárat tól |
+| `year_to` | INTEGER | ✅ | NULL | ❌ | Évjárat ig |
+| `fuel_type` | VARCHAR | ✅ | NULL | ✅ | Üzemanyag típus |
+| `power_kw` | INTEGER | ✅ | NULL | ✅ | Teljesítmény (kW) |
+| `engine_capacity` | INTEGER | ✅ | NULL | ✅ | Hengerűrtartalom (cm³) |
+| `factory_data` | JSONB | ❌ | `'{}'::jsonb` | ❌ | Gyári adatok (JSONB) |
+
+**Egyedi korlát:** `UNIQUE (make, model, year_from, fuel_type)` – ugyanaz a modell‑változat ne kerüljön be többször.
+
+### 2.4. `vehicle.asset_costs` – Jármű költségek
+
+| Mező | Típus | Nullable | Default | Index | Leírás |
+|------|-------|----------|---------|-------|--------|
+| `id` | UUID | ❌ | `uuid_generate_v4()` | ✅ | Elsődleges kulcs |
+| `asset_id` | UUID | ❌ | – | ✅ | Külső kulcs a `vehicle.assets.id`‑re |
+| `organization_id` | INTEGER | ❌ | – | ❌ | Külső kulcs a `fleet.organizations.id`‑re |
+| `cost_category` | VARCHAR(50) | ❌ | – | ✅ | Költségkategória (pl. maintenance, repair, fuel, insurance) |
+| `amount_net` | NUMERIC(18,2) | ❌ | – | ❌ | Nettó összeg |
+| `currency` | VARCHAR(3) | ❌ | `'HUF'` | ❌ | Pénznem |
+| `date` | TIMESTAMPTZ | ❌ | `now()` | ❌ | A költség keletkezésének dátuma |
+| `invoice_number` | VARCHAR(100) | ✅ | NULL | ✅ | Számlaszám |
+| `data` | JSONB | ❌ | `'{}'::jsonb` | ❌ | Extra adatok (JSONB) |
+
+### 2.5. További táblák (rövid leírás)
+
+| Tábla | Séma | Leírás |
+|-------|------|--------|
+| `vehicle_model_definitions` | vehicle | Robotok által feltöltött technikai mesteradatok (`gold_enriched` státusszal) |
+| `gb_catalog_discovery` | vehicle | Brit (GB) felfedezési várólista |
+| `catalog_discovery` | vehicle | Globális felfedezési várólista (RDW, NHTSA, stb.) |
+| `vehicle_logbook` | vehicle | Útnyilvántartás (NAV, kiküldetés, munkábajárás) |
+| `asset_financials` | vehicle | Beszerzési adatok és amortizáció |
+| `asset_inspections` | vehicle | Napi ellenőrző listák és biztonsági check‑ek |
+| `asset_reviews` | vehicle | Jármű értékelések és visszajelzések |
+| `asset_telemetry` | vehicle | Valós idejű telemetria (jelenleg csak current_mileage) |
+| `asset_assignments` | fleet | Eszköz‑szervezet összerendelések |
+| `vehicle_ownership_history` | vehicle | Tulajdonosváltások története |
+| `vehicle_transfer_requests` | vehicle | Járműátadási kérelmek |
+| `vehicle_expenses` | vehicle | Jelentéskészítéshez használt költségek (kompatibilitási réteg) |
+
+## 3. Enum típusok
+
+### 3.1. VehicleClassEnum
+```sql
+CREATE TYPE vehicle_class_enum AS ENUM (
+    'personal',      -- Személygépjármű
+    'motorcycle',    -- Motorkerékpár
+    'light_commercial', -- Kishaszon gépjármű
+    'commercial',    -- Haszonjármű
+    'work_machine',  -- Munkagép
+    'trailer',       -- Pótkocsi/utánfutó
+    'bus',           -- Autóbusz
+    'camper',        -- Lakókocsi/lakóautó
+    'boat',          -- Hajó
+    'aircraft'       -- Repülőgép
+);
+```
+
+### 3.2. RoofTypeEnum
+```sql
+CREATE TYPE roof_type_enum AS ENUM (
+    'metal',               -- Lemeztető
+    'fabric',              -- Vászontető
+    'hardtop',             -- Nyitható keménytető
+    'folding',             -- Harmonikatető
+    'targa',               -- Targatető
+    'fixed_glass',         -- Fix üvegtető
+    'panoramic',           -- Panorámatető
+    'fixed_sunroof',       -- Fix napfénytető
+    'openable_sunroof',    -- Nyitható napfénytető
+    'retractable_sunroof', -- Elhúzható napfénytető
+    'motorized_sunroof',   -- Motoros napfénytető
+    'openable_panoramic'   -- Nyitható panorámatető
+);
+```
+
+### 3.3. AssetEventTypeEnum
+```sql
+CREATE TYPE asset_event_type_enum AS ENUM (
+    'SERVICE',     -- Szerviz
+    'REPAIR',      -- Javítás
+    'ACCIDENT',    -- Baleset
+    'INSPECTION',