=== projekt szabályok === # Hibrid architektúra: Legacy vs. Modern A projekt jelenleg átmeneti fázisban van a régi Laravel 8-as architektúráról a modern Laravel 12-es felépítésre. KRITIKUS fontosságú a két "világ" megkülönböztetése: ### 1. Legacy Világ (Csak karbantartás) - **Technológiai stekk**: jQuery, Bootstrap, Laravel Mix (`webpack.mix.js`), DataTables, Mustache.js. - **Belépési pont**: `resources/views/layout/core.blade.php`, `/legacy` útvonalak, és a hagyományos Blade nézeteket használó kontrollerek. - **Assetek**: A `mix()` függvénnyel kezelve. A fájlok a `resources/js/` mappában találhatók (kivéve a `modern` almappát). - **Szabály**: Ezekhez CSAK hibajavítás vagy kisebb módosítás esetén nyúlj. NE implementálj ide új funkciókat, hacsak nincs rá kifejezett kérés. ### 2. Modern Világ (Elsődleges fejlesztés) - **Technológiai stekk**: Laravel 12, Filament v4 (TALL stekk: Tailwind, Alpine.js, Laravel, Livewire), Vite (`vite.config.js`). - **Belépési pont**: `/admin` (Filament Dashboard), `resources/modern/` mappa. - **Assetek**: A `vite()` függvénnyel kezelve. A stílusokhoz Tailwind CSS v4-et használunk. - **Szabály**: MINDEN új funkciót Filament resource-ok/oldalak vagy modern Livewire komponensek használatával kell megvalósítani. ### 3. Átállás és Modernizáció - **"Clean Cut" megközelítés**: Szisztematikusan váltjuk ki a régi jQuery megoldásokat modern Laravel 12-es megfelelőkre. - **Auditálás**: Használd a `BaseAuditable` osztályt minden új modellnél a konzisztens követhetőség érdekében. - **Refaktorálás**: Ha egy legacy kontroller/nézet jelentős átalakítást igényel, javasold annak áthelyezését egy Filament Resource-ba. # Projekt-specifikus szabályok - **API válaszok**: Használd a `flugger/laravel-responder` csomagot (`responder()` helper) minden API válaszhoz. Kövesd az `OrderController.php`-ban látható mintát. - **API verziózás**: Az API verziókat a névterekből kell kinyerni a `parseAPIVersionFromNamespace(__NAMESPACE__)` helper segítségével. - **Dokumentáció**: Használd a Scribe-ot az API dokumentációhoz. Használj `@group`, `@authenticated`, `@bodyParam`, és `@responseField` annotációkat a kontrollerekben. - **Modellek**: Az új modelleknek jellemzően a `BaseAuditable` osztályból kell származniuk a sima Eloquent `Model` helyett, ha auditálás szükséges. - **Helperek**: Használd az `app/helpers.php` fájlban definiált projekt-specifikus helpereket (pl. `formatterPhoneNumber`, `formatterDateTime`, `getSql`). - **Fordítások**: Használd a `laravel-lang/lang` csomagot a többnyelvű támogatáshoz. - **Enumok**: Használd a `bensampo/laravel-enum` csomagot a típusbiztos felsorolásokhoz (pl. `OrderStatusEnum`, `OrderType`). === alapvető szabályok === # Laravel Boost Irányelvek A Laravel Boost irányelveket kifejezetten a Laravel karbantartói állították össze ehhez az alkalmazáshoz. Ezeket az irányelveket szigorúan be kell tartani a legjobb Laravel fejlesztési élmény biztosítása érdekében. ## Alapvető kontextus Ez egy Laravel alkalmazás, a fő ökoszisztéma csomagok és verziók alább láthatók. Te ezeknek a szakértője vagy. Gondoskodj róla, hogy tartsd magad ezekhez a specifikus csomagokhoz és verziókhoz. - php - 8.4 - filament/filament (FILAMENT) - v4 - laravel/framework (LARAVEL) - v12 - laravel/prompts (PROMPTS) - v0 - laravel/sanctum (SANCTUM) - v4 - livewire/livewire (LIVEWIRE) - v3 - laravel/boost (BOOST) - v2 - laravel/mcp (MCP) - v0 - laravel/pail (PAIL) - v1 - laravel/sail (SAIL) - v1 - pestphp/pest (PEST) - v3 - phpunit/phpunit (PHPUNIT) - v11 - tailwindcss (TAILWINDCSS) - v4 ## Képességek aktiválása Ez a projekt tartomány-specifikus képességekkel rendelkezik. Kötelező aktiválnod a releváns képességet, amikor abban a tartományban dolgozol — ne várd meg, amíg elakadsz. - `laravel-best-practices` — Használd ezt a képességet Laravel PHP kód írásakor, átnézésekor vagy refaktorálásakor. Ez magában foglalja kontrollerek, modellek, migrációk, form requestek, policy-k, jobok, ütemezett parancsok, service osztályok és Eloquent lekérdezések készítését vagy módosítását. Aktiváld N+1 és lekérdezési teljesítményproblémák, gyorsítótárazási stratégiák, autorizációs és biztonsági minták, validáció, hibakezelés, sor- és job konfiguráció, útvonal definíciók és architektúrális döntések esetén. Használd továbbá Laravel kód áttekintéséhez és meglévő kódok refaktorálásához a legjobb gyakorlatok szerint. Minden Laravel háttér PHP kódmintát érintő feladathoz. - `livewire-development` — Használd minden olyan feladathoz vagy kérdéshez, amely a Livewire-t érinti. Aktiváld, ha a felhasználó említi a Livewire-t, a wire: direktívákat, vagy Livewire-specifikus koncepciókat, mint a wire:model, wire:click. Lefedi az új komponensek építését, reaktivitási hibák keresését, valós idejű form validációt, betöltési állapotokat, a Livewire 2-ről 3-ra való migrációt, komponens formátumok konvertálását és teljesítményoptimalizálást. Ne használd nem-Livewire reaktív UI-hoz (React, Vue, csak Alpine, Inertia.js) vagy standard Laravel formokhoz Livewire nélkül. - `pest-testing` — Ezt a képességet kizárólag Pest PHP teszteléshez használd Laravel projektekben. Aktiváld, amikor tesztet írsz, szerkesztesz, javítasz vagy refaktorálsz — beleértve a kódmódosítás után eltört tesztek javítását, asszerciók hozzáadását, PHPUnit tesztek Pest-re konvertálását, datasetek hozzáadását és TDD munkafolyamatokat. Mindig aktiváld, ha a felhasználó Pest-ben való írásról kérdez, teszt fájlokat vagy könyvtárakat említ (tests/Feature, tests/Unit), vagy architektúra teszteket. Lefedi az it()/expect() szintaxist, dataseteket, mockolást, böngésző tesztelést, arch()-ot, Livewire komponens teszteket, RefreshDatabase-t és minden Pest 4 funkciót. Ne használd factory-k, seeder-ek, migrációk, kontrollerek, modellek vagy nem teszt jellegű PHP kódok szerkesztéséhez. - `tailwindcss-development` — Mindig aktiváld, ha a felhasználó üzenete bármilyen formában tartalmazza a 'tailwind' szót. Továbbá használd: responzív rács elrendezések (többoszlopos kártya rácsok, termék rácsok), flex/grid oldalstruktúrák (oldalsávos dashboardok, fix fejlécek, mobil-navigáció), UI komponensek stílusozása (kártyák, táblázatok, navigációs sávok, árazási szakaszok, formok, inputok, jelvények), sötét mód variánsok hozzáadása, térköz vagy tipográfia javítása, valamint Tailwind v3/v4 munkák esetén. Fő felhasználási eset: Tailwind utility osztályok írása vagy javítása HTML sablonokban (Blade, JSX, Vue). Hagyd ki háttér PHP logika, adatbázis lekérdezések, API útvonalak, HTML/CSS komponens nélküli JavaScript, CSS fájl auditok, build eszköz konfiguráció és vanilla CSS esetén. ## Konvenciók - Követned kell az alkalmazásban használt összes meglévő kódkonvenciót. Fájl létrehozásakor vagy szerkesztésekor ellenőrizd a szomszédos fájlokat a helyes struktúra, megközelítés és elnevezés érdekében. - Használj leíró neveket a változókhoz és metódusokhoz. Például: `isRegisteredForDiscounts`, nem pedig `discount()`. - Új komponens írása előtt ellenőrizd a meglévő komponenseket az újrahasznosíthatóság érdekében. ## Ellenőrző szkriptek - Ne készíts ellenőrző szkripteket vagy kísérletezz, ha a tesztek lefedik az adott funkciót és bizonyítják a működését. Az egység- és funkcionális tesztek fontosabbak. ## Alkalmazás struktúra és architektúra - Tartsd magad a meglévő könyvtárstruktúrához; ne hozz létre új alapkatalógusokat jóváhagyás nélkül. - Ne változtasd meg az alkalmazás függőségeit jóváhagyás nélkül. ## Frontend csomagolás - Ha a felhasználó nem látja a frontend változást a felületen, az jelentheti azt, hogy futtatnia kell az `npm run build`, `npm run dev` vagy `composer run dev` parancsot. Kérdezz rá. ## Dokumentációs fájlok - Dokumentációs fájlokat csak akkor hozz létre, ha a felhasználó kifejezetten kéri. ## Válaszok - Légy tömör a magyarázatokban - fókuszálj a fontos dolgokra, ahelyett, hogy nyilvánvaló részleteket magyaráznál. === boost szabályok === # Laravel Boost ## Eszközök - A Laravel Boost egy kifejezetten ehhez az alkalmazáshoz tervezett eszközökkel rendelkező MCP szerver. Preferáld a Boost eszközöket a manuális alternatívákkal szemben, mint a shell parancsok vagy fájlbeolvasások. - Használd a `database-query` eszközt csak olvasható lekérdezések futtatásához az adatbázison, ahelyett, hogy nyers SQL-t írnál a tinkerbe. - Használd a `database-schema` eszközt a táblák szerkezetének vizsgálatához migrációk vagy modellek írása előtt. - Használd a `get-absolute-url` eszközt a projekt URL-jeinek helyes sémájának, domainjének és portjának feloldásához. Mindig használd ezt, mielőtt URL-t osztanál meg a felhasználóval. - Használd a `browser-logs` eszközt a böngésző naplók, hibák és kivételek beolvasásához. Csak a friss naplók hasznosak, hagyd figyelmen kívül a régi bejegyzéseket. ## Dokumentáció keresése (FONTOS) - Kódmódosítás előtt mindig használd a `search-docs` eszközt. Ne hagyd ki ezt a lépést. Ez automatikusan a telepített csomagok alapján ad verzióspecifikus dokumentációt. - Adj át egy `packages` tömböt az eredmények szűkítéséhez, ha tudod, mely csomagok relevánsak. - Használj több széles, téma alapú keresést: `['rate limiting', 'routing rate limiting', 'routing']`. Számíts rá, hogy a legrelevánsabb eredmények lesznek elöl. - Ne adj csomagneveket a kereséshez, mert a csomaginformáció már meg van osztva. Használd a `test resource table` kifejezést, ne a `filament 4 test resource table`-t. ### Keresési szintaxis 1. Használj szavakat az automatikusan csonkolt ÉS logikához: a `rate limit` találatot ad a "rate" ÉS "limit" szavakra is. 2. Használj `"idézőjeles kifejezéseket"` a pontos pozícióillesztéshez: az `"infinite scroll"` megköveteli az egymás melletti szavakat a megadott sorrendben. 3. Kombináld a szavakat és kifejezéseket a vegyes kereséshez: `middleware "rate limit"`. 4. Használj több keresést a VAGY logikához: `queries=["authentication", "middleware"]`. ## Artisan - Futtasd az Artisan parancsokat közvetlenül a parancssorból (pl. `php artisan route:list`). Használd a `php artisan list` parancsot az elérhető parancsok felfedezéséhez, és a `php artisan [command] --help` parancsot a paraméterek ellenőrzéséhez. - Vizsgáld meg az útvonalakat a `php artisan route:list` paranccsal. Szűrj: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. - Olvass be konfigurációs értékeket pont jelöléssel: `php artisan config:show app.name`, `php artisan config:show database.default`. Vagy olvasd a konfigurációs fájlokat közvetlenül a `config/` könyvtárból. - A környezeti változók ellenőrzéséhez olvasd közvetlenül a `.env` fájlt. ## Tinker - Futtass PHP kódot az alkalmazás környezetében hibakereséshez és teszteléshez. Ne hozz létre modelleket felhasználói jóváhagyás nélkül, preferáld a factory-kkal ellátott teszteket. Preferáld a meglévő Artisan parancsokat az egyedi tinker kódok helyett. - Mindig használj szimpla idézőjeleket a shell kifejtés megakadályozására: `php artisan tinker --execute 'Your::code();'` - Használj dupla idézőjelet a PHP stringekhez belül: `php artisan tinker --execute 'User::where("active", true)->count();'` === php szabályok === # PHP - Mindig használj kapcsos zárójeleket a vezérlési szerkezeteknél, még az egysoros törzseknél is. - Használd a PHP 8 konstruktor property promotion-t: `public function __construct(public GitHub $github) { }`. Ne hagyj üres, nulla paraméteres `__construct()` metódusokat, hacsak a konstruktor nem privát. - Használj explicit visszatérési típus deklarációkat és típusjelzéseket minden metódus paraméternél: `function isAccessible(User $user, ?string $path = null): bool` - Használj TitleCase-t az Enum kulcsokhoz: `FavoritePerson`, `BestLake`, `Monthly`. - Preferáld a PHPDoc blokkokat az inline kommentekkel szemben. Csak kivételesen összetett logika esetén adj hozzá inline kommenteket. - Használj array shape típusdefiníciókat a PHPDoc blokkokban. === laravel/core szabályok === # Csináld a Laravel Útján - Használd a `php artisan make:` parancsokat új fájlok (pl. migrációk, kontrollerek, modellek stb.) létrehozásához. Az elérhető Artisan parancsokat a `php artisan list` paranccsal listázhatod, és a paramétereiket a `php artisan [command] --help` paranccsal ellenőrizheted. - Ha generikus PHP osztályt hozol létre, használd a `php artisan make:class` parancsot. - Minden Artisan parancsnak add át a `--no-interaction` jelzőt a felhasználói beavatkozás nélküli működés érdekében. A helyes működéshez a megfelelő `--options` opciókat is meg kell adnod. ### Modell létrehozás - Új modellek létrehozásakor készíts hozzájuk hasznos factory-kat és seedereket is. Kérdezz rá a felhasználónál, ha másra is szükség van, a `php artisan make:model --help` segítségével ellenőrizve az elérhető opciókat. ## API-k és Eloquent Resource-ok - API-k esetén alapértelmezés szerint használj Eloquent API Resource-okat és API verziózást, hacsak a meglévő API útvonalak nem másképp teszik, ekkor kövesd a meglévő alkalmazáskonvenciót. ## URL generálás - Más oldalakra mutató linkek generálásakor preferáld a nevesített útvonalakat és a `route()` függvényt. ## Tesztelés - Modellek létrehozásakor a tesztekhez használd a modellek factory-jait. Ellenőrizd, hogy a factory rendelkezik-e egyedi állapotokkal (states), amelyeket használni lehet, mielőtt manuálisan állítanád be a modellt. - Faker: Használj olyan metódusokat, mint a `$this->faker->word()` vagy a `fake()->randomDigit()`. Kövesd a meglévő konvenciókat, hogy a `$this->faker`-t vagy a `fake()`-et használd. - Tesztek létrehozásakor használd a `php artisan make:test [opciók] {név}` parancsot funkcionális teszt létrehozásához, és add át a `--unit` jelzőt egységteszt készítéséhez. A legtöbb tesztnek funkcionális tesztnek kell lennie. ## Vite hiba - Ha "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" hibát kapsz, futtathatod az `npm run build` parancsot, vagy kérd meg a felhasználót, hogy futtassa az `npm run dev` vagy a `composer run dev` parancsot. === laravel/v12 szabályok === # Laravel 12 - KRITIKUS: MINDIG használd a `search-docs` eszközt a verzióspecifikus Laravel dokumentációhoz és frissített kódpéldákhoz. - Ez a projekt a Laravel 10-ről lett frissítve az új, áramvonalasított Laravel fájlstruktúrára való áttérés nélkül. - Ez teljesen rendben van és a Laravel által ajánlott. Kövesd a Laravel 10-ből származó meglévő struktúrát. Nem kell áttérnünk az új Laravel struktúrára, hacsak a felhasználó kifejezetten nem kéri. ## Laravel 10 struktúra - A middleware-ek jellemzően az `app\Http/Middleware/` mappában, a service providerek pedig az `app\Providers/` mappában találhatók. - Nincs `bootstrap/app.php` alkalmazáskonfiguráció a Laravel 10 struktúrában: - A middleware regisztráció az `app\Http/Kernel.php` fájlban történik. - A kivételkezelés az `app\Exceptions/Handler.php` fájlban található. - A konzol parancsok és az ütemezés az `app\Console/Kernel.php` fájlban vannak regisztrálva. - A sebességkorlátok (rate limits) valószínűleg a `RouteServiceProvider`-ben vagy az `app\Http/Kernel.php`-ban találhatók. ## Adatbázis - Oszlop módosításakor a migrációnak tartalmaznia kell az oszlophoz korábban definiált összes attribútumot. Ellenkező esetben azok elvesznek. - A Laravel 12 natívan lehetővé teszi az eager loaded rekordok korlátozását külső csomagok nélkül: `$query->latest()->limit(10);`. ### Modellek - A castok beállíthatók és célszerű is beállítani a modell `casts()` metódusában a `$casts` tulajdonság helyett. Kövesd a többi modell meglévő konvencióit. === livewire/core szabályok === # Livewire - A Livewire lehetővé teszi dinamikus, reaktív felületek építését PHP-ben, JavaScript írása nélkül. - Az Alpine.js-t használhatod kliensoldali interakciókhoz JavaScript keretrendszerek helyett. - Tartsd az állapotot a szerver oldalon, hogy a UI azt tükrözze. Validálj és autorizálj az action-ökben, ahogy a HTTP kéréseknél tennéd. === pest/core szabályok === ## Pest - Ez a projekt a Pest-et használja teszteléshez. Hozz létre teszteket: `php artisan make:test --pest {név}`. - Futtasd a teszteket: `php artisan test --compact` vagy szűrj: `php artisan test --compact --filter=tesztNeve`. - NE törölj teszteket jóváhagyás nélkül.