# 🏎️ 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).