108 lines
9.5 KiB
Markdown
108 lines
9.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, 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).
|