shopPRO/docs/PROJECT_STRUCTURE.md

# Struktura Projektu shopPRO

Dokumentacja struktury projektu shopPRO do szybkiego odniesienia.

## System Cache (Redis)

### Klasy odpowiedzialne za cache

#### RedisConnection
- **Plik:** `autoload/class.RedisConnection.php`
- **Opis:** Singleton zarządzający połączeniem z Redis
- **Metody:**
  - `getInstance()` - pobiera instancję połączenia
  - `getConnection()` - zwraca obiekt Redis

#### CacheHandler
- **Plik:** `autoload/class.CacheHandler.php`
- **Opis:** Handler do obsługi cache Redis
- **Metody:**
  - `get($key)` - pobiera wartość z cache
  - `set($key, $value, $ttl = 86400)` - zapisuje wartość do cache
  - `exists($key)` - sprawdza czy klucz istnieje
  - `delete($key)` - usuwa pojedynczy klucz
  - `deletePattern($pattern)` - usuwa klucze według wzorca

#### Klasa S (pomocnicza)
- **Plik:** `autoload/class.S.php`
- **Metody cache:**
  - `clear_redis_cache()` - czyści cały cache Redis (flushAll)
  - `clear_product_cache(int $product_id)` - czyści cache konkretnego produktu

### Wzorce kluczy Redis

#### Produkty
```
shop\product:{product_id}:{lang_id}:{permutation_hash}
```
- Przechowuje zserializowany obiekt produktu
- TTL: 24 godziny (86400 sekund)
- Klasa: `shop\Product::getFromCache()` - `autoload/shop/class.Product.php:121`

#### Opcje ilościowe produktu
```
\shop\Product::get_product_permutation_quantity_options:{product_id}:{permutation}
```
- Przechowuje informacje o ilości i komunikatach magazynowych
- Klasa: `shop\Product::get_product_permutation_quantity_options()` - `autoload/shop/class.Product.php:549`

#### Zestawy produktów
```
\shop\Product::product_sets_when_add_to_basket:{product_id}
```
- Przechowuje produkty często kupowane razem
- Klasa: `shop\Product::product_sets_when_add_to_basket()` - `autoload/shop/class.Product.php:316`

## Integracje z systemami zewnętrznymi (CRON)

### Plik: `cron.php`

#### Apilo
- **Aktualizacja pojedynczego produktu:** synchronizacja cen i stanow
  - Czestotliwosc: Co 10 minut
- **Synchronizacja cennika:** masowa aktualizacja cen z Apilo
  - Czestotliwosc: Co 1 godzine

**Uwaga:** Integracje Sellasist i Baselinker zostaly usuniete w ver. 0.263.

## Panel Administratora

### Routing
- Główny katalog: `admin/`
- Template główny: `admin/templates/site/main-layout.php`
- Kontrolery (nowe): `autoload/admin/Controllers/`
- Kontrolery legacy (fallback): `autoload/admin/controls/`

### Przycisk "Wyczyść cache"
- **Lokalizacja UI:** `admin/templates/site/main-layout.php:172`
- **JavaScript:** `admin/templates/site/main-layout.php:235-274`
- **Endpoint AJAX:** `/admin/settings/clear_cache_ajax/`
- **Kontroler:** `autoload/admin/Controllers/SettingsController.php:43-60`
- **Działanie:**
  1. Pokazuje spinner "Czyszczę cache..."
  2. Czyści katalogi: `temp/`, `thumbs/`
  3. Wykonuje `flushAll()` na Redis
  4. Pokazuje "Cache wyczyszczony!" przez 2 sekundy
  5. Przywraca stan początkowy

## Struktura katalogów

```
shopPRO/
├── admin/                      # Panel administratora
│   ├── templates/              # Szablony widoków
│   └── layout/                 # Zasoby CSS/JS/ikony
├── autoload/                   # Klasy autoloadowane
│   ├── admin/                  # Klasy panelu admin
│   │   ├── Controllers/        # Nowe kontrolery DI
│   │   ├── controls/           # Kontrolery legacy (fallback)
│   │   └── factory/            # Fabryki/helpery
│   ├── Domain/                 # Repozytoria/logika domenowa
│   ├── front/                  # Klasy frontendu
│   │   └── factory/            # Fabryki/helpery
│   └── shop/                   # Klasy sklepu
├── docs/                       # Dokumentacja techniczna
├── libraries/                  # Biblioteki zewnętrzne
├── temp/                       # Cache tymczasowy
├── thumbs/                     # Miniatury zdjęć
└── cron.php                    # Zadania CRON
```

## Baza danych

### Główne tabele produktów
- `pp_shop_products` - produkty główne
- `pp_shop_products_langs` - tłumaczenia produktów
- `pp_shop_products_images` - zdjęcia produktów
- `pp_shop_products_categories` - kategorie produktów
- `pp_shop_products_custom_fields` - pola własne produktów

### Tabele integracji
- Kolumny w `pp_shop_products`:
  - `apilo_product_id`, `apilo_product_name`, `apilo_get_data_date`
- Tabele ustawien:
  - `pp_shop_apilo_settings` (key-value)
  - `pp_shop_shoppro_settings` (key-value)

### Tabele checkout
- `pp_shop_payment_methods` - metody platnosci sklepu (mapowanie `apilo_payment_type_id`)
- `pp_shop_transports` - rodzaje transportu sklepu (mapowanie `apilo_carrier_account_id`)
- `pp_shop_transport_payment_methods` - powiazanie metod transportu i platnosci

Pelna dokumentacja tabel: `DATABASE_STRUCTURE.md`

## Konfiguracja

### Redis
- Konfiguracja: `config.php` (zmienna `$config['redis']`)
- Parametry: host, port, password

