# Commerce-Prozessdokumente

Status: Konzeptvorschau. Die Abläufe sind Abnahmespezifikationen für die spätere Implementierung.

## 1. Onboarding und Kanalwahl

**Ziel:** Vor dem ersten Datenabruf stehen das konkrete Verkaufskonto, sein Marktbereich und die Systemzuständigkeit fest.

1. Der Verkäufer wählt das zu synchronisierende Verkaufskonto und den zugehörigen Marktbereich.
2. Er gibt an, ob heute das Verkaufskonto, ein Shop-/ERP-System oder ein Mehrkanal-System führend ist.
3. Er wählt getrennt den Modus `observe`, `read` oder `write` und die fachlichen Flows `inventory`, `offers`, `orders`, `shipments`, `cancellations`, `returns` und `refunds`. Preise gehören zum Flow `offers`; `observe` ist kein Flow.
4. Der Assistent prüft für jeden gewählten Flow, ob dieselbe Kombination aus Verbindung, Verkaufskonto, Marktbereich und optionalem Angebot bereits durch ein anderes System geschrieben wird.
5. Der Verkäufer legt Sicherheitsbestand, maximale Angebotsmenge, Lagerorte, Versandprofil und Preisstrategie fest.
6. Die Verbindung wird mit minimalen Rechten autorisiert.
7. Die Einrichtung bleibt im Zustand `draft`, bis der erste Abgleich geprüft und freigegeben wurde.

**Abbruchkriterium:** Ein ungeklärter zweiter Schreiber blockiert jeden Schreibmodus.

## 2. Übernahme einer vorhandenen Shopanalyse

**Ziel:** Vorhandene Analyseergebnisse als Matching-Hilfe verwenden, ohne sie als aktuelle Bestandswahrheit zu behandeln.

1. Analyseberechtigung und Mandantenzuordnung prüfen.
2. Gespeicherte Angebotskennungen und Verkäufer-SKUs übernehmen.
3. Nach der Kontoautorisierung den aktuellen Bestand vollständig neu lesen.
4. Zuordnung in vier Gruppen erzeugen: `exact`, `review_required`, `conflict`, `unmatched`.
5. Match-Reihenfolge: stabile Angebots-ID, Verkäufer-SKU, stabile Lagerstück-ID, eindeutige Identifikatorenkombination, sonst manuelle Prüfung.
6. Titel, Beschreibung oder Bilder dürfen nie allein eine automatische Zuordnung auslösen.
7. Der Verkäufer bestätigt alle Konfliktentscheidungen; sie werden revisionsfest protokolliert.

## 3. Initialer Bestandsabgleich

**Ziel:** Einen vollständigen Ausgangszustand erzeugen, bevor laufende Deltas aktiviert werden.

```text
Autorisierter Vollabruf
  → Normalisierung
  → Matching
  → Validierung
  → Änderungsvorschau
  → Freigabe
  → atomarer Snapshot
  → Beobachtungsphase
  → Soll-Ist-Abgleich
```

Der Snapshot enthält eine Sequenz, erwartete Datensatzanzahlen und eine Prüfsumme. Bei einem Vollbestand schaltet der neue Stand atomar um. Bei einem Delta müssen Vorgänger-Sequenz und Zielrevision lückenlos passen. Jede Lücke stoppt das Anwenden und startet einen Nachlade- oder Neuaufbauprozess.

## 4. Laufende Bestandssynchronisation

**Ziel:** Überverkäufe vermeiden und jede Veränderung wiederholbar verarbeiten.

1. Eine Bestandsänderung erhält Ereignis-ID, Lagerstück-ID, erwartete Revision und Idempotenzschlüssel.
2. Der Commerce Core prüft Zuständigkeit und Revision.
3. Verkaufbare Menge wird aus physischem Bestand, Reservierungen, Sicherheitsbestand und maximaler Angebotsmenge berechnet.
4. Das Ereignis wird genau einmal fachlich angewendet; technische Wiederholungen liefern dasselbe Ergebnis.
5. Betroffene Angebote werden aktualisiert.
6. Der nachgelagerte Zustand wird erneut gelesen und verglichen.
7. Bleibt eine Differenz, erscheint sie in der Klärungswarteschlange.

## 5. Auftragsprozess

