service-finder/docs/vehicle_api_frontend_architecture.md

# 🚗 Service Finder - Jármű API és Frontend Architektúra Elemzés

> **Verzió:** 1.0  
> **Dátum:** 2026-06-05  
> **Szerző:** Rendszer-Architect  
> **Cél:** A backend jármű API teljes áttekintése és frontend csoportosítási javaslat

---

## 1. 📊 Backend API Réteg - Teljes Végpont Térkép

A FastAPI routerek a `backend/app/api/v1/api.py` fájlban vannak összefogva. Az összes járművel kapcsolatos végpont az alábbi prefixek alatt fut:

### 1.1 `/assets` prefix - Jármű (Asset) Menedzsment

**Router:** `backend/app/api/v1/endpoints/assets.py`

| Metódus | Végpont | Cél | Adatbázis kapcsolat |
|---------|---------|-----|---------------------|
| GET | /assets/vehicles | Felhasználó járműveinek listázása (Garázs). Paginált. Támogatja: személyes mód (owner/operator) és vállalati mód (szervezet garázsai/Branch-ek). | Asset - vehicle.assets tábla |
| POST | /assets/vehicles | Új jármű hozzáadása vagy meglévő igénylése. Ellenőrzi a járműlimitet, kezeli a VIN duplikációt, XP jutalmat ad. | Asset |
| GET | /assets/{asset_id} | Jármű részletes adatai (katalógus adatokkal együtt). Jogosultság ellenőrzés (tulajdonos/szervezet). | Asset + AssetCatalog |
| GET | /assets/{asset_id}/financial-summary | Pénzügyi riport - kategóriákra bontott összesítés (Local/EUR). | AssetCost |
| GET | /assets/{asset_id}/costs | Tételes költséglista lapozással. | AssetCost |
| GET | /assets/{asset_id}/maintenance | Szerviznapló - karbantartási költségek listája. | AssetCost - cost_category='maintenance' |
| POST | /assets/{asset_id}/maintenance | Szervizbejegyzés hozzáadása (date, odometer, description, cost). Létrehoz AssetEvent-et is. | AssetCost + AssetEvent |

### 1.2 `/catalog` prefix - Jármű Katalógus

**Router:** `backend/app/api/v1/endpoints/catalog.py`

| Metódus | Végpont | Cél | Adatbázis kapcsolat |
|---------|---------|-----|---------------------|
| GET | /catalog/makes | Márkák listázása (opcionálisan vehicle_class szerint szűrve). | AssetCatalog |
| GET | /catalog/models | Típusok listázása adott márkához. | AssetCatalog |
| GET | /catalog/generations | Generációk/Évjáratok adott márka+típushoz. | AssetCatalog |
| GET | /catalog/engines | Motorváltozatok és technikai specifikációk (ID, engine_code, fuel_type, factory_data). | AssetCatalog |

### 1.3 `/vehicles` prefix - Jármű Értékelések

**Router:** `backend/app/api/v1/endpoints/vehicles.py`

| Metódus | Végpont | Cél | Adatbázis kapcsolat |
|---------|---------|-----|---------------------|
| POST | /vehicles/{vehicle_id}/ratings | Jármű értékelése 4 dimenzióban (driving_experience, reliability, comfort, consumption_satisfaction 1-10). Egy user csak egyszer értékelhet. | VehicleUserRating |
| GET | /vehicles/{vehicle_id}/ratings | Értékelések lekérése adott járműhöz. | VehicleUserRating |

### 1.4 `/expenses` prefix - Flotta Költségek (TCO)

**Router:** `backend/app/api/v1/endpoints/expenses.py`

| Metódus | Végpont | Cél | Adatbázis kapcsolat |
|---------|---------|-----|---------------------|
| POST | /expenses/ | Költség rögzítése (üzemanyag, szerviz, adó, biztosítás). Dynamic Gatekeeper: draft jármű limit ellenőrzés. | AssetCost + SystemParameter |

### 1.5 `/analytics` prefix - Jármű Analitika

**Router:** `backend/app/api/v1/endpoints/analytics.py`

| Metódus | Végpont | Cél | Adatbázis kapcsolat |
|---------|---------|-----|---------------------|
| GET | /analytics/{vehicle_id}/summary | TCO összesítő járművenként (user costs, lifetime costs, benchmark). | AssetCost, VehicleModelDefinition |
| GET | /analytics/dashboard | Dashboard analitika (mock data - havi költségek, üzemanyag-hatékonyság, cost/km trendek). | Jelenleg mock |

### 1.6 További kapcsolódó végpontok

