belépés jó, rgisztráción kicsit faragni kell még

2026-06-05 14:45:02 +00:00
parent f03b5f3916
commit b84b1bab41
7 changed files with 570 additions and 42 deletions
--- a/docs/vehicle_api_frontend_architecture.md
+++ b/docs/vehicle_api_frontend_architecture.md
@@ -0,0 +1,251 @@
+# 🚗 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.