# Terméklekérdező weboldal – terv

## 1. Cél

A felhasználó megad egy termékazonosítót egy űrlapon. A rendszer ez alapján DAX lekérdezéssel lekéri a termék adatait egy Power BI / tabular adatmodellből, és megjeleníti az oldalon. Az oldal nyitott (nincs bejelentkezés), és valós adatkapcsolat nélkül, mock adatokkal is futtatható és tesztelhető legyen.

## 2. Technológia

**Next.js (App Router, TypeScript)** – ez marad az ajánlás, mert:

- egy projektben fér el a frontend és a backend (API route handler), nem kell külön szerver
- a route handler szerver oldalon fut, így a Power BI hitelesítő adatok (ha majd élesbe megy) sosem kerülnek a böngészőbe
- egyszerű a mock/live adatforrás közti váltás env változóval
- Vercel vagy bármilyen Node hoszt egyszerűen fut vele

Alternatíva lenne egy különálló Node/Express API + statikus frontend, de mivel a DAX/Power BI hívást mindenképp szerver oldalon kell tartani (API kulcs, service principal), a Next.js beépített route handlere pont ezt a "backend-for-frontend" szerepet adja ingyen – nincs indok külön szerverre.

## 3. Adatfolyam

```
Böngésző (termékazonosító beírása)
   → GET /api/product/[id]   (Next.js route handler)
       → ProductDataSource absztrakció
            ├─ mock mód: fixtures/products.json-ból olvas
            └─ live mód (később): Power BI REST "executeQueries" DAX hívás
   → normalizált Product JSON válasz
   → React komponens megjeleníti a termékkártyát
```

## 4. DataSource absztrakció

```ts
interface ProductDataSource {
  getProductById(id: string): Promise<Product | null>;
}
```

- `MockProductDataSource` – jelenlegi implementáció, `fixtures/products.json`-ból szolgál ki adatokat, mesterséges késleltetéssel (hogy a UI betöltő állapota is tesztelhető legyen).
- `PowerBiProductDataSource` – későbbi implementáció, ugyanezt az interfészt valósítja meg, de valódi DAX hívást indít.
- Váltás env változóval: `DATA_SOURCE=mock` (alapértelmezett) vagy `DATA_SOURCE=powerbi`.

Ez a réteg teszi lehetővé, hogy a UI és az API route kódja egyáltalán ne változzon, amikor a mock adatforrást élesre cseréljük.

## 5. DAX lekérdezés terv (élesítéskor)

- Végpont: `POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/executeQueries`
- Törzs: `{ "queries": [{ "query": "EVALUATE FILTER('Product', 'Product'[ProductID] = \"<id>\")" }] }`
- Hitelesítés: Azure AD service principal (client credentials flow) + a workspace-hez rendelt megfelelő jogosultság. Ez jelenleg nincs beállítva – ha élesbe megy a rendszer, ezt külön be kell állítani (app regisztráció, workspace hozzáférés, dataset engedélyezése service principal számára).
- A termékazonosítót escape-elni / whitelistelni kell (csak alfanumerikus karakterek), mielőtt DAX stringbe kerül, DAX-injection elkerülése végett.
- A pontos tábla- és oszlopnevek (`Product`, `ProductID` stb.) egyelőre feltételezettek – ezt a valós adatmodell alapján pontosítani kell.

## 6. Megjelenítés

A design két hasábos elrendezésű termékadatlap: felül egy kompakt fejléc (logó + keresőmező a termékazonosítónak), alatta bal oldalon a termékkép és a kiegészítő termékek listája, jobb oldalon a szöveges adatok. "Nem található termék", hibaállapot, betöltés és egy márkás üres állapot (keresés előtt) is kezelve van.

### 6.1 Megjelenítendő adatok (`Product` típus, `lib/types.ts`)

- **Termék név** (`name`)
- **Termék kód / cikkszám** (`productId`) – ez az azonosító, amivel a keresés is történik
- **Brand / márka** (`brand`)
- **Miért jó választás** (`benefits`) – cím + leírás párok listája (cikklista), a jobb oldalon, formázás nélkül jelenik meg (nincs pl. ikon-készlet vagy egyedi stílus terméktípusonként, egységes kártya-lista)
- **Kiegészítő termékek** (`relatedProducts`) – a bal hasábban, a kép alatt megjelenő lista (név, rövid leírás, kategória, kép)

Ezeken felül a `Product` típus a fentieket kiegészítve még tartalmazza (nem volt kifejezetten kérve, de a jelenlegi adatlaphoz szükséges):

- `breadcrumb` – kategória-útvonal a cím fölött
- `category` – kategória neve
- `ean` – vonalkód
- `price`, `currency` – ár és pénznem
- `stock`, `deliveryEstimate` – készlet és szállítási idő
- `description` – rövid leíró szöveg
- `imageUrl` – termékkép
- `specs` – "Termékjellemzők" táblázat (label/value párok)

## 7. Tesztelhetőség

- `DATA_SOURCE=mock` az alapértelmezett `.env.local` beállítás → az oldal Power BI kapcsolat nélkül, azonnal elindítható és tesztelhető (`npm run dev`).
- 1 valós minta termék a `fixtures/products.json`-ban (KEPO kompakt pellet kazán, 25 kW – valós adatok a melindainstal.ro katalógusából), hogy a keresés, a "nem található" eset és a hibakezelés is kipróbálható legyen.
- A `ProductDataSource` interfész miatt később könnyen írható rá unit teszt (pl. Jest a route handlerhez) és e2e teszt (pl. Playwright a UI-hoz) – ez a mostani kódvázban még nincs benne, de az architektúra előkészíti.

## 8. Nyitott kérdések / kockázatok élesítés előtt

- Melyik Power BI workspace / dataset szolgáltatja majd a termékadatokat.
- Service principal létrehozása és jogosultság beállítása (app regisztráció az Azure AD-ban, dataset engedélyezés).
- A termék tábla pontos oszlopnevei és mezői – ezeket a valós modell alapján kell véglegesíteni a `Product` típusban.
- DAX injection elleni bemenet-validáció szabályainak véglegesítése.