# DB_SCHEMA

## Scope

Dokument opisuje praktyczny schema map dla `shopPRO`:
- najwazniejsze tabele i relacje,
- grupowanie po domenach biznesowych,
- kluczowe kolumny i indeksy, ktore maja znaczenie runtime,
- mapowanie tabela -> warstwa Domain.

Pelna lista tabel i historyczne notki migracyjne:
`docs/DATABASE_STRUCTURE.md` (source of truth dla detali kolumnowych).

## Konwencje globalne

- ORM: Medoo (`$mdb`)
- Prefix tabel: `pp_`
- Primary key: najczesciej `id` (INT AUTO_INCREMENT)
- Jezyki/translations: zwykle tabele `*_langs` z kluczem `lang_id`
- Wiele-do-wielu: tabele lacznikowe `*_products`, `*_payment_methods`, itp.

## Core commerce

### Produkty

- `pp_shop_products`
  - core produktu i wariantu (`parent_id` dla kombinacji)
  - ceny (`price_brutto`, `price_brutto_promo`), stany (`quantity`)
  - flagi (`status`, `archive`, `promoted`)
- `pp_shop_products_langs`
  - nazwy/opisy per jezyk
- `pp_shop_products_images`
  - obrazy produktu
- `pp_shop_products_categories`
  - przypisania produkt-kategoria
- `pp_shop_products_attributes`
  - przypisania wariantu do wartosci cech
- `pp_shop_products_custom_fields`
  - dodatkowe pola produktu

Warstwa: `Domain\Product\ProductRepository`, `Domain\Attribute\AttributeRepository`.

### Kategorie

- `pp_shop_categories`
  - drzewo kategorii (`parent_id`), status, kolejnosc
- `pp_shop_categories_langs`
  - tresci SEO i opisy kategorii

Warstwa: `Domain\Category\CategoryRepository`.

### Zamowienia

- `pp_shop_orders`
  - dane klienta "w momencie zakupu", summary, status/platnosc, daty
  - kluczowe pole integracyjne: `updated_at` (polling API)

Warstwa: `Domain\Order\OrderRepository`, `Domain\Order\OrderAdminService`.

### Klienci

- `pp_shop_clients`
  - konto klienta i dane adresowe/logowania (uzywane przez ClientRepository)

Warstwa: `Domain\Client\ClientRepository`.

## Slowniki i checkout

### Platnosci

- `pp_shop_payment_methods`
  - status, opis, mapowanie Apilo
  - limity kwotowe: `min_order_amount`, `max_order_amount`
  - COD flag: `is_cod`

Warstwa: `Domain\PaymentMethod\PaymentMethodRepository`.

### Transport

- `pp_shop_transports`
  - koszt, status, limity, mapowanie Apilo
- `pp_shop_transport_payment_methods`
  - relacja transport <-> platnosc (N:M)

Warstwa: `Domain\Transport\TransportRepository`.

### Statusy zamowien

- `pp_shop_statuses`
  - statusy predefiniowane, kolor, mapowanie Apilo

Warstwa: `Domain\ShopStatus\ShopStatusRepository`.

## Marketing i merch

### Promocje i kupony

- `pp_shop_promotion`
  - reguly promocji, daty aktywnosci, warunki i zakresy (JSON categories)
- `pp_shop_coupon`
  - kupony, licznik uzyc, ograniczenia

Warstwa: `Domain\Promotion\PromotionRepository`, `Domain\Coupon\CouponRepository`.

### Producenci

- `pp_shop_producer`
- `pp_shop_producer_lang`

Warstwa: `Domain\Producer\ProducerRepository`.

### Zestawy produktow

- `pp_shop_product_sets`
- `pp_shop_product_sets_products`

Warstwa: `Domain\ProductSet\ProductSetRepository`.

### Cechy i wartosci

