kincses/service-finder
1
0
Fork 0
Code Issues 52 Pull Requests Packages Projects 2 Releases Wiki Activity
Files
71ef33bb8508b4e89707c6ef3f19279dcbbc3fe1
service-finder/docs/vehicle_api_frontend_architecture.md

12 KiB
Raw Blame History

🚗 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
      1. réteg (hover): Gyors infók (km, állapot, utolsó szerviz)
      1. 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.

Reference in New Issue View Git Blame Copy Permalink