86 lines
6.5 KiB
Markdown
86 lines
6.5 KiB
Markdown
### 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 `<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).
|