# Thick Asset Filozófia – A Digital Twin mint elsődleges adattároló

**Verzió:** 2.0.1  
**Dátum:** 2026-03-30  
**Státusz:** Aktív  
**Kapcsolódó issue:** #179 (Asset Refactor Documentation Sync)

## 1. Mi a „Thick Asset”?

A Service Finder 2.0.1 architektúrája a **„Thick Asset”** (vastag eszköz) elvet követi. Ez azt jelenti, hogy a fizikai jármű digitális ikre (Digital Twin) nem csupán egy hivatkozás a katalógusra, hanem egy teljes értékű, önálló adattároló entitás, amely magában hordozza a jármű **összes releváns technikai, gazdasági és üzemeltetési adatát**.

### 1.1. A régi „Thin Asset” modell
- Az Asset csak egy külső kulcs a `vehicle_catalog` vagy `vehicle_model_definitions` táblákra.
- A technikai specifikációk (lökettérfogat, teljesítmény, felszereltség) kizárólag a katalógusban voltak tárolva.
- Ha egy jármű módosításon esett át (pl. tuning, átépítés), az adatok elvesztek vagy nem voltak nyomon követhetők.

### 1.2. Az új „Thick Asset” modell
- Az Asset (**`vehicle.assets`** tábla) tartalmazza a jármű **saját technikai adatait** (lásd a 22+ új oszlopot).
- A katalógus (**`vehicle.vehicle_catalog`**) továbbra is szolgál mint **ellenőrzött mestersablon**, de az Asset önállóan tárolhat eltérő értékeket.
- A modell lehetővé teszi:
  - **Egyedi módosítások** rögzítését (pl. tuning, felszereltség‑bővítés).
  - **Időbeli változások** nyomon követését (pl. motorcsere, üzemanyag‑átállítás).
  - **Hiányzó katalógus** esetén is a jármű teljes profiljának kezelését.

## 2. A filozófia előnyei

### 2.1. Adatintegritás és teljesség
- A jármű adatai **egy helyen**, az Asset rekordban összpontosulnak.
- A katalógus frissítése (pl. újabb évjárat) nem írja felül a már létező Asset adatait.
- A **profile_completion_percentage** dinamikusan számolható a ténylegesen kitöltött mezők alapján.

### 2.2. Rugalmasság a valós üzleti folyamatokhoz
- **Költségkövetés:** Minden kiadás (`vehicle.asset_costs`) közvetlenül az Asset‑hez kapcsolódik.
- **Szerviztörténet:** Az AssetEvent szolgáltatásnapló (`vehicle.asset_events`) az Asset‑hez kötődik, nem a katalógushoz.
- **Tulajdonosi változások:** A `vehicle_transfer_requests` és `vehicle_ownership_history` táblák az Asset‑en keresztül kezelik a tulajdonosváltásokat.

### 2.3. Teljesítmény és lekérdezési hatékonyság
- A gyakran használt technikai adatok (pl. `fuel_type`, `power_kw`, `vehicle_class`) indexelve vannak az Asset táblában, így a szűrés és jelentéskészítés gyorsabb.
- Nincs szükség összetett JOIN‑okra a katalógussal minden egyes lekérdezésnél.

## 3. Technikai megvalósítás

### 3.1. Az Asset tábla szerkezete
A `vehicle.assets` tábla jelenleg **22+ új oszlopot** tartalmaz a korábbi v1-hez képest. Ezek az oszlopok a következő kategóriákba sorolhatók:

1. **Azonosítás** (`vin`, `license_plate`, `name`, `catalog_id`)
2. **Osztályozás** (`vehicle_class`, `brand`, `model`, `trim_level`)
3. **Technikai specifikációk** (`fuel_type`, `engine_capacity`, `power_kw`, `torque_nm`, `cylinder_layout`, `transmission_type`, `drive_type`, `euro_classification`)
4. **Fizikai méretek** (`curb_weight`, `max_weight`, `cargo_volume_x`, `cargo_volume_y`, `door_count`, `seat_count`)
5. **Felszereltség** (`roof_type`, `audio_system_type`, `individual_equipment` (JSONB))
6. **Állapot** (`current_mileage`, `condition_score`, `status`, `data_status`)
7. **Idővonal** (`year_of_manufacture`, `first_registration_date`, `created_at`, `updated_at`)
8. **Értékesítés** (`is_for_sale`, `price`, `currency`)
9. **Szervezeti kapcsolatok** (`current_organization_id`, `branch_id`, `relocation_performed`)
10. **Tulajdonosi kapcsolatok** (`owner_person_id`, `owner_org_id`, `operator_person_id`, `operator_org_id`)

### 3.2. Kapcsolatok
- **`catalog`** – kapcsolat a `vehicle.vehicle_catalog` táblával (opcionális, ha a jármű ismert katalóguselemhez tartozik).
- **`financials`** – az AssetFinancials rekord (beszerzési adatok, amortizáció).
- **`costs`** – az AssetCost rekordok (üzemeltetési költségek).
- **`events`** – az AssetEvent rekordok (szerviznapló).
- **`logbook`** – a VehicleLogbook bejegyzések (útnyilvántartás).
- **`inspections`**, **`reviews`**, **`telemetry`**, **`assignments`**, **`ownership_history`**, **`service_requests`** – további kapcsolatok.

### 3.3. Enum típusok
A következő enumerációk definiálva vannak a modellben:
- **`VehicleClassEnum`** – járműosztályok (personal, motorcycle, light_commercial, commercial, work_machine, trailer, bus, camper, boat, aircraft).
- **`RoofTypeEnum`** – tetőtípusok (metal, fabric, hardtop, folding, targa, fixed_glass, panoramic, fixed_sunroof, openable_sunroof, retractable_sunroof, motorized_sunroof, openable_panoramic).
- **`AssetEventTypeEnum`** – eseménytípusok a digitális szervizkönyvben (SERVICE, REPAIR, ACCIDENT, INSPECTION, TIRE_CHANGE, MAINTENANCE, UPGRADE, RECALL).

## 4. Migrációs útmutató

A meglévő, „thin” Asset rekordok frissítése a következő lépésekből áll:
1. **Katalógus keresés** – ha a jármű ismert márka/modell/évjárat kombináció, a `catalog_id` beállítása.
2. **Hiányzó mezők kitöltése** – a katalógusból másolható adatok (pl. `engine_capacity`, `power_kw`) átmásolása az Asset rekordba.
3. **Adatminőség javítása** – a `data_status` mező beállítása (DRAFT, DISCOVERED, ENRICHED, ACTIVE, ARCHIVED) a kitöltöttség függvényében.

A migrációt a `sync_engine.py` szkript végzi automatikusan, amikor a séma változás észlelhető.

## 5. Jövőbeli kiterjesztések

- **Real‑time telemetria** – az `asset_telemetry` tábla bővítése GPS, üzemanyag‑fogyasztás, hibakódok rögzítésére.
- **Predictive maintenance** – a szervizesemények és költségek alapján javaslatok generálása.
- **Multi‑asset kapcsolatok** – pl. pótkocsi‑vontató összerendelés, flotta‑szintű optimalizálás.

## 6. API Végpontok és Payload Struktúrák

### 6.1. Asset Létrehozás (POST /api/v1/assets)

**Endpoint:** `POST /api/v1/assets`
**RBAC:** `asset:create` jogosultság szükséges
**Státusz logika:** Automatikus státusz meghatározás az adatkomplettség alapján

**Request Body (AssetCreate):**
```json
{
  "license_plate": "ABC-123",
  "vin": "WBA12345678901234",
  "brand": "BMW",
  "model": "320i",
  "vehicle_class": "personal",
  "fuel_type": "petrol",
  "catalog_id": 12345,
  "engine_capacity": 1998,
  "power_kw": 135,
  "year_of_manufacture": 2020,
  "organization_id": 1
}
```

