d2d.emegrendeles.hu/.junie/guidelines.md

Irányelvek és Konvenciók

Ez a fájl tartalmazza a projekt fejlesztési irányelveit a hatékony és tiszta kód érdekében.

Általános elvek

• Tisztaság (Clean Code): A kódot úgy írd, hogy az emberi olvasó számára is egyértelmű legyen. Használj beszédes változó- és függvényneveket.
• SOLID: Kövesd az objektumorientált programozás elveit.
• DRY (Don't Repeat Yourself): Kerüld a kódismétlést, használj segédfüggvényeket, Trait-eket vagy Service-eket.

Technológiai keretrendszer

• PHP: Legalább 8.2-es verziót használunk. Kötelező a típusok (type hinting) használata mindenütt (függvény paramétereknél és visszatérési értékeknél is).
• Laravel: A legújabb stabil Laravel verziókkal kompatibilis kódírás (L12 supportra való felkészülés).
• Blade: UI fejlesztéshez Laravel Blade sablonmotort használunk.
• Eloquence: Az adatbázis eléréshez és kezeléshez elsődlegesen az Eloquent ORM-et használjuk.

Architektúra és Struktúra

• Controller: A kontrollerek maradjanak vékonyak (thin controllers). Az üzleti logika kerüljön a Service-ekbe.
• Service réteg: Az összetett műveleteket Service osztályokban valósítsd meg (app/Services/ alatt). Használj Dependency Injection-t a Service-ek bevezetéséhez a kontrollerekbe.
• Route: Használj névvel ellátott útvonalakat (named routes).
• Requests: Form Validation-re használd a Laravel FormRequest osztályait a kontrollerek metódusain belül.
• DTO (Data Transfer Objects): Használj DTO-kat vagy Typed Array-eket nagyobb adatszerkezetek továbbításakor (pl. Extra library).

Modellek, Auditálás és Workflow

• Minden fő modellnek a App\Models\BaseAuditable osztályból kell származnia.
• Ez biztosítja a created_by, updated_by és deleted_by mezők automatikus töltését a ModelUserIdAppenderTrait segítségével.
• Használjunk SoftDeletes-t, ahol az adatok megőrzése fontos.
• Enums: Amennyiben egy modell mezőjéhez meghatározott értékkészlet tartozik, kötelező PHP Enum használata és annak beállítása a $casts tömbben.
• Workflow Kezelés: Összetett, több lépésből álló folyamatok (pl. árlista feldolgozás) kezeléséhez PHP Enum-okat használunk:
  • Az Enum definiálja a lépéseket, a címkéket (label()), a végrehajtó Job-okat (jobClass()) és a színeket (color()).
  • A modell workflow_steps JSON mezője tárolja a folyamat állapotát, amit a modell creating eseményében inicializálunk az Enum defaultSteps() metódusával.
  • A Service réteg felelős a státuszok léptetéséért a folyamat során.

Hibrid Frontend Architektúra (Mix & Vite) és a "Clean Cut" elv

A projekt fokozatos modernizáció alatt áll, ezért két párhuzamos build rendszert használunk a "Clean Cut" (tiszta vágás) elv mentén:

• Lényege: A modern technológiával (Filament, Tailwind CSS, Vite) készülő modulok teljes mértékben elkülönülnek a régi, jQuery/Bootstrap alapú rendszertől. Nem ágyazzuk be őket AJAX-szal a régi keretbe, hanem saját, teljes oldalas layoutot kapnak a stílusütközések elkerülése érdekében.
• Legacy (Laravel Mix): A meglévő jQuery, Bootstrap 4 és AdminLTE alapú kódokhoz.
  • Forrásfájlok: resources/js/, resources/sass/, resources/css/.
• Modern (Vite & Filament): Új funkciókhoz, Tailwind CSS-hez és Filament alapú admin felületekhez.
  • Forrásfájlok: resources/modern/js/, resources/modern/css/, resources/css/filament/.
  • Nézetek: resources/modern/views/, resources/views/filament/.
  • Használat Blade-ben: @vite(['resources/modern/css/app.css', 'resources/modern/js/app.js']).
• A modern nézeteket a Laravel automatikusan felismeri a config/view.php konfigurációja alapján.

Modernizációs és Design Irányelvek (Filament & Tailwind)

• Vizuális Konzisztencia: Az új moduloknak (Filament) illeszkedniük kell a legacy "Pepper Grinder" színvilágához.
  • Használjunk egyedi színpalettát az AdminPanelProvider-ben (Primary: #b83400, Gray: Pepper Grinder bézs/barna skála).
  • A kerekítéseket és árnyékokat a theme.css-ben rögzített szögletesebb stílushoz kell igazítani.
• Tailwind v4 Konfiguráció: A Vite build folyamatban a @tailwindcss/vite plugint használjuk.
  • Minden új Filament/Livewire forrást rögzíteni kell a theme.css @source direktívái között.
• Navigáció Szeparáció:
  • A legacy és modern részek közötti váltáshoz sima linkeket használunk (teljes oldalújratöltés).
  • A navigációs linkeknél a data-no-ajax="true" attribútumot kell használni, hogy a legacy JS (app.js) ne próbálja AJAX-szal betölteni a modern tartalmat.
• Közös Elemek (Render Hooks): A megszokott elemeket (pl. speedButtonNavBar) Filamentben Render Hook-ok segítségével injektáljuk a fejlécbe (TOPBAR_START), biztosítva a funkcionális folytonosságot.

JavaScript Architektúra és Modulok

• A JS kód alapja egy egyedi objektumorientált rendszer.
• Osztály-alapú felépítés: Minden adminisztrációs felülethez (vagy összetettebb modulhoz) tartozzon egy specifikus JavaScript osztály (pl. ProductAdmin), amely a resources/js/admin/ könyvtárban kap helyet.
• DataModel használata: Az adatok kliensoldali reprezentációjához használjunk a globális DataModel osztályból származtatott modelleket.
• Globális APP objektum: A példányosított modulokat és a globális beállításokat a window.APP objektumban tároljuk (pl. APP.ProductAdmin). Ez biztosítja a modulok közötti átjárhatóságot.

Felhasználói Felület (UI) és Komponensek

• DataTables Konvenciók:
  • Használjuk a $.fn.dataTable.defaults-ban definiált globális magyar nyelvű és formázási beállításokat.
  • A táblázat sorvégi műveletgombjait (Szerkesztés, Törlés, Megtekintés) az APP.datatableAddRowEditButton(), APP.datatableAddRowTrashButton() stb. segédfüggvényekkel generáljuk a konzisztencia érdekében.
• Mustache.js Sablonozás:
  • Dinamikus HTML tartalmak (pl. popupok, egyedi táblázat sorok) generálásához Mustache.js-t használunk.
  • A sablonokat a Blade fájlokban a <template> tag-ek között definiáljuk.
  • Az egyedi elhatároló jelek a következők: [[ változó_neve ]] (ez elkerüli az ütközést a Blade szintaxisával).
• UI Segédeszközök:
  • Select2: Összetett választómezőkhöz és AJAX alapú keresésekhez.
  • Toast: Felhasználói visszajelzésekhez (sikeres mentés, hiba) a globális Toast osztályt használjuk.
  • Datepicker: Dátumválasztó mezőkhöz (yy-mm-dd formátumban).

AJAX és Form Kezelés

• Navigáció: A fő tartalom frissítéséhez az APP.loadMainContent(url, callback) függvényt vagy az ajaxlink jQuery plugint használjuk a teljes oldalújratöltés helyett.
• Űrlapok küldése: Az adatok szerializálásához és a küldés előkészítéséhez használjuk a formDataToDataObjectAPICall függvényt, amely kezeli a speciális mezőket (pl. tömbök, fájlok).
• Hibakezelés: Minden AJAX kérésnél támaszkodjunk a globális ajaxErrorHandler-re, amely egységes módon jeleníti meg a validációs és szerveroldali hibákat a felhasználónak.

JavaScript Kódolási Stílus

• Használjunk modern ES6+ szintaxist (osztályok, arrow functions, let/const).
• A globális segédfüggvényeket (pl. debug(), latinise()) a resources/js/app.js-ben definiáljuk vagy tartsuk karban.
• Az eseménykezelőket (.on(), .off()) mindig megfelelően kössük és oldjuk fel, különösen dinamikusan betöltött tartalmak esetén.

Blade Sablonok

• A nézetek az resources/views mappában találhatóak, logikusan csoportosítva (pl. admin/product, admin/statistics).
• A szűrők és közös komponensek gyakran külön fájlokba vannak kiszervezve (pl. filter.blade.php).

Eszközök és Konvenciók - CLI

• Artisan parancsok: Generáló parancsok (pl. make:filament-resource) esetén törekedni kell az interakciómentes futtatásra a --no-interaction kapcsoló használatával.
• Filament Resource: Új Resource létrehozásakor kötelező megadni a --record-title-attribute paramétert (pl. name vagy filename), és javasolt a --generate használata, ha az adatbázis séma már rendelkezésre áll.

Verziókezelés (Git)

• Üzenetek: Angol vagy magyar nyelven, rövid de tömör leírással, hogy mit változtattál. Példa: feature: Add order archive export functionality.
• Méretes fájlok: Ne committolj nagyméretű képeket, build artifactokat vagy érzékeny adatokat (.env).

Adatbázis kezelés

• Migrációk: Minden adatbázis sémaváltoztatást migrációval kell végrehajtani.
• Enums: Ha egy mező meghatározott értékkészlettel rendelkezik, a migrációban is enum típust kell használni, az értékeket pedig dinamikusan a megfelelő PHP Enum osztályból kell kinyerni (pl. array_column(Enum::cases(), 'value')).
• Factories/Seeders: Új modulokhoz hozz létre gyárat (factory) és seedert a könnyű tesztelhetőségért.

Tesztelés

• PHPUnit: Új funkciókhoz írj Feature vagy Unit tesztet. Futtasd a teszteket a composer test parancsal commit előtt.

Eszközök és Környezet

• PHP: ^8.2
• Framework: Laravel ^12.0
• Frontend Build: Webpack/Mix (elsődleges), új megoldásoknál Vite.
• Csomagkezelés: Composer (PHP), NPM (JS).