### 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 és Auditálás
- 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.

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