Magazyn (inventory)
Moduł stanów magazynowych w wielu magazynach: dane magazynów, liczniki stanu fizycznego (on-hand) i
zarezerwowanego (reserved) dla każdej pary (product, warehouse), przypisanie magazynów do kanałów
sprzedaży, alerty o niskim stanie, przedziały dostępności wyświetlane w sklepie, sprzedaż na
zamówienie (backorder), produkty bez śledzenia stanu, powiadomienia o dostępności, import CSV oraz
zapis alokacji stock_allocations dla każdej pozycji zamówienia.
Moduł zastępuje pierwotny model z jednym wspólnym stanem. Migracja
20260503T182812_inventory_workflow.ts zachowuje pierwotną tabelę
stock_levels, ale rozszerza unikalność do (product_id, variant_id, warehouse_id), tworzy magazyn
Default ze stałym UUID 00000000-0000-4000-8000-00000000d017 i przypisuje do niego każdy aktywny
kanał sprzedaży przez nową tabelę warehouse_channel_assignments.
Encje modułu
| Encja | Przeznaczenie |
|---|---|
Warehouse | Dane magazynu (nazwa, kod, flaga aktywności, kontakt, adres) |
StockLevel | Wiersz (product_id, variant_id, warehouse_id) z on_hand i reserved |
WarehouseChannelAssignment | Przypisanie wiele-do-wielu magazyn ↔ kanał sprzedaży; najwyżej jedno is_default = true na kanał |
InventoryThreshold | Progi przedziałów dostępności w zakresie global / category / product |
StockAllocation | Jeden wiersz na parę (order_item, warehouse) — skąd realizowana jest pozycja i podstawa zwolnienia rezerwacji |
AvailabilityNotification | Zapis klienta albo anonimowego adresu e-mail na powiadomienie o ponownej dostępności |
Ustawienia modułu
Dziewięć kluczy w grupie inventory:
| Kod | Typ | Wartość domyślna | Uwagi |
|---|---|---|---|
inventory.enabled | boolean | true | Włączanie i wyłączanie modułu przez operatora (dla całej platformy); wyłączenie zachowuje każdy magazyn, stan i oczekujące powiadomienie |
inventory.display_mode | string | band | Sposób pokazywania stanu w storefroncie: exact / band / available_or_not |
inventory.fulfilment_strategy | string | default_first | any / default_first / lowest_stock_first / highest_stock_first / defined_order |
inventory.fulfilment_strategy_warehouse_order | json | [] | Kolejność magazynów dla strategii defined_order |
inventory.global_threshold_high | number | 100 | Łączny stan, od którego produkt ma „wysoki stan” |
inventory.global_threshold_medium | number | 20 | Od którego ma „średni stan” |
inventory.global_threshold_low | number | 1 | Od którego ma „niski stan”; poniżej jest niedostępny |
inventory.low_stock_alert_recipient_email | string | '' | Gdy puste, używana jest zmienna środowiskowa INVENTORY_LOW_STOCK_RECIPIENT |
inventory.allow_negative_stock | boolean | false | Globalna zgoda na zamówienia poniżej stanu, dla kanału sprzedaży: dopóki jest false, żaden produkt nie przyjmuje zamówienia poniżej dostępnego stanu, niezależnie od flagi backorderEnabled |
API publiczne
Trasy administracyjne są chronione przez inventory:read (odczyt) i inventory:write (zapis) —
własne kody modułu od 2026-08-29. Wcześniej wszystkie 21 tras wymagało orders:read i
catalog:write; zobacz Uprawnienia niżej.
Tabela wymienia wszystkie 21 tras administracyjnych. Do 2026-08-29 wymieniała dziesięć i pomijała zapis progów dla par (produkt, magazyn) oraz obie trasy zachowane dla zgodności wstecznej — to ten rodzaj luki, który każda z czterech wcześniejszych poprawek uprawnień znajdowała na stronie modułu.
| Metoda i ścieżka | Uprawnienie | Przeznaczenie |
|---|---|---|
GET /api/v1/admin/inventory | inventory:read | Wskaźniki na stronę główną: śledzone produkty, łączny stan, liczba produktów niedostępnych i z niskim stanem, sumy dla magazynów |
GET /api/v1/admin/inventory/levels | inventory:read | Lista produktów z łącznym stanem, rozbiciem na magazyny i przedziałem dostępności |
PUT /api/v1/admin/inventory/levels | inventory:write | Ustawienie bezwzględnego stanu dla (productId, warehouseId, variantId?); emituje inventory.adjusted.v1 |
PUT /api/v1/admin/inventory/warehouse-low-stock-thresholds | inventory:write | Progi niskiego stanu dla par (produkt, magazyn) |
GET /api/v1/admin/inventory/low-stock | inventory:read | Produkty, których łączny stan jest równy lowStockThreshold albo niższy |
GET /api/v1/admin/inventory/thresholds | inventory:read | Odczyt progów przedziałów dostępności — globalnych, dla kategorii i dla produktów |
PATCH /api/v1/admin/inventory/thresholds | inventory:write | Aktualizacja progów |
GET /api/v1/admin/warehouses[/:id] | inventory:read | Lista i szczegóły magazynów |
POST/PATCH/DELETE /api/v1/admin/warehouses[/:id] | inventory:write | Zarządzanie magazynami; usunięcie jest odrzucane, gdy magazyn jest domyślny dla kanału albo ma stan |
GET /api/v1/admin/sales-channels/:id/warehouses | inventory:read | Magazyny przypisane do kanału |
POST/PATCH/DELETE /api/v1/admin/sales-channels/:id/warehouses[/:assignmentId] | inventory:write | Przypisanie kanał ↔ magazyn, z najwyżej jednym magazynem domyślnym na kanał |
GET /api/v1/admin/inventory/availability-notifications | inventory:read | Podgląd kolejki powiadomień o ponownej dostępności |
PATCH /api/v1/admin/inventory/availability-notifications/:id | inventory:write | Anulowanie zapisu na powiadomienie |
POST /api/v1/admin/inventory/import | inventory:write | Import stanów z CSV (?dryRun=true sprawdza dane bez zapisu) |
PUT /api/v1/admin/inventory | inventory:write | Wycofywany zapis w pierwotnym modelu z jednym stanem; deleguje do StockLevelService.setOnHand dla magazynu Default |
GET /api/v1/admin/inventory/legacy | inventory:read | Wycofywana lista w pierwotnym modelu z jednym stanem |
Trasy publiczne
| Metoda i ścieżka | Odbiorca | Przeznaczenie |
|---|---|---|
GET /api/v1/storefront/inventory/display-mode | anonimowy | Jak kanał sprzedaży żądania pokazuje stan |
GET /api/v1/storefront/inventory/stock/:id | anonimowy | Stan produktu z łącznym stanem liczonym tylko z magazynów przypisanych do kanału wywołującego (dodatkowo zawężonych do listy dozwolonych magazynów jego organizacji, jeśli jest ustawiona); 404 dla produktu, którego wywołujący nie może zobaczyć, oceniane w kanale i języku żądania (tagi Accept-Language od największej wagi q, każdy dopasowany do języków kanału, w przeciwnym razie język domyślny kanału) |
POST /api/v1/storefront/inventory/notify-when-available | anonimowy lub zalogowany | Zapisuje adres e-mail podany w treści żądania na powiadomienie o ponownej dostępności |
POST /api/v1/catalog/products/:id/notify-when-available | zalogowany klient | Zapisuje adres e-mail konta klienta na powiadomienie o ponownej dostępności |
Uprawnienia
inventory:read i inventory:write, należące do modułu od 2026-08-29.
Wcześniej wszystkie 21 tras administracyjnych wymagało kodów dwóch innych modułów — dziewięć odczytów
orders:read, a dwanaście zapisów catalog:write. Kto mógł edytować opis produktu, mógł tworzyć,
zmieniać nazwy i usuwać magazyny, nadpisywać stany, uruchamiać import CSV obejmujący stany wszystkich
produktów i przypisywać magazyny do kanałów sprzedaży lub je odłączać; a kto mógł czytać zamówienia,
mógł wyliczyć wszystkie magazyny i ich adresy. Żaden z tych kodów nie opisuje danych, do których daje
dostęp — a właśnie to rozstrzyga, kto jest właścicielem uprawnienia: osobno dla każdej trasy, a nie dla
modułu.
Nie ma migracji danych: rola, która miała dostęp do tych ekranów dzięki catalog:write albo
orders:read, musi jawnie dostać nowe kody na /admin-roles, gdzie manifest dodaje je
automatycznie. Przyznanie ich każdemu, kto ma stare kody, odtworzyłoby nadmierne uprawnienia, które
ten podział usuwa.
backend/test/contract/inventory/permission-authority.test.ts sprawdza oba kierunki i oba stare kody.
Wycofywane trasy
Dwie pierwotne trasy są starsze niż opisane wyżej API dla wielu magazynów i zawsze dotyczą magazynu Default utworzonego przy instalacji. Nic w platformie nie wywołuje żadnej z nich — żaden ekran panelu, żadne wywołanie klienta API panelu, żadne dane początkowe, żaden skrypt — więc istnieją wyłącznie dla własnych integracji wdrożeń. Nie opieraj na nich nowego kodu.
| Metoda i ścieżka | Przeznaczenie | Zastępstwo |
|---|---|---|
PUT /api/v1/admin/inventory | Ustawienie bezwzględnego stanu dla (productId, variantId?) w magazynie Default | PUT /api/v1/admin/inventory/levels, który przyjmuje jawne warehouseId |
GET /api/v1/admin/inventory/legacy | Płaskie wiersze stock_levels, od najnowszych, z opcjonalnym filtrem productId | GET /api/v1/admin/inventory/levels — zawiera wszystko oprócz variantId i updatedAt |
PUT deleguje teraz do tej samej usługi co PUT .../levels, więc emituje inventory.adjusted.v1 i
dla nieznanego produktu odpowiada 404, zamiast zapisywać dla niego wiersz stanu. Zostanie usunięty,
gdy logi dostępu z produkcji albo właściciel wdrożenia potwierdzą, że nic go nie wywołuje.
Flagi produktu
Pięć nowych pól w products, zapisywanych przez PATCH /api/v1/admin/catalog/products/:id; zakładka Magazyn edytora produktu przygotowuje je i zapisuje jednym przyciskiem Zapisz edytora, w changes.product żądania PUT /api/v1/admin/catalog/products/:id/scoped-values:
manageStock(domyślnietrue) — gdyfalse, storefront traktuje produkt jako zawsze dostępny, a koszyk i zamówienia w ogóle pomijają rezerwację.backorderEnabled(domyślniefalse) — gdytrue, ainventory.allow_negative_stockjest włączone dla kanału, checkout przy zerowym stanie jest akceptowany; powstały wierszstock_allocationsmais_backorder = true.lowStockThreshold— opcjonalna liczba całkowita; gdy null, produkt nie wywołuje alertów o niskim stanie.fulfilmentStrategy— nadpisanie strategii globalnej dla produktu.fulfilmentStrategyWarehouseOrder— przy strategiidefined_orderuporządkowana lista UUID magazynów.
Wyznaczanie przedziału dostępności
Wyszukiwanie progów w trzech zakresach (product, category[], global) odbywa się osobno dla każdego
klucza (high / medium / low), więc produkt może nadpisać tylko low, dziedzicząc high i medium z
wartości globalnych. Mechanizm znajduje się w
packages/modules/inventory/src/backend/services/threshold-resolver.ts i jest czystą funkcją w pełni
pokrytą testami jednostkowymi.
Mechanizm w packages/modules/inventory/src/backend/services/display-band-resolver.ts przypisuje
łącznemu stanowi jeden z przedziałów high | medium | low | out_of_stock | available (available to
osobna kategoria dla manageStock = false).
Strategie realizacji
Pięć strategii znajduje się w fulfilment-strategy-resolver.ts:
| Strategia | Działanie |
|---|---|
any | Wybiera pierwszy magazyn (według kodu, leksykograficznie), który w całości pokrywa pozycję |
default_first | Jedyna strategia, która dzieli pozycję między magazyny; najpierw magazyn domyślny, potem pozostałe według kodu |
lowest_stock_first | Magazyn z najmniejszym wystarczającym available (remisy według kodu) |
highest_stock_first | Magazyn z największym available (remisy według kodu) |
defined_order | Przechodzi skonfigurowaną listę magazynów w podanej kolejności; wygrywa pierwszy wystarczający |
Gdy backorderEnabled = true (i inventory.allow_negative_stock jest włączone), każda z pięciu strategii pozwala złożyć zamówienie, a brakująca część
jest oznaczana jako sprzedaż na zamówienie w magazynie pierwszego wyboru.
Składanie zamówienia zapisuje jeden wiersz stock_allocations dla każdej pozycji. Anulowanie
zamówienia oddaje ten stan: zwolnienie dla każdej alokacji zmniejsza stock_levels.reserved
i zapisuje released_at. Co je uruchamia i co się dzieje, gdy nie może się zakończyć, opisuje
następna sekcja.
Rezerwacja i zwolnienie
OrderService.placeOrder w transakcji składania zamówienia wykonuje SELECT … FOR UPDATE na każdym
wierszu (product_id, variant_id, warehouse_id). Magazyn domyślny jest wyznaczany z
warehouse_channel_assignments dla kanału sprzedaży zamówienia. Równoczesne zamówienia są
wykonywane po kolei; to, które przegra, kończy się 409 STOCK_UNAVAILABLE, chyba że produkt ma
backorderEnabled = true, a inventory.allow_negative_stock jest włączone dla kanału — wtedy pozycja przechodzi z is_backorder = true.
Zwolnienie jest działaniem następczym anulowania. Moduł orders zapisuje je w tej samej
transakcji co status anulowania, podejmuje próbę w tym samym żądaniu i ponawia je w tle, aż się
zakończy — nieudane zwolnienie nie zostawia więc już anulowanego zamówienia, które trzyma stan
i którego nic nie może zwolnić. Obok zapisywane jest zwolnienie limitu kredytowego; oba są od
siebie niezależne i niepowodzenie jednego nie wstrzymuje drugiego. Działania następcze,
powiadomienie na stronie zamówienia w panelu oraz polecenie dla operatora, które naprawia
zamówienia pozostawione przez wcześniejszą wersję, opisuje strona modułu orders.
Sam zapis należy do tego modułu: InventoryReservationApplyPort.releaseForOrderItems
(@endora-commerce/mod-inventory/ports) aktualizuje stock_allocations i stock_levels
w transakcji otwartej przez wywołującego, więc zmniejszenie licznika i zapis released_at to
jedna operacja. Jest idempotentny — już zwolnione wiersze są pomijane dzięki
released_at IS NULL, więc ponowienie niczego nie zwalnia drugi raz — i nigdy nie sprowadza
reserved poniżej zera.
Dopóki moduł inventory jest wyłączony, nic nie jest zwalniane: wiersze alokacji i liczniki
zostają dokładnie takie, jakie były, oczekiwanie nie liczy się jako nieudana próba, a zwolnienie
wykonuje się w ciągu minuty od ponownego włączenia modułu.
Powiadomienia o dostępności
Klient zapisuje się przez POST /api/v1/catalog/products/:id/notify-when-available (zalogowani
klienci; używany jest adres e-mail ich konta) albo przez
POST /api/v1/storefront/inventory/notify-when-available (anonimowo lub po zalogowaniu; adres e-mail
w treści żądania). Zapis jest
odrzucany z PRODUCT_UNMANAGED_STOCK, gdy produkt nie ma śledzenia stanu; ponowny zapis jest
idempotentny i zwraca istniejący wiersz.
AvailabilityWorker.attach(eventBus) nasłuchuje zdarzeń inventory.adjusted.v1. Powiadomienia są
rozsyłane tylko wtedy, gdy stan łączny we wszystkich magazynach zmienia się z 0 na > 0 — uzupełnienie
jednego magazynu, które nie podnosi stanu łącznego powyżej zera, nigdy nie wywołuje e-maili.
Zanim cokolwiek zostanie wysłane, rozsyłka raz odczytuje produkt i sprawdza jego stan globalny:
- Usunięty albo nieodnaleziony — nic nie jest wysyłane, a każdy oczekujący zapis na ten produkt zostaje anulowany. Usunięcia nie da się cofnąć, więc produkt nie wróci.
- Zarchiwizowany, wyłączony (
inactive) albo poza oknem publikacji — nic nie jest wysyłane, a zapisy pozostają w kolejce. Każdy z tych stanów da się odwrócić (przywrócenie, ponowne włączenie produktu, otwarcie okna), a subskrybent prosił o wiadomość, gdy będzie mógł kupić produkt. - W pozostałych przypadkach — każdy oczekujący subskrybent dostaje e-mail, a zapis zostaje oznaczony jako powiadomiony.
Sprawdzany jest wyłącznie stan globalny produktu. Nadpisania statusu, okna publikacji czy grupy odbiorców dla kanału sprzedaży albo języka nie są brane pod uwagę.
Zapis przechowuje kanał sprzedaży i język, w którym powstał: kanał, na który zostało rozwiązane
żądanie, oraz język wyznaczony z nagłówka Accept-Language spośród języków tego kanału (domyślny
język kanału, gdy kanał nie obsługuje żadnego z nich). E-mail podaje nazwę produktu taką, jaką
widział subskrybent — nazwę dla kanału i języka, a gdy jej nie ma, nazwę dla kanału, a w ostateczności
nazwę globalną. Zapis utworzony, zanim kanał i język były przechowywane, albo zapis, którego kanał
został później usunięty, dostaje nazwę globalną.
Sama wiadomość to e-mail transakcyjny Back in stock notification (availability_back_in_stock),
który operator edytuje w kreatorze e-maili jak każdy inny, i również on jest renderowany w kanale i
języku zapisu: nadpisanie kanału dla tego języka, a gdy go nie ma, nadpisanie globalne, a w
ostateczności treść domyślna (angielska i polska). Zapis utworzony, zanim kanał i język były
przechowywane, albo zapis, którego kanał został później usunięty, jest renderowany w domyślnym kanale
systemu i w jego domyślnym języku. Operator, który wyłączy ten e-mail, wyłącza go dla wszystkich
subskrybentów: zapisy zostają zużyte i nic nie jest wysyłane — także żaden tekst zastępczy.
Znane ograniczenie. Rozsyłka uruchamia się tylko wtedy, gdy stan rośnie od zera. Jeśli produkt zostanie przywrócony albo ponownie włączony, gdy ma już stan, oczekujący subskrybenci dostaną powiadomienie dopiero przy następnym wzroście stanu od zera.
Alerty o niskim stanie
LowStockAlertService.attach(eventBus) nasłuchuje tego samego zdarzenia. Gdy łączny stan spada
powyżej lowStockThreshold produktu do tej wartości albo poniżej, wysyłany jest jeden e-mail do
odbiorcy z inventory.low_stock_alert_recipient_email. Wykrywanie działa dla całej platformy, a nie
osobno dla kanałów.
Uzgadnianie przy starcie
WarehouseChannelReconciler wykonuje się przy starcie PO DefaultChannelReconciler, dzięki czemu
każdy aktywny kanał sprzedaży ma co najmniej jeden przypisany magazyn i dokładnie jedno przypisanie
is_default. Uzgadnianie jest idempotentne i obsługuje kanały utworzone po migracji.
Stałe
DEFAULT_WAREHOUSE_ID=00000000-0000-4000-8000-00000000d017DEFAULT_WAREHOUSE_CODE=default
Obie są eksportowane z packages/modules/inventory/src/backend/entities/warehouse.entity.ts.