ApiCore/docs/superpowers/specs/2026-10-02-bestandsabgleich-design.md

Bestandsabgleich ApiCore ↔ Wabenhain — Design

Stand: 2026-10-02 · Betrifft: ApiCore (Backend + Frontend) und Wabenhain (Webshop)

1. Ziel

Es gibt eine Restmenge je Charge, und sie wird in ApiCore geführt. ApiCore und der Webshop zeigen jederzeit dieselbe Zahl:

• Ein bezahlter Webshop-Verkauf mindert den Rest in ApiCore.
• Storno nach Zahlung und erstattete Retoure buchen zurück.
• Eine Entnahme in ApiCore (Hofladen, Eigenbedarf, Bruch …) mindert sofort auch den Webshop-Bestand.
• ApiCore unterscheidet sichtbar zwischen abgefüllter bzw. hergestellter Menge und Rest.

Das gilt für alle Waren: Honig sowie Kerzen, Propolis-Produkte und andere Waren.

Entscheidungen

Frage	Entscheidung
Wann gilt eine Bestellung als verkauft?	Bei Zahlung (Status BEZAHLT). Unbezahlte Reservierungen erreichen ApiCore nie.
Woraus verkauft der Shop?	Aus dem gesamten Restbestand, nicht aus einem Kontingent.
Weg der Daten	Ereignisse in beide Richtungen + vollständiger Abgleich alle 10 Minuten (Variante A).
Honig im Shop	Ein Shop-Produkt je Abfüllung (Jahrgang), wie bisher.
Andere Waren im Shop	Ein Shop-Produkt je Artikel; Bestand = Summe aller Chargen; Abbuchung älteste Charge zuerst (FIFO).

Nicht Teil dieses Designs (eigene Specs, in dieser Reihenfolge)

1. Rohstoffe: Wachs und Propolis (Ernteform) mit eigenen Chargen und Beständen erfassen.
2. Herstellung: Ein Herstellungslauf verbraucht Rohstoff-Chargen und erzeugt eine Herstellungscharge (z. B. Wachs → Kerzen, Propolis → Tinktur/Salbe).

Dieses Design lässt dafür Platz: Die Herstellungscharge (Abschnitt 2.2) ist das spätere Ziel eines Herstellungslaufs; eine Tabelle "verbrauchte Rohstoffe" kann ohne Umbau daran hängen.

2. ApiCore

2.1 Artikelart

Neue Pflichtfelder am Artikel (Product):

• kind: BOTTLED_HONEY (Bestand je Abfüllung) oder MANUFACTURED (Bestand je Herstellungscharge).
• shopCategory: HONIG, KERZEN, PROPOLIS, SONSTIGES — Vorgabe für die Kategorie des Shop-Produkts.

Migration: bestehende Artikel bekommen BOTTLED_HONEY / HONIG. Ein Artikel mit Abfüllungen kann nicht auf MANUFACTURED umgestellt werden und umgekehrt (sonst wäre unklar, wo der Bestand liegt).

2.2 Herstellungscharge (neu)

ProductionBatch — Gegenstück zur Abfüllung für MANUFACTURED-Artikel:

Feld	Bedeutung
productId	Artikel (muss MANUFACTURED sein)
lotNumber	Chargennummer, eindeutig
date	Herstelldatum
quantity	hergestellte Stückzahl (Ganzzahl > 0)
bestBeforeDate	optional (z. B. Propolis-Tinktur)
notes	optional, intern

Seiten im Frontend: Liste, Anlegen, Detail — aufgebaut wie die Abfüllungs-Seiten.

2.3 Bewegungsbuch

BatchMovement — jede Bestandsänderung einer Charge, nie gelöscht:

Feld	Bedeutung
bottlingBatchId / productionBatchId	genau eines von beiden gesetzt (CHECK-Constraint)
type	SHOP_SALE, SHOP_RETURN, WITHDRAWAL, CORRECTION
quantity	Ganzzahl mit Vorzeichen: minus = raus, plus = rein
reason	bei WITHDRAWAL: HOFLADEN, EIGENBEDARF, BRUCH, PROBE, SONSTIGES
notes	optional
shopRequestId	gesetzt bei Buchungen aus dem Shop (siehe 2.4)
userId / apiKeyId	wer gebucht hat
createdAt	Zeitpunkt

Rest einer Charge = Ausgangsmenge (jarCount bzw. quantity) + Summe ihrer Bewegungen. Der Rest wird immer berechnet, nie gespeichert — er kann nicht auseinanderlaufen. Eine nachträgliche Korrektur von jarCount/quantity wirkt sofort auf den Rest.

