frontend kínlódás

2026-03-31 06:20:43 +00:00
parent 2508ae7452
commit c7cbe60976
46 changed files with 6091 additions and 136 deletions
--- a/docs/masterbook_2.0.1/service_book_specification.md
+++ b/docs/masterbook_2.0.1/service_book_specification.md
@@ -0,0 +1,141 @@
+# AssetEvent Service Book – Digitális Szervizkönyv Specifikáció
+
+**Verzió:** 2.0.1  
+**Dátum:** 2026-03-30  
+**Státusz:** Aktív  
+**Kapcsolódó issue:** #179 (Asset Refactor Documentation Sync)
+
+## 1. Áttekintés
+
+Az **AssetEvent** modell a Service Finder digitális szervizkönyvének magja. Minden olyan jelentős eseményt rögzít, amely egy járművel (Asset) történik: szerviz, javítás, baleset, műszaki vizsga, gumicsere, karbantartás, fejlesztés, visszahívás.
+
+A Service Book célja, hogy **egyetlen, hiteles forrást** biztosítson a jármű teljes élettörténetéről, összekapcsolva a szervizeseményeket a költségekkel, a kilométerállással és a szolgáltatóval.
+
+## 2. Főbb jellemzők
+
+### 2.1. Eseménytípusok (AssetEventTypeEnum)
+
+| Típus | Leírás | Kapcsolódó költségkategória |
+|-------|--------|-----------------------------|
+| **SERVICE** | Rendszeres szerviz (olajcsere, szűrőcsere, fékellenőrzés) | `maintenance` |
+| **REPAIR** | Hibajavítás (motor, fékrendszer, elektromika) | `repair` |
+| **ACCIDENT** | Baleset (karosszéria javítás, üvegcserék) | `accident` |
+| **INSPECTION** | Műszaki vizsga, környezetvédelmi vizsgálat | `inspection` |
+| **TIRE_CHANGE** | Gumi csere (nyári/téli, sérült gumi) | `tires` |
+| **MAINTENANCE** | Preventív karbantartás (fűtés‑hűtés, futómű) | `maintenance` |
+| **UPGRADE** | Fejlesztés (hangrendszer, navigáció, biztonsági rendszer) | `upgrade` |
+| **RECALL** | Gyártói visszahívás (garanciás javítás) | `recall` (általában ingyenes) |
+
+### 2.2. Adatmodell (`vehicle.asset_events` tábla)
+
+| Mező | Típus | Kötelező | Leírás |
+|------|-------|----------|--------|
+| `id` | UUID | Igen | Egyedi azonosító |
+| `asset_id` | UUID | Igen | Kapcsolódó Asset (FK: `vehicle.assets.id`) |
+| `user_id` | Integer | Nem | A felhasználó, aki rögzítette (FK: `identity.users.id`) |
+| `organization_id` | Integer | Nem | A szervezet, amelyhez az esemény tartozik (FK: `fleet.organizations.id`) |
+| `event_type` | String(50) | Igen | Az esemény típusa (AssetEventTypeEnum) |
+| `odometer_reading` | Integer | Nem | Km óra állás az esemény időpontjában |
+| `description` | Text | Nem | Szabad szöveges leírás (pl. „Első 15 000 km‑es szerviz”) |
+| `cost_id` | UUID | Nem | Kapcsolódó költségrekord (FK: `vehicle.asset_costs.id`) |
+| `event_date` | DateTime | Igen (default: now) | Az esemény dátuma |
+| `created_at` | DateTime | Igen (default: now) | Rögzítés időpontja |
+| `updated_at` | DateTime | Nem | Utolsó módosítás időpontja |
+
+### 2.3. Kapcsolatok
+
+- **`asset`** – az eseményhez tartozó jármű (Asset).
+- **`user`** – a felhasználó, aki rögzítette (opcionális).
+- **`organization`** – a szervezet, amelyhez az esemény tartozik (opcionális).
+- **`cost`** – a költségrekord (ha van).
+
+## 3. Működési folyamat
+
+### 3.1. „Verified Service Entry” létrehozása
+
+A **hitelesített szervizbejegyzés** (Verified Service Entry) egy olyan AssetEvent, amely:
+1. **Kapcsolódik egy AssetCost rekordhoz** (`cost_id` kitöltve).
+2. **Van odometer_reading értéke** (a jármű kilométerállása az eseménykor).
+3. **Legalább egy szervezethez vagy felhasználóhoz köthető** (`user_id` vagy `organization_id` kitöltve).
+
+A létrehozás lépései:
+
+```mermaid
+graph TD
+    A[Szerviz teljesítése] --> B[Költség rögzítése AssetCost táblában]
+    B --> C{Költség rekord létrejött?}
+    C -->|Igen| D[AssetEvent létrehozása cost_id hivatkozással]
+    C -->|Nem| E[AssetEvent létrehozása cost_id nélkül]
+    D --> F[Verified Service Entry]
+    E --> G[Unverified Service Entry]
+```
+
+### 3.2. Költségek összekapcsolása
+
+Az AssetCost tábla (`vehicle.asset_costs`) a következő mezőket tartalmazza:
+- `asset_id` – a jármű
+- `cost_category` – a költség kategóriája (pl. `maintenance`, `repair`, `fuel`, `insurance`)
+- `amount_net` – nettó összeg
+- `currency` – pénznem
+- `date` – a költség keletkezésének dátuma
+- `invoice_number` – számlaszám (opcionális)
+- `data` – JSONB extra adatok (pl. szolgáltató neve, garancia információ)
+
+Amikor egy AssetEvent létrejön `cost_id` hivatkozással, a rendszer automatikusan ki tudja számolni:
+- **Összes szervizköltség** egy adott időszakban.
+- **Átlagos szervizköltség / 10 000 km**.
+- **Legdrágább szervizesemény** az Asset élettartama alatt.
+
+### 3.3. Idővonal és jelentések
+
+Az AssetEvent rekordok alapján a rendszer képes generálni:
+- **Teljes szerviztörténet** időrendi sorrendben.
+- **Költség‑összesítő** eseménytípusonként.
+- **Kilométer‑alapú szerviz előrejelzés** (pl. „Következő olajcsere 5 000 km múlva”).
+
+## 4. API végpontok
+
+| Metódus | Útvonal | Leírás |
+|---------|---------|--------|
+| **GET** | `/api/v1/assets/{asset_id}/events` | Egy jármű összes eseményének listázása (szűrhető típus, dátum szerint) |
+| **POST** | `/api/v1/assets/{asset_id}/events` | Új esemény létrehozása |
+| **GET** | `/api/v1/assets/{asset_id}/events/{event_id}` | Egy esemény részletei |
+| **PUT** | `/api/v1/assets/{asset_id}/events/{event_id}` | Esemény módosítása |
+| **DELETE** | `/api/v1/assets/{asset_id}/events/{event_id}` | Esemény törlése (soft‑delete) |
+| **GET** | `/api/v1/assets/{asset_id}/events/summary` | Összesítő statisztika (költség, km, események száma) |
+
+## 5. Admin felület integráció
+
+Az admin felületen a Service Book a következő módokon jelenik meg:
+
+1. **Jármű részletek oldal** – „Szerviztörténet” fül, táblázatos lista az eseményekről.
+2. **Költség‑esemény kapcsolás** – a költségek listáján egy „Szerviznaplóhoz hozzáadás” gomb.
+3. **Exportálás** – CSV vagy PDF formátumban a teljes szerviztörténet letöltése.
+4. **Értesítések** – ha egy esemény típusa „RECALL”, a rendszer értesíti a tulajdonost.
+
+## 6. Példa: Teljes szervizfolyamat
+
+1. **Jármű:** 2018‑as Toyota Corolla (Asset ID: `abc123`)
+2. **Szerviz:** 30 000 km‑es nagyszerviz (olaj, szűrők, fékbetét).
+3. **Költség rögzítése:**
+   - `AssetCost` rekord létrehozása:
+     - `cost_category`: `maintenance`
+     - `amount_net`: 85 000 HUF
+     - `invoice_number`: `INV‑2026‑0330‑001`
+4. **Esemény létrehozása:**
+   - `event_type`: `SERVICE`
+   - `odometer_reading`: 30 150
+   - `description`: „30 000 km‑es nagyszerviz – olaj, szűrők, fékbetét”
+   - `cost_id`: (a fenti AssetCost rekord ID‑ja)
+5. **Eredmény:** A Toyota Corolla szerviztörténetében megjelenik a bejegyzés, a költségek automatikusan hozzáadódnak a TCO számításhoz.
+
+## 7. Jövőbeli bővítések
+
+- **OCR‑alapú számlafelismerés** – a feltöltött számlákból automatikus AssetEvent generálás.
+- **AI‑javaslatok** – a korábbi események alapján javasolt szervizintervallumok.
+- **Szolgáltatói portál** – külső szervizek közvetlen rögzítése a Service Bookba.
+- **Garancia követés** – garanciális események külön kezelése, lejárati figyelmeztetések.
+
+## 8. Összefoglaló
+
+Az **AssetEvent Service Book** a Service Finder 2.0.1 egyik legfontosabb vállalati funkciója. Nem csupán napló, hanem egy **élő, összekapcsolt adatháló**, amely lehetővé teszi a járművek teljes életciklusának nyomon követését, a költségek pontos elszámolását és a flotta megbízhatóságának folyamatos javítását.
--- a/docs/masterbook_2.0.1/thick_asset_philosophy.md
+++ b/docs/masterbook_2.0.1/thick_asset_philosophy.md
@@ -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