**Státusz meghatározás szabályai:**
- **"active" státusz:** Ha mind az 5 alapvető mező (`license_plate`, `brand`, `model`, `vehicle_class`, `fuel_type`) kitöltve van
- **"draft" státusz:** Ha bármelyik alapvető mező hiányzik
- A `vin` mező nem kötelező az "active" státuszhoz, de növeli a profil kitöltési százalékot

### 6.2. Asset Válasz (GET /api/v1/assets/{id})

**Response Body (AssetResponse):**
```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "vin": "WBA12345678901234",
  "license_plate": "ABC-123",
  "brand": "BMW",
  "model": "320i",
  "vehicle_class": "personal",
  "fuel_type": "petrol",
  "engine_capacity": 1998,
  "power_kw": 135,
  "status": "active",
  "data_status": "enriched",
  "is_verified": false,
  "profile_completion_percentage": 85,
  "year_of_manufacture": 2020,
  "current_organization_id": 1,
  "owner_organization_id": 1,
  "created_at": "2026-03-30T21:30:00Z",
  "updated_at": "2026-03-30T21:30:00Z",
  "catalog": {
    "id": 12345,
    "make": "BMW",
    "model": "3 Series",
    "generation": "G20",
    "vehicle_class": "personal",
    "fuel_type": "petrol",
    "power_kw": 135,
    "engine_capacity": 1998
  }
}
```

### 6.3. Catalog Snapshot Sync Funkcionalitás

Ha a kérés tartalmaz `catalog_id`-t, a rendszer automatikusan betölti a hiányzó technikai adatokat a `VehicleModelDefinition` táblából:

**Szinkronizációs logika:**
1. Ha a felhasználó nem ad meg értéket egy mezőhöz (pl. `power_kw`), de a katalógus tartalmazza, a katalógus értéke kerül felhasználásra
2. Ha a felhasználó explicit megad egy értéket, az felülírja a katalógus értékét
3. A szinkronizáció csak a következő mezőkre vonatkozik: `brand`, `model`, `vehicle_class`, `fuel_type`, `power_kw`, `engine_capacity`, `euro_classification`, `body_type`

### 6.4. Service Book API (Digitális Szervizkönyv)

**Esemény hozzáadása (POST /api/v1/assets/{id}/events):**
```json
{
  "event_type": "SERVICE",
  "odometer_reading": 50000,
  "description": "Rendszeres szerviz: olajcsere, szűrők cseréje",
  "event_date": "2026-03-30T10:00:00Z"
}
```

**RBAC szabályok:**
- Csak a `operator_org_id` vagy `owner_org_id` szervezethez tartozó felhasználók adhatnak hozzá eseményeket
- Admin felhasználók bármely eszközhöz hozzáadhatnak eseményeket

### 6.5. SaaS Limit Integráció

A `create_or_claim_vehicle` metódus továbbra is tiszteletben tartja a meglévő SaaS limit logikát:
- A `get_user_vehicle_limit` függvény ellenőrzi a felhasználó és szervezet limitjeit
- Csak "active" státuszú járművek számítanak a limitbe
- "draft" státuszú járművek nem érintik a limitet

## 7. Összefoglaló

A **Thick Asset filozófia** a Service Finder 2.0.1 alapvető pillére. Biztosítja, hogy a digitális ikrek ne csupán üres héjak legyenek, hanem teljes értékű, önállóan kezelhető üzleti entitások, amelyek képesek a valós világ változásait tükrözni és támogatni a flottavezetés, költségkövetés és szerviznaplózás összetett folyamatait.

**Kulcsfontosságú implementációs pontok:**
1. **Backward compatibility:** A meglévő SaaS limit és RBAC logika változatlan marad
2. **Automatikus státuszkezelés:** Az adatkomplettség alapján automatikus "draft" vs "active" státusz
3. **Intelligens katalógus szinkron:** Hiányzó technikai adatok automatikus kitöltése katalógusból
4. **Service Book integráció:** Teljes körű digitális szervizkönyv támogatás RBAC védelme mellett