# Plan refaktoryzacji frontendu shopPRO

## Kontekst

Panel administratora (33 moduły) został w pełni zmigrowany na architekturę Domain + DI + Controllers (ver. 0.237–0.277). Teraz kolej na frontend: klasy `front/`, `shop/`, `cms/`, klasy utility z `autoload/` oraz szablony `templates/`.

**Cel:** przenieść logikę biznesową z warstwy frontendowej do warstwy domenowej (`Domain/`), zachowując kompatybilność wsteczną przez fasady. Zastosować te same wzorce co w adminie (DI, repozytoria/serwisy, testy PHPUnit).

---

## Inwentaryzacja — co istnieje

### front/controls/ (8 klas — handlery requestów)
| Klasa | Status | Logika biznesowa |
|-------|--------|-----------------|
| Site | Router główny | route(), check_url_params(), title() |
| ShopBasket | MIXED | Operacje koszyka, add/remove/quantity, checkout |
| ShopClient | Fasada | Deleguje do factory |
| ShopOrder | KRYTYCZNY | Webhooki płatności (tPay, Przelewy24, Hotpay) — bezpośrednie operacje DB |
| ShopProduct | Fasada | lazy_loading, warehouse_message, draw_product_attributes |
| ShopProducer | Fasada | list(), products() |
| ShopCoupon | Fasada | use_coupon(), delete_coupon() |
| Newsletter | Fasada | signin(), confirm(), unsubscribe() |

### front/factory/ (20 klas — pobieranie danych + logika)
| Klasa | Status | Priorytet migracji |
|-------|--------|--------------------|
| ShopProduct | ORYGINALNA LOGIKA (~370 linii) | KRYTYCZNY — product_details(), promoted/top/new products |
| ShopOrder | ORYGINALNA LOGIKA (~180 linii) | KRYTYCZNY — basket_save() tworzy zamówienie |
| ShopClient | ORYGINALNA LOGIKA | KRYTYCZNY — login (BUG: hardcoded bypass 'Legia1916'), signup, recover |
| ShopCategory | ORYGINALNA LOGIKA | WYSOKI — złożone SQL z language fallback |
| Articles | ORYGINALNA LOGIKA | WYSOKI — złożone SQL z language fallback |
| ShopPromotion | ORYGINALNA LOGIKA | WYSOKI — silnik promocji (5 typów) |
| ShopBasket | Fasada | ŚREDNI — summary_price, count |
| ShopTransport | CZĘŚCIOWO zmigrowana | ŚREDNI — transport_methods z filtrowaniem |
| ShopPaymentMethod | ZMIGROWANA (Domain) | — |
| ShopStatuses | ZMIGROWANA (Domain) | — |
| Scontainers | ZMIGROWANA (Domain) | — |
| Newsletter | CZĘŚCIOWO zmigrowana | ŚREDNI |
| Settings | Fasada (BUG: get_single_settings_value ignoruje $param) | NISKI |
| Languages | Fasada | NISKI |
| Layouts | Fasada | NISKI |
| Banners | Fasada | NISKI |
| Menu | Fasada | NISKI |
| Pages | Fasada | NISKI |
| ShopAttribute | Fasada | NISKI |
| ShopCoupon | Model danych | NISKI |

### front/view/ (12 klas — renderowanie)
| Klasa | Status |
|-------|--------|
| Site | KRYTYCZNY — show() ~600 linii, pattern substitution engine |
| ShopCategory | VIEW z logiką routingu (infinite scroll vs pagination) |
| Articles, Banners, Languages, Menu, Newsletter, Scontainers | Czyste VIEW |
| ShopClient, ShopOrder, ShopPaymentMethod | Czyste VIEW |
| ShopTransport | PUSTA klasa (placeholder) |