- `pp_shop_attributes`
- `pp_shop_attributes_langs`
- `pp_shop_attributes_values`
- `pp_shop_attributes_values_langs`

Warstwa: `Domain\Attribute\AttributeRepository`.

## CMS i frontend content

### Artykuly

- `pp_articles`
- `pp_articles_langs`
- `pp_articles_pages`
- `pp_articles_images`
- `pp_articles_files`

Warstwa: `Domain\Article\ArticleRepository`.

### Strony i layouty

- `pp_pages`
- `pp_layouts`
- `pp_layouts_pages`
- `pp_layouts_categories`

Warstwa: `Domain\Pages\PagesRepository`, `Domain\Layouts\LayoutsRepository`.

### Banery i kontenery statyczne

- `pp_banners`
- `pp_banners_langs`
- `pp_scontainers`
- `pp_scontainers_langs`

Warstwa: `Domain\Banner\BannerRepository`, `Domain\Scontainers\ScontainersRepository`.

## Ustawienia i system

### Ustawienia aplikacji

- `pp_settings`
  - klucze globalne (w tym `api_key` dla REST API)
- `pp_shop_apilo_settings`
- `pp_shop_shoppro_settings`

Warstwa: `Domain\Settings\SettingsRepository`, `Domain\Integrations\IntegrationsRepository`.

### Jezyki i tlumaczenia

- `pp_langs`
- `pp_langs_translations`

Warstwa: `Domain\Languages\LanguagesRepository`.

### Uzytkownicy admina

- `pp_users`
  - login, hash hasla, status
  - pola 2FA (`twofa_*`)

Warstwa: `Domain\User\UserRepository`.

## Routing i URL mapping

- `pp_routes`
  - regex `pattern` -> `destination` query string
  - obsluguje trasy encji oraz trasy systemowe
  - cache Redis: `pp_routes:all`

Runtime wykorzystanie:
- `index.php`
- `Shared\Helpers\Helpers::htacces()`
- repozytoria encji generujace/odswiezajace trasy.

## Kolejka cron

- `pp_cron_jobs`
  - status processing pipeline (`pending`, `processing`, `completed`, `failed`, `cancelled`)
  - retry/backoff: `attempts`, `max_attempts`, `scheduled_at`
  - indeksy:
    - `(status, priority, scheduled_at)`
    - `(job_type)`
    - `(status)`
- `pp_cron_schedules`
  - harmonogramy okresowe (`interval_seconds`, `next_run_at`)
  - indeks `(enabled, next_run_at)`

Warstwa: `Domain\CronJob\CronJobRepository`, `Domain\CronJob\CronJobProcessor`.

## Najwazniejsze relacje (FK logiczne)

- Produkt glowny -> wariant: `pp_shop_products.parent_id -> pp_shop_products.id`
- Produkt -> tlumaczenia: `pp_shop_products_langs.product_id -> pp_shop_products.id`
- Produkt -> kategoria: `pp_shop_products_categories.product_id -> pp_shop_products.id`
- Kategoria -> tlumaczenia: `pp_shop_categories_langs.category_id -> pp_shop_categories.id`
- Zamowienie -> klient: `pp_shop_orders.client_id -> pp_shop_clients.id` (opcjonalne)
- Transport <-> platnosc: `pp_shop_transport_payment_methods`
- Cecha -> wartosci -> warianty: `attributes -> values -> shop_products_attributes`
- Producent -> tlumaczenia: `pp_shop_producer_lang.producer_id -> pp_shop_producer.id`
- Kontener -> tlumaczenia: `pp_scontainers_langs.container_id -> pp_scontainers.id`

## Uwaga operacyjna

Ten dokument jest skrotem architektonicznym.
Przy zmianach SQL/migracji zawsze aktualizuj rownolegle:
1. `docs/DATABASE_STRUCTURE.md` (detal techniczny)
2. `.paul/docs/DB_SCHEMA.md` (mapa domenowa i impact runtime)