update

.paul/docs/DB_SCHEMA.md

@@ -1,3 +1,228 @@
-# DB_SCHEMA
+# DB_SCHEMA
 
-> Schemat bazy danych — tabele, kolumny, FK, indeksy.
+## 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)