erp_naurua/docs/SPEC_PHASE1_COMPONENTS.md

Phase 1 Component Specification

Dokumentstatus

1. Typ: operational
2. Zweck: verbindliche Umsetzungs-Spezifikation fuer Schritt 1 Komponenten
3. Normative Referenz: /Users/mathias/Documents/Dokumente Chouchou/Codebases/erp_naurua/docs/CONCEPT.md
4. Abgeleitete Referenz: /Users/mathias/Documents/Dokumente Chouchou/Codebases/erp_naurua/docs/SCHEMA_PHASE1.sql
5. Prozessreferenz: /Users/mathias/Documents/Dokumente Chouchou/Codebases/erp_naurua/docs/PROCESS_PHASE1.md
6. Implementierungsreferenz: /Users/mathias/Documents/Dokumente Chouchou/Codebases/erp_naurua/db/migrations/

Scope

Diese Spezifikation deckt alle Schritt-1-Komponenten ab:

1. Bestellerfassung
2. Kontakt- und Adressdaten
3. Artikel-Mapping und Stuecklisten
4. Lagerverwaltung mit Chargen, MHD, Zu-/Abgaengen
5. Chargenrueckverfolgung
6. Teil-/Vollstorno
7. Inbound/Outbound Webhooks
8. Audit und technische Guardrails

Globale Invarianten

1. sales_order.external_ref ist eindeutig und dient als Upsert-Schluessel (Shop: BestellungNr, Direktverkauf: DIR-...).
2. Datensaetze werden nicht geloescht; Statusaenderungen und Audit-Trail werden verwendet.
3. Verkaufsbewegungen sind immer chargengebunden.
4. Negativbestand ist unzulaessig.
5. Pro Produkt existieren exakt eine current-Charge und eine open-Charge.
6. open darf nie fehlen.
7. Zahlungsstatus aus Shop wird intern auf paid normalisiert.
8. Direktverkaeufe haben order_source = direct und external_ref mit DIR--Praefix.

Komponente 1: Bestellerfassung

Ziel

Persistente Erfassung von Bestellungen aus Shop und Direktverkauf inkl. Positionen, Summen und Import-/Erfassungsdaten.

Eingangsquelle

1. n8n Inbound Webhook mit Shop-JSON (order_source = wix)
2. Manuelle ERP-Erfassung fuer Direktverkauf (order_source = direct)

Datenregeln

1. Upsert auf sales_order.external_ref fuer Shop-Bestellungen.
2. Direktbestellungen erhalten ERP-interne Nummern mit DIR--Praefix.
3. order_status initial imported.
4. Summenfelder werden direkt gespeichert (amount_net, amount_shipping, amount_tax, amount_discount, total_amount).
5. webhook_payload wird fuer Shop-Rohdaten gespeichert (Nachvollziehbarkeit).
6. Fuer Direktverkauf darf party_id leer sein (Laufkundschaft).

Fehlerverhalten

1. Bei fehlender BestellungNr: Import ablehnen, Audit-Log import_rejected.
2. Bei unbekanntem Artikelfehler: Bestellung speichern, Position mit Rohdaten speichern, Mapping-Luecke markieren.

Akzeptanzkriterien

1. Wiederholter Import derselben BestellungNr erzeugt kein Duplikat.
2. Direktbestellungen sind ueber den DIR--Praefix eindeutig erkennbar.
3. Positionsdaten bleiben stabil und auditierbar.

Komponente 2: Kontakt- und Adressdaten

Ziel

Speicherung von Kundenkontakt, Lieferadresse und optionaler Rechnungsadresse.

Datenregeln

1. Rechnungsadresse darf vollstaendig NULL sein.
2. Lieferadresse wird als eigener Datensatz gespeichert.
3. Land wird immer doppelt gespeichert: country_name + country_iso2.
4. Keine serverseitige Adressvalidierung in Phase 1.
5. Ausnahmefaelle bei Name/Firma werden unveraendert uebernommen.
6. Bei Direktverkauf ist keine Kontakt-/Adressanlage erforderlich.

Akzeptanzkriterien

1. Bestellung kann ohne Rechnungsadresse gespeichert werden.
2. Liefer- und Rechnungsadresse sind getrennt auswertbar.

Komponente 3: Artikel-Mapping und Stuecklisten

Ziel

Stabile Entkopplung von Shop-Artikeln und lagergefuehrten Produkten.

Datenmodell

1. sellable_item: verkaufbarer Artikel (auch Bundles).
2. external_item_alias: Mapping Shop-Artikelnummer/Titel -> sellable_item.
3. sellable_item_component: Stueckliste sellable_item -> product mit Menge.

Aufloesungsreihenfolge

1. Match ueber external_article_number.
2. Fallback ueber normalisierten Titel.
3. Wenn beides fehlschlaegt: Position als unmapped speichern und auditieren.

Akzeptanzkriterien

1. Bundle-Artikel koennen auf mehrere Lagerprodukte aufgeloest werden.
2. Ohne Mapping bleibt Bestellung dennoch erfassbar.

Komponente 4: Lagerverwaltung und Chargen

Ziel

Konsistente Bestandsfuehrung je Charge inklusive Auto-Wechsel.

Statusmodell Charge

1. open: vorbereitete Charge
2. current: aktive Entnahmecharge
3. closed: abgeschlossene Charge

Lebenszyklus

1. open -> current -> closed
2. Wenn current auf qty_net <= 0 faellt:
   1. alte current wird closed
   2. vorhandene open wird current
   3. neue open wird auto-angelegt

