service-finder/docs/service_book_schema_audit.md

🔍 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 modell kezeli, a dokumentumokat (biztosítás, műszaki) pedig az Asset.individual_equipment JSONB mező.

---

2. Táblaszerkezet Áttekintés

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

Modell: AssetEvent
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):

• 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 (Many-to-One)
• user → User (Many-to-One)
• organization → Organization (Many-to-One)
• cost → AssetCost (Many-to-One)

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

Modell: OdometerReading
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
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 — 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 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 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 modellhez tartozik egy POST /{asset_id}/maintenance végpont (create_maintenance_record), 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