# RGE Klíma — Laravel alkalmazás

## Projekt

Laravel 13 alapú webalkalmazás az RGE Klíma cég részére. Az admin felület
[Laravel Backpack](https://backpackforlaravel.com/) CRUD (`backpack/crud` ^7.1,
Tabler téma) segítségével készül.

## Helyi környezet

- **PHP**: 8.5, Composer 2.10 (Homebrew)
- **Webszerver**: Laravel Valet — a projekt a `~/.config/valet/Sites/rgeklima`
  symlinken keresztül van linkelve ide: `/Users/takacstamas/Projects/rgeklima`
- **URL**: https://rgeklima.test (Valet `secure`-rel TLS-esítve, http→https redirect)
- **Admin felület**: https://rgeklima.test/admin
  (jelenleg minden bejelentkezett user admin — lásd
  `app/Http/Middleware/CheckIfAdmin.php`, ezt módosítani kell, ha külön
  admin/user szerepkör lesz)
- **Adatbázis**: MySQL 9.7 (DBngin, `127.0.0.1:3306`, `root` user, jelszó nélkül)
  - adatbázis neve: `rge_klima`
  - kapcsolati adatok a `.env`-ben (`DB_CONNECTION=mysql`)
- Teszt admin user: `admin@rgeklima.test` / `password` (csak helyi fejlesztéshez)
- **Email**: Mailpit fut helyben (SMTP `127.0.0.1:1025`, webes felület
  http://127.0.0.1:8025), `.env`-ben `MAIL_MAILER=smtp` erre állítva — helyben
  minden kimenő email ide fut be, nem valódi címre.

## Git branch stratégia

- **`main`**: stabil ág, ide csak megfontoltan, review után kerül kód.
- **`development`**: az aktív fejlesztés ága, jelenleg ez az alapértelmezett
  munkaágunk. Új funkciók, fixek ide (vagy ebből nyitott feature branch-ekbe)
  kerülnek.

## FONTOS — commit és push szabály

**`git push`-t kizárólag a felhasználó kifejezett engedélyével szabad
végrehajtani** — enélkül soha ne pushold a változtatásokat.

**`git commit`**: jóváhagyott, GitLab issue-hoz köthető implementációs munka
után **szabadon commitolható, külön rákérdezés nélkül** (a felhasználó ezt
2026-09-05-én kifejezetten engedélyezte). Minden más esetben (pl. issue-hoz
nem köthető, kísérleti, vagy a tervekhez képest eltérő irányú változtatás)
készítsd elő a változtatásokat, és kérdezz rá, mielőtt commitolsz.

**Commit üzenet formátuma – Conventional Commits**: `feat(scope): leírás` /
`fix(scope): leírás` / `chore(scope): leírás` / `docs(scope): leírás` stb.
A `scope` a lehető legkonkrétabb legyen (pl. `feat(cms): Page modell
verziózással`, `fix(checkout): fgáz-elágazás validáció`). A leírás pontosan
tükrözze, mi változott — sose legyen általános ("update", "fix stuff").

## Graphify

Ennél a projektnél is használd a `graphify` skillt (lásd
`~/.claude/skills/graphify/SKILL.md`), hogy a kódbázisról és annak
felépítéséről tudásgráf épüljön — ez segíti a további fejlesztést és a
gyorsabb tájékozódást a kódban. Ha létezik `graphify-out/` könyvtár, a
kódbázisra vonatkozó kérdéseket először graphify lekérdezésként kezeld.

## Termék: bemutatkozó oldal + webshop, moduláris package-ekre bontva

A cél egy Laravel + Backpack alapú bemutatkozó oldal és webshop, aminek a
motorja **újrafelhasználható legyen más (jövőbeli, más cégnek szóló)
projektekben is**. Ezért a webshop/CMS funkciókat lehetőség szerint saját,
elkülönített Laravel package-ekre kell bontani (`btdigital/*` névtér,
kezdetben Composer path repository-ként a `packages/` alatt), nem az
alkalmazásba ágyazva. Az `rgeklima` repó maga csak az alkalmazás héja
(konfiguráció, package-ek összekötése, RGE Klíma-specifikus tartalom/branding)
marad. A részletes architektúra és fázisterv a GitLab Wiki
"Fejlesztesi-terv" oldalán található.

## FONTOS — kódolási alapszabály: Controller / Action / Service

**Controllerben nem lehet adatbázis-művelet** (nincs benne közvetlen Eloquent
lekérdezés/mentés). A Controller csak a HTTP kérést szolgálja ki: bemenet
validálása, a megfelelő Action vagy Service meghívása, válasz visszaadása.
Üzleti logika/DB-művelet mindig **Action** osztályba (egy konkrét művelet,
`execute()`/`handle()`) vagy **Service** osztályba (több lépéses/külső
integrációt igénylő logika) kerül. Ez különösen fontos az újrafelhasználható
package-eknél: így HTTP réteg nélkül (Artisan parancsból, queue jobból, más
alkalmazásból) is használhatók maradnak. Részletek a GitLab Wiki
"Fejlesztesi-terv" oldalának 3. pontjában.

## Frontend dizájn és technológia

**A publikus frontend Blade + Tailwind CSS + Alpine.js (nem React/SPA).**
Indoklás: SEO (szerveroldali renderelés kell a katalógus/termékoldalakhoz),
egyszerűség (nincs külön API-réteg, nincs SPA build-komplexitás), és mert az
admin (Backpack) is Blade-alapú, így egységes marad a stack. Ahol
oldalújratöltés nélküli, szerveroldali logikára támaszkodó frissítés kell
(katalógus-szűrés, kosár-widget), ott **Laravel Livewire** használandó Alpine.js
helyett/mellett — sose vezessünk be React-et vagy külön SPA-t emiatt. Tailwind
a Laravel 13 vázhoz alapból drótozva van (Vite), nem ütközik a Backpack/Tabler
(Bootstrap 5) admin témájával, mert elkülönülő route-csoportok.

A konkrét oldalstruktúra (főoldal, termékkatalógus, termékoldal,
kosár/checkout, mobil nézet) egy kapott látványterv "B" csomagja alapján
készült — a részletes, oldalankénti leírás a GitLab Wiki "Fejlesztesi-terv"
oldalának 14. pontjában található. Az eredeti látványterv PDF (`latvanyterv.pdf`)
bizalmassági jelölést visel, ezért **soha nem kerülhet a git repóba**
(gitignore-olva) — csak a belőle levezetett szöveges leírás a Wikin.

## FONTOS — csak ingyenes csomagok kereskedelmi használatra

Mielőtt bármilyen Backpack/Laravel plugint bevezetnél, **ellenőrizd a
tényleges licencét**, ne csak azt, hogy "ingyenesnek hangzik". Példa:
`Laravel-Backpack/Settings` YUMMY licence alatt fut — csak nem-kereskedelmi
használatra ingyenes, egy webshopnál (kereskedelmi cél) fizetős licenc
kellene hozzá, ezért NEM használjuk (helyette saját `btdigital/settings`
key/value store, ld. Wiki 13. pont). Hasonló csapda máshol is előfordulhat.

## Webshop részletterve

A webshop funkcionális/adatmodell terve (termékek + rugalmas attribútumok,
GPSR megfelelőség, F-gáz/telepítés logika, szállítás/MPL, kosár, checkout,
rendelés-snapshot, vásárlói fiók, akadálymentesítés stb.) egy külön GitLab
Wiki oldalon található: **"Fejlesztesi-terv-Webshop"**. Ez a 2. fázis
(webshop motor) részletterve — az itt szereplő tételekhez tartozó issue-k
csak külön jóváhagyás után készülnek el, ahogy az 1. fázisnál is történt.

## FONTOS — GitLab issue munkafolyamat

**Minden új funkció vagy nagyobb változtatás implementálása előtt megfelelően
labelezett GitLab issue-t kell nyitni** (apró javítások/hibajavítások
kivételével, azoknál nem kötelező). Ne kezdj bele érdemi implementációba
issue nélkül. **Amint egy issue-hoz tartozó munka elkészült:**
1. az issue-ra kerüljön a **`statusz:done`** label,
2. **kommentet kell írni az adott issue-ra**, ami leírja, mi készült el / mi
   lett módosítva, implementálva (röviden, konkrétan — fájlok/komponensek
   szintjén, nem csak "kész"),
3. **az issue-t magát NE zárd le** — a `statusz:done` label jelzi a
   készültséget, de a lezárást a felhasználó végzi review után.

A GitLab eléréséhez a `GITLAB_API_TOKEN` környezeti változó használható
(gitlab.btdigital.eu, projekt: `tamas.takacs/rgeklima`, id: 7).