plenty-dojo/instances/7843.md

Plenty Dojo — PID 7843 (ServerShop24 / Tradeo GmbH)

Shop-spezifische Lektionen und Patterns für Plenty-ID 7843 (ServerShop24 / Tradeo GmbH). Diese Datei enthält interne Workflows, eigene Statuswerte, Konfigurationen und Geschäftslogik.

Allgemeingültige Plentymarkets-Lektionen stehen in DOJO.md (im Repo-Root).

---

I. Auftrags-Status-Landschaft

Übersicht aller genutzten Status

Pool-Status (5.x) — Aufträge warten auf Bearbeitung

Status	Bezeichnung	Verwendung
5	Freigegeben	Zwischenstatus bei Statuswechsel
5.1	Standardauftrag im Pool	Bereit zur Kommissionierung (Hauptstatus)
5.11	Zurückgestellt	Temporär aus dem Pool genommen, wird im UI ignoriert
5.12	Im Fulfilment sichtbar	Wird aktiv bearbeitet / zugewiesen
5.2	Abholauftrag	Kunde holt selbst ab (eigenes Kanban-Board)
5.31	Sonderstatus	Spezialbehandlung nötig, im UI ignoriert
5.32	Express	Vorrangige Bearbeitung, wird im Stapel vorne einsortiert
5.9	Server-Produktion	Server in Produktion

WIP-Status (6.x) — In Bearbeitung / Versendet

Status	Bezeichnung	Verwendung
6	Zielstatus nach Druck	Kommissionierschein gedruckt, Auftrag in Bearbeitung
6.01	Verpackt	Auftrag fertig verpackt
6.1	Upgrade in Arbeit	Upgrade-Auftrag wird bearbeitet
6.3	Sperre / Warten	Wartet auf Klärung, im UI ignoriert
6.32	Sperre 2	Zweite Sperrstufe, im UI ignoriert
6.58	Versandvorbereitung	Kurz vor Versand
6.59	Nahezu versendet	Fast fertig

Abschluss-Status (7.x+)

Status	Bezeichnung	Verwendung
7	Versendet	Standard-Versandbestätigung
7.2	Versendet (Variante)	Alternative Versandbestätigung
7.5	Zugestellt	Paket beim Kunden angekommen
7.6	Zugestellt (Variante)	Alternative Zustellbestätigung
8+	Storniert / Archiviert	Außerhalb unseres Scopes

Ignorierte Status (werden im UI ausgeblendet)

Standard-Konfiguration: 5.11, 5.2, 5.31, 6.3, 6.32

Diese Status werden weder im Pool noch im WIP angezeigt, aber die Orders bleiben in der DB.

Source-Status (werden gesynct und in den Pool aufgenommen)

Standard-Konfiguration: 5.1, 5.12, 5.32

Target-Status (Ziel nach Druck)

Standard-Konfiguration: 6

---

Wichtig: Event-Procedures in Plenty

Plenty hat automatisierte Event-Procedures, die auf Statuswechsel reagieren. Niemals davon ausgehen, dass ein Auftrag in dem Status bleibt, in den man ihn geschoben hat. Beispiele:

• Auftrag wird auf 6 gesetzt → Event-Procedure schiebt ihn sofort auf 6.5
• Auftrag wird auf 7 gesetzt → Event-Procedure generiert automatisch Versandbestätigung
• Mehrere Event-Procedures können in der gleichen Sekunde feuern → identische Timestamps in der Statushistorie

---

II. Auftragsklassifizierung

Server vs. Kleinteile

Die Klassifizierung bestimmt, in welchem Strang (Server oder Parts) ein Auftrag bearbeitet wird.

Server-Erkennung

Ein Auftrag ist ein "Server" wenn mindestens ein Item diese Kriterien erfüllt:

1. Der Name enthält "server" oder "workstation" (case-insensitive)
2. UND das Item gehört zu einer Kategorie, die Nachfahre von Kategorie 93 (Server) oder Kategorie 325 (Workstation) ist

Kleinteile

Alles was nicht als Server klassifiziert wird = Kleinteile (Fallback).

Server-Anzahl

