# 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:**
```sql
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:

```sql
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:

```javascript
// 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).

---