diff --git a/.gitignore b/.gitignore index d6a9760..8bd9943 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ -# PID-spezifische Dateien (shop-interne Lektionen) -# Für Kollegen-Sharing: diesen Block entfernen oder eigenes Repo nutzen -instances/ +# PID-spezifische Dateien sind standardmäßig NICHT ignoriert, +# da dieses Repo privat geteilt wird (handverlesene Collaborators). +# +# Wer seine PID-Datei NICHT pushen will: +# echo "instances/" >> .git/info/exclude diff --git a/instances/7843.md b/instances/7843.md new file mode 100644 index 0000000..8169ca8 --- /dev/null +++ b/instances/7843.md @@ -0,0 +1,287 @@ +# 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). + +---