frontend kínlódás
This commit is contained in:
Roo
192
docs/masterbook_2.0.1/thick_asset_philosophy.md
Normal file
192
docs/masterbook_2.0.1/thick_asset_philosophy.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user