Markdown (Eisvogel)

autoassigncustomergroups-anwenderdokumentation.md

---
title: "AutoAssignCustomerGroups"
subtitle: "Anwenderdokumentation"
author: ["André Fischer"]
date: "30-03-2026"
lang: de
titlepage: true
titlepage-color: "1E3A5F"
titlepage-text-color: "FFFFFF"
titlepage-rule-color: "4A90D9"
titlepage-rule-height: 4
toc: true
toc-own-page: true
numbersections: true
header-left: "AutoAssignCustomerGroups"
header-right: "Anwenderdokumentation"
footer-left: "ITK Computer GmbH"
---

# Konfiguration

Pfad: **Erweiterungen → Meine Erweiterungen** → Plugin **„Automatische Zuweisung von Kundengruppen“** / **Auto Assign Customer Groups** → **Konfigurieren** (ggf. **pro Verkaufskanal**, je nachdem wie du Plugin-Configs pflegst).

| Feld (intern) | Was du einträgst |
|---------------|------------------|
| **Weiterleitungs-URL nach der Registrierung** (**redirectUrl**) | Optionale vollständige URL (z. B. `https://dein-shop.de/danke`). Wenn gesetzt, antwortet der Server nach erfolgreicher Registrierung mit einer **Weiterleitung** auf diese URL. **Hinweis:** Das passiert serverseitig im Registrierungs-Event; prüfe im Zweifel ob das zu DSGVO-Hinweisen passt. |

Wenn du das Feld leer lässt, gibt es **keine** zusätzliche Redirect-Logik durch diese Einstellung.

---

# Kundengruppen richtig einstellen

Unter **Einstellungen → Shop → Kundengruppen** bearbeitest oder erstellst du die gewünschte Gruppe. Nach Plugin-Installation hängt am Custom Field Set **„BYOD zuweisung“** (bzw. Configure automatic assignment) drei Felder:

| Anzeigename | Technischer Schlüssel | Zweck |
|------------------|----------------------|--------|
| **Automatische Zuweisung** | `custom_itk_computer_gmbh_auto_assign_customer_group` | Wenn aktiv: Nach der Registrierung wird die **angeforderte** Kundengruppe automatisch übernommen (der Kunde „landet“ fest in dieser Gruppe). |
| **Registrierungscodes verwenden** | `custom_itk_computer_gmbh_use_registration_codes` | Wenn aktiv: Im **Registrierungsformular dieser Kundengruppe** erscheint das Pflichtfeld für den **Registrierungscode** (**rcode**). |
| **API-URL aufrufen** | `custom_itk_computer_gmbh_call_api_url` | Optional: URL für einen **POST**-Request mit JSON **{"customerId":"<uuid>"}** direkt nach erfolgreicher automatischer Zuweisung (nur wenn „Automatische Zuweisung“ greift und der Ablauf ohne Fehler durchläuft). |

Du kannst z. B. nur **Automatische Zuweisung** nutzen (ohne Codes) oder Codes **und** automatische Zuweisung kombinieren – je nachdem, wie du die Gruppe konfigurierst.

---

# Registrierungscodes verwalten (Administration)

Im Shopware-Admin gibt es einen Menüeintrag unter **Kunden**:

- Menüeintrag in der Nähe der Kundenverwaltung mit dem Titel aus den Snippets (**registration-code** / Registrierungscodes).
- Routen: **Liste**, **Neu anlegen**, **Bearbeiten**, **Generieren** (Stapel/Generator, je nach Implementierung der Vue-Seiten).

Dort pflegst du Einträge der Entität **Registrierungscode**. Inhaltlich sind das im Wesentlichen:

- **Code** – der String, den der Nutzer im Shop eingibt (wird bei der Suche **exakt** wie übergeben verglichen – Groß-/Kleinschreibung beachten, es sei denn ihr habt das im Theme/Prozess vereinheitlicht).
- **Schulname** (`school_name`) – in diesem Plugin **Pflicht** (fachlicher Bezug, z. B. Organisation).
- **Projektname** (`project_name`) – optional.
- **Verwendet am** (`used_at`) / **Kunden-E-Mail** (`customer_email`) – werden bei Nutzung gesetzt; du siehst damit, ob ein Code schon „verbraucht“ ist.

**Wichtig:** Ein Code mit gesetztem `used_at` wird bei einer neuen Registrierung **abgelehnt** („already used“). Plane also pro Person einen eigenen Code oder einen klaren Prozess zum Anlegen neuer Codes.

---

# Ablauf aus Sicht des Kunden

## Diagramm: Registrierung vereinfacht

