200d52f917
Geteilte Plentymarkets API Learnings (DOJO.md, ANTI-PATTERNS.md), Claude Code Skill (/plenty-dojo), und Install-Script für neue User.
232 lines
6.9 KiB
Markdown
232 lines
6.9 KiB
Markdown
# Plenty Dojo — Anti-Patterns
|
|
|
|
> Dinge, die man mit der Plentymarkets API **nicht** tun sollte.
|
|
> Diese Datei ist allgemeingültig und kann an jeden Plenty-Entwickler weitergegeben werden.
|
|
>
|
|
> Shop-spezifische Anti-Patterns stehen in `instances/<PID>.md`.
|
|
> Ausführliche Erklärungen stehen in `DOJO.md`.
|
|
|
|
---
|
|
|
|
## 1. Delta-Sync mit exaktem oder zu knappem Timestamp
|
|
|
|
```javascript
|
|
// FALSCH: Exakter Timestamp
|
|
const syncSince = lastSyncTimestamp;
|
|
|
|
// AUCH FALSCH: 3h Overlap reicht nicht
|
|
const OVERLAP = 3 * 60 * 60 * 1000;
|
|
```
|
|
|
|
**Problem:** Race Condition — wenn ein Sync exakt zur gleichen Sekunde läuft, in der eine Order geändert wird, fällt die Order permanent durch alle folgenden Syncs. 3h Overlap half nicht, weil zwischen Container-Restarts (Deploys) und der Order-Änderung mehr als 3h vergehen können.
|
|
|
|
**Fix:** 24h Overlap. Kostet ~200 extra Orders pro Sync, eliminiert aber die Race Condition. **Siehe DOJO.md #4**
|
|
|
|
---
|
|
|
|
## 2. Statushistorie nach Timestamp sortieren
|
|
|
|
```sql
|
|
ORDER BY createdAt DESC -- oder ORDER BY status_at DESC
|
|
```
|
|
|
|
**Problem:** Mehrere Statuswechsel in derselben Sekunde → zufällige Reihenfolge → falscher "letzter" Status.
|
|
|
|
**Fix:** `ORDER BY plenty_id ASC/DESC` — eindeutig, aufsteigend, chronologisch. **Siehe DOJO.md #13**
|
|
|
|
---
|
|
|
|
## 3. Aufträge im Schnellfeuer-Modus verschieben
|
|
|
|
```javascript
|
|
for (const order of orders) {
|
|
await api.updateStatus(order.id, 6); // kein Warten, keine Prüfung
|
|
}
|
|
```
|
|
|
|
**Problem:** Event-Procedures reagieren sofort auf Statuswechsel. Race Conditions zwischen eigenem Write und Plenty-Automationen sind häufig.
|
|
|
|
**Fix:** Pause + Verifizieren nach jedem Write. **Siehe DOJO.md #15**
|
|
|
|
---
|
|
|
|
## 4. Timestamps ohne Timezone-Offset senden
|
|
|
|
```javascript
|
|
"2026-03-30T02:30:00" // kein Offset — Interpretation unklar
|
|
```
|
|
|
|
**Problem:** Plenty's Verhalten bei fehlenden Offsets ist undokumentiert und endpoint-abhängig. Bei DST-Wechseln kritisch.
|
|
|
|
**Fix:** Immer `+00:00` für UTC. **Siehe DOJO.md #19**
|
|
|
|
---
|
|
|
|
## 5. Nur Zielstatus prüfen, nicht die Transition
|
|
|
|
```javascript
|
|
if (order.statusId === 6) { /* OK */ }
|
|
```
|
|
|
|
**Problem:** Auftrag kann im Zielstatus sein, aber zwischendurch durch andere Status gelaufen sein. Oder er war kurz dort und wurde weitergeschoben.
|
|
|
|
**Fix:** Statushistorie abrufen und Transition als Sequenz prüfen. **Siehe DOJO.md #15**
|
|
|
|
---
|
|
|
|
## 6. contactId ohne Relations-Fallback lesen
|
|
|
|
```javascript
|
|
const contactId = order.contactId; // kann undefined sein!
|
|
```
|
|
|
|
**Problem:** `contactId` ist nicht immer direkt am Order-Objekt vorhanden. Ohne `relations` in den `with`-Parametern fehlt er komplett.
|
|
|
|
**Fix:**
|
|
```javascript
|
|
const contactId = order.contactId
|
|
|| order.relations?.find(r => r.referenceType === 'contact')?.referenceId;
|
|
```
|
|
**Siehe DOJO.md #6, Quirk #1**
|
|
|
|
---
|
|
|
|
## 7. Status-IDs als Integer behandeln
|
|
|
|
```javascript
|
|
if (parseInt(order.statusId) === 5) { /* FALSCH */ }
|
|
if (order.statusId === 5) { /* FALSCH */ }
|
|
```
|
|
|
|
**Problem:** Plenty verwendet fraktionale Status-IDs: 5.1, 5.12, 5.32, 6.01 etc. `parseInt(5.12)` ergibt `5`, `5.12 === 5` ist `false`.
|
|
|
|
**Fix:** `parseFloat()` und Range-Vergleiche:
|
|
```javascript
|
|
const s = parseFloat(order.statusId);
|
|
if (s >= 5 && s < 6) { /* Pool */ }
|
|
```
|
|
**Siehe DOJO.md #16**
|
|
|
|
---
|
|
|
|
## 8. Status-History-Response als Array erwarten
|
|
|
|
```javascript
|
|
const entries = history; // Manchmal ist es aber { entries: [] }!
|
|
```
|
|
|
|
**Problem:** Der Endpoint gibt manchmal ein Array, manchmal ein Objekt mit `entries`-Feld zurück.
|
|
|
|
**Fix:**
|
|
```javascript
|
|
const entries = Array.isArray(history) ? history : (history.entries || []);
|
|
```
|
|
**Siehe DOJO.md #14**
|
|
|
|
---
|
|
|
|
## 9. Dokument sofort nach Generierung fetchen
|
|
|
|
```javascript
|
|
await api.post(`/rest/orders/${id}/documents/invoice/generate`);
|
|
const docs = await api.get(`/rest/orders/${id}/documents`);
|
|
// → Dokument hat status: 'pending', nicht 'done'!
|
|
```
|
|
|
|
**Problem:** Dokument-Generierung ist asynchron. Das Dokument ist nicht sofort verfügbar.
|
|
|
|
**Fix:** Retry-Loop mit steigenden Delays (3s, 5s, 8s, 10s, 15s), immer auf `status === 'done'` filtern. **Siehe DOJO.md #17**
|
|
|
|
---
|
|
|
|
## 10. Dokument-Download über Order-Endpoint
|
|
|
|
```javascript
|
|
// FALSCH:
|
|
await api.get(`/rest/orders/${id}/documents/${docId}`);
|
|
```
|
|
|
|
**Problem:** Der Download-Endpoint ist `/rest/documents/{docId}` — OHNE Order-Prefix!
|
|
|
|
**Fix:**
|
|
```javascript
|
|
const res = await api.getRaw(`/rest/documents/${docId}`);
|
|
const buffer = Buffer.from(await res.arrayBuffer());
|
|
```
|
|
**Siehe DOJO.md #18**
|
|
|
|
---
|
|
|
|
## 11. amounts-Array ohne Null-Check lesen
|
|
|
|
```javascript
|
|
const total = order.amounts[0].invoiceTotal; // Can crash!
|
|
```
|
|
|
|
**Problem:** `amounts` ist ein Array das leer sein kann. Kein Array-Zugriff ohne Check.
|
|
|
|
**Fix:**
|
|
```javascript
|
|
const total = order.amounts?.[0]?.invoiceTotal ?? null;
|
|
```
|
|
**Siehe DOJO.md #11, Quirk #7**
|
|
|
|
---
|
|
|
|
## 12. Bundle-Komponenten als eigene Artikel zählen
|
|
|
|
```javascript
|
|
const serverCount = items.filter(i => isServer(i)).reduce((sum, i) => sum + i.quantity, 0);
|
|
// → Zählt Bundle-Komponenten (typeId 3) doppelt!
|
|
```
|
|
|
|
**Problem:** Bundle-Header (`typeId 2`) enthält die Gesamtmenge. Bundle-Komponenten (`typeId 3`) sind die Einzelteile des Bundles. Beides zählen = Doppelzählung.
|
|
|
|
**Fix:** Nur `typeId 1` (Variation), `typeId 2` (Bundle-Header), `typeId 11` (Variations-Bundle) zählen. `typeId 3` (Komponenten) ignorieren. **Siehe DOJO.md #12**
|
|
|
|
---
|
|
|
|
## 13. Tag-Operationen als Fehler behandeln wenn idempotent
|
|
|
|
```javascript
|
|
// FALSCH: 409 beim Hinzufügen und 404 beim Löschen als Fehler werfen
|
|
const res = await api.post(`.../variation_tags`, { tagId: 123 });
|
|
if (res.status !== 200) throw new Error('Tag konnte nicht gesetzt werden');
|
|
```
|
|
|
|
**Problem:** `409 Conflict` beim Hinzufügen = Tag existiert bereits (gewünschter Zustand!). `404 Not Found` beim Löschen = Tag existiert nicht (auch gewünscht!).
|
|
|
|
**Fix:** Diese HTTP-Codes als Erfolg behandeln, nicht als Fehler.
|
|
|
|
---
|
|
|
|
## 14. Neue Eigenschaften über den Merkmale-Endpoint setzen
|
|
|
|
```javascript
|
|
// FALSCH: variation_properties ist für das ALTE Merkmal-System
|
|
await api.post(`/rest/items/${itemId}/variations/${varId}/variation_properties`, {
|
|
propertyId: 5, selectionRelationId: 48
|
|
});
|
|
// → 500 Foreign Key Constraint (plenty_character_item)
|
|
```
|
|
|
|
**Problem:** `variation_properties` arbeitet mit dem Legacy-Merkmal-System (`plenty_character_*`-Tabellen). Neue Eigenschaften (Property-System) werden über `/rest/properties/relations` verwaltet — komplett andere API.
|
|
|
|
**Fix:** `/rest/properties/relations` mit `relationTypeIdentifier: 'item'` verwenden. **Siehe DOJO.md #25**
|
|
|
|
---
|
|
|
|
## 15. Mehrere Bulk-Scripts parallel gegen die API laufen lassen
|
|
|
|
```javascript
|
|
// Script A: Care Packs setzen (600ms delay)
|
|
// Script B: Lizenzen setzen (600ms delay)
|
|
// → Effektiv ~3,3 Requests/s → 429 Rate Limit!
|
|
```
|
|
|
|
**Problem:** Jedes Script hält seinen eigenen Delay ein, aber die API sieht die Summe aller Requests. Andere Crons/Services teilen sich dasselbe Rate-Limit-Budget.
|
|
|
|
**Fix:** Bulk-Operationen immer sequenziell (eins nach dem anderen). Delay ≥ 1.500ms wenn andere Services parallel laufen. **Siehe DOJO.md #2**
|
|
|
|
---
|