Diese Serie hat ein ungewöhnliches Ziel: nicht ein einzelnes Magento-2-Feature zu erklären, sondern wirklich jeden Bausteintyp, aus dem ein eigenes Magento-2-Modul bestehen kann - Model und ResourceModel, EAV-Entities, eigene Attribute auf Produkt, Kategorie, Kunde, Firma und Bestellung, Observer und Cron, Plugins und Preferences, Controller und Router, Blocks und ViewModels, Widgets und Page Builder, eigene Zahlungs- und Versandarten, ein eigener Produkttyp, REST- und GraphQL-API, Konfigurationstypen, Übersetzungen und Unit Tests. 32 Bereiche, 106 Kapitel, 12 Blöcke - und ein einziges, durchgehendes Beispielprojekt, das all das braucht, ohne sich künstlich anzufühlen.

Das Business-Szenario: Mironsoft Loyalty & Rewards

Das Beispielprojekt heißt Mironsoft Loyalty & Rewards: ein Treuepunkte- und Prämienprogramm für einen Magento-2-Shop. Kunden sammeln beim Einkauf Punkte, die je nach Produkt, Kategorie und - bei B2B-Kunden - Firmen-Tier unterschiedlich hoch ausfallen. Sie sehen ihren Punktestand im Kundenkonto, lösen Punkte gegen Prämien ein (Rabattgutscheine, Gratisprodukte, Gratisversand) oder nutzen Punkte als Teilzahlung im Checkout. Ein tägliches Cronjob lässt alte Punkte verfallen und berechnet Treue-Stufen (Bronze, Silber, Gold) neu.

Dieses eine Feature ist bewusst gewählt, weil es organisch jeden der 32 angeforderten Modul-Bereiche benötigt - keiner davon wird künstlich hinzugefügt, nur um ihn abzuhaken. Eine Prämie mit variablen Eigenschaften braucht eine EAV-Entity. Punkte-pro-Produkt braucht ein Produkt-Attribut. Der Punkte-Verfall braucht Cron. Eine Teilzahlung mit Punkten braucht eine eigene Zahlungsart. Und so weiter - jedes Kapitel baut auf demselben Modul Mironsoft\Loyalty auf.

Architektur-Überblick: alle 32 Bereiche und wo sie vorkommen

Der Rest dieses Kapitels ordnet alle 32 angeforderten Modul-Bereiche den zwölf Blöcken dieser Serie zu - als Wegweiser, nicht als vollständige Erklärung. Jeder Bereich wird in seinem eigenen Kapitel im Detail behandelt.

Datenhaltung, Konfiguration, Cache und CLI (Block 1, dieser Block)

Block 1 legt das Fundament: eine schlichte Datenbanktabelle, darüber Model, ResourceModel, Collection und Repository, eine eigene Konfigurationsseite, ein eigener Cache-Typ und ein Konsolenbefehl.

• Model (Kapitel 4): das klassische Model/ResourceModel/Collection-Dreigespann für den Punkte-Ledger.
• System/Config/Setting (Kapitel 7): eine eigene Konfigurationsseite unter Stores > Configuration mit Punkte-pro-Euro, Ablaufzeit und Tier-Schwellenwerten.
• Cache (Kapitel 8): ein eigener Cache-Typ für den Prämienkatalog, der in Block 2 gefüllt wird.
• Console Command (Kapitel 9): ein CLI-Befehl zur manuellen Punkte-Neuberechnung und zum Audit des Ledgers.

Die Prämien-Entity als EAV (Block 2)

Eine Prämie ("Reward") hat variable, erweiterbare Eigenschaften - der klassische Anwendungsfall für eine eigene EAV-Entity, nach demselben Muster wie catalog_product_entity.

• EAV Entity (Kapitel 10-18): die komplette Reward-Entity mit Entity- und Attribut-Tabellen, Model, Collection und Admin-Grid.
• EAV Attribute, custom (Kapitel 13-14): eigene Attribute wie points_cost, discount_value und reward_type per Setup-Skript definieren.

Attribute auf bestehenden Entitäten (Block 3)

Punkte müssen sich an Produkt, Kategorie, Kunde, Firma und Bestellung festmachen lassen - fünf verschiedene Attribut-Typen an fünf verschiedenen Kern-Entitäten.

• Product Attribute (Kapitel 19): loyalty_points_multiplier am Produkt.
• Category Attribute (Kapitel 20): ein Bonus-Multiplikator pro Kategorie.
• Customer Attribute (Kapitel 21): Punktestand und Treue-Stufe am Kunden.
• Company Attribute (Kapitel 22): B2B-Sonderkonditionen auf der Firma (Magento_Company).
• Sales Attribute (Kapitel 23): erzielte Punkte an Order und Order Item.

