d2d.emegrendeles.hu/AGENTS.md

=== 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.