```text
Auftrag empfangen oder nachladen
  → unveränderliche Eingangsreferenz deduplizieren und salesOrderId zuweisen
  → Positionen eindeutig zuordnen
  → Bestand atomar reservieren
  → verfügbare Menge auf betroffenen Angeboten reduzieren
  → Auftrag bestätigen
  → kommissionieren und versenden
  → Versandstatus melden
  → Zustellung und finanziellen Abschluss abgleichen
```

Aufträge mit unklarer Artikelzuordnung oder fehlgeschlagener Reservierung werden nicht still bestätigt. Sie wechseln in `review_required`; sichere Gegenmaßnahmen gegen einen weiteren Verkauf können separat ausgelöst werden.

Der erste sichere Pilot verarbeitet nur einzelne physische Verkaufseinheiten mit einer Positionsmenge von eins automatisch. Bundles und Mengen größer eins wechseln in `review_required` und werden weder automatisch bestätigt noch reserviert. Ihre automatische Verarbeitung ist ein P1-Produktions-Gate, bis Komponenten, Mengenwirkung und Rückabwicklung vollständig modelliert und getestet sind. Teilbestätigung, Teilversand und Teilstorno werden nur für den jeweils freigegebenen Modellumfang aktiviert.

## 6. Storno

- Vor Bestätigung kann eine noch nicht erfüllte Position storniert und ihre Reservierung freigegeben werden.
- Nach Teilversand betrifft ein Storno nur die offenen Mengen.
- Jede Freigabe erhöht den verfügbaren Bestand höchstens einmal.
- Gebührenvorschau und späterer Gebührenbeleg werden um die stornierte Basis korrigiert.
- Nicht automatisch lösbare Zustandskonflikte gehen in die Klärungswarteschlange.

## 7. Versand

1. Versand enthält konkrete Auftragspositionen und Mengen.
2. Mehrere Sendungen pro Auftrag und mehrere Positionen pro Sendung sind erlaubt.
3. Versandereignisse sind monoton: `pending → announced → in_transit → delivered`.
4. Ein korrigierter Transportbeleg ersetzt nicht die Historie, sondern erzeugt eine neue Revision.
5. Ein fehlgeschlagener Rückkanal wird wiederholt; der Auftrag darf dabei nicht erneut reserviert oder bestätigt werden.

## 8. Retoure und Erstattung

```text
Retoure angefragt
  → genehmigt oder abgelehnt
  → Rücksendung unterwegs
  → eingegangen
  → Prüfung mit Befund erfassen
  → Disposition wieder einlagern, sperren oder aussondern
  → Erstattung auslösen
  → Geld und Gebühren abgleichen
```

Retouren und Erstattungen sind getrennte Objekte. Eine eingegangene Retoure ist noch keine erfolgte Erstattung. Teilmengen, abweichende Prüfentscheidungen und mehrere Erstattungen pro Auftrag müssen abbildbar sein.

Die Prüfung wird als eigene, revisionsgeschützte Operation mit `POST /commerce/v1/returns/{returnId}/review` dokumentiert. Sie erfasst positionsbezogen Entscheidung, geprüfte Menge, Befund und Zeitpunkt, verändert den Bestand aber noch nicht. Erst `POST /commerce/v1/returns/{returnId}/disposition` legt je geprüfter Position die Bestandswirkung `restock`, `repair`, `recycle`, `dispose` oder `hold` fest. Beide Operationen benötigen Idempotenzschlüssel und erwartete Revision; eine wiederholte Zustellung darf weder Bestand noch Erstattung doppelt verändern.

## 9. Rechnung und Gutschrift

1. Eine Rechnung wird aus dem unveränderlichen Auftrags-, Versand-, Steuer- und Preissnapshot erzeugt oder als externer Beleg normalisiert übernommen.
2. Rechnungsnummer, Ausstellungszeitpunkt, Währung, Positionen, Steueraufschlüsselung, Versand, Rabatt und Gesamtsummen werden unveränderlich gespeichert.
3. Eine nachträgliche Korrektur überschreibt keine Rechnung. Sie erzeugt eine referenzierte Gutschrift mit positionsbezogenen Mengen und Beträgen.
4. Mehrere Teilgutschriften sind möglich; ihre Summe darf den zulässigen Korrekturbetrag nicht überschreiten.
5. Rechnung, Gutschrift, Erstattung, Gebührenkorrektur und Auszahlung werden gemeinsam abgeglichen, bleiben aber getrennte Fachobjekte.
6. Fehlt einem angebundenen Konto ein automatischer Beleg-Rückkanal, zeigt die Fähigkeitsmatrix diese Richtung als nicht freigegeben.

