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