service-finder/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md

🏎️ 18_ASSET_AND_FLEET_SPECIFICATION (v1.2)

Ez a dokumentum írja le a rendszer magját képező "széf" logikát, ahol minden közlekedési eszköz (Asset) egyedi életutat és digitális lenyomatot kap.

1. Az Alapelv: "Mindenki Flottatulajdonos"

A rendszerben a technikai réteg nem tesz különbséget magánszemély és cég között.

• Privát Flotta: A regisztráció során automatikusan létrejövő szervezet (Organization).
• Széf (Safe Deposit): A flotta izolált része, ahol az eszközök (járművek) és azok bizalmas okmányai (Vault) találhatók.

---

2. Eszköz Típusok és Univerzális Azonosítók (UAI)

Minden eszköz rendelkezik egy Univerzális Állandó Azonosítóval (UAI), amely az életútja során soha nem változik.

Kategória	Elsődleges Azonosító (UAI)	Speciális Adatpontok
Közúti (Car, Bike, Bus)	VIN (Alvázszám)	Rendszám, Motorkód, Sebességváltó kód
Vízi (Boat, Yacht)	HIN (Hull ID)	MMSI kód, IMO szám, Hajó neve
Légi (Aircraft)	Serial Number	Lajstromjel (Registration), Típusjelzés
Heavy Duty / Agri	Egyedi sorozatszám	Üzemóra, Teljesítmény, Kanál/Vágóasztal típus
Micro-mobility	Vázszám / UUID	Akkumulátor ciklus, Hatótáv

Kiegészítő mérőszámok:

• Futásteljesítmény (Odometer): Közúti járműveknél (km/mérföld).
• Üzemóra (Operating Hours): Hajók, repülők és munkagépek esetén az elsődleges szervizintervallum-mérő.
• VIN Validáció: Közúti járműveknél kötelező a VIN Checksum (MOD 11) ellenőrzése rögzítéskor.

---

3. A Jármű DNS (Deep Data Structure)

A rendszer két rétegben kezeli a jármű adatait a teljes életút követéséhez.

3.1. Gyári Konfiguráció (Factory Specs)

• Trim Level: Felszereltségi szint (pl. AMG Pack, S-Line).
• Technikai paraméterek: Motorvariációk, kW/LE, nyomaték, gyári felni/gumi méretek (ET számmal), folyadékmennyiségek.
• Szervizintervallumok: Gyártói előírások (idő vagy távolság alapú).

3.2. Aktuális Állapot és Módosítások

• Status Quo: Gyári extrák, utólagos módosítások (Aftermarket - pl. vonóhorog, gázszett) és hiányzó gyári elemek követése.

---

4. Digitális Szervizkönyv és Minősítés

4.1. Eseményalapú Idővonal (Timeline)

Minden bejegyzés megváltoztathatatlan (immutable) logként rögzül:

• Típusok: Karbantartás, Javítás, Műszaki Vizsga, Baleset, Tulajdonosváltás.
• Csatolmányok: Alkatrész fotók, számlák (OCR), munkalapok.

4.2. Kettős Értékelési Rendszer

1. AI Health Score (Technikai): Algoritmus alapú pontszám a szerviztörténet és a gyári előírások betartása alapján.
2. Driver Rating (Emocionális): Szubjektív sofőrértékelés (Komfort, Vezetési élmény, Praktikum).

---

5. Multi-Robot Harvester Architektúra

A katalógus feltöltéséért és frissítéséért kategória-specifikus robotok felelnek (BaseHarvester alapokon).

5.1. Robot Típusok:

• Autó / Motor Robot: Közúti adatokra.
• Heavy Duty / Agri Robot: Teherautókra és munkagépekre.
• Specialty Robot: Vízi és légi azonosítókra (MMSI, Lajstrom).

5.2. Adatgyűjtési Szintek:

• Initial Load: A top 1000 európai típus alapfeltöltése.
• On-Demand Fetch: Felhasználói "Trigger" hatására indított soron kívüli mélykeresés (Deep Web Scrape).
• Verification Status: verified (teljes), incomplete (részleges), pending (ellenőrzésre vár).

---

6. OCR és Dokumentum Validációs Stratégia

A dokumentumfelismerés (OCR) hibrid technológiát és Tier-alapú prioritást alkalmaz.

6.1. Feldolgozási Sorrend (Failover Logic)

