161 lines
7.6 KiB
Markdown
161 lines
7.6 KiB
Markdown
# 🔍 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
|