### shop/ (14 klas — encje biznesowe)
| Klasa | Linii | Status | Priorytet |
|-------|-------|--------|-----------|
| Product | ~950 | KRYTYCZNY — pricing, atrybuty, search, cache, permutacje | KRYTYCZNY |
| Order | ~500+ | KRYTYCZNY — statusy, Apilo sync, emaile, webhooki | KRYTYCZNY |
| Promotion | ~200 | WYSOKI — matching aktywnych promocji + delegacja do factory | WYSOKI |
| Basket | ~80 | ŚREDNI — walidacja stanów magazynowych | ŚREDNI |
| Category | ~60 | NISKI — proste zapytania, pusty konstruktor | NISKI |
| Search | ~80 | NISKI — wrapper na szablony | NISKI |
| Coupon | ~60 | NISKI — niekompletne metody | NISKI |
| Transport | ~30 | NISKI — transport_list() | NISKI |
| PaymentMethod | — | ZMIGROWANA (fasada do Domain) | — |
| Producer | — | ZMIGROWANA (fasada do Domain) | — |
| ProductSet | — | ZMIGROWANA (fasada do Domain) | — |
| ProductAttribute | ~100 | OK — dobry caching | — |
| ProductCustomField | ~50 | OK — Redis caching | — |
| Shop | ~30 | OK — utility do cen | — |

### autoload/ root (klasy utility)
| Klasa | Linii | Status |
|-------|-------|--------|
| S | ~1130 | htacces() ~500 linii — generowanie .htaccess; reszta to utility |
| Tpl | ~90 | OK — silnik szablonów, bez zmian |
| CacheHandler | ~50 | OK — Redis wrapper |
| RedisConnection | ~40 | OK — singleton |
| Email | ~100 | OK — PHPMailer wrapper (drobne poprawki) |
| Log | ~20 | OK — audit logging |
| DbModel | ~60 | OK — base ORM |
| Cache | ~50 | LEGACY — file-based cache, rozważyć usunięcie |
| Html | ~80 | OK — form helpers |
| Image | ~100 | OK — GD wrapper |
| Mobile_Detect | — | Third-party, bez zmian |

### cms/ (1 klasa)
| Klasa | Status |
|-------|--------|
| Layout | BUG w __get() — referuje $this->data które nie istnieje |

### templates/ (75 plików w 15 modułach)
articles(8), banner(2), controls(1), menu(4), newsletter(2), scontainers(1), shop-basket(9), shop-category(6), shop-client(8), shop-coupon(1), shop-order(3), shop-producer(3), shop-product(12), shop-search(3), site(11)

### Entry points
- `index.php` — główny frontend (autoload, sesja, DB, routing, DOM post-processing)
- `ajax.php` — AJAX handler (koszyk, transport, kontakt)
- `api.php` — REST API (Ekomi CSV export)
- `download.php` — pobieranie plików
- `cron-turstmate.php` — TrustMate integracja

---

## Znane bugi do naprawy podczas refaktoringu

1. **KRYTYCZNY** `front\factory\ShopClient::login()` — hardcoded password bypass `'Legia1916'`
2. `front\factory\Settings::get_single_settings_value()` — ignoruje `$param`, zawsze zwraca `firm_name`
3. `front\factory\Newsletter::newsletter_unsubscribe()` — błędna składnia SQL w delete
4. `cms\Layout::__get()` — referuje nieistniejące `$this->data`
5. `shop\Search` — typo w use: `shop\Produt` (brak 'c')

---

## Kolejność migracji (graf zależności)

```
Settings, Languages (liście — brak zależności)
    ↓
Banners, Menu, Pages, Articles, Layouts (zależą od Languages)
    ↓
Category (zależy od Languages)
    ↓
Promotion (zależy od Category — rozbicie circular dep)
    ↓
Product Frontend (zależy od Category, Promotion, Languages)
    ↓
Client/Auth (standalone + security fix)
    ↓
Transport, Payment, Coupon (frontend serwisy)
    ↓
Basket (zależy od Product, Promotion, Transport, Coupon)
    ↓
Order Creation (zależy od Basket, Product, Transport, Payment)
    ↓
Payment Webhooks (zależy od Order)
    ↓
shop\Order instance + Apilo (zależy od Order Operations)
    ↓
shop\Product instance + cache (zależy od ProductFrontendService)
    ↓
Frontend App + Controllers (nowa warstwa DI)
    ↓
Site Layout Engine (zależy od wszystkiego)
    ↓
Entry Point Unification (index.php, ajax.php)
    ↓
Legacy Cleanup
```

---

## Etapy migracji

### Etap: Settings + Languages — ZREALIZOWANY

**Cel:** Dodac metody frontendowe (z cache Redis) do istniejacych repozytoriow Domain.

