Documentation

Checkout-Erweiterungen

Das ShopBite Plugin bietet erweiterte Checkout-Funktionen, die speziell für Gastronomie- und Einzelhandelsbetriebe entwickelt wurden. Dieses Kapitel erklärt die Konfiguration und Nutzung dieser Funktionen.

Übersicht

Die Checkout-Erweiterungen umfassen:

  • Container-basierte Produkte: Spezielle Verarbeitung für Produktgruppen
  • Bon-Drucktypen: Unterschiedliche Druckformate für verschiedene Produkte
  • Custom Fields: Erweiterte Produktattribute für Gastronomie
  • Lieferzeitberechnung: Dynamische Berechnung basierend auf Produktattributen
  • Bestelltypen: Abholung, Lieferung, Vor Ort

Container-basierte Produkte

Funktionsweise

Container-basierte Produkte ermöglichen die Gruppierung von Artikeln:

  • Beispiel: Menü mit Hauptgericht, Beilage und Getränk
  • Vorteile: Einfache Bestellung komplexer Produktkombinationen
  • Verarbeitung: Spezielle Logik im Checkout-Prozess

Konfiguration

  1. Produkt erstellen:
    • Navigieren Sie zu Katalog > Produkte
    • Neues Produkt erstellen
    • Produkttyp: "Container" auswählen
  2. Container-Inhalte definieren:
    • Container-Elemente hinzufügen
    • Pflichtfelder markieren
    • Auswahloptionen konfigurieren
  3. Preisgestaltung:
    • Fester Preis: Gesamtpreis für den Container
    • Dynamischer Preis: Summe der enthaltenen Artikel
    • Rabatte: Container-spezifische Rabatte

Beispiel: Pizza-Menü

Container: Pizza-Menü
- Hauptgericht: Pizza (Pflichtfeld)
  - Optionen: Margherita, Salami, Hawaii
- Beilage: Salat oder Pommes (Pflichtfeld)
  - Optionen: Caesar Salat, Gemischter Salat, Pommes
- Getränk: Optional
  - Optionen: Cola, Fanta, Wasser, Bier

Bon-Drucktypen

Custom Fields Konfiguration

  1. Custom Fields einrichten:
    • Navigieren Sie zu Einstellungen > Custom Fields
    • ShopBite Produkt Set auswählen
  2. Bon-Drucktyp Feld:
    • Feldname: shopbite_receipt_print_type
    • Typ: Auswahlfeld
    • Optionen:
      • standard: Normaler Bon-Druck
      • kitchen: Küchenbon für Zubereitung
      • bar: Barbon für Getränke
      • no_print: Kein Bon-Druck erforderlich

Produktkonfiguration

  1. Produkt bearbeiten:
    • Navigieren Sie zu Katalog > Produkte
    • Produkt auswählen
  2. Custom Fields setzen:
    • Bon-Drucktyp auswählen
    • Speichern

Beispielkonfiguration

ProduktBon-DrucktypBeschreibung
Pizza MargheritakitchenWird in der Küche zubereitet
Cola 0,33lbarWird an der Bar ausgegeben
DessertstandardNormaler Bon-Druck
Gutscheinno_printKein physischer Bon nötig

Technische Implementierung

Der ReceiptPrintTypeProcessor verarbeitet die Bon-Drucktypen:

// src/Checkout/Cart/ReceiptPrintTypeProcessor.php

public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
{
    foreach ($toCalculate->getLineItems()->filterFlatByType(LineItem::PRODUCT_LINE_ITEM_TYPE) as $lineItem) {
        $productId = $lineItem->getReferencedId();
        if ($productId === null) {
            continue;
        }
        
        $product = $data->get(self::DATA_KEY . $productId);
        if ($product === null) {
            continue;
        }
        
        $customFields = $product->getCustomFields() ?? [];
        if (!isset($customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE])) {
            continue;
        }
        
        $lineItem->setPayloadValue(
            CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE,
            $customFields[CustomFieldsInstaller::SHOPBITE_RECEIPT_PRINT_TYPE]
        );
    }
}