### Autoload
- Funkcja: `__autoload_my_classes()` w `cron.php:6`
- Wzorzec: `autoload/{namespace}/class.{ClassName}.php`

## Klasy pomocnicze

### \S (autoload/class.S.php)
Główna klasa helper z metodami:
- `seo($val)` - generowanie URL SEO
- `normalize_decimal($val, $precision)` - normalizacja liczb
- `send_email()` - wysyłanie emaili
- `delete_dir($dir)` - usuwanie katalogów
- `htacces()` - generowanie .htaccess i sitemap.xml

### Medoo
- Plik: `libraries/medoo/medoo.php`
- Zmienna: `$mdb`
- ORM do operacji na bazie danych

## Najważniejsze wzorce

### Namespace'y
- `\admin\Controllers\` - nowe kontrolery panelu admin (DI)
- `\admin\controls\` - kontrolery legacy (fallback)
- `\Domain\` - repozytoria/logika domenowa
- `\admin\factory\` - helpery/fabryki admin
- `\front\factory\` - helpery/fabryki frontend
- `\shop\` - klasy sklepu (Product, Order, itp.)

### Cachowanie produktów
```php
// Pobranie produktu z cache
$product = \shop\Product::getFromCache($product_id, $lang_id, $permutation_hash);

// Czyszczenie cache produktu
\S::clear_product_cache($product_id);

// Czyszczenie całego cache
\S::clear_redis_cache();
```

## Refaktoryzacja do Domain-Driven Architecture

### Nowa struktura (w trakcie migracji)
```
autoload/
├── Domain/                    # Nowa warstwa biznesowa (namespace \Domain\)
│   ├── Product/
│   │   └── ProductRepository.php
│   ├── Banner/
│   │   └── BannerRepository.php
│   ├── Settings/
│   │   └── SettingsRepository.php
│   ├── Cache/
│   │   └── CacheRepository.php
│   ├── Article/
│   │   └── ArticleRepository.php
│   ├── User/
│   │   └── UserRepository.php
│   ├── Languages/
│   │   └── LanguagesRepository.php
│   ├── Layouts/
│   │   └── LayoutsRepository.php
│   ├── Newsletter/
│   │   └── NewsletterRepository.php
│   ├── Scontainers/
│   │   └── ScontainersRepository.php
│   ├── Dictionaries/
│   │   └── DictionariesRepository.php
│   ├── Pages/
│   │   └── PagesRepository.php
│   ├── Integrations/
│   │   └── IntegrationsRepository.php
│   ├── Promotion/
│   │   └── PromotionRepository.php
│   ├── Coupon/
│   │   └── CouponRepository.php
│   ├── ShopStatus/
│   │   └── ShopStatusRepository.php
│   ├── Transport/
│   │   └── TransportRepository.php
│   └── ...
├── admin/
│   ├── Controllers/                # Nowe kontrolery (namespace \admin\Controllers\)
│   ├── class.Site.php              # Router: nowy kontroler → fallback stary
│   ├── controls/                   # Stare kontrolery (niezależny fallback)
│   ├── factory/                    # Stare helpery (niezależny fallback)
│   └── view/                       # Widoki (statyczne - bez zmian)
├── shop/                           # Legacy - fasady do Domain
└── front/factory/                  # Legacy - stopniowo migrowane
```

**Aktualizacja 2026-02-14 (ver. 0.268):**
- Dodano modul domenowy `Domain/PaymentMethod/PaymentMethodRepository.php`.
- Dodano kontroler DI `admin/Controllers/ShopPaymentMethodController.php`.
- Modul `/admin/shop_payment_method/*` dziala na nowych widokach (`payment-methods-list`, `payment-method-edit`).
- Usunieto legacy: `autoload/admin/controls/class.ShopPaymentMethod.php`, `autoload/admin/factory/class.ShopPaymentMethod.php`, `autoload/admin/view/class.ShopPaymentMethod.php`, `admin/templates/shop-payment-method/view-list.php`.

**Aktualizacja 2026-02-14 (ver. 0.269):**
- Dodano modul domenowy `Domain/Transport/TransportRepository.php`.
- Dodano kontroler DI `admin/Controllers/ShopTransportController.php`.
- Modul `/admin/shop_transport/*` dziala na nowych widokach (`transports-list`, `transport-edit`).
- Usunieto legacy: `autoload/admin/controls/class.ShopTransport.php`, `autoload/admin/view/class.ShopTransport.php`, `admin/templates/shop-transport/view-list.php`.
- `admin\factory\ShopTransport` i `front\factory\ShopTransport` przepiete na repozytorium.

### Routing admin (admin\Site::route())
1. Sprawdź mapę `$newControllers` → utwórz instancję z DI → wywołaj
2. Jeśli nowy kontroler nie istnieje (`class_exists()` = false) → fallback na `admin\controls\`
3. Stary kontroler jest NIEZALEŻNY od nowych klas (bezpieczny fallback)

### Dependency Injection
Nowe klasy używają **Dependency Injection** zamiast `global` variables:
```php
// STARE
global $mdb;
$quantity = $mdb->get('pp_shop_products', 'quantity', ['id' => $id]);

// NOWE
$repository = new \Domain\Product\ProductRepository($mdb);
$quantity = $repository->getQuantity($id);
```

## Testowanie (tylko dla deweloperów)

**UWAGA:** Pliki testów NIE są częścią aktualizacji dla klientów!

### Narzędzia
- **PHPUnit 9.6.34** - framework testowy
- **test.bat** - uruchamianie testów
- **composer.json** - autoloading PSR-4

Pelna dokumentacja testow: `TESTING.md`

---
*Dokument aktualizowany: 2026-02-14*