Korekty i zadania masowe

Cztery endpointy zapisu księgują po jednym ruchu. To, co niżej, księguje wiele naraz, albo księguje różnicę zamiast ilości, albo w ogóle nie kończy się w obrębie żądania.

Liczenie

POST warehouse/stock/count ACL: p2lab_stockly.execute_stock_operations

Ustawia miejsca na to, co ktoś policzył. Endpoint przyjmuje cały arkusz, nie jedną linię:

{
  "warehouseId": "0191f1…",
  "level": "aggregate",
  "comment": "Liczenie cykliczne, alejka A",
  "lines": [
    { "productId": "0191f3…", "binLocationId": "0191f2…", "countedQty": 22 },
    { "productId": "0191f8…", "binLocationId": "0191f2…", "countedQty": 0 }
  ]
}

level to aggregate (suma produktu w binie) albo batch. Na poziomie partii każda linia może nieść dodatkowo batchId, batchNumber i expiresAt.

Odpowiedź mówi, co każda linia faktycznie zmieniła:

{ "success": true, "results": [
  { "productId": "0191f3…", "binLocationId": "0191f2…", "batchId": null, "delta": -2 }
] }

Księgowana jest wyłącznie różnica, jako ruch typu count. Linia, której policzona liczba już się zgadza, nie księguje niczego i zgłasza delta: 0. Policzone zero jest w porządku, bo pusta półka musi dać się zaksięgować, ale liczba ujemna jest odrzucana przez P2LAB_STOCKLY__STOCK__NEGATIVE_COUNT: fizyczne liczenie nie ma kierunku.

Stan systemowy jest odczytywany ponownie w chwili księgowania, a nie w chwili liczenia, więc wynik równa się liczbie policzonej niezależnie od tego, ile zmieniło się w międzyczasie.

Uwaga

I właśnie dlatego ten endpoint jest niewłaściwy dla arkusza zatwierdzanego z opóźnieniem. Jeśli arkusz zostanie zatwierdzony kilka godzin po policzeniu, zapis wartości bezwzględnej po cichu wymaże każdą kompletację i każde odłożenie z tego okresu. Ekrany kontroli stanu księgują zamiast tego różnicę, zamrożoną w chwili skanu i prawdziwą niezależnie od tego, co ruszyło się później. Liczenie zatwierdzane po przeglądzie musi księgować różnice, a nie sumy.

Poprawianie partii

POST warehouse/stock/batch/{batchId}/correct ACL: p2lab_stockly.execute_stock_operations

Zmienia opis partii: jej numer, jej termin. Neutralne dla stanu: księguje ruch batch_correction o ilości zero, żeby historia produktu pokazywała, kiedy partia dostała nowy termin, nigdy nie sugerując, że ruszyły się sztuki.

Porządki

Metoda	Ścieżka	Co robi	ACL
POST	warehouse/stock/delete-empty	usuwa jeden pusty wiersz zapasu po stockId	p2lab_stockly.execute_stock_operations
POST	warehouse/stock/sync-product/{productId}	przelicza product.stock z półek	p2lab_stockly.execute_stock_operations

delete-empty odmawia z kodem 409 not_deletable, gdy wiersz wciąż trzyma stan albo sztuki zarezerwowane. Warunek siedzi w samej instrukcji usuwającej, więc wiersz, który przed chwilą nabrał znaczenia, nie zostanie usunięty przez żądanie będące już w drodze.

sync-product jest naprawą product.stock, który ktoś nadpisał. Nie potrzebuje ładunku i można go powtarzać bezpiecznie, ponieważ wyprowadza wartość, a nie koryguje ją o różnicę.

Zadania działające w tle

Cztery operacje odsyłają progressId natychmiast i pracują dalej w tle:

Metoda	Ścieżka	Uruchamia	ACL
POST	warehouse/stock/initialize/{warehouseId}	zasilenie wierszy zapasu z product.stock	p2lab_stockly.execute_stock_operations
POST	warehouse/stock/transfer-bulk	przelanie jednego magazynu w drugi	p2lab_stockly.execute_stock_operations
POST	warehouse/{warehouseId}/auto-assign-bins	nadanie binu każdemu nieprzypisanemu wierszowi	p2lab_stockly.execute_stock_operations
POST	warehouse/stock/sync-variants	zsumowanie stanu wariantów na produkt nadrzędny	p2lab_stockly.execute_stock_operations

Każda odpowiada {"success": true, "progressId": "0191f9…"}. Odpytuj o postęp:

GET /api/_action/p2lab-stockly/warehouse/stock/job/{progressId}/status

{ "progressId": "0191f9…", "status": "running",
  "totalItems": 4812, "processedItems": 1200, "error": null }

initialize i sync-variants mają własne trasy statusu, warehouse/stock/initialize/{progressId}/status i warehouse/stock/sync-variants/{progressId}/status, o tym samym kształcie odpowiedzi. Wszystkie trzy wymagają p2lab_stockly_task_progress:read, czyli innego uprawnienia niż to, które uruchomiło zadanie: system, który może patrzeć, nie jest automatycznie systemem, który może działać.

Nieznane progressId to 404.

Notatka

Zadania idą przez kolejkę komunikatów. Bez uruchomionego workera żądanie zostanie przyjęte, odeśle progressId i nigdy nie ruszy z miejsca, co wygląda jak zawieszenie, a jest brakiem workera.

Zasilanie magazynu

initialize kopiuje product.stock na bin unassigned magazynu i celowo jest wąskie w tym, czego dotyka:

• tylko produkty bez wariantów potomnych, ponieważ stan produktu nadrzędnego jest sumą jego dzieci, więc zasilenie obu policzyłoby wszystko dwa razy;
• produkty ze stanem większym od zera;
• produkty nieobecne jeszcze w żadnym magazynie, ponieważ product.stock jest sumą dla całej sieci, więc zasilenie artykułu, który już gdzieś leży, skopiowałoby całą jego ilość drugi raz, a następne przeliczenie zawyżyłoby liczbę.

To jednorazowy krok wdrożenia, nie synchronizacja. Drugie uruchomienie nie dokłada niczego i taki jest zamysł.

Uprawnienia pokrewne

p2lab_stockly.execute_stock_operations obejmuje zwykłą ścieżkę zapisu. Cztery operacje mają osobne bramki, bo są decyzjami, a nie ruchami:

Uprawnienie	Chroni
p2lab_stockly.commit_stocktake	zatwierdzenie albo wycofanie sesji kontroli stanu
p2lab_stockly.variance_approve	akceptację linii wstrzymanych przez bramkę rozbieżności
p2lab_stockly.reassign_bins	przeniesienie binu wraz z zapasem do innego magazynu
p2lab_stockly.run_integrity_fix	naprawę spójności i przejęcie otwartych zamówień

Integracja, która tylko księguje ruchy, nie powinna dostać żadnego z tych czterech.

Dalej

• Jak położyć zapas w binie
• Obce zapisy — co się dzieje, gdy ktoś to wszystko omija
• Kontrola stanu — liczenie oczami operatora