Fehlbuchungen werden durch Gegenbuchung korrigiert, nicht durch Löschen. Eine Charge mit Bewegungen kann nicht gelöscht werden (409, "Bewegungen vorhanden").

2.4 Shop-Buchungen und Idempotenz

ShopStockRequest — eine Buchungsanfrage des Shops:

Feld	Bedeutung
externalId	eindeutig, vom Shop vergeben (ID seiner Warteschlangen-Zeile)
kind	SALE oder RETURN
bottlingBatchId / productId	Ziel: eine Abfüllung (Honig) oder ein Artikel (MANUFACTURED)
quantity	Stückzahl, immer positiv
reversesExternalId	bei RETURN: die externalId des Verkaufs, der zurückgebucht wird

Eine Anfrage erzeugt eine oder mehrere BatchMovement-Zeilen:

• Honig-Verkauf: eine Bewegung SHOP_SALE auf der Abfüllung.
• Artikel-Verkauf (FIFO): Verteilung auf die Chargen des Artikels mit Rest > 0, sortiert nach MHD aufsteigend (ohne MHD zuletzt), dann Herstelldatum aufsteigend. Reicht der Gesamtrest nicht, geht der Überhang auf die neueste Charge (Rest wird negativ, siehe 2.7).
• Rückbuchung: spiegelt genau die Bewegungen des Verkaufs reversesExternalId (gleiche Chargen, gleiche Mengen; bei Teilmenge in umgekehrter FIFO-Reihenfolge).

Kommt eine externalId erneut, wird nichts gebucht; die Antwort meldet duplicate mit dem Ergebnis der ersten Buchung.

2.5 API

Alle unter /api/v1/shop-sync, Zugang per API-Schlüssel.

Endpunkt	Recht	Inhalt
GET /shop-sync	shop-sync:read	wie bisher; zusätzlich je Abfüllung remainingCount, neue Liste productionBatches (id, productId, lotNumber, date, quantity, bestBeforeDate, remainingCount), je Artikel kind, shopCategory, remainingCount (nur MANUFACTURED)
GET /shop-sync/stock	shop-sync:read	nur Bestände: bottlings: [{id, remainingCount}], products: [{id, remainingCount}] (nur MANUFACTURED)
POST /shop-sync/movements	shop-sync:write	Body { requests: ShopStockRequest[] } (max. 100); Antwort je Anfrage { externalId, status: "created" | "duplicate" | "rejected", error?, allocations: [{ batchType, batchId, lotNumber, quantity }], remainingCount }

Neue Felder halten SHOP_SYNC_CONTRACT_VERSION = 1 (Verbraucher ignorieren Unbekanntes). Ungültige Anfragen (unbekanntes Ziel, Ziel passt nicht zu kind, reversesExternalId unbekannt) bekommen rejected mit Fehlertext; die übrigen Anfragen derselben Sendung werden trotzdem verarbeitet.

shop-sync:write kommt in API_KEY_SCOPES (bisher nur Lesen).

2.6 Webhook

Neues Ereignis stock.changed nach jeder Bewegung (aus UI oder Shop). Nutzlast nur Bezeichner: { bottlingBatchIds: [], productIds: [] }. Der Empfänger holt die Zahlen selbst über GET /shop-sync/stock — ein Webhook setzt nie Bestände.

2.7 Oberfläche

Abfüllung (Detail) und Herstellungscharge (Detail):

• Kopfzeile: Abgefüllt/Hergestellt · Webshop verkauft · Entnommen · Rest. Rest < 0 rot mit "Prüfen".
• Knopf Entnehmen: Anzahl (1 … Rest), Grund, Notiz. Mehr als der Rest wird abgelehnt.
• Knopf Inventur korrigieren: gezählten Bestand eingeben → Bewegung CORRECTION mit der Differenz; Notiz Pflicht.
• Bewegungsliste: Datum, Art, Anzahl, Grund/Notiz, wer.

Listen: Spalte "Rest" in Abfüllungs- und Chargenliste. Artikel-Detail (MANUFACTURED): Summe Rest und Liste der Chargen.

2.8 Rechte

• bottling:withdraw — Entnehmen und Inventur bei Abfüllungen.
• production-batch:read, :create, :update, :delete, :withdraw — Herstellungschargen.
• Bestehende Rollen: wer heute bottling:update hat, bekommt die neuen Rechte per Migration.

3. Wabenhain

3.1 Verknüpfung