```mermaid
flowchart TD
  R[Registrierung starten] --> C{Registrierungscodes aktiv?}
  C -->|Ja| Code[Code eingeben]
  C -->|Nein| Send[Absenden]
  Code --> OK{Code gueltig?}
  OK -->|Nein| Err[Fehlermeldung]
  OK -->|Ja| Send
  Send --> A{Automatische Zuweisung?}
  A -->|Ja| G[Kundengruppe fix]
  A -->|Nein| Std[Standard Ablauf]
  G --> X[Optional API und Redirect]
```
1. Der Kunde erhält & öffnet die **Registrierung für eine bestimmte Kundengruppe**.
2. Ist an dieser Gruppe **„Registrierungscodes verwenden“** aktiv, sieht er ein Feld für den **Registrierungscode** (technisch **rcode**). Es ist im Template als **Pflichtfeld** markiert – ohne Eingabe kann das Formular nicht sinnvoll abgeschickt werden.
3. Beim Absenden prüft das Plugin, ob der Code **existiert** und noch **nicht verwendet** (`used_at` leer) ist. Wenn nicht → Fehler (ungültiger oder bereits genutzter Code).
4. Schlägt die Prüfung fehl, bricht die Registrierung an dieser Stelle ab. **Hinweis:** In der aktuellen Implementierung kann der Datensatz des Codes **bereits mit E-Mail und Zeitstempel vor dem finalen Speichern des Kunden** aktualisiert werden; wenn danach die Registrierung aus anderen Gründen scheitert, kann der Code fachlich „blockiert“ sein – im Zweifel im Admin prüfen oder neuen Code vergeben (siehe Troubleshooting).
5. Wenn an der Kundengruppe **„Automatische Zuweisung“** aktiv ist, wird nach erfolgreicher Registrierung die angeforderte Gruppe **fest** zugewiesen.
6. Optional: Aufruf eurer **API-URL** und/oder **Weiterleitung** laut Plugin-Konfiguration.

---

# Konsole (CLI) – Kurzüberblick

Alle Befehle im Projektroot, typischerweise:

```bash
php bin/console <befehl>
```

| Befehl | Zweck |
|--------|--------|
| `itk:registration-code:list` | Codes auflisten. |
| `itk:registration-code:create` | Code anlegen (`--school` Pflicht, optional `--code`, `--project`, `--interactive`). |
| `itk:registration-code:edit` | Eintrag bearbeiten. |
| `itk:registration-code:delete` | Eintrag löschen. |
| `itk:registration-code:generate` | Codes generieren (Stapel). |
| `itk:registration-code:export` | Export. |
| `itk:registration-code:stats` | Statistiken. |
| `itk:registration-code:setup` | Interaktives Setup/Menü. |
| `itk:test` | Technischer Test („Test command works!“) – für Entwicklung/Betrieb ohne fachliche Funktion. |

Für genaue Optionen jeweils **php bin/console <befehl> --help** ausführen.

**Hinweis:** Es gibt **keinen** mitgelieferten Befehl wie **assign-customer** oder **cleanup** – Zuweisungen laufen über den Registrierungsprozess bzw. den Admin.

---

# Logging

Das Plugin schreibt nach:

`var/log/auto_assign_customer_groups.log`

Dort findest du Meldungen zu Gruppenbestätigung, Zuweisung, API-Aufrufen und Fehlern im Subscriber. Wenn etwas „still“ fehlschlägt, ist das die erste Anlaufstelle neben den Shopware-Standardlogs.

---

# Grenzen und bewusste Besonderheiten

- Registrierungscodes sind **nicht** „10× nutzbar“ oder „gültig bis Datum“ in der Datenbank dieses Stands – es gibt **einmalige Nutzung** über `used_at` und fachliche Felder Schul-/Projektname.
- Die **Kundengruppe**, in die der Kunde „fest“ kommt, steht **nicht** im Code-Datensatz, sondern ergibt sich aus der **gewählten Registrierungs-Kundengruppe** plus **Automatische Zuweisung**.
- **API-URL** und **Redirect** sind **Power-Features** – teste sie auf Staging und achte auf DSGVO (wohin gehen Kundendaten).

---

# Troubleshooting

| Symptom | Was du prüfst |
|---------|----------------|
| Code wird nicht akzeptiert | Existiert der Code? Ist `used_at` noch leer? Exakte Schreibweise des Codes? |
| Feld „Registrierungscode“ fehlt | Custom Field **Registrierungscodes verwenden** an **dieser** Kundengruppe aktiv? Cache leeren, Theme kompilieren. |
| Kunde bleibt in falscher Gruppe | Ist **Automatische Zuweisung** an der **angeforderten** Gruppe gesetzt? Logs prüfen – ohne Flag wirft der interne Check eine Exception und die Zuweisung erfolgt nicht. |
| API wird nicht aufgerufen | URL korrekt? curl auf dem Server erlaubt? Logs in `auto_assign_customer_groups.log`. |
| Redirect passiert nicht | System-Config **redirectUrl** gesetzt? Nur relevant, wenn der Registrierungs-Event komplett durchläuft und die Zuweisung-Logik greift. |

---

# FAQ

**Muss jeder Kunde einen Code haben?**  
Nur wenn die Kundengruppe **Registrierungscodes verwenden** hat – dann ist das Feld im Template vorgesehen. Ohne dieses Flag erscheint kein Code-Feld.

**Kann ich dieselbe Kundengruppe für mehrere Schulen nutzen?**  
Du unterscheidest über **Codes** und die Felder Schul-/Projektname in den Datensätzen; die **Shopware-Gruppe** ist eine pro Registrierungslink bzw. gewählte Gruppe.