shopPRO/.paul/docs/DB_SCHEMA.md

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)