Die Anzahl der Server im Auftrag wird aus den Mengen der Server-Items berechnet. Achtung: Bundle-Komponenten (orderItem.typeId === 3) nicht mitzählen, sonst werden Server doppelt gezählt.

---

Upgrade-Aufträge

• Erkennung: Contact ID = 216862 (Upgrade-Kontakt)
• Referenz: Erste Position enthält "Auftrag XXXXX" im Namen → matchedOrderId extrahieren
• Kategorie-Vererbung: Upgrade erbt die Kategorie vom gematchten Kundenauftrag
• Matching: Upgrade wird mit dem referenzierten Kundenauftrag als Paar verarbeitet (zusammen gedruckt, zusammen in Status 6 geschoben)

---

Kombiversand (Combined Shipment)

• Erkennung: Item-Name enthält "KOMBI-VERSAND" oder "COMBINED SHIPMENT"
• Referenz: "Bestellung XXXXX" im Item-Namen → kombi_ref_order_id
• Verhalten: Kombiversand-Aufträge werden als Gruppe bearbeitet — alle Orders im Kombi müssen Dokumente haben, bevor gedruckt wird

---

Vorab-Austausch (Advance Replacement)

• Erkennung: Item-Name enthält "VORAB-AUSTAUSCH"
• Order typeId: 5 (Garantieauftrag)
• Automatische Priorisierung: Wird immer als is_priority = 1 markiert
• Verhalten: Wird im Pool mit Prio-Flag angezeigt und im Stapel vorgezogen

---

Papierrechnung

• Erkennung: Variation ID 51433 oder 39001 im Auftrag
• Verhalten: Rechnung wird beim Drucken als zusätzliches PDF hinter den Kommissionierschein gehängt
• Abruf: On-Demand beim Drucken (nicht beim Sync), mit Retry-Logik falls noch nicht generiert

---

III. Shipping Profiles

ID	Versandart	Express?
19	DHL Paket	Nein
23	Spedition	Nein
24	Selbstabholung	Nein
27	DHL Express 12	Ja
28	DHL Express 9	Ja
29	DHL Nachnahme	Nein
34	FedEx Economy Express	Ja
35	FedEx Economy	Nein
36	UPS Standard	Nein
39	DHL Express Intl.	Ja
40	Kein Versand	Nein
41	UPS Express Saver	Ja
43	Individuell	Nein
44	UPS Express	Ja
45	DHL Express Sa.	Ja
46	Swiss Post	Nein
48	DHL Europaket	Nein

Express-Profile (Config: express_shipping_profiles): 27, 28, 34, 39, 41, 44, 45

Express-Aufträge werden im Pool mit Express-Flag markiert und im Druckstapel ganz vorne einsortiert (vor Standard-Aufträgen, sortiert nach Wartezeit).

---

IV. Payment Methods

ID	Zahlart
1	Nachnahme
2	Rechnung
3	Lastschrift
4	Bar
5	PayPal
6000	Vorkasse
5000	Manuell
5001	Bankbuchung
7001	Kreditkarte
7003	Amazon Pay
7004	PayPal (Variante)
7036	Klarna
7051	SOFORT
7064	PayPal (Variante 2)

---

V. Sync-Architektur

Drei Sync-Mechanismen

Mechanismus	Intervall	Zweck
Delta-Sync	Alle 5 Minuten	Änderungen seit letztem Sync laden (24h Overlap)
Active Refresh	Täglich 04:00	Volle Neuklassifizierung aller Orders im Scope
Outbound Control	Täglich 06:00	Prüft Warenausgang-Übernahme von Kunden- auf Upgrade-Aufträge

Delta-Sync (*/5 * * * *)

• Lädt alle Orders die seit last_sync_at - 24h geändert wurden
• Filtert in Scope (Status 5–8) und Out-of-Scope
• Klassifiziert neue In-Scope-Orders als Server/Kleinteile
• Aktualisiert Status für bestehende DB-Einträge
• Fetcht Dokumente für Orders ohne Kommissionierschein
• Speichert Kommentare und Statushistorie

Active Refresh (0 4 * * *)