| Metódus | Végpont | Cél | Router helye |
|---------|---------|-----|-------------|
| POST | /documents/upload/{parent_type}/{parent_id} | Dokumentumfeltöltés járműhöz | documents.py |
| POST | /evidence/scan-registration | OCR regisztrációs dokumentum szkennelés | evidence.py |
| GET | /search/match | Geo-keresés PostGIS segítségével | search.py |
| POST | /services/hunt | Szerviz vadászat indítása | services.py |
| GET | /reports/summary/{vehicle_id} | Jármű összesítő jelentés | reports.py |
| GET | /reports/trends/{vehicle_id} | Jármű trend jelentés | reports.py |

---

## 2. 🗄️ Adatbázis Modell Réteg - Jármű Domain

### 2.1 Core Asset Model - A "Digital Twin"

Az Asset modell (backend/app/models/vehicle/asset.py) a központi entitás:

```
Asset ──┬── AssetCatalog (katalógus kapcsolat)
        ├── AssetFinancials (pénzügyi adatok)
        ├── AssetCost (költségnapló)
        ├── AssetEvent (eseménynapló - Digitális Szervizkönyv)
        ├── VehicleLogbook (útnyilvántartás)
        ├── AssetInspection (ellenőrzési napló)
        ├── AssetReview (értékelések)
        ├── AssetTelemetry (telemetria)
        ├── AssetAssignment (szervezeti hozzárendelés)
        ├── VehicleOwnership (tulajdonosváltás)
        └── ServiceRequest (szervizkérések)
```

### 2.2 Főbb Modellek Leírása

| Modell | Tábla (séma) | Cél |
|--------|-------------|-----|
| Asset | vehicle.assets | Fizikai eszköz (Digital Twin) - Minden adat itt fut össze |
| AssetCatalog | vehicle.vehicle_catalog | Jármű katalógus mesteradatok |
| VehicleModelDefinition | vehicle.vehicle_model_definitions | Multi-Tier MDM Master - technikai igazságforrás |
| VehicleType | vehicle.vehicle_types | Jármű kategóriák |
| CostCategory | vehicle.cost_categories | Standardizált költségkategória fa |
| AssetCost | vehicle.asset_costs | Üzemeltetési költség (TCO) |
| AssetEvent | vehicle.asset_events | Digitális Szervizkönyv események |
| VehicleOdometerState | vehicle.vehicle_odometer_states | Km óra állapot és becslés |
| VehicleUserRating | vehicle.vehicle_user_ratings | Jármű értékelés 4 dimenzióban |

---

## 3. 🔌 Jelenlegi Frontend Implementáció

### 3.1 Garázs Nézet (DashboardView.vue)

A frontend egy egységes garázs nézetet használ, ahol az összes jármű egy grid-ben jelenik meg:

- Adatforrás: GET /api/v1/assets/vehicles -> vehicleStore.fetchVehicles()
- Megjelenítés: Minden jármű egy kártyán, amely tartalmazza az EU-s rendszámtáblát, márka+modell nevet, gyártási évet, állapot score-t, futott km-t, státusz badge-t
- UI élmény: Zen mód (UI elrejtése), 3D téreffektusok

### 3.2 Hiányzó Frontend Funkciók

A backend által biztosított API-k közül a frontend CSAK a járműlista lekérést használja. Az alábbi funkciók NINCSENEK implementálva:

- Jármű hozzáadása (POST /assets/vehicles)
- Jármű részletes adatlapja (GET /assets/{id})
- Költségnapló megjelenítése/rögzítése
- Szerviznapló (karbantartási rekordok)
- Katalógus böngésző (márka -> modell -> generáció -> motor)
- TCO analitika és dashboard
- Jármű értékelés
- Dokumentumfeltöltés
- Útnyilvántartás (logbook)

---

## 4. 🎯 Frontend Csoportosítási Javaslat

### 4.1 Javasolt Menü Szerkezet

Az alábbi csoportosítás a DDD (Domain-Driven Design) elveket követi, és a felhasználói élményt (UX) helyezi előtérbe:

```
GARÁZS (fő nézet)
│
├── 🔧 JÁRMŰVEK
│   ├── Garázs áttekintés         <- Jelenlegi DashboardView
│   ├── Jármű hozzáadása          <- POST /assets/vehicles
│   ├── Katalógus böngésző        <- GET /catalog/makes -> models -> engines
│   └── Jármű részletek           <- GET /assets/{id}
│
├── 📊 PÉNZÜGYEK & TCO
│   ├── Költségnapló               <- GET /assets/{id}/costs, POST /expenses
│   ├── Pénzügyi riport            <- GET /assets/{id}/financial-summary
│   ├── TCO Analitika              <- GET /analytics/{id}/summary
│   └── Dashboard analitika        <- GET /analytics/dashboard
│
├── 🔧 KARBANTARTÁS
│   ├── Szerviznapló               <- GET /assets/{id}/maintenance
│   ├── Új szerviz bejegyzés       <- POST /assets/{id}/maintenance
│   ├── Eseménynapló               <- AssetEvent adatok
│   └── Km óra állapot             <- GET /admin/odometer/{id}
│
├── 📄 DOKUMENTUMOK
│   ├── Feltöltés                  <- POST /documents/upload/vehicle/{id}
│   └── OCR szkennelés             <- POST /evidence/scan-registration
│
└── ⭐ KÖZÖSSÉG
    ├── Értékelés                  <- POST /vehicles/{id}/ratings
    └── Vélemények                 <- GET /vehicles/{id}/ratings
```

