kincses/service-finder
1
0
Fork 0
Code Issues 7 Pull Requests Packages Projects 2 Releases Wiki Activity

FEAT: Integrated Document Engine with WebP optimization, Thumbnail generation and Hybrid (NAS/SSD) storage logic

Browse Source
This commit is contained in:
Kincses
2026-02-07 22:16:03 +00:00
parent e370ca3021
commit 4e14d57bf6
20 changed files with 657 additions and 607 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md
View File

@@ -1,206 +1,130 @@
# 🏎️ Asset és Flotta Specifikáció: A Járművek DNS-e
# 🏎️ 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 nincs különbség egy magánszemély és egy cég között a technikai rétegben.
- **Privát Flotta:** A regisztráció (Step 2) során automatikusan létrejövő szervezet (Organization).
- **Széf (Safe Deposit):** A flotta része, ahol az eszközök (járművek) és azok bizalmas okmányai laknak.
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 Speciális Azonosítók
Minden eszköz rendelkezik egy **Univerzális Állandó Azonosítóval (UAI)**, ami az életútja során soha nem változik.
---
| Típus | Elsődleges Azonosító (UAI) | Speciális Adatpontok |
## 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** | VIN (Alvázszám) | Rendszám, Motorkód, Sebességváltó kód |
| **Vízi** | HIN (Hull ID / Testszám) | MMSI kód, IMO szám, Név |
| **Légi** | Serial Number (Gyári szám) | Lajstromjel (Registration), Típusjelzés |
| **Egyéb** | Egyedi sorozatszám | Gyártó, Teljesítmény |
| **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, munkagépek és versenytechnika esetén kritikus.
- **Ü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)
Az adatbázisnak ismernie kell a járművet "gyári" állapotában és annak minden módosítását.
A rendszer két rétegben kezeli a jármű adatait a teljes életút követéséhez.
### A) Gyári Konfiguráció (Factory Specs)
- **Trim Level:** Felszereltségi csomag (pl. S-Line, AMG Pack, Comfortline).
- **Technikai paraméterek:** Motorválaszték, kW/LE, nyomaték, gyári felni- és gumiméret (ET számmal), folyadékmennyiségek.
- **Szervizintervallumok:** Gyártó által előírt periodikus karbantartások (idő vagy távolság alapú).
### 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ú).
### B) Aktuális Állapot és Módosítások (Modifications)
- **Gyári extrák:** Mi az, ami benne maradt? (pl. bőrbelső, napfénytető).
- **Utólagos (Aftermarket):** Mi került bele? (pl. vonóhorog, gázszett).
- **Hiányzó:** Mi került ki belőle? (pl. kiszerelt gyári hifi).
### 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 (Digital Service Book)
Nem csak egy lista, hanem egy **Eseményalapú Idővonal (Timeline)**. Minden bejegyzés megváltoztathatatlan (immutable-szerű) logként rögzül.
---
## 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:** Fotók az alkatrészekről, számlák PDF-ben, munkalapok.
- **Csatolmányok:** Alkatrész fotók, számlák (OCR), munkalapok.
## 5. Jármű Minősítés és Értékelés
A jármű két különálló, de egymást kiegészítő minősítést kap:
### 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).
### A) Technikai Minősítés (AI Health Score)
- **Algoritmus alapú:** A szerviztörténet, az üzemóra/futás aránya és a gyári specifikációk betartása alapján kalkulált pontszám.
---
### B) Emocionális és Közösségi Értékelés (Driver Rating)
A járművet használó sofőrök értékelhetik az eszközt szubjektív szempontok alapján:
- **Komfort:** Mennyire kényelmes hosszú távon?
- **Vezetési élmény:** "Lelke van", vagy csak egy gép?
- **Praktikum:** Mennyire használható a mindennapokban?
- **Megbízhatóság érzet:** Mennyire érzi magát benne biztonságban a sofőr?
## 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).
Ez a kettős mérőszám adja meg a jármű valós "piaci és használati értékét".
### 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).
## 6. Az Adat-Gondnok (Harvester Robot)
A rendszer integritásáért és az adatok pontosságáért egy automata Robot felel.
### 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).
### Funkciók:
1. **Initial Load:** A legnépszerűbb 1000 európai járműtípus alapértelmezett feltöltése.
2. **On-Demand Fetch:** Ha egy felhasználó ismeretlen típust keres, a Robot prioritással kutatja fel és rögzíti azt.
3. **Deep Data Scrape:** A Robot nemcsak a típust, hanem a gyári specifikációkat (olajmennyiség, guminyomás, szervizintervallum) is gyűjti.
4. **Maintenance:** Negyedévente frissíti a meglévő adatokat (új modellévek, módosított gyári előírások).
### Adatforrások hierarchiája:
1. Hivatalos gyártói API-k (ahol elérhető).
2. Nyilvános műszaki adatbázisok (Auto-Data, UltimateSpecs).
3. VIN/HIN dekóder algoritmusok.
## 7. Kivételkezelés: Ismeretlen és Egyedi Járművek
---
Ha egy jármű nem található a globális katalógusban, a rendszer kétlépcsős mentőövet nyújt:
## 6. OCR és Dokumentum Validációs Stratégia
A dokumentumfelismerés (OCR) hibrid technológiát és Tier-alapú prioritást alkalmaz.
### A) On-Demand Harvester (Robot hívása)
1. A felhasználó jelzi, hogy hiányzik a típus.
2. A Robot utasítást kap egy mélyebb keresésre (Deep Web Search).
3. Ha találat van, a Robot rögzíti a katalógusba, és a felhasználó folytathatja a rögzítést.
### 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.
### B) Custom Asset (Egyedi/Sport jármű rögzítése)
Ha a jármű sehol nem szerepel (pl. épített versenyautó, egyedi yacht):
1. **Manuális nyilatkozat:** A felhasználó rögzíti az adatokat.
2. **Dokumentum alapú validáció:** A forgalmi engedély vagy sportigazolvány fotóját kötelező feltölteni.
3. **AI Verifikáció:** A rendszer OCR-rel (szövegfelismerés) kiolvassa az adatokat a fotóról, és összeveti a manuális bevitelével.
4. **"Unverified Model" jelzés:** A katalógusban egyedi azonosítót kap, amíg egy admin vagy a Robot más forrásból meg nem erősíti.
### 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.
## 8. Multi-Robot Harvester Architektúra
A rendszer kategóriánként különálló kutató robotokat használ az erőforrások optimalizálása és az adatok pontossága érdekében.
### A) Működési elv
- **Ütemezett futás:** Minden kategória (Autó, Motor, Teher, Hajó) saját időablakban frissít, elkerülve a szerver túlterhelését.
- **Hiányos adatok kezelése:** A Robot köteles rögzíteni a járművet akkor is, ha csak részleges információt talál (pl. csak márka és típus).
- **Státusz jelölések (`verification_status`):**
- `verified`: Teljes DNS adatsor (Robot által hitelesítve).
- `incomplete`: Alapadatok megvannak, de hiányoznak technikai részletek (pl. guminyomás, olaj).
- `pending`: Felhasználó által felvett, Robot általi ellenőrzésre váró egyedi típus.
---
### B) On-Demand prioritás
Amikor a felhasználó olyan típust keres, ami nem szerepel a katalógusban, a rendszer egy "Priority Trigger"-t küld az adott kategória Robotjának, amely soron kívül megkezdi a célzott adatgyűjtést.
## 9. OCR és Dokumentum Validációs Stratégia
A rendszer a járműokmányok (forgalmi engedély, hajólevél, lajstrom) feldolgozására hibrid OCR (Optical Character Recognition) technológiát alkalmaz.
### A) Hibrid Feldolgozási Sorrend (Failover Logic)
A költséghatékonyság és a pontosság érdekében a rendszer az alábbi sorrendben próbálkozik:
1. **Tier 1 (External Free/Limited APIs):** Ingyenes keretű felhő szolgáltatások (pl. Google Vision API, Azure Form Recognizer). A rendszer figyeli a havi limiteket, és azok elérésekor automatikusan vált a következő szolgáltatóra.
2. **Tier 2 (Saját Erőforrás - Fallback):** Ha minden ingyenes külső keret elfogyott, a rendszer a saját szerveren futó PaddleOCR (AI alapú) modult használja.
### B) Monetizáció és Jogosultságok
A dokumentum alapú automata rögzítés és validáció prémium funkció:
- **Free/Lite:** Manuális rögzítés (limitált mezők).
- **VIP:** Automata rögzítés (OCR) 1-2 eszközre.
- **VIP + / Premium +:** Korlátlan okmányfelismerés, automata lejárati figyelmeztetések és hivatalos adat-összevetés.
## 10. Multi-Robot Harvester (Moduláris Felépítés)
A járműkatalógus feltöltését egy bázis-osztályra (`BaseHarvester`) épülő, kategória-specifikus robotcsalád végzi.
- **Autó Robot:** Közúti gépjárművekre optimalizálva.
- **Motor Robot:** Kétkerekű és hobbi járművekre.
- **Heavy Duty Robot:** Teherautók, kamionok és munkagépek specifikációira.
- **Specialty Robot:** Vízi és légi járművek egyedi azonosítóihoz (MMSI, Lajstrom).
# 🏎️ Asset és Flotta Specifikáció: A Járművek DNS-e (v1.2)
## 7. Kivételkezelés: Ismeretlen és Egyedi Járművek
- **On-Demand Harvester:** Ha a katalógus hiányos, a Robot kérésre (Trigger) indítja a mélykeresést.
- **Custom Asset:** Egyedi/Sport eszközök rögzítése dokumentum alapú validációval.
## 8. Multi-Robot Harvester Architektúra
A rendszer kategória-specifikus (Car, Bike, Truck, Specialty) robotokat használ.
- **Ütemezés:** Éjszakai batch-futás a szerver terhelésének minimalizálására.
- **Státuszok:** `verified` (teljes), `incomplete` (részleges), `pending` (ellenőrzésre vár).
## 9. VIN (Alvázszám) és Validáció
- **Algoritmus:** Minden közúti járműnél kötelező a VIN Checksum (MOD 11) ellenőrzése a beíráskor.
- **Auto-Fill:** Érvényes alvázszám esetén a rendszer felajánlja a gyártói adatok (gyártási év, üzem, motorverzió) automatikus kitöltését.
## 10. Dokumentum Kezelés és Tárolás (NAS)
Minden eszközhöz csatolt dokumentum (forgalmi, fotók, számlák) központi NAS tárolón kerül rögzítésre.
## 7. Infrastruktúra és Adatkezelés
### 7.1. Dokumentum Tárolás (NAS)
- **Elérési út:** `/mnt/nas/app_data/assets/{asset_id}/`
- **Archiválás:** `/mnt/nas/git_vault/` (Adatbázis mentések és konfigurációk).
- **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).
## 11. OCR és Üzleti Logika (Tier-based)
A dokumentumfelismerés (OCR) prioritása a felhasználói csomagtól függ:
- **VIP+ / Premium+:** Azonnali (Real-time) OCR feldolgozás. A felhasználó a feltöltés után 3-5 másodperccel már látja az előtöltött adatokat.
- **Alap csomag:** Háttérfolyamat (Background task). A feldolgozás sorban állítás után történik, a felhasználó értesítést kap a befejezésről.
- **Failover:** Külső API-k (Google/Azure) és saját erőforrás (PaddleOCR) hibrid használata a költségkontroll érdekében.
### 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).
## 12. OCR Monetizáció és Kreditszabályok (Admin Kontroll)
---
A rendszer az OCR alapú adatbeolvasást kvótákhoz és kreditekhez köti.
## 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.
### A) Csomag alapú kvóták (Admin beállítás)
Az Admin felületen csomagonként (Lite, VIP, VIP+) meghatározható egy ingyenes havi dokumentum-beolvasási keret:
- **Lite:** 0-1 scan/hó.
- **VIP:** 10 scan/hó.
- **VIP+:** Korlátlan vagy magas limit (pl. 100).
## 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).
### B) Kreditalapú túllépés
Ha a felhasználó kimerítette a keretét, minden további beolvasás kreditért vásárolható meg.
- **Egységár:** Admin felületről állítható (pl. 1 beolvasás = 10 kredit).
- **Tranzakció:** A rendszer levonja a kreditet a felhasználó `Wallet`-jéből a sikeres OCR feldolgozás után.
## 7.4 Dokumentum Életciklus és Pufferelés (v2.2)
### C) Egyedi engedélyek (Permissions)
Lehetőség van egyedi felhasználóknak vagy flottáknak "OCR_Override" jogot adni, amivel a csomagtól függetlenül ingyenes vagy kedvezményes beolvasást kapnak (pl. tesztelők vagy stratégiai partnerek).
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.
## 13. Kiterjesztett Jármű Kategóriák
A rendszer az alábbi kategóriákat különbözteti meg az életút- és költségkövetéshez:
- **Bus:** Tömegközlekedési és távolsági buszok.
- **Motorhome:** Lakóautók és speciális lakókocsik.
- **Trailer:** Utánfutók, pótkocsik, trélerek.
- **Construction:** Munkagépek (markolók, daruk).
- **Agriculture:** Mezőgazdasági vontatók, kombájnok.
- **Micro-mobility:** E-roller, e-bike flották.
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.
# 18. ASSET ÉS FLOTTA SPECIFIKÁCIÓ (v1.1)
## 1. Dokumentum Tárolási és Feldolgozási Stratégia
A rendszer a tárhelyköltségek optimalizálása és a gyors elérés érdekében hibrid tárolást alkalmaz:
### A) Tárolási típusok
- **Vault (Tartós):** Jogilag kritikus okmányok (Alapító okirat, Forgalmi, Adásvételi).
- Tárolás: NAS, hash-elt fájlnévvel.
- Elérhetőség: Korlátlan ideig, amíg az Asset/Szervezet aktív.
- **Ephemeral (Ideiglenes):** Napi bizonylatok (Parkolási jegy, Tankolási nyugta).
- Folyamat: Feltöltés -> OCR adatkinyerés -> Adatbázis rögzítés -> Kép törlése (90 nap után).
### B) Képoptimalizálási Motor
Minden feltöltött dokumentum (JPG/PNG) automata feldolgozáson esik át:
- Átmretezés: Max 1600px szélesség.
- Formátum konverzió: WebP (veszteségmentes tömörítés).
- Eredmény: ~80-90%-os tárhely megtakarítás olvashatóság vesztése nélkül.
## 2. Címkezelési Protokoll (Atomizált Adatok)
A pontos szűrés és a hivatalos iratok generálása érdekében a címeket az alábbi bontásban tároljuk:
- Irányítószám (IRSZ)
- Település (Város)
- Közterület neve
- Közterület jellege (utca, út, tér, stb. - választható listából)
- Házszám (emelet, ajtó, lépcsőház kiegészítéssel)
Címkezelés (v2.0): Minden magánszemély és szervezet címét atomizált formában tároljuk (IRSZ, Város, Utca, Házszám, HRSZ). Ez alapfeltétele a későbbi flotta-riportoknak és a pontos térképi megjelenítésnek.
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.