# RiccardoOffers – persönliche Angebote

Rabattcodes je Kunde, Kundengruppe oder Tag, angezeigt als Band mit Countdown,
Code-Kopierknopf und Ein-Klick-Einlösung.

## Aufteilung: wer rechnet den Rabatt?

Den **Rabatt rechnet Shopware** über eine ganz normale Aktion (Marketing →
Aktionen) mit Aktionscode. Dieses Plugin kümmert sich nur um die
**Personalisierung und die Anzeige** – wer welchen Code sieht, wie lange, und mit
welchem Text. So bleiben Rabattlogik, Mehrfachverwendung und Warenkorbprüfung dort,
wo Shopware sie schon beherrscht.

Im Angebot wird deshalb beides hinterlegt: die Aktion (Referenz) und der Code, der
im Banner steht. Der Code muss zum Aktionscode passen.

## Zielgruppen

| Zielgruppe | Wer sieht das Angebot |
|---|---|
| Ausgewählte Kunden | nur die zugeordneten Kundenkonten |
| Kundengruppe | alle Kunden dieser Gruppe |
| Kunden mit Tag | alle Kunden mit diesem Tag |
| Alle angemeldeten Kunden | jedes eingeloggte Konto |

Gäste sehen nie ein Angebot – ohne Konto gibt es keine Personalisierung.
Passen mehrere Angebote, gewinnt die höhere **Priorität**.

## Fristen

* **Persönlicher Countdown** (`durationHours`): die Frist startet, wenn der Kunde das
  Banner zum ersten Mal sieht. Start und Ablauf stehen in `riccardo_offer_state` je
  Kunde – der Countdown läuft also nicht für alle gleich (wie bei eis.de).
* **Feste Frist**: `startsAt` / `endsAt`.
* Beides gesetzt? Dann gilt der früheste Ablauf.

Ist der Code eingelöst, wird `redeemedAt` gesetzt und das Banner verschwindet für
diesen Kunden – ein nachrangiges Angebot rückt nach.

## Warum per JavaScript nachgeladen?

Persönliche Inhalte dürfen nicht in einer cachebaren Seite landen. Das Theme setzt
nur den Platzhalter `<div data-rz-offer>`; den Inhalt holt
`rz-offer.plugin.js` von `/widgets/riccardo/angebot` (Antwort `no-store`, ohne
Angebot HTTP 204). Der Countdown läuft im Browser mit, ab zwei Tagen Restzeit wird
auf Tage umgestellt.

Einlösen geht über `/widgets/riccardo/angebot/einloesen`: der Code wird als
Aktionsposition in den Warenkorb gelegt, das Angebot als eingelöst vermerkt und auf
den Warenkorb weitergeleitet.

## Pflege

*Marketing → Persönliche Angebote*: Anzeige (Überschrift, Störer, Text, Link),
Rabatt (Aktion + Code), Zielgruppe und Gültigkeit. Die Karte „Gültigkeit" zeigt in
Worten, was eingestellt ist.

Demodaten: `php dev/demo-data/offers.php [kunden-mail]` legt zwei Aktionen
(RABATT30, TREUE10) und zwei Angebote an – eines persönlich für die angegebene
Adresse mit 48-Stunden-Countdown, eines für alle Kunden mit fester Frist.

## Build

`bin/build-storefront.sh` und `bin/console theme:compile`; für das Admin-Modul
`bin/build-administration.sh` und `bin/console assets:install`.