Feldregeln

1. lot_number bei open darf leer sein.
2. lot_number fuer current/closed ist Pflicht.
3. Chargennummer ist pro Produkt eindeutig.
4. Chargensalden werden aus stock_move berechnet (v_stock_lot_balance).
5. Abverkaufprognose pro aktueller Charge wird im System gepflegt (sellout_date, warning_state).

Korrekturregeln

1. Korrekturen erfolgen ueber adjustment-Bewegungen.
2. Keine direkten Netto-Setzungen als Betriebsprozess.

Akzeptanzkriterien

1. Nach jeder Entnahme bleibt die Invariante 1x current + 1x open erhalten.
2. Negativbestand wird technisch verhindert.
3. Warnstatus fuer UI ist ohne E-Mail nutzbar (none, due_60d, due_now).

Komponente 5: Chargenrueckverfolgung

Ziel

Lueckenlose Rueckverfolgung Bestellung -> Position -> Produkt -> Charge -> Lagerbewegung.

Datenregeln

1. Jede Entnahme schreibt stock_move (move_type = out) mit lot_id.
2. Pro Entnahme wird sales_order_line_lot_allocation geschrieben.
3. allocation_status in Phase 1 standardmaessig allocated.

Akzeptanzkriterien

1. Fuer jede ausgelieferte Position ist die verwendete Charge abfragbar.
2. Rueckverfolgung funktioniert auch nach Teilstorno.

Komponente 6: Storno (Teil/Voll)

Ziel

Revisionssicheres Storno ohne physisches Loeschen.

Datenregeln

1. Teil- und Vollstorno sind erlaubt.
2. sales_order_line.qty_cancelled wird fortgeschrieben.
3. line_status: allocated, partially_cancelled, cancelled.
4. Bei Storno von bereits allocated Mengen erfolgt Gegenbuchung als adjustment in auf dieselbe Charge.
5. Bestellung bleibt erhalten; Statuswechsel statt Delete.

Akzeptanzkriterien

1. Historische Ursprungs- und Korrekturbewegungen bleiben sichtbar.
2. Vollstorno setzt sales_order.order_status = cancelled.

Komponente 7: Webhooks

Inbound (n8n -> ERP)

1. Transport: JSON via HTTP.
2. Idempotenzschluessel: BestellungNr.
3. Verarbeitung: Upsert Bestellung, Kontakt, Positionen, Lagerabgang, Audit.
4. Quelle wird als order_source = wix gespeichert.

Direkt (ERP intern)

1. Transport: manuelle Erfassung in ERP-Maske.
2. Nummernlogik: ERP erzeugt external_ref mit DIR--Praefix.
3. Verarbeitung: Bestellung (optional ohne Kontakt), Positionen, Lagerabgang, Audit.

Outbound (ERP -> n8n)

1. Transport: Queue-basierter POST ueber outbound_webhook_event.
2. Events Phase 1:
   1. order.imported
   2. order.cancelled.partial
   3. order.cancelled.full
   4. lot.auto_switched
3. Signatur: X-ERP-Signature (HMAC-SHA256).
4. Zustellung: Retry mit Backoff; final dead_letter.

Akzeptanzkriterien

1. Event-Zustellung ist idempotent (event_key eindeutig).
2. Fehlgeschlagene Events sind operativ auffindbar.
3. Outbound-Payload enthaelt die Quelle (order_source), damit wix und direct getrennt auswertbar sind.

Komponente 8: Audit und Betriebssicherheit

Audit

1. Jede fachliche Aenderung schreibt audit_log.
2. Pflichtfelder: entity_name, entity_id, action, changed_at.
3. Vorher/Nachher-Daten werden als JSON gespeichert, wenn verfuegbar.

Guardrails

1. Check-Constraints fuer Statuswerte.
2. Check-Constraints fuer Mengenbereiche.
3. Unique-Constraints fuer kritische Eindeutigkeiten.
4. Outbox-Statusmaschine fuer robuste externe Zustellung.

Komponenten-Matrix

1. Bestellerfassung Zustandsquelle: sales_order, sales_order_line Hauptereignisse: order.imported, order.cancelled.*
2. Kontakt/Adressen Zustandsquelle: party, contact, address Hauptereignisse: order.imported
3. Artikel-Mapping Zustandsquelle: sellable_item, external_item_alias, sellable_item_component Hauptereignisse: order.imported
4. Lagerverwaltung Zustandsquelle: stock_lot, stock_move, v_stock_lot_balance Hauptereignisse: order.imported, lot.auto_switched, order.cancelled.*
5. Rueckverfolgung Zustandsquelle: sales_order_line_lot_allocation Hauptereignisse: alle Abgaenge und Stornos
6. Outbound-Integration Zustandsquelle: outbound_webhook_event Hauptereignisse: alle publizierten Domain-Events

Nicht in Phase 1

1. Rechnungswesen, Buchungssaetze, OCR-Verarbeitung.
2. Automatisierte Preis-/Steuerneuberechnung.
3. Vollautomatische Chargennummerngenerierung nach Produktklasse.

Change Governance

1. Konzeptaenderungen zuerst in CONCEPT.md.
2. Prozess- und Betriebsablauf in PROCESS_PHASE1.md.
3. Technische Ableitung in SCHEMA_PHASE1.sql.
4. Diese Spezifikation synchronisiert alle Komponenten auf Umsetzungsniveau.