Kassen-Dashboard: ein Kassensystem mit Shopify synchronisieren

Ein 504 beim ersten Upload des kompletten Katalogs. Kein Codefehler: Der Reverse-Proxy des VPS brach einen legitim langen Sync per Timeout ab. Zuerst musste ich feststellen, dass der Server gar kein Standard-nginx-Layout nutzt. Er läuft über aaPanel, und die echte Konfiguration liegt in einem vom Panel generierten Proxy-Verzeichnis, das ein grep über /etc/nginx nie gefunden hätte. Erst dann ließ sich der Fix anwenden: ein gezielter Timeout-Override in einer Datei, die die Panel-Oberfläche nicht überschreibt.

Drei Vertragsbrüche der Shopify Admin API in Folge. Ein Feld, das laut Doku richtig aussah (ignoreCompareQuantity), existierte am Input-Typ gar nicht. Das Feld, das es ersetzte (changeFromQuantity), ist eine verpflichtende Compare-and-Set-Vorbedingung, keine optionale Metainformation. Danach lehnte die Mutation jede Anfrage ab, weil eine neu vorgeschriebene @idempotent-Direktive fehlte. Jedes Problem diagnostizierte ich aus dem rohen GraphQL-Fehlerpayload und Shopifys Changelog. Der Fix für das zweite ist selbst defensives Design: Der Sync holt den Live-Bestand direkt vor dem Schreiben, statt einem lokalen Cache zu vertrauen, und schützt so nebenbei vor dem Überschreiben eines Verkaufs, der dazwischen passiert ist.

Ein Cache, der ein Produkt für immer scheitern lassen konnte. Ein Produkt wurde in Shopify gelöscht und neu angelegt, ein Routinevorgang, und bekommt dabei eine neue interne ID. Der Sync hatte keinen Weg zurück von „die gecachte ID existiert nicht mehr“, außer bei jedem künftigen Lauf für diese SKU zu scheitern. Jetzt heilt er sich selbst: Ein „nicht gefunden“ leert gezielt den veralteten Cache und fällt auf eine frische Suche per SKU zurück. Eine falsche ID wird so nicht zur dauerhaften, stillen Lücke im Katalog.

Erfolg melden für einen Schreibvorgang, der nie stattfand. Ein fehlgeschlagener Shopify-Write speicherte kurzzeitig trotzdem den beabsichtigten neuen Bestand lokal, bevor der Write bestätigt war. Ein vorübergehender Fehler konnte so dazu führen, dass der Cache-Check im nächsten Lauf einen falschen Treffer sah, den Wiederholungsversuch still übersprang und „Erfolg“ meldete für einen Bestand, den Shopify nie erhielt. Behoben: Lokaler Zustand wird nur noch nach einem bestätigten Remote-Write geschrieben.

Windows SmartScreen auf dem Rechner einer nicht-technischen Nutzerin. Bei der ersten Übergabe der .exe traf sie die Reibung, die ein unsigniertes Binary erwarten lässt: Sie sah einen blockierenden Sicherheitsdialog, las ihn als „der Computer lässt mich nicht“ und schloss ihn. Den Dialog blind zu diagnostizieren, anhand einer zweizeiligen Nachricht auf Ungarisch und ohne das Binary selbst ausführen zu können, hieß: die Anleitung in ihrer Sprache und für ihren konkreten Bildschirm zu schreiben, kein generisches Troubleshooting-Dokument.