Lieferzeitberechnung

Custom Fields für Lieferzeiten

  1. Lieferzeitfaktor Feld:
    • Feldname: shopbite_delivery_time_factor
    • Typ: Ganzzahl
    • Standardwert: 1
  2. Produktkonfiguration:
    • Faktor 1: Standard-Lieferzeit
    • Faktor 2: Doppelte Lieferzeit
    • Faktor 3: Dreifache Lieferzeit

Berechnungslogik

// Beispielberechnung in der Storefront
function calculateDeliveryTime(product) {
    const baseTime = 30; // Basis-Lieferzeit in Minuten
    const factor = product.customFields?.shopbite_delivery_time_factor || 1;
    
    return baseTime * factor; // Ergebnis in Minuten
}

// Beispiel
const pizza = { customFields: { shopbite_delivery_time_factor: 2 } };
const deliveryTime = calculateDeliveryTime(pizza); // 60 Minuten

Beispielprodukte

ProduktFaktorBerechnete Lieferzeit
Pizza260 Minuten
Salat130 Minuten
Getränk0.515 Minuten
Dessert130 Minuten

Bestelltypen

Konfiguration

  1. Bestelltypen aktivieren:
    • Navigieren Sie zu ShopBite > Checkout > Bestelltypen
    • Gewünschte Typen aktivieren
  2. Bestelltypen:
    • Abholung: Kunden holen die Bestellung selbst ab
    • Lieferung: Bestellung wird geliefert
    • Vor Ort: Bestellung für den sofortigen Verzehr

Checkout-Integration

// Bestelltypen in der Storefront
const orderTypes = [
    { id: 'pickup', name: 'Abholung', description: 'Selbst abholen' },
    { id: 'delivery', name: 'Lieferung', description: 'Zustellung' },
    { id: 'on_site', name: 'Vor Ort', description: 'Hier verzehren' }
];

// Bestelltyp auswählen
function selectOrderType(typeId) {
    // Logik zur Auswahl des Bestelltyps
    console.log(`Bestelltyp ausgewählt: ${typeId}`);
}

Custom Fields Installation

Automatische Installation

Das Plugin installiert die Custom Fields automatisch:

// src/Service/CustomFieldsInstaller.php

public function install(Context $context): void
{
    $customFieldSetId = Uuid::fromHexToBytes(self::CUSTOM_FIELDSET_ID);
    
    $customFieldSetData = [
        'id' => self::CUSTOM_FIELDSET_ID,
        'name' => self::CUSTOM_FIELDSET_NAME,
        'config' => [
            'label' => [
                'en-GB' => 'ShopBite',
                'de-DE' => 'ShopBite',
            ],
        ],
        'customFields' => [
            [
                'id' => '0198be8b24a0722cac46b07e3a9686ec',
                'name' => 'shopbite_delivery_time_factor',
                'type' => CustomFieldTypes::INT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Delivery Time Factor',
                        'de-DE' => 'Lieferzeitfaktor',
                    ],
                ],
            ],
            [
                'id' => '01944f2b1875706596395b8d23966952',
                'name' => self::SHOPBITE_RECEIPT_PRINT_TYPE,
                'type' => CustomFieldTypes::SELECT,
                'config' => [
                    'label' => [
                        'en-GB' => 'Receipt Print Type',
                        'de-DE' => 'Bon-Drucktyp',
                    ],
                    'options' => [
                        ['value' => 'standard', 'label' => ['en-GB' => 'Standard', 'de-DE' => 'Standard']],
                        ['value' => 'kitchen', 'label' => ['en-GB' => 'Kitchen', 'de-DE' => 'Küche']],
                        ['value' => 'bar', 'label' => ['en-GB' => 'Bar', 'de-DE' => 'Bar']],
                        ['value' => 'no_print', 'label' => ['en-GB' => 'No Print', 'de-DE' => 'Kein Druck']],
                    ],
                ],
            ],
        ],
    ];
    
    $this->customFieldSetRepository->upsert([$customFieldSetData], $context);
}

Manuelle Installation

Falls die automatische Installation fehlschlägt:

