instances/ nicht mehr gitignored, PID 7843 hinzugefügt

Repo ist privat — PID-Dateien können mitgeteilt werden. Wer seine PID lokal halten will: echo "instances/" >> .git/info/exclude
2026-04-09 21:24:48 +00:00
parent 200d52f917
commit 4de8f3de3f
2 changed files with 292 additions and 3 deletions
--- 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
--- a/instances/7843.md
+++ 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).
+
+---