instances/ gitignored, PID-Dateien in eigene Repos ausgelagert

Haupt-Repo enthält nur allgemeines Plenty-Wissen.
Shop-spezifische Lektionen (PID) werden als eigenes Repo
in instances/ geklont. README + install.sh angepasst.
This commit is contained in:
Sebastian Poll
2026-04-09 21:34:29 +00:00
parent d4509a6cd2
commit b7a1d4fc8c
4 changed files with 48 additions and 337 deletions

8
.gitignore vendored
View File

@@ -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/

View File

@@ -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/<PID>.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 <REPO-URL> ~/.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/<DEINE-PID>.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 <PID-REPO-URL> ~/.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/<DEINE-PID>.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.

View File

@@ -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
# 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
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).
---
<!-- Trage hier deine shop-spezifischen Learnings ein. -->
TEMPLATE
echo " Instanz erstellt: instances/${PID}.md"
else
echo " Übersprungen — du kannst später manuell eine instances/<PID>.md anlegen."
fi
else
echo " Instanzen bereits vorhanden: $(ls "${DOJO_DIR}/instances/")"
echo " Keine shop-spezifischen Lektionen gefunden."
echo " Falls dein Team ein PID-Repo hat:"
echo ""
echo " rm -rf ${DOJO_DIR}/instances"
echo " git clone <PID-REPO-URL> ${DOJO_DIR}/instances"
echo ""
echo " Oder erstelle eine lokale Datei: instances/<DEINE-PID>.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/<PID>.md"
echo "Tipp: Ergänze deine CLAUDE.md — siehe README.md für den Textblock."

View File

@@ -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 58) 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 57 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 MontagFreitag 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).
---