# 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