# Custom Fields manuell installieren
bin/console shopbite:custom-fields:install

# Custom Fields prüfen
bin/console custom-field:set:list | grep shopbite

API-Integration

Checkout-API-Endpunkte

POST /store-api/checkout/cart/line-item

Beispielanfrage

curl -X POST "https://Ihre-Shopware-Domain.de/store-api/checkout/cart/line-item" \
  -H "Authorization: Bearer IhrAPIToken" \
  -H "sw-access-key: IhrAccessKey" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ]
  }'

Beispielantwort

{
  "data": {
    "lineItems": [
      {
        "id": "019a36f224b0704fb6835914050392f4",
        "type": "product",
        "referencedId": "019a36f224b0704fb6835914050392f4",
        "quantity": 1,
        "payload": {
          "shopbite_receipt_print_type": "kitchen",
          "shopbite_delivery_time_factor": 2
        }
      }
    ],
    "deliveryTime": 60
  }
}

Best Practices

1. Konsistente Produktkonfiguration

  • Verwenden Sie einheitliche Custom Fields für alle Produkte
  • Dokumentieren Sie die Bedeutung der Felder
  • Schulen Sie Ihr Team in der korrekten Nutzung

2. Performance-Optimierung

-- Indizes für Custom Fields
CREATE INDEX `idx_custom_fields` ON `product` (`custom_fields`);

-- Optimierung für häufige Abfragen
CREATE INDEX `idx_receipt_print_type` ON `product` 
  ((CAST(custom_fields->>'$.shopbite_receipt_print_type' AS CHAR(50))));

3. Validierung

// Validierung im Checkout-Prozess
public function validateCheckout(Cart $cart): array
{
    $errors = [];
    
    foreach ($cart->getLineItems() as $lineItem) {
        $payload = $lineItem->getPayload();
        
        if (!isset($payload['shopbite_receipt_print_type'])) {
            $errors[] = sprintf(
                'Produkt %s hat keinen Bon-Drucktyp',
                $lineItem->getLabel()
            );
        }
        
        if (!isset($payload['shopbite_delivery_time_factor'])) {
            $errors[] = sprintf(
                'Produkt %s hat keinen Lieferzeitfaktor',
                $lineItem->getLabel()
            );
        }
    }
    
    return $errors;
}

4. Caching-Strategie

# In config/packages/cache.yaml
framework:
    cache:
        pools:
            shopbite.checkout:
                adapter: cache.adapter.redis
                default_lifetime: 300  # 5 Minuten Cache

Fehlerbehandlung

Häufige Probleme

Problem: Custom Fields werden nicht angezeigt

Symptome:

  • Custom Fields fehlen in der Administration
  • Felder werden nicht gespeichert

Lösungen:

# Custom Fields neu installieren
bin/console shopbite:custom-fields:install --force

# Cache leeren
bin/console cache:clear

# Datenbank prüfen
mysql -u shopware -p shopware -e "SELECT * FROM custom_field_set WHERE name = 'shopbite_product_set';"

Problem: Bon-Drucktyp wird ignoriert

Symptome:

  • Alle Bons werden mit Standardtyp gedruckt
  • Custom Field-Werte werden nicht übernommen

Lösungen:

# Checkout-Prozessor prüfen
bin/console debug:container --tag=shopware.checkout.cart.processor

# Plugin-Cache leeren
bin/console plugin:refresh ShopBite

# Custom Fields prüfen
bin/console custom-field:set:list

Problem: Lieferzeitberechnung falsch

Symptome:

  • Falsche Lieferzeiten
  • Berechnung stimmt nicht mit Erwartungen überein

Lösungen:

# Custom Field-Werte prüfen
mysql -u shopware -p shopware -e "
  SELECT id, custom_fields FROM product 
  WHERE custom_fields LIKE '%shopbite_delivery_time_factor%' LIMIT 5;
"

# Berechnungslogik prüfen
bin/console config:get ShopBitePlugin.config.baseDeliveryTime

# Debug-Modus aktivieren
bin/console config:set ShopBitePlugin.config.debug true

Nächste Schritte