1. Tier 1 (External Cloud): Google Vision / Azure Form Recognizer (ingyenes keret erejéig).
2. Tier 2 (Saját Fallback): Helyi szerveren futó PaddleOCR modul.

6.2. Üzleti Logika és Monetizáció

• VIP+ / Premium+: Azonnali (Real-time) OCR feldolgozás (3-5 másodperc).
• Lite: Háttérfolyamat (sorban állás), korlátozott havi kvóta (pl. 1 scan/hó).
• Kreditalapú túllépés: A kvóta feletti beolvasások a Wallet-ből levont kreditért vásárolhatók meg.

---

7. Infrastruktúra és Adatkezelés

7.1. Dokumentum Tárolás (NAS)

• Elérési út: /mnt/nas/app_data/assets/{asset_id}/
• Típusok:
  • Vault (Tartós): Kritikus okmányok (Forgalmi, Adásvételi) hash-elt fájlnévvel.
  • Ephemeral (Ideiglenes): Napi bizonylatok (Parkolójegy), melyek OCR után 90 nappal törlődnek.
• Képoptimalizálás: Automata átméretezés (max 1600px) és WebP konverzió (~80-90% megtakarítás).

7.2. Címkezelési Protokoll (v2.0)

Minden címet (székhely, tulajdonos, szerviz) atomizált formában tárolunk a pontos riportáláshoz:

• Irányítószám, Település, Közterület neve, Közterület jellege (utca, út stb.), Házszám (emelet/ajtó kiegészítéssel).

---

8. Kivételkezelés: Ismeretlen Járművek

Ha az eszköz nem szerepel a katalógusban:

1. Custom Asset: Manuális rögzítés kötelező dokumentum-fotóval.
2. AI Verifikáció: OCR-rel összeveti a fotót a bevitt adatokkal.
3. "Unverified Model" jelzés: Amíg a Robot vagy egy Admin meg nem erősíti az adatok hitelességét.

3. Document Engine & Optimization

• Processing: Feltöltéskor automatikus méretoptimalizálás (max 1600px) és WebP konverzió.
• Thumbnails: Minden képből 300px széles WebP előnézet generálódik a gyors UI eléréshez.
• Supported Formats: JPG, PNG, WEBP (képek); PDF, DOCX (dokumentumok).
• OCR Integration: Számlák és munkalapok esetén automata adatkinyerés (alkatrészek, árak, kilométeróra állás).

7.4 Dokumentum Életciklus és Pufferelés (v2.2)

A rendszer háromlépcsős tárolási és feldolgozási logikát alkalmaz az optimális hálózati és szerver-teljesítmény érdekében:

1. Ingestion (TEMP - Helyi SSD): - Minden feltöltött állomány a /app/temp/uploads/ mappába érkezik.

   • Itt történik az AI/OCR elemzés és a képoptimalizálás (Pillow).
   • A nyers forrásfájl a feldolgozás után 30 percig marad itt (puffer), hogy a felhasználó azonnal visszanézhesse, mielőtt a NAS-ra kerül.

2. Presentation (THUMBNAIL - Helyi SSD):

   • A Pillow által generált 300px széles WebP miniképek a szerver lokális /app/static/previews/ könyvtárába kerülnek.
   • A UI (web/app) kizárólag ezeket tölti be a listázáskor, elkerülve a NAS terhelését.

3. Vault (NAS - Hosszú távú tároló):

   • A feldolgozott, nagyfelbontású (max 1600px) WebP állomány átkerül a NAS-ra: /mnt/nas/app_data/organizations/{id}/vault/.
   • A NAS-hoz csak akkor fordul a rendszer, ha a felhasználó kifejezetten a dokumentum nagy változatát kéri.

   5. Discovery Bot Strategy

5.1 Prioritási Sorrend

A Botok az alábbi sorrendben pásztázzák az adatforrásokat:

1. Land (Földi járművek):
   • Személyautók (Car), Motorok (Bike), Teherautók (Truck).
   • Adatforrás: Márkakereskedői listák, Gyártói API-k.
2. Infrastructure (Infrastruktúra):
   • Benzinkutak, Elektromos töltők (OpenChargeMap API).
   • Ezek könnyen elérhető, statikus adatok.
3. Services (Szervizek):
   • Google Maps API, Cégjegyzék adatok.
   • Ezeket jelöli meg a rendszer "Unverified" (Bot-talált) státusszal.

