diff --git a/.gitignore b/.gitignore index 8bd9943..659b30b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,3 @@ -# 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 +# PID-spezifische Dateien — werden über eigene Repos verwaltet +# und als Symlink/Clone in instances/ eingebunden +instances/ diff --git a/README.md b/README.md index f9b6682..0a76b84 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,18 @@ Dieses Repo ist eine geteilte Wissensbasis, die Claude Code (oder andere AI-Codi ## Was ist drin? -| Datei | Inhalt | Geteilt? | -|-------|--------|----------| -| `DOJO.md` | Allgemeine API-Patterns & Lektionen | Ja | -| `ANTI-PATTERNS.md` | Was man NICHT tun soll | Ja | -| `instances/.md` | Shop-spezifische Lektionen (Status, IDs, Workflows) | Nein (gitignored) | +| Datei | Inhalt | +|-------|--------| +| `DOJO.md` | Allgemeine API-Patterns & Lektionen | +| `ANTI-PATTERNS.md` | Was man NICHT tun soll | +| `instances/` | Platz für shop-spezifische Lektionen (gitignored, siehe unten) | ## Installation ### 1. Repo klonen ```bash -git clone ~/.claude/plenty-dojo +git clone https://git.tradeo.de/sebastian/plenty-dojo.git ~/.claude/plenty-dojo ``` ### 2. Install-Script ausführen @@ -27,12 +27,27 @@ bash ~/.claude/plenty-dojo/install.sh ``` Das Script: -- Symlinkt den Skill nach `~/.claude/commands/plenty-dojo.md` -- Erstellt `instances/` mit einer Vorlage für deine Plenty-ID +- Symlinkt den `/plenty-dojo` Skill nach `~/.claude/commands/` +- Erstellt eine Vorlage für deine Plenty-ID unter `instances/` -### 3. Plenty-ID eintragen +### 3. Shop-spezifische Lektionen einrichten (optional) -Öffne `~/.claude/plenty-dojo/instances/.md` und trage deine shop-spezifischen Learnings ein. Diese Datei wird nicht ins geteilte Repo gepusht. +Das `instances/`-Verzeichnis ist für shop-spezifische Learnings (eigene Status-Codes, Workflows, IDs). Diese werden **nicht** ins Haupt-Repo gepusht. + +**Option A — Eigenes PID-Repo (empfohlen für Teams):** + +Wenn dein Team ein eigenes PID-Repo hat (z.B. `plenty-dojo-7843`), klone es als `instances/`: + +```bash +rm -rf ~/.claude/plenty-dojo/instances +git clone ~/.claude/plenty-dojo/instances +``` + +Danach kannst du shop-spezifische Änderungen separat committen und mit deinem Team teilen. + +**Option B — Lokale Datei (nur für dich):** + +Erstelle einfach eine Datei `instances/.md` — sie wird vom Haupt-Repo ignoriert. ### 4. CLAUDE.md ergänzen @@ -60,13 +75,11 @@ Der Skill wird über Claude Code aufgerufen: ## Beitragen -Direkt in `DOJO.md` oder `ANTI-PATTERNS.md` schreiben und pushen. Jeder Eintrag hat: +Direkt in `DOJO.md` oder `ANTI-PATTERNS.md` schreiben und pushen. Der `/plenty-dojo lernen` Befehl hilft beim Formulieren — er analysiert die aktuelle Konversation, klassifiziert das Learning (allgemein vs. shop-spezifisch) und formatiert den Eintrag. -- **Überschrift** mit fortlaufender Nummer +Jeder Eintrag enthält: - **Lektion** — ein Satz - **Warum** — was genau passiert ist - **Pattern** — Codebeispiel (richtig) - **Anti-Pattern** — Codebeispiel (falsch) - **Entdeckt** — Datum + Kontext - -Der `/plenty-dojo lernen` Befehl hilft beim Formulieren und Einordnen. diff --git a/install.sh b/install.sh index db7ae5b..8b04ad0 100755 --- a/install.sh +++ b/install.sh @@ -2,7 +2,7 @@ set -euo pipefail # Plenty Dojo — Install Script -# Symlinkt den Skill und richtet die lokale Instanz ein. +# Symlinkt den Skill und zeigt Setup-Hinweise. DOJO_DIR="$(cd "$(dirname "$0")" && pwd)" COMMANDS_DIR="${HOME}/.claude/commands" @@ -23,40 +23,27 @@ elif [ -f "${COMMANDS_DIR}/plenty-dojo.md" ]; then fi ln -s "${DOJO_DIR}/commands/plenty-dojo.md" "${COMMANDS_DIR}/plenty-dojo.md" -echo " Skill verlinkt: ${COMMANDS_DIR}/plenty-dojo.md -> commands/plenty-dojo.md" +echo " Skill verlinkt: ${COMMANDS_DIR}/plenty-dojo.md" -# 3. Instances-Verzeichnis erstellen -mkdir -p "${DOJO_DIR}/instances" - -# 4. PID abfragen und Vorlage erstellen -if [ -z "$(ls -A "${DOJO_DIR}/instances/" 2>/dev/null)" ]; then - echo "" - read -rp " Deine Plentymarkets-ID (PID), z.B. 7843: " PID - if [ -n "${PID}" ]; then - cat > "${DOJO_DIR}/instances/${PID}.md" << TEMPLATE -# Plenty Dojo — PID ${PID} - -> Shop-spezifische Lektionen und Patterns für **Plenty-ID ${PID}**. -> Diese Datei enthält interne Workflows, eigene Statuswerte, Konfigurationen und Geschäftslogik. -> -> Allgemeingültige Plentymarkets-Lektionen stehen in \`DOJO.md\` (im Repo-Root). - ---- - - -TEMPLATE - echo " Instanz erstellt: instances/${PID}.md" - else - echo " Übersprungen — du kannst später manuell eine instances/.md anlegen." - fi +# 3. Instances prüfen +if [ -d "${DOJO_DIR}/instances/.git" ]; then + echo " Shop-spezifisches Repo gefunden: instances/" + echo " Dateien: $(ls "${DOJO_DIR}/instances/"*.md 2>/dev/null | xargs -I{} basename {} | tr '\n' ' ')" +elif [ -d "${DOJO_DIR}/instances" ] && ls "${DOJO_DIR}/instances/"*.md &>/dev/null; then + echo " Lokale PID-Dateien gefunden: $(ls "${DOJO_DIR}/instances/"*.md | xargs -I{} basename {} | tr '\n' ' ')" else - echo " Instanzen bereits vorhanden: $(ls "${DOJO_DIR}/instances/")" + mkdir -p "${DOJO_DIR}/instances" + echo "" + echo " Keine shop-spezifischen Lektionen gefunden." + echo " Falls dein Team ein PID-Repo hat:" + echo "" + echo " rm -rf ${DOJO_DIR}/instances" + echo " git clone ${DOJO_DIR}/instances" + echo "" + echo " Oder erstelle eine lokale Datei: instances/.md" fi echo "" echo "Fertig! Nutze '/plenty-dojo' in Claude Code." echo "" -echo "Vergiss nicht, in deiner CLAUDE.md auf das Dojo zu verweisen:" -echo " ~/.claude/plenty-dojo/DOJO.md" -echo " ~/.claude/plenty-dojo/ANTI-PATTERNS.md" -echo " ~/.claude/plenty-dojo/instances/.md" +echo "Tipp: Ergänze deine CLAUDE.md — siehe README.md für den Textblock." diff --git a/instances/7843.md b/instances/7843.md deleted file mode 100644 index 8169ca8..0000000 --- a/instances/7843.md +++ /dev/null @@ -1,287 +0,0 @@ -# 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). - ----