DEV-Ist-Stand fuer Phase 1 dokumentiert

2026-06-02 21:49:57 +02:00
parent 0d8353fb9c
commit 70272e81d6
1 changed files with 501 additions and 0 deletions
@@ -0,0 +1,501 @@
 # Phase 1: DEV-Ist-Stand Tabellen- und Prozesskonzept
 Stand: 2026-06-02
 Status: Verbindlicher DEV-Ist-Stand fuer Phase 1
 ## 1. Uebersicht
 Dieses Dokument beschreibt die technische Wahrheit des aktuellen DEV-Standes auf Basis von:
 - `docs/CONCEPT.md`
 - `docs/SCHEMA_PHASE1.sql`
 - `docs/PROCESS_PHASE1.md`
 - `db/migrations/0001_phase1_core.sql` bis `db/migrations/0006_phase1_otc_products.sql`
 - `order-import.php`
 - `n8n/exports/current/*.json`
 Wichtige Einordnung:
 - `SCHEMA_PHASE1.sql` bleibt ein Draft und ist nicht identisch mit der live DB.
 - Die live DB hat 18 Base Tables und 1 View.
 - Die Forecast-Erweiterung aus `0003_phase1_inventory_forecast.sql` ist im live Schema nicht aktiv.
 - Die Doku unten trennt deshalb zwischen implementiertem Ist-Stand und nicht gefundenen Zielbild-Teilen.
 Tabellen:
 - `party`
 - `address`
 - `contact`
 - `product`
 - `sellable_item`
 - `external_item_alias`
 - `sellable_item_component`
 - `warehouse`
 - `location`
 - `stock_lot`
 - `payment_method`
 - `shipping_method`
 - `sales_order`
 - `sales_order_line`
 - `stock_move`
 - `sales_order_line_lot_allocation`
 - `audit_log`
 - `outbound_webhook_event`
 View:
 - `v_stock_lot_balance`
 Prozesse:
 - `n8n.bestell-eingang-online-shop`
 - `order-import.php`
 - `db.trigger.sales_order`
 - `db.trigger.sales_order_line`
 - `db.trigger.stock_move`
 - `db.trigger.product`
 - `n8n.adressetikette-erstellen`
 - Outbox-Ablage ueber `outbound_webhook_event`
 ## 2. Zweck
 Dieses Dokument beschreibt die aktuelle DB- und Prozesswahrheit fuer Phase 1 auf dem DEV-Stand.
 Es ist eine technische Uebersicht fuer Analyse, Umsetzung und Review.
 Nicht Bestandteil dieses Dokuments sind:
 - API-Details
 - UI-Details
 - Migrations-Rollout-Planung
 - offene Zielbilddiskussionen ausserhalb des aktuellen DEV-Standes
 ## 3. Normatives Datenmodell
 ### 3.1 `party`
 Zweck:
 - gemeinsamer Kontaktstamm fuer Kunden und Lieferanten
 Ist-Stand:
 - `type` ist `customer`, `supplier` oder `both`
 - `status` ist `active` oder `inactive`
 - `email` wird fuer Match/Upsert genutzt
 ### 3.2 `address`
 Zweck:
 - Rechnungs- und Lieferadressen pro `party`
 Ist-Stand:
 - `type` ist `billing` oder `shipping`
 - `raw_payload` speichert die Rohdaten des Eingangsdokuments
 ### 3.3 `contact`
 Zweck:
 - zusaetzliche Ansprechpartnerdaten pro `party`
 Ist-Stand:
 - keine weitere Prozesslogik im Code gefunden
 ### 3.4 `product`
 Zweck:
 - lagergefuehrtes Produkt mit Bestand und Charge
 Ist-Stand:
 - `sku` ist eindeutig
 - beim Insert erzeugt der Trigger `trg_product_bootstrap_lots` sofort eine `current`- und eine `open`-Charge
 ### 3.5 `sellable_item`
 Zweck:
 - verkaufbarer Shop-Artikel
 Ist-Stand:
 - Bestellungen referenzieren zuerst `sellable_item`
 - der Import kann neue `sellable_item`-Datensaetze automatisch erzeugen
 ### 3.6 `external_item_alias`
 Zweck:
 - Mapping externer Shop-Daten auf `sellable_item`
 Ist-Stand:
 - `source_system = 'wix'`
 - Aufloesung ueber Artikelnummer, normalisierten Titel oder Originaltitel
 ### 3.7 `sellable_item_component`
 Zweck:
 - Stueckliste eines `sellable_item` auf lagergefuehrte Produkte
 Ist-Stand:
 - `qty_per_item > 0`
 - wird vom Import und von Seed-Skripten gepflegt
 ### 3.8 `warehouse`
 Zweck:
 - oberer Lagerstandort
 Ist-Stand:
 - im Seed ist ein Hauptlager vorgesehen
 ### 3.9 `location`
 Zweck:
 - konkreter Lagerort innerhalb eines `warehouse`
 Ist-Stand:
 - `type` ist `storage`, `receiving`, `dispatch` oder `adjustment`
 ### 3.10 `stock_lot`
 Zweck:
 - Charge eines Produkts
 Ist-Stand:
 - `status` ist `open`, `current` oder `closed`
 - pro Produkt sind `current` und `open` per Unique Index abgesichert
 - die live DB hat keine `sellout_date`- oder `warning_state`-Spalten
 - die Sicht `v_stock_lot_balance` ist die Bestandswahrheit
 ### 3.11 `payment_method`
 Zweck:
 - normalisierte Zahlungsart
 Ist-Stand:
 - Seed-Werte im DEV: `card`, `twint`, `bank_transfer`, `cash`, `paypal`
 ### 3.12 `shipping_method`
 Zweck:
 - normalisierte Versandart
 Ist-Stand:
 - Seed-Werte im DEV: `post_standard`, `pickup`
 ### 3.13 `sales_order`
 Zweck:
 - Bestellkopf fuer Online-Import und Direktverkauf
 Ist-Stand:
 - `external_ref` ist eindeutig
 - `order_source` ist `wix` oder `direct`
 - `party_id` ist nullable
 - `payment_status` ist faktisch auf `paid` beschraenkt
 - `shipping_date` existiert im live Schema und wird per Trigger berechnet, falls leer
 ### 3.14 `sales_order_line`
 Zweck:
 - Bestellposition
 Ist-Stand:
 - `qty_cancelled` und `line_status` werden per Trigger synchronisiert
 - `sellable_item_id` kann `NULL` sein
 ### 3.15 `stock_move`
 Zweck:
 - Bewegungsjournal fuer Zu- und Abgaenge
 Ist-Stand:
 - `move_type` ist `in`, `out`, `transfer` oder `adjustment`
 - Bewegungen werden vor Insert/Update gegen Negativbestand validiert
 ### 3.16 `sales_order_line_lot_allocation`
 Zweck:
 - explizite Rueckverfolgung zwischen Bestellposition und Charge
 Ist-Stand:
 - `allocation_status` ist `reserved`, `allocated`, `released` oder `cancelled`
 - im Import wird `allocated` verwendet
 ### 3.17 `audit_log`
 Zweck:
 - technische Historisierung
 Ist-Stand:
 - im Schema vorhanden
 - im geprüften PHP- und n8n-Flow nicht als zentraler Pflichtpfad sichtbar
 ### 3.18 `outbound_webhook_event`
 Zweck:
 - Outbox fuer ERP-Events
 Ist-Stand:
 - Spalten: `event_type`, `event_key`, `aggregate_type`, `aggregate_id`, `payload`, `status`, `attempt_count`, `next_attempt_at`, `last_attempt_at`, `last_error`, `created_at`, `sent_at`
 - `fn_enqueue_event(...)` schreibt idempotent in diese Tabelle
 - ein Dispatcher/Worker fuer die Auslieferung wurde im geprüften DEV-Baum nicht gefunden
 ### 3.19 `v_stock_lot_balance`
 Zweck:
 - berechneter Chargensaldo
 Ist-Stand:
 - die Sicht ermittelt `qty_in`, `qty_out` und `qty_net`
 - sie ist die Grundlage fuer Bestandspruefung und Auto-Switch
 ## 4. Normatives Prozessmodell
 Alle Prozesse gehoeren fachlich zur Phase-1-Bestell-, Lager- und Integrationslogik.
 ### 4.1 `n8n.bestell-eingang-online-shop`
 Fachliche Aufgabe:
 - E-Mail auf `Neue Bestellung` erkennen
 - Payload in ERP-JSON umformen
 - JSON per HTTP POST an `order-import.php` senden
 Liest:
 - IMAP-Eingang
 - n8n-Extraktionslogik
 Schreibt:
 - keine DB direkt
 Fachliche Wirkung:
 - n8n ist hier nur die Integrationshuelle fuer den ERP-Import
 ### 4.2 `order-import.php`
 Fachliche Aufgabe:
 - eingehende Bestelldaten idempotent in die ERP-DB schreiben
 - Kontakte, Adressen, Bestellkopf, Positionen und Chargenrueckverfolgung aufbauen
 - bei Reimport vorhandene Allokationen zurueckbuchen
 - nach Commit die Label- und Excel-Flows direkt anstossen
 Liest:
 - `.env`
 - eingehendes Webhook-JSON
 - `party`, `address`, `sales_order`, `sales_order_line`
 - `external_item_alias`
 - `sellable_item_component`
 - `stock_lot`
 - `v_stock_lot_balance`
 Schreibt:
 - `party`
 - `address`
 - `sales_order`
 - `sales_order_line`
 - `sellable_item`
 - `external_item_alias`
 - `sellable_item_component`
 - `warehouse`
 - `location`
 - `stock_lot`
 - `stock_move`
 - `sales_order_line_lot_allocation`
 Fachliche Wirkung:
 - die Bestellung wird im ERP gespeichert und mit Lagerbewegung verknuepft
 - vorhandene Allokationen derselben `external_ref` werden vor dem Neuimport rueckwaerts gebucht
 - nach erfolgreichem Commit werden Label- und Excel-N8N-Flows direkt per HTTP ausgelöst
 ### 4.3 `db.trigger.sales_order`
 Fachliche Aufgabe:
 - `shipping_date` aus `order_date` ableiten
 - `order.imported` und `order.cancelled.full` in die Outbox schreiben
 - `direct`-Bestellungen automatisch mit `DIR-...` Nummer versehen
 Liest:
 - `sales_order`
 - `fn_next_business_day(timestamp)`
 Schreibt:
 - `sales_order.shipping_date`
 - `outbound_webhook_event`
 Fachliche Wirkung:
 - fehlendes `shipping_date` wird auf den naechsten Werktag gesetzt
 - neue Auftraege und Vollstornos werden als Event in die Outbox gelegt
 - direkte Auftraege erhalten bei leerer Nummer automatisch einen `DIR-...`-Ref
 ### 4.4 `db.trigger.sales_order_line`
 Fachliche Aufgabe:
 - `line_status` aus `qty_cancelled` ableiten
 - Partial-Cancel-Event enqueuen
 Liest:
 - `sales_order_line`
 Schreibt:
 - `sales_order_line.line_status`
 - `outbound_webhook_event`
 Fachliche Wirkung:
 - `allocated`, `partially_cancelled` und `cancelled` werden deterministisch gesetzt
 - ein Wechsel auf `partially_cancelled` erzeugt ein `order.cancelled.partial`-Event
 ### 4.5 `db.trigger.stock_move`
 Fachliche Aufgabe:
 - Negativbestand verhindern
 - Chargenwechsel bei leerer `current`-Charge ausloesen
 Liest:
 - `stock_move`
 - `stock_lot`
 - `v_stock_lot_balance`
 Schreibt:
 - `stock_lot`
 - `outbound_webhook_event`
 Fachliche Wirkung:
 - `out`-Bewegungen sind nur auf `current`-Chargen erlaubt
 - bei `qty_net <= 0` wird die naechste `open`-Charge `current`
 - danach wird wieder eine neue `open`-Charge angelegt
 ### 4.6 `db.trigger.product`
 Fachliche Aufgabe:
 - neue Produkte sofort chargenfaehig machen
 Liest:
 - `product`
 Schreibt:
 - `stock_lot`
 Fachliche Wirkung:
 - jedes neue Produkt bekommt direkt eine `current`- und eine `open`-Charge
 ### 4.7 `n8n.adressetikette-erstellen`
 Fachliche Aufgabe:
 - Lieferadresse entgegennehmen
 - Felder normalisieren
 - HTML/CSS in PDF/PNG umsetzen
 - Ergebnis per SFTP hochladen
 Liest:
 - Webhook-Input
 - Gotenberg / pdf2png / SFTP-Ziele
 Schreibt:
 - keine ERP-DB
 Fachliche Wirkung:
 - eigenstaendiger Ausgabekanal fuer Versandetiketten
 ### 4.8 Outbox-Ablage ueber `outbound_webhook_event`
 Fachliche Aufgabe:
 - Eventdaten fuer spaetere Auslieferung sammeln
 Liest:
 - `fn_enqueue_event`
 Schreibt:
 - `outbound_webhook_event`
 Fachliche Wirkung:
 - Queue wird im geprüften DEV-Stand befuellt
 - ein dazugehoeriger Dispatcher/Worker wurde im Code nicht gefunden
 ## 5. Technische Einbettung
 Die reale Phase-1-Logik bildet einen kleinen operativen Kern mit vier Schwerpunkten:
 1. Kontakt- und Adressstamm
 2. Bestellimport via n8n -> PHP -> DB
 3. Chargen- und Lagerbewegung mit Trigger-Logik
 4. Label-Generierung als separater n8n-Ausgang
 Wichtige Abweichungen zum alten Zielbild:
 - Sellout-Forecast ist im live Schema nicht aktiv.
 - Ein Dispatcher fuer `outbound_webhook_event` wurde im geprüften DEV-Baum nicht gefunden.
 - Eine separate Direct-Sale-Eingabestrecke wurde im geprüften DEV-Baum nicht gefunden; vorhanden ist nur die DB-/Trigger-Unterstuetzung fuer `order_source = direct`.
 ## 6. Kurzfazit
 Die aktuelle technische Wahrheit von Phase 1 ist auf Nachvollziehbarkeit und direkte Integrationspfade ausgerichtet:
 - Bestellungen werden idempotent gespeichert
 - Lagerbestand wird ueber Chargen und Bewegungen abgebildet
 - Rueckverfolgung erfolgt ueber explizite Allokationen
 - n8n importiert und erzeugt Labels direkt
 - Outbox-Events werden geschrieben, aber ein Dispatcher ist im geprüften DEV-Stand nicht vorhanden