4de8f3de3f
Repo ist privat — PID-Dateien können mitgeteilt werden. Wer seine PID lokal halten will: echo "instances/" >> .git/info/exclude
288 lines
10 KiB
Markdown
288 lines
10 KiB
Markdown
# 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).
|
||
|
||
---
|