5.2 Adatgazdagítás

A Bot nem csak a nevet keresi. Célzottan gyűjti:

• Nyitvatartási idők.
• Kapcsolattartói adatok (Email, Weboldal).
• Közösségi média linkek.
• Szabály: A Bot által hozott adat felülírható a "Service Hunt" során a felhasználó által (magasabb megbízhatóság).

6. Multi-Source Consensus Logic

A szervizek és szolgáltatók hitelességét nem csak az Admin, hanem a források száma határozza meg.

6.1 Bizalmi szintek (Confidence Score)

• Score 1: Egyetlen forrás (Bot vagy User). Státusz: pending.
• Score 2: Két független forrás megerősítése.
• Score 3+: Automatikus hitelesítés (verified). Nincs szükség emberi beavatkozásra.

6.2 Bot Adatforrások (Priority: Car & Bike)

A Botok az alábbi sorrendben dolgoznak:

1. Hivatalos gyártói oldalak (Márkaszervizek).
2. Szakmai adatbázisok (pl. Autóklub, Kamarák).
3. Google/Social media API-k.

4. Telephelyek (Locations) és Szervizpontok

Minden szolgáltató (Organization) több telephelyet tarthat fenn.

4.1 Kötelező Adatstruktúra

Minden telephely rögzítésekor az alábbi bontott címadatok kötelezőek:

• Irányítószám, Város, Közterület neve, Közterület típusa, Házszám.
• Opcionális: Helyrajzi szám (parcel_id) külterületi vagy HRSZ alapú azonosításhoz.

4.2 Validációs Folyamat

A rögzített címek automatikusan bekerülnek a Master Geo adatbázisba, építve a rendszer globális címjegyzékét.

5. Járművek és Költségek (MVP)

A járműadatok kezelése hibrid módon történik.

5.1 Jármű Katalógus

• A rendszer egy központi katalógust (asset_catalog) épít.
• Új rögzítéskor a rendszer először a katalógusból kínál fel opciókat (Dropdown).
• Ha a modell nem létezik, a rendszer automatikusan felveszi (Self-learning catalog).

5.2 Költségkövetés (TCO)

• Minden Asset-hez rögzíthető költség (asset_costs).
• Kötelező adatok: Kategória, Összeg, Dátum.
• Opcionális: Km óra állása (az amortizáció és szervizintervallum számításához).

2026.02.10 FRISSÍTÉS - ATOMIZÁLT ADATMODELL ÉS MODULÁRIS API

1. Adatbázis Szerkezet (A 4 Pillér)

A járművek kezelése "Single Responsibility" elv alapján 4 modulra bomlott:

1. Identity (Asset): Alapadatok (VIN, Rendszám, Tulajdonos).
2. Catalog (AssetCatalog): Gyári statikus adatok (Típus, Motor, Akku). Ezt a Robotok töltik.
3. Telemetry (AssetTelemetry): Változó állapot (KM óra, VQI minőség index, DBS vezetési stílus).
4. Financials (AssetCost): Pénzügyi tranzakciók 9 kategóriába sorolva (Fuel, Service, Tax, stb.).

2. Moduláris API Végpontok

A teljesítmény optimalizálása érdekében a `Full Profile` helyett 3 dedikált végpontot használunk:

• `GET /api/v1/assets/{id}`: Csak identitás és katalógus (Gyors nézet).
• `GET /api/v1/assets/{id}/costs`: Csak pénzügyi történet és grafikonok.
• `GET /api/v1/assets/{id}/telemetry`: Csak élő adatok (Dashboard).

A javított AssetAssignment logika dokumentálása.

# 18. Asset & Fleet Management Specification

## 18.2. Asset Assignment Logic
A járművek és eszközök hozzárendelése a rendszer egyik legkritikusabb része.

### 18.2.1. Assignment Model (`AssetAssignment`)
Kapcsolatot teremt egy Jármű (`Asset`) és egy Szervezet (`Organization`) között.
- **asset_id**: UUID (Melyik jármű?)
- **organization_id**: Integer (Melyik cég használja?)
- **status**: Active / Released
- **Validáció:** Egy jármű egyszerre csak egy szervezetnél lehet `active` státuszban.

*(Megjegyzés: A v1.2.5 frissítés javította az ORM kapcsolatokat, így a lekérdezések most már közvetlenül elérik az `assignment.organization` objektumot.)*