# 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',