varsite / catalog

v0.11.0 2026-08-11 08:02 UTC

Requires

• php: ^8.3
• illuminate/database: ^12.0|^13.0
• illuminate/http: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• varsite/platform: ^0.11

proprietary

Published on Packagist.org on 2026-08-11 08:03 UTC

README

Katalog produktów dla Varsite Platform — uniwersalna domena produktowa.

composer require varsite/catalog
php artisan varsite:module install catalog

Uniwersalność zamiast sklepu

Model jest neutralny handlowo: opisuje rzecz, którą można prezentować lub oferować, i nie zakłada koszyka, zamówienia ani procesu sprzedaży. Ten sam katalog obsłuży sklep internetowy, katalog B2B, ERP, aplikację mobilną i zwykłą stronę produktową. Logika handlowa należy do modułów, które dojdą później (Inventory, Orders, Payments).

Model domenowy

Element	Rola
Product	korzeń agregatu: tożsamość, opis, status prezentacji
ProductVariant	to, co realnie oferowane: SKU, cena, atrybuty — wewnątrz agregatu
Category	taksonomia, osobny agregat o własnym cyklu życia
Money	obiekt wartości: liczba całkowita w groszach + waluta ISO

Cena nigdy jako float — arytmetyka zmiennoprzecinkowa na pieniądzach daje błędy klasy „0.1 + 0.2 ≠ 0.3". Waluta jest częścią kwoty, bo cena bez waluty nie ma znaczenia poza jednym rynkiem.

Publiczne API (kontrakt API-first)

GET /api/v1/catalog/products?category={slug}
GET /api/v1/catalog/products/{slug}
GET /api/v1/catalog/categories

Kontrakt jest projektowany dla konsumentów, nie jako odbicie panelu: nie wydaje identyfikatorów wewnętrznych ani statusów roboczych, a warianty zwraca w postaci gotowej do prezentacji.

{ "data": {
  "slug": "lampa-stolowa", "name": "Lampa stołowa",
  "category": { "slug": "oswietlenie", "name": "Oświetlenie" },
  "image": { "url": "…", "mime_type": "image/jpeg" },   // null bez modułu Media
  "variants": [
    { "sku": "LAMP-1", "price": { "amount": 12900, "currency": "PLN", "formatted": "129.00" },
      "attributes": {}, "available": true }
  ]
} }

Zależność od modułu Media — opcjonalna

Zdjęcie jest identyfikatorem, nie kluczem obcym. Katalog sięga po nie przez kontrakt rdzenia MediaLibrary; bez modułu Media pole jest puste, a katalog działa dalej. composer remove varsite/media nie psuje sklepu.

Warianty bez Extension Bundle

Warianty to osobny zasób panelu z filtrem po produkcie, nie zagnieżdżona kolekcja w formularzu produktu. Ta decyzja pozwoliła zrealizować pełną edycję w modelu deklaratywnym — i przy setkach wariantów jest wygodniejsza niż jeden rozdęty formularz.

Granice domeny

Poza katalogiem, świadomie: magazyn, zamówienia, klienci, płatności, wysyłka, promocje. Test przynależności: własny cykl życia + własne reguły biznesowe = osobny moduł. Projekt domeny: docs/DOMAIN-CATALOG.md.