Przejdź do głównej zawartości

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​

EncjaPrzeznaczenie
WarehouseDane magazynu (nazwa, kod, flaga aktywności, kontakt, adres)
StockLevelWiersz (product_id, variant_id, warehouse_id) z on_hand i reserved
WarehouseChannelAssignmentPrzypisanie wiele-do-wielu magazyn ↔ kanał sprzedaży; najwyżej jedno is_default = true na kanał
InventoryThresholdProgi przedziałów dostępności w zakresie global / category / product
StockAllocationJeden wiersz na parę (order_item, warehouse) — skąd realizowana jest pozycja i podstawa zwolnienia rezerwacji
AvailabilityNotificationZapis klienta albo anonimowego adresu e-mail na powiadomienie o ponownej dostępności

Ustawienia modułu​

Dziewięć kluczy w grupie inventory:

KodTypWartość domyślnaUwagi
inventory.enabledbooleantrueWłą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_modestringbandSposób pokazywania stanu w storefroncie: exact / band / available_or_not
inventory.fulfilment_strategystringdefault_firstany / default_first / lowest_stock_first / highest_stock_first / defined_order
inventory.fulfilment_strategy_warehouse_orderjson[]Kolejność magazynów dla strategii defined_order
inventory.global_threshold_highnumber100Łączny stan, od którego produkt ma „wysoki stan”
inventory.global_threshold_mediumnumber20Od którego ma „średni stan”
inventory.global_threshold_lownumber1Od którego ma „niski stan”; poniżej jest niedostępny
inventory.low_stock_alert_recipient_emailstring''Gdy puste, używana jest zmienna środowiskowa INVENTORY_LOW_STOCK_RECIPIENT
inventory.allow_negative_stockbooleanfalseGlobalna 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żkaUprawnieniePrzeznaczenie
GET /api/v1/admin/inventoryinventory:readWskaź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/levelsinventory:readLista produktów z łącznym stanem, rozbiciem na magazyny i przedziałem dostępności
PUT /api/v1/admin/inventory/levelsinventory:writeUstawienie bezwzględnego stanu dla (productId, warehouseId, variantId?); emituje inventory.adjusted.v1
PUT /api/v1/admin/inventory/warehouse-low-stock-thresholdsinventory:writeProgi niskiego stanu dla par (produkt, magazyn)
GET /api/v1/admin/inventory/low-stockinventory:readProdukty, których łączny stan jest równy lowStockThreshold albo niższy
GET /api/v1/admin/inventory/thresholdsinventory:readOdczyt progów przedziałów dostępności — globalnych, dla kategorii i dla produktów
PATCH /api/v1/admin/inventory/thresholdsinventory:writeAktualizacja progów
GET /api/v1/admin/warehouses[/:id]inventory:readLista i szczegóły magazynów
POST/PATCH/DELETE /api/v1/admin/warehouses[/:id]inventory:writeZarządzanie magazynami; usunięcie jest odrzucane, gdy magazyn jest domyślny dla kanału albo ma stan
GET /api/v1/admin/sales-channels/:id/warehousesinventory:readMagazyny przypisane do kanału
POST/PATCH/DELETE /api/v1/admin/sales-channels/:id/warehouses[/:assignmentId]inventory:writePrzypisanie kanał ↔ magazyn, z najwyżej jednym magazynem domyślnym na kanał
GET /api/v1/admin/inventory/availability-notificationsinventory:readPodgląd kolejki powiadomień o ponownej dostępności
PATCH /api/v1/admin/inventory/availability-notifications/:idinventory:writeAnulowanie zapisu na powiadomienie
POST /api/v1/admin/inventory/importinventory:writeImport stanów z CSV (?dryRun=true sprawdza dane bez zapisu)
PUT /api/v1/admin/inventoryinventory:writeWycofywany zapis w pierwotnym modelu z jednym stanem; deleguje do StockLevelService.setOnHand dla magazynu Default
GET /api/v1/admin/inventory/legacyinventory:readWycofywana lista w pierwotnym modelu z jednym stanem

Trasy publiczne​

Metoda i ścieżkaOdbiorcaPrzeznaczenie
GET /api/v1/storefront/inventory/display-modeanonimowyJak kanał sprzedaży żądania pokazuje stan
GET /api/v1/storefront/inventory/stock/:idanonimowyStan 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-availableanonimowy lub zalogowanyZapisuje adres e-mail podany w treści żądania na powiadomienie o ponownej dostępności
POST /api/v1/catalog/products/:id/notify-when-availablezalogowany klientZapisuje 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żkaPrzeznaczenieZastępstwo
PUT /api/v1/admin/inventoryUstawienie bezwzględnego stanu dla (productId, variantId?) w magazynie DefaultPUT /api/v1/admin/inventory/levels, który przyjmuje jawne warehouseId
GET /api/v1/admin/inventory/legacyPłaskie wiersze stock_levels, od najnowszych, z opcjonalnym filtrem productIdGET /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ślnie true) — gdy false, storefront traktuje produkt jako zawsze dostępny, a koszyk i zamówienia w ogóle pomijają rezerwację.
  • backorderEnabled (domyślnie false) — gdy true, a inventory.allow_negative_stock jest włączone dla kanału, checkout przy zerowym stanie jest akceptowany; powstały wiersz stock_allocations ma is_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 strategii defined_order uporzą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:

StrategiaDziałanie
anyWybiera pierwszy magazyn (według kodu, leksykograficznie), który w całości pokrywa pozycję
default_firstJedyna strategia, która dzieli pozycję między magazyny; najpierw magazyn domyślny, potem pozostałe według kodu
lowest_stock_firstMagazyn z najmniejszym wystarczającym available (remisy według kodu)
highest_stock_firstMagazyn z największym available (remisy według kodu)
defined_orderPrzechodzi 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-00000000d017
  • DEFAULT_WAREHOUSE_CODE = default

Obie są eksportowane z packages/modules/inventory/src/backend/entities/warehouse.entity.ts.