Atrybuty Produktów

Atrybuty definiują cechy produktów, które klienci używają do filtrowania i wyboru wariantu (rozmiar, kolor, materiał).

Typy atrybutów

Typ	Opis	Przykład
TEXT	Wartość tekstowa	Materiał: "Bawełna 100%"
SELECT	Wybór z listy	Rozmiar: S, M, L, XL
COLOR	Kolor z swatchem	Kolor: #FF0000 (Czerwony)
NUMBER	Wartość liczbowa	Waga: 250g
BOOLEAN	Tak/Nie	Wegańskie: Tak

Tworzenie atrybutu

W panelu Sklep → Atrybuty → Nowy atrybut:

Pole	Opis
Nazwa	Nazwa atrybutu (np. "Rozmiar")
Kod	Wewnętrzny identyfikator (np. "size") - unikalny
Typ	TEXT, SELECT, COLOR, NUMBER, BOOLEAN
Wymagany	Czy atrybut jest obowiązkowy dla produktu
Filtrowalny	Czy atrybut pojawia się w filtrach na storefront
Widoczny	Czy wyświetlany na karcie produktu
Kolejność	Pozycja w liście atrybutów

Wartości atrybutu (dla SELECT/COLOR)

Dla typów SELECT i COLOR definiujesz listę dozwolonych wartości:

• Etykieta: Nazwa wyświetlana (np. "Czerwony")
• Wartość: Wartość techniczna (np. "red" lub "#FF0000")
• Kolejność: Pozycja na liście

Atrybuty a warianty

Warianty produktu powstają z kombinacji atrybutów:

• Produkt "T-shirt" z atrybutami Rozmiar (S,M,L) i Kolor (Biały, Czarny)
• = 6 wariantów: S/Biały, S/Czarny, M/Biały, M/Czarny, L/Biały, L/Czarny

Każdy wariant ma własną cenę, SKU i stan magazynowy.

Import atrybutów

Atrybuty przyjeżdżają razem z produktami przy imporcie z innego sklepu - system dopasowuje je po kodzie i sam tworzy brakujące wartości. Które źródła są obsługiwane i jak przygotować dane: Import danych.

Zestawy atrybutów - szablon konfiguratora dla wielu produktów

