# 🔍 Digitális Szerviznapló (Service Book) Architektúra Audit

**Dátum:** 2026-06-15  
**Auditor:** Fast Coder (Core Developer)  
**Cél:** A Vezető Tervező részére készült mélyreható elemzés a Szerviz események, Javítások és Okmány lejáratok adatbázis-szintű előkészítettségéről.

---

## 1. Összefoglaló

A rendszer **rendelkezik dedikált táblákkal** a Digitális Szerviznaplóhoz, de azok **részben előkészítettek**, részben pedig a `JSONB` mezőkbe vannak integrálva. Nincs külön `ServiceEvent` vagy `Document` tábla — a szerviz eseményeket az [`AssetEvent`](../backend/app/models/vehicle/asset.py:395) modell kezeli, a dokumentumokat (biztosítás, műszaki) pedig az [`Asset.individual_equipment`](../backend/app/models/vehicle/asset.py:114) JSONB mező.

---

## 2. Táblaszerkezet Áttekintés

### 2.1. `vehicle.asset_events` — Digitális Szervizkönyv (Fő tábla)

**Modell:** [`AssetEvent`](../backend/app/models/vehicle/asset.py:395)  
**Tábla:** `vehicle.asset_events`

| Mező | Típus | Leírás |
|------|-------|--------|
| `id` | UUID (PK) | Elsődleges kulcs |
| `asset_id` | UUID (FK → `vehicle.assets.id`) | Jármű hivatkozás |
| `user_id` | Integer (FK → `identity.users.id`) | Ki végezte a műveletet |
| `organization_id` | Integer (FK → `fleet.organizations.id`) | Szervezet |
| `event_type` | String(50) | Esemény típusa (lásd `AssetEventTypeEnum`) |
| `odometer_reading` | Integer (nullable) | Km óra állás az eseménykor |
| `description` | Text (nullable) | Leírás |
| `cost_id` | UUID (FK → `vehicle.asset_costs.id`, nullable) | Kapcsolódó költség |
| `event_date` | DateTime | Esemény dátuma |
| `created_at` / `updated_at` | DateTime | Időbélyegek |

**Támogatott eseménytípusok** ([`AssetEventTypeEnum`](../backend/app/models/vehicle/asset.py:383)):
- `SERVICE` — Szerviz
- `REPAIR` — Javítás
- `ACCIDENT` — Baleset
- `INSPECTION` — Műszaki vizsga
- `TIRE_CHANGE` — Gumi csere
- `MAINTENANCE` — Karbantartás
- `UPGRADE` — Fejlesztés
- `RECALL` — Visszahívás

**Kapcsolatok:**
- `asset` → [`Asset`](../backend/app/models/vehicle/asset.py:69) (Many-to-One)
- `user` → [`User`](../backend/app/models/identity/user.py) (Many-to-One)
- `organization` → [`Organization`](../backend/app/models/marketplace/organization.py) (Many-to-One)
- `cost` → [`AssetCost`](../backend/app/models/vehicle/asset.py:246) (Many-to-One)

### 2.2. `vehicle.odometer_readings` — Km óra állás történet

**Modell:** [`OdometerReading`](../backend/app/models/vehicle/asset.py:353)  
**Tábla:** `vehicle.odometer_readings`

| Mező | Típus | Leírás |
|------|-------|--------|
| `id` | UUID (PK) | Elsődleges kulcs |
| `asset_id` | UUID (FK → `vehicle.assets.id`) | Jármű |
| `reading` | Integer | Km óra állás |
| `recorded_at` | DateTime | Rögzítés ideje |
| `source` | String(30) | Forrás: `manual`, `api`, `telemetry` |
| `cost_id` | UUID (FK → `vehicle.asset_costs.id`, nullable) | Kapcsolódó költség |

### 2.3. `vehicle.asset_costs` — Költségnapló

**Modell:** [`AssetCost`](../backend/app/models/vehicle/asset.py:246)  
**Tábla:** `vehicle.asset_costs`

A költségek `data` JSONB mezőjében tárolódnak a szerviz specifikus adatok:
- `odometer` — km óra állás a költségkor
- `description` — leírás
- `type` — típus (pl. `maintenance`)
- `invoice_number` — számlaszám

### 2.4. `vehicle.assets.individual_equipment` — JSONB (Okmányok, Biztosítás)

**Mező:** [`Asset.individual_equipment`](../backend/app/models/vehicle/asset.py:114) — JSONB