### 4.2 Javasolt Vue Router Struktúra

```
/dashboard                          Garázs áttekintés (DashboardView)
/vehicles/add                       Jármű hozzáadása
/vehicles/catalog                   Katalógus böngésző
/vehicles/{id}                      Jármű részletes nézet
/vehicles/{id}/costs                Költségek
/vehicles/{id}/maintenance          Szerviznapló
/vehicles/{id}/analytics            TCO Analitika
/vehicles/{id}/documents            Dokumentumok
/vehicles/{id}/ratings              Értékelések
```

### 4.3 Javasolt Store Bővítés

A jelenlegi vehicleStore bővítendő az alábbiakkal:

```
ÚJ state-ek:
  - selectedVehicle         Aktuálisan kiválasztott jármű
  - vehicleCosts            Költségnapló tételek
  - maintenanceRecords      Szerviz rekordok
  - financialSummary        Pénzügyi összesítő

ÚJ katalógus state-ek:
  - catalogMakes            Márkák listája
  - catalogModels           Modellek listája
  - catalogGenerations      Generációk listája
  - catalogEngines          Motorváltozatok listája

ÚJ action-ök:
  - fetchVehicleDetail(id)
  - createVehicle(payload)
  - fetchCosts(assetId)
  - createExpense(payload)
  - fetchMaintenance(assetId)
  - fetchFinancialSummary(assetId)
  - fetchAnalytics(assetId)
  - fetchMakes(vehicleClass?)
  - fetchModels(make)
  - fetchGenerations(make, model)
  - fetchEngines(make, model, gen)
```

### 4.4 UX/UI Javaslatok

1. **Garázs Szűrők:** A járművek szűrhetők legyenek járműosztály (personal, motorcycle, commercial), státusz (active, draft, maintenance) és márka szerint.

2. **Jármű Kártya Információs Rétegek:**
   - 1. réteg (alap): Rendszám, márka, modell, státusz - látszik a grid-ben
   - 2. réteg (hover): Gyors infók (km, állapot, utolsó szerviz)
   - 3. réteg (kattintás): Teljes részletes nézet

3. **TCO Dashboard:** A garázs nézet tetején egy összesítő sáv (teljes flotta km, havi költség, átlagos állapot). Minden járműkártyán egy "TCO" gomb.

4. **Katalógus Böngésző:** Lépcsőzetes dropdown-ok (márka -> modell -> generáció -> motor). Gyors hozzáadás: "Add this to my garage" gomb.

---

## 5. 📝 Összefoglalás

A backend rendelkezésre álló API végpontok lefedik a járműkezelés teljes életciklusát:

| Fázis | API Végpontok | Állapot |
|-------|--------------|---------|
| Felfedezés (Katalógus) | /catalog/makes, /catalog/models, /catalog/generations, /catalog/engines | Backend kész |
| Létrehozás | POST /assets/vehicles | Backend kész |
| Megtekintés (Garázs) | GET /assets/vehicles, GET /assets/{id} | Backend kész, Frontend részleges |
| Költségkövetés (TCO) | POST /expenses/, GET /assets/{id}/costs, GET /assets/{id}/financial-summary | Backend kész, Frontend hiányzik |
| Karbantartás | GET/POST /assets/{id}/maintenance | Backend kész, Frontend hiányzik |
| Analitika | GET /analytics/{id}/summary, GET /analytics/dashboard | Backend kész (részben mock), Frontend hiányzik |
| Értékelés | GET/POST /vehicles/{id}/ratings | Backend kész, Frontend hiányzik |
| Dokumentumok | POST /documents/upload/{parent_type}/{parent_id} | Backend kész, Frontend hiányzik |

**Következtetés:** A backend erős alapokon áll a járműkezeléshez. A frontenden a garázs nézet (DashboardView) csak a járművek listázását valósítja meg. A javasolt csoportosítás (Járművek -> Pénzügyek -> Karbantartás -> Dokumentumok -> Közösség) egy logikus, felhasználó-központú navigációs struktúrát adna a teljes jármű életciklus kezeléséhez.