diff --git a/.junie/guidelines.md b/.junie/guidelines.md new file mode 100644 index 0000000..450cc32 --- /dev/null +++ b/.junie/guidelines.md @@ -0,0 +1,85 @@ +### 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) +A projekt fokozatos modernizáció alatt áll, ezért két párhuzamos build rendszert használunk: +- **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)**: Új funkciókhoz, Tailwind CSS-hez és reaktív komponensekhez. + - Forrásfájlok: `resources/modern/js/`, `resources/modern/css/`. + - Nézetek: `resources/modern/views/`. + - 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. + +##### 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 `