# 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.