**DODANE METODY (do istniejacych klas):**
- `Domain/Settings/SettingsRepository` — `allSettings($skipCache)`, `getSingleValue($param)` (FIX: uzywa poprawnie $param)
- `Domain/Languages/LanguagesRepository` — `defaultLanguage()`, `activeLanguages()`, `translations($lang)`
- Testy: dopisane do `SettingsRepositoryTest` (6 testow), `LanguagesRepositoryTest` (7 testow)

**ZMIANA:**
- `front/factory/Settings` → fasada delegujaca do `SettingsRepository`
- `front/factory/Languages` → fasada delegujaca do `LanguagesRepository`
- `tests/bootstrap.php` — uzupelniony stub CacheHandler o `get()`/`set()`/`exists()`

**BUG FIX:** `get_single_settings_value()` — zmiana `['param' => 'firm_name']` na `['param' => $param]`

---

### Etap: Category Frontend Service

**Cel:** Migracja `front\factory\ShopCategory` do Domain.

**NOWE:**
- `Domain/Category/CategoryFrontendService.php` — `getCategorySort()`, `categoryName()`, `categoryUrl()`, `blogCategoryProducts()`, `categoryProducts()`, `productsId()` (złożone SQL z sortowaniem/language fallback/paginacją), `categoryDetails()`, `categoriesDetails()` (rekurencyjne), `categoryProductsCount()`
- Testy: `CategoryFrontendServiceTest`

**ZMIANA:**
- `front/factory/ShopCategory` → fasada
- `front/factory/ShopProduct::product_categories()` → deleguje do `CategoryFrontendService`

---

### Etap: Banners, Menu, Pages, Articles, Layouts Frontend Services

**Cel:** Migracja pozostałych fabryk "liściowych".

**NOWE:**
- `Domain/Banner/BannerFrontendService.php` — `mainBanner()`, `banners()` (filtrowanie po datach)
- `Domain/Menu/MenuFrontendService.php` — `menuDetails()`, `menuPages()` (rekurencja)
- `Domain/Pages/PagesFrontendService.php` — `pageDetails()`, `mainPageId()`, `langUrl()`, `pageSort()`
- `Domain/Article/ArticleFrontendService.php` — `articleDetails()`, `news()`, `pageArticles()`, `pageArticlesCount()`, `generateTableOfContents()`, `generateHeadersIds()`
- `Domain/Layouts/LayoutsFrontendService.php` — `activeLayout()`, `articleLayout()`, `productLayout()`, `categoryLayout()`, `defaultLayout()`, `categoryDefaultLayout()`
- Testy: 5 plików testowych

**ZMIANA:**
- `front/factory/Banners`, `Menu`, `Pages`, `Articles`, `Layouts` → fasady

**BUG FIX:** `cms\Layout::__get()` — poprawka referencji do `$this->data`

---

### Etap: Promotion Engine (rozbicie circular dependency)

**Cel:** Przeniesienie silnika promocji do Domain. Rozbicie cyklicznej zależności `shop\Promotion ↔ front\factory\ShopPromotion`.

**Obecna zależność cykliczna:**
```
shop\Promotion::find_promotion() → front\factory\ShopPromotion::promotion_type_XX()
front\factory\ShopPromotion::promotion_type_XX() → shop\Product::is_product_on_promotion()
```

**Rozwiązanie:** Wszystko w jednym serwisie `PromotionFrontendService`.

**NOWE:**
- `Domain/Promotion/PromotionFrontendService.php`:
  - `getActivePromotions()` (z `shop\Promotion`)
  - `applyPromotions(array $basket)` (z `shop\Promotion::find_promotion()`)
  - `private applyType01..05()` (z `front\factory\ShopPromotion`)
  - `private isProductOnPromotion()` (z `shop\Product` — proste zapytanie)
- Testy: `PromotionFrontendServiceTest` (7 typów promocji + brak aktywnych)

**ZMIANA:**
- `shop/Promotion` → fasada do `PromotionFrontendService::applyPromotions()`
- `front/factory/ShopPromotion` → fasada

---

### Etap: Product Frontend Service

**Cel:** Migracja `front\factory\ShopProduct` i statycznych metod `shop\Product` do Domain.