Events, Observer und Cron (Block 4)

Punkte werden nicht synchron im Checkout-Code vergeben, sondern reaktiv über Events - und der tägliche Verfall läuft über eine eigene Cron-Gruppe.

• Observer/Event (Kapitel 29-31, 35-36): Punktevergabe bei Bestellabschluss, Rückbuchung bei Gutschrift, eigene Events für andere Module.
• Crongroup (Kapitel 32): eine eigene Cron-Gruppe mironsoft_loyalty mit eigener Ausführungsfrequenz.
• Cronjob (Kapitel 33): der tägliche Job für Punkte-Ablauf und Tier-Neuberechnung.

Plugins, Preferences und Helper (Block 5)

Manchmal reicht Eventbeobachtung nicht - der Checkout-Rabatt durch Punkte muss aktiv in eine bestehende Berechnung eingreifen.

• Plugin (Kapitel 38-39): ein Interceptor auf den Checkout-Totals-Collector, der den Punkte-Rabatt anwendet.
• Preference/Rewrite (Kapitel 40-42): wann eine Preference statt eines Plugins nötig ist, an einer eigenen Punkte-Berechnung gezeigt.
• Helper (Kapitel 44): wann eine klassische Helper-Klasse trotz ViewModel-Präferenz noch sinnvoll ist (Legacy-Kompatibilität).

Controller, Router und Frontend-Anzeige (Block 6)

Kunden brauchen eine sichtbare Oberfläche: eine Punkte-Historie-Seite und einen Prämienkatalog unter einer eigenen, sprechenden URL.

• Controller (Kapitel 45, 50): die Punkte-Historie-Seite und der Redeem-Controller zum Einlösen einer Prämie.
• Router (Kapitel 46): ein eigener Router für URLs unter /treuepraemien/ beziehungsweise /rewards/.
• Block (Kapitel 47): der direkte Vergleich Block-Klasse gegen ViewModel in der Praxis.
• Viewmodel (Kapitel 48): das ViewModel für den Punktestand auf der Kontoseite.

Widget und Page Builder (Block 7)

• Widget (Kapitel 55-57): ein "Meine Punkte"-Widget für CMS-Seiten mit Admin-konfigurierbaren Parametern.
• PageBuilder Content Type (Kapitel 58-60): ein eigener "Punkte-Banner"-Content-Type samt Vorschau-Template.

Zahlungs- und Versandarten (Block 8)

• Payment Method (Kapitel 62-65): "Punkte einlösen" als eigene Zahlungsart für die Teilzahlung im Checkout.
• Shipping Method (Kapitel 66-69): "Kostenloser Versand durch Punkte" als eigene Versandart mit eigener Rate-Kalkulation.

Ein eigener Produkttyp (Block 9)

• Product Type (Kapitel 71-78): ein "Punkte-Paket"-Produkttyp, mit dem Kunden Punkte direkt kaufen können - von etc/product_types.xml bis zur Bestellabwicklung.

API und GraphQL (Block 10)

• Api (Kapitel 79-81): eine eigene REST-API für Punktestand und Prämien-Einlösung, abgesichert über ACL.
• GraphQl Endpoint (Kapitel 82-83): Punktestand und Prämienkatalog per GraphQL abfragen, eine Prämie per Mutation einlösen.
• Customer(Section) Data (Kapitel 84): der Punktestand live im Mini-Cart und Checkout per AJAX (Customer Section Data).

Konfigurationstypen, Sprache und Tests (Block 11)

• Configuration Type (Kapitel 88): eigene Config-Typen jenseits von System/Config.
• Language (Kapitel 89-90): eigene i18n-CSV-Dateien für Store-Views und Admin-Oberfläche.
• Unit Test (Kapitel 91-95): der PointsCalculator-Service als Ziel für Unit Tests, Mocking von Repositories, Integration Tests, Testabdeckung und CI.

Zusammenspiel und Abschluss (Block 12)

Block 12 führt keine neuen Bereiche mehr ein, sondern zeigt, wie alle 32 Bausteine in einem einzigen Modul zusammenspielen: Modul-Abhängigkeiten, Deployment-Sequenz, Performance- und Sicherheitsüberlegungen, ein Troubleshooting-Leitfaden und ein Spickzettel über alle 32 Bereiche zum Nachschlagen.