## 10. Preisstrategie und Aktionen

| Modus | Verhalten |
| --- | --- |
| `unchanged` | vorhandener Verkäuferpreis bleibt bestehen |
| `fixed_markup` | fester Aufschlag ohne Netto-Garantie |
| `target_net` | Endpreis wird aus Zielerlös und bekannten variablen Belastungen berechnet |
| `custom_rules` | Regeln je Preisband, Kategorie, Land oder Marktbereich |

Ein pauschaler Aufschlag in Höhe der Beteiligungsrate kompensiert eine Beteiligung auf den erhöhten Endpreis nicht vollständig. Ohne weitere variable Belastungen berechnet `target_net` den nötigen Endpreis als `Zielerlös / (1 − Beteiligungsrate)`; Geldwerte werden anschließend nach der freigegebenen Währungsregel gerundet. Konkrete, freigegebene Sätze werden ausschließlich in der dafür vorgesehenen Preisoberfläche oder geschützten Konfiguration aufgelöst.

Vor Aktivierung zeigt die Vorschau Altpreis, Neupreis, Beteiligung, bekannte variable Belastungen, Rundung, erwarteten Erlös und Abweichung. Bei unbekannten variablen Kosten darf die Oberfläche keine Risikolosigkeit garantieren.

## 11. Reconciliation

Der Abgleich läuft mindestens für:

- Angebote, Menge und Preis;
- fehlende oder doppelte Aufträge;
- Ereignislücken und unverarbeitete Zustandsänderungen;
- Versand-, Storno-, Retouren- und Erstattungsstatus;
- Rechnungen, Gutschriften und Steuer-/Summenaufschlüsselung;
- Gebührenbasis, Korrekturen und erwartete Auszahlung.

Ein Verkaufskonto gilt nur dann als vollständig, wenn Marktbereich und Funktionsumfang, garantierter Startpunkt, letzte lückenlose Sequenz und letzter erfolgreicher Soll-Ist-Abgleich bekannt sind und keine kritische Differenz offen ist. Die Oberfläche zeigt `vollständig abgeglichen von <Start> bis <Ende> · 0 kritische Differenzen` statt einer pauschalen Vollständigkeitszusage.

Eine Differenz wird nicht durch Überschreiben des Abgleichs gelöst. `POST /commerce/v1/reconciliations/{reconciliationId}/discrepancies/{discrepancyId}/resolution` dokumentiert Entscheidung, Aktion, Begründung, Actor, erwartete Revision und Zeitstempel als eigenes unveränderliches Ergebnis. Erlaubte Aktionen bleiben auf den fachlich geprüften Fall begrenzt; Geld-, Auftrags- und Zuständigkeitskonflikte benötigen menschliche Freigabe. Erst ein erneuter Soll-Ist-Abgleich darf den kritischen Restzähler reduzieren und eine Vollständigkeitsanzeige freigeben.

## 12. Störung und Wiederanlauf

1. Technische Fehler mit demselben Idempotenzschlüssel wiederholen.
2. Ereignislücken nachladen; ist das nicht möglich, Vollabgleich anfordern.
3. Geld- und Auftragsdifferenzen niemals automatisch überschreiben.
4. Nach einer längeren Unterbrechung zunächst in den Beobachtungsmodus wechseln.
5. Schreibmodus erst nach einem erfolgreichen Abgleich wieder aktivieren.

## 13. Offboarding

1. Neue Schreibvorgänge stoppen.
2. Offene Aufträge und Rückabwicklungen zu Ende führen oder sichtbar übergeben.
3. Letzten Vollabgleich und exportierbaren Abschlussbericht erzeugen.
4. Verbindung widerrufen und Tokens unbrauchbar machen.
5. Aufbewahrungs- und Löschregeln ausführen.
6. Zuständigkeit an das gewählte führende System zurückgeben.