**NOWE:**
- `Domain/Product/ProductFrontendService.php`:
  - Z `front\factory\ShopProduct`: `productDetails()` (~330 linii z Redis), `promotedProducts()`, `topProducts()`, `newProducts()`, `productUrl()`, `getMinimalPrice()`, `isProductActive()`, `getProductSku()`, `getProductEan()`, `productImage()`, `productWp()`, `randomProducts()`, `warehouseMessageZero()`, `warehouseMessageNonzero()`
  - Z `shop\Product` (statyczne): `isProductOnPromotion()`, `getProductImg()`, `getProductUrl()`, `addVisit()`, `productSetsForBasket()`, `searchProductsByName()`, `searchProductByNameAjax()`
- Testy: `ProductFrontendServiceTest`

**ZMIANA:**
- `front/factory/ShopProduct` → fasada
- `shop/Product` statyczne metody → fasady do `ProductFrontendService`

**UWAGA:** Konstruktor `shop\Product`, `getFromCache()`, `calculate_basket_product_price()` — zostają na razie (instancyjne, używane w szablonach). Migracja w etapie "Product Instance + Cache".

---

### Etap: Client Authentication (Security Fix)

**Cel:** Migracja `front\factory\ShopClient` + NAPRAWIENIE hardcoded password bypass.

**NOWE:**
- `Domain/Client/ClientFrontendService.php`:
  - `login()` — **BEZ** bypassa 'Legia1916', z opcjonalną migracją md5 → password_hash
  - `signup()`, `registerConfirm()`, `sendPasswordRecovery()`, `resetPassword()`
  - `clientDetails()`, `clientOrders()`
  - CRUD adresów: `saveAddress()`, `deleteAddress()`, `getAddresses()`, `markAddressAsCurrent()`
- Testy: `ClientFrontendServiceTest` — **KRYTYCZNY test: login z 'Legia1916' NIE przechodzi**

**ZMIANA:**
- `front/factory/ShopClient` → fasada
- `front/controls/ShopClient` → deleguje do serwisu

---

### Etap: Transport, Payment, Coupon Frontend Services

**Cel:** Frontend serwisy dla transportu, płatności i kuponów.

**NOWE:**
- `Domain/Transport/TransportFrontendService.php` — `transportMethods()` (filtrowanie WP, free delivery), `transportCost()`, `transportDetails()`
- `Domain/PaymentMethod/PaymentMethodFrontendService.php` — `activePaymentMethods()`, `paymentMethodsByTransport()`, `paymentMethodDetails()`
- `Domain/Coupon/CouponFrontendService.php` — `validateCoupon()`, `applyCoupon()`, `markCouponUsed()`
- Testy: 3 pliki testowe

**ZMIANA:**
- `front/factory/ShopTransport` → fasada
- `front/factory/ShopCoupon` → fasada
- `shop/Coupon` → fasada
- `shop/Transport` → fasada

---

### Etap: Basket Service

**Cel:** Migracja logiki koszyka do `Domain\Basket\BasketService`.

**NOWE:**
- `Domain/Basket/BasketService.php`:
  - `addProduct()`, `removeProduct()`, `changeQuantity()`, `increaseQuantity()`, `decreaseQuantity()`
  - `summaryPrice()`, `countProducts()`, `countProductsText()`
  - `validateStock()` (z `shop\Basket::check_product_quantity_in_stock()`)
  - `calculateProductPrice()` (z `shop\Product::calculate_basket_product_price()` ~112 linii)
- Testy: `BasketServiceTest` (pricing z promocjami/kuponami, walidacja stanów)

**ZMIANA:**
- `front/factory/ShopBasket` → fasada
- `front/controls/ShopBasket` — wewnętrznie używa `BasketService`
- `shop/Basket` → fasada
- `shop/Product::calculate_basket_product_price()` → fasada

---

### Etap: shop\Product Instance + Cache

**Cel:** Refaktoring konstruktora `shop\Product` i `getFromCache()`.

**NOWE:**
- `Domain/Product/ProductDataLoader.php`:
  - `loadFull(int $productId, ?string $langId, ?string $permutationHash)` — ładowanie pełnych danych produktu
  - `loadCached()` — Redis cache wrapper
- Testy: `ProductDataLoaderTest`

**ZMIANA:**
- `shop/Product` — konstruktor i `getFromCache()` delegują do `ProductDataLoader`
- ArrayAccess interface zachowany (szablony dalej używają `$product->property`)

