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

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:

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.