Itt tárolódnak a **dokumentum lejáratok** és egyéb jármű specifikus adatok:
- `insurance_due_date` — Biztosítás fordulónap
- `insurance_premium` — Biztosítás díja
- `mot_due_date` — Műszaki vizsga lejárata
- `tire_change_date` — Gumicsere időpont
- `tire_change_description` — Gumicsere leírás
- `avg_consumption` — Átlagos fogyasztás
- `avg_cost_per_km` — Átlagos km költség
- `is_primary` — Elsődleges jármű flag
- `color` — Szín
- `next_service_days` — Következő szerviz napokban

---

## 3. Hiányosságok és Javaslatok

### 3.1. Dedikált `service_book` tábla hiánya

**Jelenlegi állapot:** Az [`AssetEvent`](../backend/app/models/vehicle/asset.py:395) modell egy generalista eseménytábla, amely minden típusú eseményt (szerviz, javítás, baleset, műszaki) egy táblában kezel. Nincs külön `ServiceEvent` tábla.

**Javaslat:** Az `AssetEvent` megfelelő a Digitális Szerviznaplóhoz, de érdemes lehet:
- `service_provider` (Integer, FK → `marketplace.service_providers.id`) mező hozzáadása a szervizpartner azonosításához
- `parts_cost` / `labor_cost` bontás a költségekhez
- `warranty_claim` (Boolean) mező a garanciális javításokhoz

### 3.2. Dokumentumok tárolása

**Jelenlegi állapot:** A biztosítás, műszaki vizsga és gumicsere adatok az [`individual_equipment`](../backend/app/models/vehicle/asset.py:114) JSONB mezőben vannak. Nincs dedikált `Document` tábla a jármű dokumentumokhoz.

**Javaslat:** Hozz létre egy `vehicle.vehicle_documents` táblát az alábbi mezőkkel:
- `id` (UUID, PK)
- `asset_id` (UUID, FK → `vehicle.assets.id`)
- `document_type` (String) — pl. `insurance`, `mot`, `registration`, `service_invoice`
- `document_number` (String) — pl. biztosítási kötvényszám
- `issue_date` (Date)
- `expiry_date` (Date)
- `document_url` (String) — feltöltött fájl elérési útja
- `notes` (Text)

### 3.3. Szerviz intervallumok

**Jelenlegi állapot:** A következő szerviz számítása a frontenden történik (`nextServiceKm = current_mileage + 15000`), nincs adatbázis szintű szervizütemezés.

**Javaslat:** Vezess be egy `vehicle.service_schedules` táblát:
- `id` (UUID, PK)
- `asset_id` (UUID, FK → `vehicle.assets.id`)
- `schedule_type` (String) — `time_based` vagy `mileage_based`
- `interval_km` (Integer) — km intervallum
- `interval_days` (Integer) — nap intervallum
- `last_service_km` (Integer) — utolsó szerviz km állása
- `last_service_date` (Date) — utolsó szerviz dátuma
- `next_service_km` (Integer) — következő esedékes km
- `next_service_date` (Date) — következő esedékes dátum

### 3.4. API végpontok hiánya

**Jelenlegi állapot:** Az [`AssetEvent`](../backend/app/models/vehicle/asset.py:395) modellhez tartozik egy `POST /{asset_id}/maintenance` végpont ([`create_maintenance_record`](../backend/app/api/v1/endpoints/assets.py:580)), de nincs:
- `GET /assets/{id}/events` — események listázása
- `GET /assets/{id}/events/{event_id}` — egy esemény részletei
- `PUT /assets/{id}/events/{event_id}` — esemény módosítása
- `DELETE /assets/{id}/events/{event_id}` — esemény törlése

---

## 4. Következtetés

| Komponens | Státusz | Megjegyzés |
|-----------|---------|------------|
| Szerviz események (`AssetEvent`) | ✅ **Kész** | Dedikált tábla, 8 eseménytípussal |
| Km óra állás (`OdometerReading`) | ✅ **Kész** | Időbeli nyomonkövetés |
| Költségnapló (`AssetCost`) | ✅ **Kész** | JSONB adatokkal |
| Okmány lejáratok | ⚠️ **JSONB-ben** | `individual_equipment` mezőben |
| Szerviz intervallumok | ❌ **Hiányzik** | Frontenden számolva |
| API végpontok | ⚠️ **Részleges** | Csak `POST /maintenance` létezik |
| Dedikált dokumentum tábla | ❌ **Hiányzik** | Javasolt létrehozni |

A Digitális Szerviznapló alap infrastruktúrája készen áll, de a következő fejlesztési fázisban érdemes:
1. Létrehozni a `vehicle_documents` táblát
2. Létrehozni a `service_schedules` táblát
3. Kibővíteni az API végpontokat CRUD műveletekkel
4. Átmigrálni a JSONB adatokat a dedikált táblákba