---

### Etap: Order Creation Frontend Service

**Cel:** Migracja `front\factory\ShopOrder::basket_save()` (~180 linii).

**NOWE:**
- `Domain/Order/OrderFrontendService.php`:
  - `createOrder()` — tworzenie zamówienia z koszyka (walidacja, kalkulacja cen, insert, redukcja stanów, obsługa kuponu, wysyłka emaili, auto-status dla pobrania)
  - `generateOrderNumber()` — format YYYY/MM/NNN
  - `orderDetails()`, `orderIdByHash()`, `orderHashById()`
- Testy: `OrderFrontendServiceTest`

**ZMIANA:**
- `front/factory/ShopOrder` → fasada

---

### Etap: Payment Webhook Service

**Cel:** Wyodrębnienie webhooków płatności z `front\controls\ShopOrder`.

**NOWE:**
- `Domain/Payment/PaymentWebhookService.php`:
  - `processTpay(array $params)` — weryfikacja tPay
  - `processPrzelewy24(array $params)` — weryfikacja przez API + walidacja kwoty
  - `processHotpay(array $params)` — walidacja SHA256 hash
  - `private markOrderPaid()` — wspólna logika (update status + email + Apilo sync)
- Testy: `PaymentWebhookServiceTest`

**ZMIANA:**
- `front/controls/ShopOrder` — webhooki stają się thin wrappers

**POPRAWA:** Zamiana `file_put_contents('tpay.txt')` na `\Log::save_log()`

---

### Etap: shop\Order Instance + Apilo Service

**Cel:** Refaktoring `shop\Order` instancyjnych metod + wyodrębnienie integracji Apilo.

**NOWE:**
- `Domain/Integrations/ApiloService.php`:
  - `syncPayment()`, `syncStatus()`, `processQueue()`
  - `private queueSync()`, `private loadQueue()`, `private saveQueue()`
- `Domain/Order/OrderOperationsService.php`:
  - `setAsPaid()`, `setAsUnpaid()`, `updateStatus()`, `sendStatusChangeEmail()`, `resendConfirmationEmail()`
- Testy: `ApiloServiceTest`, `OrderOperationsServiceTest`

**ZMIANA:**
- `shop/Order` instancyjne metody → fasady do `OrderOperationsService`
- Konstruktor i ArrayAccess bez zmian

---

### Etap: Frontend App + Controllers (DI layer)

**Cel:** Stworzenie `front\App` (wzorowanego na `admin\App`) z mapą kontrolerów i DI.

**NOWE:**
- `autoload/front/App.php` — `render()`, `handleAjax()`, `getControllerFactories()` (DI wiring)
- `autoload/front/Controllers/ShopBasketController.php` — DI z `BasketService`, `ProductFrontendService`
- `autoload/front/Controllers/ShopOrderController.php` — DI z `OrderFrontendService`, `PaymentWebhookService`
- `autoload/front/Controllers/ShopClientController.php` — DI z `ClientFrontendService`
- Testy: 3 pliki testowe kontrolerów

**ZMIANA:**
- `front/controls/ShopBasket`, `ShopOrder`, `ShopClient` → delegują do nowych kontrolerów

---

### Etap: Site Layout Engine

**Cel:** Refaktoring `front\view\Site::show()` (~600 linii) na testowalny `LayoutEngine`.

**NOWE:**
- `autoload/front/View/LayoutEngine.php`:
  - `resolveLayout(array $page, array $params)` — wybór layoutu (product > category > article > page > default)
  - `processPatterns(string $html, array $context)` — zamiana tagów szablonowych
  - Osobne prywatne metody: `replaceCategories()`, `replaceProducts()`, `replaceMenus()`, `replaceLanguageTags()`, `replaceBanners()`, `replaceArticles()`, `replaceContainers()`, `replaceMetaTags()`, etc.
- Testy: `LayoutEngineTest`

**ZMIANA:**
- `front/view/Site::show()` → thin wrapper na `LayoutEngine`

---

### Etap: Entry Point Unification

**Cel:** Ujednolicenie bootstrapu `index.php` i `ajax.php`.

