Externe Änderungen

product.stock ist eine Ausgabe. Stockly leitet sie nach jedem Vorgang aus den Regalen ab und überschreibt, was es dort vorfindet. Eine Integration, die sie schreibt, spricht nicht mit dem Lager; sie liefert sich ein Rennen mit der nächsten Neuberechnung und verliert.

Diese Seite ist der Mechanismus. Die Einstellung, der Registerbildschirm und die tägliche Zusammenfassung sind unter externe Bestandsänderungen für die beschrieben, die sie bedienen.

Wie eine fremde Änderung nachgewiesen wird

Jede rechtmäßige Änderung aktualisiert product.stock und einen Verfügbarkeitsschatten in derselben Transaktion. Weil das Paar sich atomar bewegt, kann eine unter der Zeilensperre des Aufrufers beobachtete Abweichung kein Zwischenzustand sein, weil nichts auf halbem Weg sein kann. Jemand hat das Feld geschrieben, ohne es dem Modul zu sagen.

Der Schatten wird gepflegt, ob die Erkennung eingeschaltet ist oder nicht, die Erkennung später einzuschalten beginnt also auf einer aktuellen Grundlinie statt an einer Klippe falscher Meldungen.

Zwei Erkennungspunkte, mit unterschiedlichem Zeitpunkt:

Quellwert	Geschrieben von	Abgefangen
dal	der Admin-API, der Administrationsoberfläche, jeder DAL-Schreibung	sofort, aus der Produktschreibung
sql	rohem SQL unmittelbar in die Datenbank	verzögert, beim nächsten Bestandsereignis des Produkts — genau in dem Moment, in dem das Modul es sonst stillschweigend überschriebe

Das Bedrohungsmodell ist eine falsch konfigurierte Integration, keine Sabotage aus der Datenbank heraus. Ein fremdes System, das auch die Schattentabelle fälscht, liegt außerhalb der Reichweite jedes Mechanismus auf Anwendungsebene.

Die drei Reaktionen

Die Richtlinie ist eine Einstellung, und ihre Werte erreichen die Integration wortgleich in policyApplied:

Wert	Was mit der Zahl geschieht
off	keine Erkennung und kein Nachweis: eine DAL-Änderung wird als gewöhnliche Bestandskorrektur übernommen, eine Roh-SQL-Änderung von der nächsten Neuberechnung überschrieben
correct	die externe Zahl gewinnt — die Differenz wird ins Lager gebucht und der Vorfall erfasst
restore	die Regale gewinnen — es wird nichts gebucht, das Feld wird aus den Regalen neu geschrieben, und die verworfene Änderung wird erfasst

Unter correct landet die Differenz als echte Bewegung, die Korrektur steht also wie jede andere in der Historie des Produkts. Unter restore gibt es keine Bewegung, denn es hat sich körperlich nichts geändert.

Hinweis

Eine bekannte blinde Stelle, dokumentiert statt behoben: Das Löschen eines Lagers berechnet jedes betroffene Produkt in einem Zug neu. Eine fremde Änderung, die zu diesem Zeitpunkt dort steht, wird ohne erfassten Vorfall überschrieben: dieselbe Wirkung wie restore, nur ohne die Zeile.

Benachrichtigt werden

p2lab_stockly.external_stock_write_detected greift einmal je Produkt und Arbeitseinheit, nach dem Commit:

Schlüssel
productId
expectedValue	was Stockly hielt
foundValue	was der Schreiber hinterlassen hat
delta	die Abweichung
source	dal oder sql
policyApplied	off, correct oder restore

Anders als jedes andere Event im Katalog trägt dieses skalare Werte statt des gemeinsamen Umschlags, weil es für den Flow Builder und für Webhooks des App Systems geschrieben ist, und deshalb kann ein Händler es auch ohne eine Zeile Code an eine Mail hängen.

Das Register

p2lab_stockly_external_stock_incident, eine Zeile je Erkennung:

Feld
productId
expectedAtp	die Zahl, zu der sich die Regale addieren
foundValue	die Zahl, die jemand geschrieben hat
delta
source	dal oder sql
policyApplied	correct oder restore
userId, integrationId	wer sie geschrieben hat, wenn die Änderung über die API kam

integrationId ist die nützliche für einen Integrationsautor: Sie benennt die API-Integration, welche die Änderung vorgenommen hat, und das macht aus einer vagen Meldung über überschriebene Bestände ein bestimmtes Zugangsdatum.

Lesen Sie es wie jede Entität (/api/search/p2lab-stockly-external-stock-incident); eine steigende Zahl bei einer integrationId ist eine eigene Meldung wert.

Zeilen überleben das Löschen des Produkts, mit Absicht: Ein Prüfpfad, der mit seinem Gegenstand verschwindet, ist kein Prüfpfad. Sie werden nach einem Jahr entfernt.

Was stattdessen zu tun ist

Sie wollen	Aufrufen
Ware einbuchen	warehouse/stock/add
Ware ausbuchen	warehouse/stock/remove
eine Zahl auf eine gezählte korrigieren	warehouse/stock/count
ein product.stock reparieren, das jemand bereits überschrieben hat	warehouse/stock/sync-product/{productId}

Jedes davon hinterlässt eine Journalzeile, berechnet die veröffentlichte Zahl neu und aktualisiert den Schatten — und das ist der ganze Unterschied zwischen einer Bestandsänderung und einer Bestandsänderung, die später niemand erklären kann.

Besitzt ein externes System die Zahlen wirklich, ist das eine berechtigte Architektur: Setzen Sie die Richtlinie auf correct und lassen Sie es ausdrücklich gewinnen, mit jeder Überschreibung erfasst. Nie richtig ist es, das Feld bei ausgeschalteter Erkennung zu schreiben und anzunehmen, dass es hielt.

Weiter

• Bestand in einen Lagerplatz legen — der unterstützte Weg
• Das Bestandsmodell — warum das Feld überhaupt abgeleitet ist
• Integritätsprüfung — bereits bestehende Abweichungen aufräumen