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

```markdown
# 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.)*

## 4.0 Catalog 2022+ Strategy (Hybrid Mode)
A CarQueryAPI korlátai miatt 2022 utáni modelleknél a Robot 1 az alábbi hibrid logikát alkalmazza:
1. **API Ninjas & Auto-Data Sync:** Elsődleges technikai forrás.
2. **European Scraper Mode:** A mobile.de és autoscout24.hu portálok típusválasztóinak (meta-adatok) aratása a legfrissebb modellek és motorváltozatok rögzítéséhez.

## 6. Szerviz Logika és Intervallumok
A szervizkönyv nem csak eseménynapló, hanem előrejelző rendszer.

### 6.1 Karbantartási Terv (Maintenance Plan)
Az MDM-ben rögzített `specifications` tartalmazza a fődarabok szervizigényét:
- **Folyadékok:** Típus, mennyiség, csereperiódus (km/hónap).
- **Alkatrészek:** Gyári kódok és alternatívák (cross-reference).
- **Biztonság:** Időszakos vizsgák (érintésvédelem, emelőhátfal, hajó szemle).