**NOWE:**
- `autoload/front/Bootstrap.php` — `init()` (autoloader, config, sesja, DB, lang/settings)
- `autoload/front/PostProcessor.php` — ekstrakcja DOM manipulacji z `index.php` (GTM, Facebook Pixel, WebP, lazy loading)

**ZMIANA:**
- `index.php` → uproszczony: `Bootstrap::init()` → `App::render()` → `PostProcessor::process()`
- `ajax.php` → uproszczony: `Bootstrap::init()` → `App::handleAjax()`

---

### Etap: Legacy Cleanup

**Cel:** Finalne porządki.

**USUNIĘCIE:**
- Martwy kod `eval()` dla `[PHP]` bloków (jeśli nieużywany)
- `class.Cache.php` (legacy file-based) jeśli wszystkie użycia przeniesione na `CacheHandler`
- Pusta klasa `front\view\ShopTransport`

**ZMIANA:**
- Dodanie `@deprecated` do wszystkich metod-fasad w `front/factory/`, `front/controls/`, `shop/`
- PHPDoc do wszystkich nowych klas Domain z `@since`
- Aktualizacja `tests/bootstrap.php`
- BUG FIX: `shop\Search` — typo `shop\Produt` → `shop\Product`
- BUG FIX: `front\factory\Newsletter::newsletter_unsubscribe()` — poprawka SQL

---

## Podsumowanie

| Etap | Zakres | Priorytet | Nowe klasy Domain | Testy |
|------|--------|-----------|-------------------|-------|
| Settings + Languages | Fundamenty | FUNDAMENT | 2 serwisy | 2 |
| Category Frontend | Kategorie | WYSOKI | 1 serwis | 1 |
| Banners/Menu/Pages/Articles/Layouts | Treści | ŚREDNI | 5 serwisów | 5 |
| Promotion Engine | Promocje | KRYTYCZNY | 1 serwis | 1 |
| Product Frontend | Produkty | KRYTYCZNY | 1 serwis | 1 |
| Client/Auth (security fix) | Klienci | KRYTYCZNY | 1 serwis | 1 |
| Transport/Payment/Coupon | Dostawa/Płatności | WYSOKI | 3 serwisy | 3 |
| Basket Service | Koszyk | WYSOKI | 1 serwis | 1 |
| Product Instance + Cache | Produkt cache | ŚREDNI | 1 loader | 1 |
| Order Creation | Zamówienia | WYSOKI | 1 serwis | 1 |
| Payment Webhooks | Webhooki | WYSOKI | 1 serwis | 1 |
| Order Instance + Apilo | Zamówienie + Apilo | ŚREDNI | 2 serwisy | 2 |
| Frontend App + Controllers | DI layer | WYSOKI | App + 3 kontrolery | 3 |
| Layout Engine | Silnik layoutu | ŚREDNI | 1 engine | 1 |
| Entry Point Unification | Entry points | ŚREDNI | Bootstrap + PostProcessor | 1 |
| Legacy Cleanup | Porządki | NISKI | — | — |

**Łącznie:** 16 etapów, ~24 nowe klasy Domain, ~25 plików testowych

### Wzorce do przestrzegania (z migracji admin)
- Konstruktor DI z `$db` (medoo)
- CacheHandler (Redis) dla cachingu — unifikacja (usunięcie starego `Cache`)
- Fasady w `shop\*` i `front\factory\*` dla kompatybilności wstecznej
- Testy PHPUnit z mockami medoo
- Namespace `\Domain\*` → `autoload/Domain/*/`
- Namespace `\front\Controllers\` → `autoload/front/Controllers/`
- **Klasy Domain sa wspolne dla admin i frontendu** — NIE tworzymy osobnych FrontendService/AdminService. Metody frontendowe (z cache Redis) dodajemy do istniejacych repozytoriow/serwisow Domain. Klasy sa ladowane lazy (instancja tworzona dopiero przy wywolaniu), wiec nie wplywaja na wydajnosc.

### Weryfikacja po każdym etapie
1. `composer test` (pełny suite PHPUnit)
2. Manualne sprawdzenie frontendu: strona główna, kategoria, produkt, koszyk, zamówienie
3. Sprawdzenie AJAX: dodawanie do koszyka, zmiana transportu, kupon
4. Sprawdzenie webhooków płatności (tPay, Przelewy24, Hotpay)