• Honig: Product.apicoreBottlingId (besteht).
• Andere Waren: neu Product.apicoreProductId (eindeutig).
• Neue Kategorie SONSTIGES in ProductCategory.
• Produkt-Formular: Auswahl "ApiCore-Artikel verknüpfen" (nur MANUFACTURED-Artikel, noch nicht verknüpft). Damit werden bestehende Kerzen/Propolis-Produkte angebunden — vor dem ersten Sync, sonst legt der Sync zusätzliche Entwürfe an.
• Sync: legt für unverknüpfte MANUFACTURED-Artikel deaktivierte Entwürfe an (Preis 0, wie beim Honig).
• Produkte ohne Verknüpfung behalten den manuellen Bestand; das Dashboard zeigt "N Produkte noch nicht mit ApiCore verknüpft".

3.2 Bestand

Für verknüpfte Produkte wird Inventory.quantity nicht mehr von Hand gepflegt, sondern berechnet:

Shop-Bestand = ApiCore-Rest
             + Summe der noch nicht bestätigten Warteschlangen-Buchungen
               (Verkauf negativ, Rückbuchung positiv)
             − in unbezahlten Bestellungen (Status NEU) reservierte Menge

Beispiel: ApiCore-Rest 100, 2 Gläser bezahlt aber noch nicht bestätigt, 1 Glas in einer unbezahlten Bestellung → 97. Nach Bestätigung: ApiCore-Rest 98, nichts offen → weiterhin 97.

Der Abgleich schreibt diesen Wert in einer Transaktion mit Zeilensperre auf Inventory — derselbe Schutz, den der Checkout nutzt. Kein Überverkauf bei gleichzeitigem Checkout. Ein negativer Wert wird als 0 geschrieben. Das Bestandsfeld im Admin ist für verknüpfte Produkte gesperrt ("Entnahmen und Inventur in ApiCore").

Batch.glassCount und Batch.remainingGlasses (Honig) zeigen die ApiCore-Werte.

3.3 Warteschlange

ApiCoreStockEvent — geschrieben in derselben Transaktion wie die auslösende Statusänderung:

Feld	Bedeutung
id	wird als externalId gesendet
kind	SALE / RETURN
orderItemId	Bestellposition
apicoreBottlingId / apicoreProductId	Ziel
quantity	positiv
reversesEventId	bei RETURN: der Verkauf, der zurückgebucht wird
sentAt, attempts, lastError, nextAttemptAt	Zustellung

Auslöser:

Ereignis im Shop	Buchung
Bestellung bezahlt	SALE je Position
Storno einer bezahlten Bestellung	RETURN je Position
Retoure erstattet	RETURN je Position
Stornierte Bestellung wieder geöffnet	SALE je Position (neue Zeilen)
Bezahlte Bestellung gelöscht	RETURN je Position
Unbezahlte Bestellung verfällt / wird storniert	keine

Alle Stellen, die heute reserveOrderItems/restockOrderItems aufrufen, gehen künftig über eine gemeinsame Funktion, die je nach Zahlungsstand auch die Warteschlangen-Zeilen schreibt — damit kein Pfad vergessen wird.

Nach Bestätigung durch ApiCore speichert Wabenhain die Chargen-Zuordnung an der Bestellposition (OrderItem.apicoreAllocations, JSON: Chargennummer + Menge) — für Rückverfolgung und Rückruf.

3.4 Übertragung

• Sofort: nach dem Commit, nicht blockierend (after() aus next/server).
• Nachreichen + Vollabgleich: CronJob wabenhain-apicore-stock alle 10 Minuten (scripts/apicore-stock-sync.ts, Muster wie release-stale-orders): offene Buchungen senden (Backoff 1, 5, 15, 60 Minuten, danach stündlich), dann alle verknüpften Bestände abgleichen.
• Webhook-Empfang: POST /api/apicore/webhook. Prüft HMAC-Signatur mit APICORE_WEBHOOK_SECRET und Zeitstempel (max. 5 Minuten alt), sonst 401. Gleicht danach nur die genannten Ziele ab (Zahlen über GET /shop-sync/stock). Rate-limitiert.
• Sync-Knopf im Admin: ruft zusätzlich denselben Abgleich auf.
• Dashboard-Warnung: Buchung länger als 15 Minuten unbestätigt → Hinweis mit letztem Fehler; 403 von ApiCore → "ApiCore-Schlüssel braucht Schreibrecht".

4. Fehlerfälle