Gdy wiele produktów dzieli te same pola konfiguratora (np. wszystkie kopiarki mają „Materiały eksploatacyjne", „Podajnik ADF", „Finiszer"), nie definiujesz ich per produkt - tworzysz zestaw atrybutów i przypinasz go do produktów.

Katalog → Atrybuty → Zestawy atrybutów → Nowy zestaw:

Element	Opis
Nazwa zestawu	Np. „Konfigurator Kopiarki" - widzisz ją na produkcie w polu „Współdzielony szablon"
Atrybuty w zestawie	Zaznaczasz atrybuty globalne, które mają wejść do szablonu. Widoczne są tylko atrybuty globalne - pola tworzone na konkretnym produkcie (podstrona „Konfigurator dla klienta") nie mogą wejść do wspólnego szablonu
Kolejność na stronie produktu	Przeciągnij pola w listę - w tej kolejności zobaczy je klient w konfiguratorze i w tej kolejności zwraca je API sklepu

Przypisanie do produktu: na stronie produktu, w karcie „Więcej" (boczna kolumna) kliknij wiersz Konfigurator klienta - otworzy się podstrona „Konfigurator dla klienta" z polem „Szablon atrybutów (AttributeSet)". Wybierz zestaw - produkt dziedziczy wszystkie jego pola. Zostaw puste, jeśli produkt ma pola unikalne albo nie potrzebuje wspólnych.

Jak zmiany się propagują: edycja zestawu (dodanie pola, zmiana kolejności) działa od razu na wszystkich produktach z tym zestawem. Dostosowania per produkt (nadpisania opcji, ukrycia pól - sekcje niżej) zostają nietknięte. Usunięcie zestawu odpina go od produktów, ale nie kasuje definicji pól - możesz je spiąć w nowy zestaw.

Kategorie mogą wskazywać zestaw jako podpowiedź - przy przypisywaniu produktu do kategorii panel zasugeruje pasujący szablon, ale nigdy nie przypina go automatycznie.

Cechy produktu a konfigurator - dwa różne miejsca

Wartości atrybutów rozdzielają się na stronie produktu według tego, kto je wypełnia:

• Ty, w panelu (np. „Producent: Konica", „Gramatura papieru: 80g") - karta Specyfikacja w bocznej kolumnie. Karta jest edytorem: lista „cecha: wartość" z oznaczeniem cech ukrytych w sklepie; uchwyt przy wierszu zmienia kolejność (myszą albo klawiaturą: Spacja, strzałki, Spacja), ołówek otwiera okno jednej cechy (wartość - dla list wyboru pigułki z dopisaniem nowej opcji - widoczność w sklepie oraz „Usuń cechę"), a przycisk Dodaj cechę pod listą wybiera cechę z biblioteki sklepu (wpisanie nowej nazwy tworzy ją w locie) i od razu otwiera jej okno. Wartości zapisują się razem z produktem.
• Klient, przy zakupie - podstrona „Konfigurator dla klienta", opisana niżej.

Podstrona „Konfigurator dla klienta"

Z karty „Więcej" na stronie produktu wchodzisz na podstronę „Konfigurator dla klienta" (licznik przy wierszu mówi, ile pól klient wypełni przy zakupie). To jedno miejsce, w którym widzisz i dostosowujesz wszystko, co klient wypełni przy zakupie tego produktu:

• Współdzielony szablon - przypisany zestaw atrybutów (sekcja wyżej). Pola z szablonu widzisz na liście „Wspólne pola z szablonu" z podziałem na „Klient wypełnia przy zakupie" i „Sprzedawca wypełnia".
• Pola własne produktu - pola, które istnieją tylko na tym produkcie (np. akcesorium dostępne wyłącznie dla jednego modelu). Dodajesz je w tej zakładce; nie wchodzą do żadnego zestawu.
• Nadpisania opcji dla tego produktu - przycisk otwierający panel dostosowań (sekcja niżej).
• Duplikuj z… - kopiuje cały konfigurator z innego produktu-wzorca: przypisany szablon (jeśli ten produkt nie ma), pola własne z opcjami i pod-komponentami, nadpisania i ukrycia. Idealne, gdy dodajesz kolejny model tej samej rodziny - konfigurujesz jeden „wzorzec" i powielasz. Pola o zajętym kodzie są pomijane, więc powtórne kopiowanie niczego nie dubluje.

Nadpisywanie opcji per produkt

Problem który rozwiązujemy

Sprzedajesz 50 drukarek i każda ma pole konfiguratora "Finiszer" z tymi samymi 3 opcjami ("Wewnętrzny", "Zewnętrzny", "Zewnętrzny SD") - ale komponenty są różne: Finiszer dla Bizhub C258 to inny SKU niż Finiszer dla C308, bo mają osobne magazyny.

Dwa podejścia:

1. Duplikacja: dla każdej drukarki kopiujesz definicję atrybutu z 3 opcjami. 50 drukarek × 3 opcje = 150 wpisów ręcznie. Zmiana etykiety "Finiszer" na "Moduł wykańczający" = edytujesz 50 produktów osobno.
2. Dziedziczenie z nadpisaniami (DoSwiftly): 1 globalny atrybut "Finiszer" z domyślnymi opcjami → wszystkie drukarki go dziedziczą. Tylko produkty z innym komponentem tworzą override. 30/50 drukarek dzieli default = 60 override'ów zamiast 150.

Jak to działa

Podstrona „Konfigurator dla klienta" → przycisk „Nadpisania opcji dla tego produktu" otwiera panel z wszystkimi opcjami dostępnymi w tym produkcie.

Każda opcja pokazuje badge:

• ℹ️ Domyślny - opcja dziedziczy wszystko z globalnej definicji atrybutu
• ✏️ Nadpisano - ten produkt ma własne ustawienie (wariant/dopłata/ukrycie)

Akcje per opcja

Akcja	Co robi
Zmień powiązany wariant	Ustawia inny wariant komponentu dla tego produktu (np. FINISZER-WEW-C258 zamiast globalnego FINISZER-GENERIC)
Odłącz wariant	Opcja nie ma powiązanego wariantu w tym produkcie (mimo że globalnie ma) - przydatne gdy dany produkt nie ma fizycznego komponentu
Dopłata (override)	Własna cena dopłaty (gdy opcja nie jest powiązana z wariantem - wariant ma własną cenę)
☐ Ukryj tę opcję	Opcja niewidoczna w konfiguratorze dla tego produktu (np. drukarka nie wspiera tego Finishera)
↩️ Przywróć domyślny	Usuwa override - produkt wraca do 100% dziedziczenia z globalnej definicji

Kluczowa zasada - „Powiązany wariant wyklucza Dopłatę"

Kiedy opcja ma powiązany wariant (komponent z własnym SKU + stockiem + ceną), pole „Dopłata" znika z UI. Cena opcji pochodzi z ceny wariantu - dodawanie dopłaty duplikowałoby cenę, więc system blokuje to na 4 poziomach:

1. UI ukrywa pole Dopłata
2. Formularz czyści pole przy zmianie wariantu
3. Serwis czyści przed zapisem
4. Baza danych odrzuca zapis z oboma ustawionymi

Odłącz wariant vs Przywróć domyślny

Wyglądają podobnie, ale robią co innego:

	Odłącz wariant	Przywróć domyślny
Co się dzieje z override	Zostaje (z linkedVariant = null, jawnie)	Znika całkowicie
Dopłata (override)	Zostaje jeśli była	Znika
Ukrycie opcji (jeśli było)	Zostaje	Znika
Wynik storefront	Opcja widoczna bez wariantu (pure info, bez stocku)	Opcja wraca do globalnego wariantu

Zakładka „Nadpisania" (Atrybuty → Nadpisania)

Globalny widok wszystkich override'ów w sklepie:

• Łącznie nadpisań - ile aktywnych override'ów
• Najczęściej nadpisywane opcje - które opcje mają najwięcej wyjątków per-produkt
• Produkty z najwięcej nadpisań - które produkty są najbardziej dostosowane

Deep-link: na stronie atrybutu kliknij liczbę produktów nadpisujących → otworzy się filtrowany widok wszystkich drukarek z customowym Finiszer. Klik w produkt na tej liście prowadzi wprost na jego podstronę Konfigurator dla klienta.

Intencje atrybutu - "Do czego będzie służyć?"

Tworząc atrybut, najpierw wybierasz intencję biznesową (4 karty). Panel automatycznie konfiguruje pod spodem pola techniczne (kto wypełnia, jak wpływa na cenę, jakie typy dozwolone) - Ty nie musisz myśleć w kategoriach fillingMode/billingMode.

Intencja	Opis	Przykład
Metadane produktu	Stała cecha ustawiana przez Ciebie w panelu. Nie wpływa na cenę.	"Producent: Konica", "Gramatura papieru: 80g"
Opcja wyboru z dopłatą	Klient wybiera na stronie produktu, dopłata doliczona do ceny produktu.	"Kolor obudowy: Srebrny +200 zł", "Gwarancja rozszerzona +350 zł"
Komponent z magazynu	Klient wybiera komponent, system pobiera cenę z magazynu i rezerwuje stock. Osobna pozycja faktury (KSeF).	"Finiszer: Zewnętrzny SD", "Podstawa: DK-516"
Pole do wypełnienia	Klient wpisuje wartość przed dodaniem do koszyka (tekst, liczba, uwagi).	"Numer telefonu serwisu", "Uwagi do zamówienia"

Po wybraniu intencji reszta formularza (typ, opcje, zaawansowane) filtruje się pod ten kontekst. Intencja nie jest zapisywana w bazie - to tylko UI-ułatwienie; możesz później edytować poszczególne pola w "Opcjach zaawansowanych" (collapse na dole formularza).

Pole klasa podatkowa pojawia się tylko dla intencji "Opcja z dopłatą" gdy ustawisz "Osobna pozycja na fakturze" - zgodnie z art. 106e ustawy o VAT, BUNDLED surcharge dziedziczy VAT z produktu głównego (jedna stawka na pozycji).

Komponenty konfiguracji - linkedVariant jako pozycja zamówienia (D-N)

Gdy opcja atrybutu ma powiązany wariant (linkedVariant), staje się realnym komponentem magazynowym - backend zamawia go jako osobny OrderItem powiązany z produktem głównym (relacja parent–child).

Przykład: klient konfiguruje drukarkę Bizhub C258 + Finiszer SD + Podstawa DK-516 + Podajnik DF-632. W zamówieniu widnieje 4 pozycje (1 drukarka + 3 komponenty), każda z własnym SKU, stockiem, VAT-em i linią na fakturze.

Dlaczego tak:

• KSeF compliance - każdy komponent ma własną stawkę VAT (drukarka 23%, akcesoria 8%) - musi być osobną pozycją faktury (art. 106e ust. o VAT).
• Magazyn - każdy komponent ma własny stock + rezerwację - system blokuje checkout gdy którykolwiek komponent się skończy.
• Zwroty - refund zamówienia kaskaduje na parent + wszystkie children (proportional split), per-komponent audit w line_items.
• Raportowanie - sprzedaż komponentów jest widoczna osobno (sell-through per SKU), nie ginie w "bundle".

Cena komponentu = cena wariantu z magazynu (nie dopłata atrybutu). Invariant D-M zabezpiecza przed podwójnym rozliczeniem: opcja z linkedVariant nie może mieć surcharge (backend czyści automatycznie gdy linkujesz wariant).

Komponentem może być też pozycja bez śledzenia stanów - usługa montażu, wdrożenie, treść cyfrowa albo cokolwiek w sklepie, który w ogóle nie prowadzi magazynu. Taka opcja jest zawsze dostępna do wyboru (nie ma czego rezerwować), a mimo to trafia na zamówienie jako osobna pozycja z własną ceną i stawką VAT. W wyborze wariantu poznasz ją po plakietce „nie śledzi" zamiast liczby sztuk.

Zestawy pojawiają się na zamówieniu jako pozycja główna wraz z pozycjami składowymi - dzięki temu widzisz, co dokładnie kupił klient, a zwrot obejmuje cały zestaw.

Pod-komponenty - pole widoczne tylko przy wybranej opcji

Niektóre akcesoria mają sens wyłącznie w konkretnej konfiguracji: zestaw dziurkacza pasuje tylko do finiszera wewnętrznego, moduł faksu tylko do wybranej podstawy. Pod-komponent to pole konfiguratora, które klient zobaczy dopiero po wybraniu wskazanej opcji w polu nadrzędnym - wcześniej jest ukryte.

Jak dodać: w polu nadrzędnym (np. „Finiszer"), przy opcji, która ma odsłaniać dodatek (np. „Wewnętrzny"), kliknij „Dodaj pod-komponent". Sekcja pod-komponentów pojawia się wyłącznie przy polu o celu „Komponent fizyczny z magazynem" - drzewo dodatków budujesz z komponentów magazynowych; metadane, opcje z dopłatą i pola wypełniane przez klienta jej nie mają. Dialog daje dwie drogi:

Droga	Kiedy
Utwórz nowy pod-komponent	Nowe pole z własnymi komponentami do wyboru (np. zestaw dziurkacza z wariantem magazynowym) - powstaje od razu z warunkiem widoczności ustawionym na wybraną opcję
Podepnij istniejący atrybut	Masz już pole (np. pod-komponent wcześniej odpięty - celowo lub przypadkiem - albo inne pole konfiguratora) - zostanie powiązane z tą opcją

Zasady, których pilnuje system:

• Klient nie zapłaci za ukryty dodatek. Wybór w polu niewidocznym jest odrzucany przy dodawaniu do koszyka; zmiana opcji nadrzędnej (np. finiszer wewnętrzny → zewnętrzny) chowa pod-komponent i czyści jego wybór.
• „Wymagany" liczy się tylko, gdy pole jest widoczne. Pod-komponent oznaczony jako wymagany blokuje zakup wyłącznie wtedy, gdy klient faktycznie go widzi.
• Łańcuchy są dozwolone (pod-komponent pod-komponentu), ale bez pętli i bez nadmiernej głębokości - panel nie pozwoli zapisać warunku, który odwołuje się do samego siebie albo tworzy cykl.
• Warunki są wspólne dla wszystkich produktów korzystających z pola. Jeżeli jeden produkt ma mieć inaczej - ukryj pole na tym produkcie albo utwórz jego kopię jako pole własne produktu.

Pod-komponent z magazynu: komponenty do wyboru w pod-komponencie możesz powiązać z wariantami magazynowymi (jak w sekcji „Komponenty konfiguracji") - dostają wtedy cenę i stan z magazynu oraz własną pozycję na zamówieniu i fakturze.

Wielokrotny wybór - kilka opcji naraz

Przy obu celach cenowych („Opcja wyboru z dopłatą" i „Komponent z magazynu") możesz wybrać typ pola Pole wyboru wielokrotnego. Klient zaznacza wtedy tyle opcji, ile chce - zamiast wybierać jedną z listy.

Kiedy tego użyć: drukarka, do której da się dołożyć finiszer i podajnik i podstawę naraz. Albo zestaw z kilkoma niezależnymi dodatkami płatnymi. Jeżeli opcje wykluczają się wzajemnie (kolor obudowy, rozmiar), zostań przy liście wyboru albo przyciskach opcji.

Co to znaczy dla zamówienia:

• Każde zaznaczenie to osobna pozycja - na zamówieniu, na fakturze i w magazynie. Klient, który zaznaczył trzy komponenty, dostaje trzy pozycje z własnymi SKU, cenami i stawkami VAT.
• Dopłaty się sumują. Trzy zaznaczone dodatki po 200 zł to 600 zł doliczone do zamówienia.
• Każdy komponent rezerwuje swój stan magazynowy osobno. Jeżeli któregokolwiek zabraknie, całe zamówienie nie przechodzi - nic nie zostaje zablokowane „w połowie".
• Możesz oznaczyć kilka opcji jako domyślne - przy polu wielokrotnego wyboru to poprawne (przy liście wyboru domyślna jest tylko jedna).

Zmiana typu pola nie kasuje opcji. Lista wyboru, przyciski opcji i pole wielokrotnego wyboru trzymają te same opcje, więc możesz przełączać się między nimi bez utraty konfiguracji. Zamówienia złożone wcześniej zachowują to, co klient wtedy wybrał.