service-finder/docs/masterbook_2.0.1/thick_asset_philosophy.md

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):

{
  "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):

{
  "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):

{
  "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