Fall	Verhalten
ApiCore nicht erreichbar	Shop verkauft aus letztem Stand; Buchungen warten; Nachreichen per CronJob; Warnung ab 15 Minuten.
Doppelte Zustellung	externalId eindeutig → duplicate, keine zweite Buchung.
Verkauf > Rest	Wird gebucht (Ware ist verkauft); Rest negativ, rot "Prüfen".
Webhook gefälscht/alt	401; selbst gültige Webhooks setzen keine Zahlen.
Webhook verloren	Vollabgleich spätestens nach 10 Minuten.
Abgleich parallel zum Checkout	Zeilensperre, kein Überverkauf.
Retoure Lagerware	Rückbuchung auf exakt die Chargen des Verkaufs.
Charge mit Bewegungen löschen	409.
Schlüssel ohne Schreibrecht	403; Dashboard-Hinweis.
Buchung von ApiCore abgelehnt (rejected)	Kein automatischer Neuversuch; Dashboard zeigt Bestellung und Fehlertext.

5. Tests

• ApiCore Unit: Restberechnung; FIFO inkl. Überhang; Duplikat; Entnahme > Rest abgelehnt; Rückbuchung auf richtige Chargen; Artikelart-Wechsel gesperrt.
• ApiCore e2e: POST /shop-sync/movements mit/ohne shop-sync:write; Webhook wird ausgelöst; Löschen mit Bewegungen → 409; GET /shop-sync/stock.
• Wabenhain Unit: Bestandsformel; Auslöser-Tabelle (alle sechs Zeilen); Signaturprüfung inkl. Zeitstempel.
• Wabenhain Integration (lokale DB): Checkout und Abgleich gleichzeitig ohne Überverkauf; Warteschlange übersteht Ausfall und sendet nach.
• Durchlauf lokal (beide Systeme): kaufen → in ApiCore entnehmen → Retoure; beide Seiten zeigen dieselbe Zahl.

6. Einrichtung nach dem Deploy

1. ApiCore: dem Wabenhain-API-Schlüssel shop-sync:write geben.
2. ApiCore: Webhook stock.changed → https://wabenhain.com/api/apicore/webhook; Secret in Wabenhain als APICORE_WEBHOOK_SECRET.
3. Wabenhain: CronJob wabenhain-apicore-stock aktivieren.
4. Bestehende Kerzen/Propolis-Produkte in ApiCore anlegen (Artikel + Herstellungscharge mit aktuellem Bestand), dann in Wabenhain verknüpfen, dann Sync.

7. Aufwand

Etwa 3 Arbeitstage: ApiCore ~1,5 (Bewegungsbuch, Herstellungschargen, API, Oberfläche), Wabenhain ~1,5 (Warteschlange, Auslöser, Abgleich, Webhook, Verknüpfung).

8. Nachtrag: Rohstoffe und Herstellung (umgesetzt)

Die in Abschnitt 1 zurückgestellten Bausteine sind umgesetzt, ohne Umbau des Bewegungsbuchs:

• Rohstoff-Charge (RawMaterialLot): Art (BEESWAX, PROPOLIS), Chargennummer, Gewinnungsdatum, Menge in Gramm, Herkunft optional (Stand, Ernte), Notiz. Rest wie bei allen Chargen aus dem Bewegungsbuch; Entnehmen und Inventur funktionieren gleich.
• Herstellung: Beim Anlegen einer Herstellungscharge werden die verbrauchten Rohstoffe angegeben (inputs: Rohstoff-Charge + Gramm). Charge und Verbrauch entstehen in einer Transaktion; mehr als der Rest einer Rohstoff-Charge wird abgelehnt (400). Gebucht als neue Bewegungsart CONSUMPTION; ProductionInput hält die Zuordnung.
• Rückverfolgung in beide Richtungen: Herstellungscharge → „Hergestellt aus", Rohstoff-Charge → „Verwendet in". Zusammen mit OrderItem.apicoreAllocations in Wabenhain reicht die Kette vom Wachs bis zur Bestellung.
• Löschen einer irrtümlich angelegten Herstellungscharge (nur ohne eigene Bewegungen) gibt den Rohstoff als eigene Bewegung zurück. Rohstoff-Chargen mit Bewegungen sind nicht löschbar.
• Rechte: raw-material:read|create|update|delete|withdraw. Rohstoff verbrauchen beim Anlegen einer Herstellungscharge verlangt zusätzlich raw-material:withdraw.
• Mengenkorrektur: Die Menge einer Rohstoff- oder Herstellungscharge kann nicht unter das bereits Verbuchte gesenkt werden; Fehlmengen gehen über „Inventur korrigieren".
• Rohstoffe werden nicht im Webshop verkauft; ihre Bewegungen lösen keinen stock.changed-Webhook aus.