🦒 ZsIRAF AIto felcser v1.0 – Műszaki Dokumentáció

1. Bevezetés

1.1 Célkitűzés

A ZsIRAF AIto felcser v1.0 egy webes alkalmazás, amelynek célja, hogy a felhasználók (autótulajdonosok és hobbiszerelők) számára gyors, AI-alapú elődiagnosztikát nyújtson. A szoftver a bevitt hibakódok (DTC) és tünetek alapján, a Google Gemini nyelvi modelljét használva azonosítja a lehetséges hibaokokat és javítási javaslatokat tesz.

1.2 Működési elv

Az alkalmazás kliensoldali (böngészőben futó) JavaScript kódot használ. Nincs saját backend szervere; közvetlenül kommunikál a Google Cloud API-val. A felhasználó megadja az adatokat, a szkript összeállít egy speciális utasítást (prompt), elküldi az AI-nak, majd a visszaérkező JSON adatokat felhasználóbarát formában megjeleníti.

2. Technikai Specifikáció

2.1 Technológiai Stack

Frontend: HTML5, CSS3 (Modern, reszponzív design), Vanilla JavaScript (ES6+).
Backend: Nincs (Serverless architektúra).
AI Szolgáltató: Google Gemini API.
AI Modell: gemini-1.5-flash (vagy fallback esetén gemini-pro).
Ikonkészlet: FontAwesome (CDN-ről betöltve).
Betűtípus: Google Fonts 'Inter' (CDN-ről betöltve).

2.2 Fájlstruktúra

A szoftver "Single File Application" (SPA) jellegű, azaz egyetlen .html fájl tartalmazza a struktúrát, a stíluslapokat és a logikát is.

index.html: A teljes alkalmazás kódja.

3. Funkcionális Leírás

3.1 Felhasználói Adatbevitel

A felület a következő bemeneti mezőket tartalmazza:

Hibakód (DTC): (pl. P0420) - Az OBD-II olvasó által adott kód.
Jármű adatok: Márka, Modell, Típus, Évjárat/Motorkód.
Élő adatok (Freeze Frame): Opcionális mező diagnosztikai értékeknek (pl. LTFT, RPM).
Tünetek: Szabadszavas leírás (pl. "rángat hidegen").
Szűrő (Threshold): Csúszka/Legördülő, amellyel beállítható, hány forrás megerősítése szükséges a "biztos" találathoz.

3.2 API Kulcs Kezelés

A felhasználónak saját Google Gemini API kulcsot kell megadnia.
Tárolás: A kulcs a böngésző localStorage-ébe kerül (gemini_api_key néven). Ez biztonsági szempontból előnyös, mert a kulcs sosem hagyja el a felhasználó gépét (kivéve a Google felé irányuló kérést).
Validáció: A rendszer ellenőrzi a kulcs meglétét, és figyelmeztet, ha hiányzik.

3.3 AI Kommunikáció (Prompt Engineering)

A szoftver lelke a runAnalysis függvény. Ez állítja össze a promptot:

Szerep (Role): "Senior Automotive Technician AI".
Feladat (Task): Diagnosztika készítése a bemeneti adatok alapján.
Kimeneti Formátum: Szigorú JSON struktúra (hogy a program fel tudja dolgozni).
- dtc: Hibakód.
- inferred_vehicle: Felismert járműtípus.
- issues: Hibaokok listája (név, leírás, forrásszám).
- checks: Ellenőrzési lépések.
- summary_hu: Magyar nyelvű összefoglaló.
- sources: Felhasznált forrástípusok.

3.4 Hiba- és Kivételkezelés (Robust API Call)

A v4.x verziókban bevezetett "Brute Force" logika biztosítja a stabilitást:

A rendszer egy listát (ENDPOINTS) tartalmaz a lehetséges modellekről és API verziókról (v1beta/gemini-1.5-flash, v1/gemini-pro, stb.).
Ciklikusan megpróbál csatlakozni az elsőhöz. Ha 404-es vagy egyéb hálózati hibát kap, automatikusan próbálja a következőt.
Ha minden próbálkozás sikertelen, részletes hibaüzenetet ad a felhasználónak (pl. "Nincs engedélyezve az API a konzolon").

3.5 Megjelenítés

A válasz JSON-t a render függvény dolgozza fel.
Színkódolás:
- Zöld: Erős találat (magas forrásszám).
- Narancs: Gyengébb/ritkább lehetőség.
Statisztika: Mini dashboard mutatja a találatok számát és a max. bizalmi szintet.
Chat: Az elemzés után megjelenő chat ablak lehetővé teszi a további kérdezést (kontextus megőrzésével).

3.6 PDF Export

A genPdf függvény egy új böngészőablakot nyit.
Dinamikusan generál egy nyomtatóbarát HTML struktúrát a diagnózisból.
Automatikusan meghívja a window.print() metódust.
A fájlnév formátuma: zsirafaitofelcser_[AUTO]_[DATUM].pdf.

4. Felhasználói Felület (UI/UX) Design

4.1 Stílusirányzat

Glassmorphism: Átlátszó, homályosított (blur) panelek sötét háttér előtt.
Cyberpunk/Tech: Neon kék és lila kiemelő színek, futurisztikus betűtípus (Inter).
Animációk:
- Háttér: HTML5 Canvas részecskehálózat (mozgó pontok és vonalak).
- Scanner: Elemzés közben futó fénycsík.
- Gombok: "Shimmer" (csillogás) effekt.

4.2 Reszponzivitás

A CSS Grid és Flexbox használatával az elrendezés automatikusan igazodik mobil, tablet és asztali képernyőkhöz.

5. Biztonsági és Adatvédelmi Szempontok

Adatkezelés: A szoftver nem gyűjt adatokat. Minden bevitt adat (autó típusa, hibakód) csak a Google szervereire kerül elküldésre az elemzés idejére.
API Kulcs: A kulcs a felhasználó böngészőjében tárolódik. A fejlesztő nem látja, nem fér hozzá.
Felelősségkizárás: Az alkalmazás minden elemzés végén és a PDF-ben is megjelenít egy jogi nyilatkozatot, miszerint az eredmények csak tájékoztató jellegűek, és nem helyettesítik a szakembert.

v1.0