• Lädt ALLE Orders in Status 5–7 aus Plenty (kein updatedAt-Filter)
• Klassifiziert von Grund auf neu
• Erkennt "verwaiste" Orders: in DB als aktiv, aber in Plenty nicht mehr im erwarteten Status
• Sicherheitscheck: Läuft nicht, wenn ein Batch auf Bestätigung wartet

Outbound Control (0 6 * * *)

• Passives Monitoring (read-only)
• Prüft, ob bei geshippten Kundenaufträgen auch die zugehörigen Upgrades einen Warenausgang haben
• Erkennt Mismatches (Kunde versendet, Upgrade noch nicht)

---

VI. Bekannte Lektionen (ServerShop-spezifisch)

1. Fehlende Aufträge im Pool diagnostizieren

Wenn ein Auftrag in Plenty in Status 5.x ist, aber im Fulfilment-Tool nicht angezeigt wird:

Mögliche Ursache	Diagnose-Query
Nicht gesynct	SELECT * FROM orders WHERE order_id = ? → leer
Dokument fehlt	document_content IS NULL
Zurückgestellt	is_deferred = 1
Bereits gebatcht	SELECT * FROM batch_orders WHERE order_id = ?
Ignorierter Status	status_id IN (5.11, 5.2, 5.31, 6.3, 6.32)
Falsch klassifiziert	order_category = 'server' statt 'parts'
Order war in Status < 5 bei Sync	Statushistorie prüfen: war Order erst kürzlich in 5.x?

Vollständige Diagnose-Query:

SELECT order_id, status_id, order_category, order_type,
       is_deferred, document_content IS NOT NULL as has_doc,
       archived_at, synced_at
FROM orders WHERE order_id = ?;

Entdeckt: 2026-04-02. Order 593646 fehlte im Pool — war in Status 3 als der Sync lief, wurde erst danach auf 5.1 gesetzt.

---

2. Status 5.12 und 5.32 als Upgrade-Marker (KPI-Projekt)

Im KPI-Projekt werden Status 5.12 und 5.32 als Marker für Upgrade-Aufträge verwendet, um KPI-Auswertungen nach Auftragstyp zu segmentieren:

EXISTS (SELECT 1 FROM status_history
        WHERE order_id = o.order_id
        AND status_id IN (5.12, 5.32))

Dies ist eine rein analytische Nutzung — im Fulfilment-Workflow haben diese Status ihre eigene Bedeutung (5.12 = im Fulfilment sichtbar, 5.32 = Express).

---

3. Cycle-Time-Berechnung: Business Hours

Für SLA-Tracking (Standard: 48h) nur Montag–Freitag zählen:

// SQLite Custom Function
db.function('business_hours', (startIso, endIso) => {
  // Wochenenden ausschließen
  // Nur Mo-Fr zählen
});

SLA-Ziel: Konfigurierbar via SLA_TARGET_HOURS (Default: 48h Business Hours von 5→7).

---

4. ATICOM-Datenbank (Read-Only)

Das Plenty-Item-Tools-Projekt hat Zugriff auf eine ATICOM-Exportdatenbank, die als Read-Only-Mount im Container liegt. Diese enthält Bestands- und Artikeldaten und wird für Tag-Automatisierung genutzt (Out-of-Stock-Erkennung).

Achtung: Nicht beschreibbar — nur als Datenquelle für Entscheidungen nutzbar.

---

VII. Plenty-Projekte auf diesem Server

Projekt	Pfad	Domain	Zweck
Fulfilment	/home/deploy/fulfilment	fulfilment.sebastianpoll.de	Kommissionierung, Drucken, Statuswechsel
Plenty-KPI	/home/deploy/plenty-kpi	plenty-kpi.sebastianpoll.de	Durchlaufzeiten, SLA-Tracking, Charts
Plenty-Item-Tools	/home/deploy/plenty-item-tools	plenty-tools.sebastianpoll.de	Tag-Management, Bestandssteuerung

Alle drei nutzen den gleichen API-Client-Pattern (Token-Refresh, Rate-Limiting, Retry) und die gleichen Credentials (PLENTY_API_URL, PLENTY_USERNAME, PLENTY_PASSWORD in docker-compose).

---