Abo Einmalprodukte: Phase 4 - Ausfuehrung, Purge & User-Retry

- UserMakeOrder: bestaetigte Einmal-Artikel in den Yard, is_abo_addon
  auf ShoppingOrderItem; amount bleibt reiner Abo-Betrag (Reihenfolge)
- AboOneTimeService::purgeAfterExecution: loescht alle Einmal-Artikel
  und rechnet Comp-Produkte neu - nur im Erfolgszweig (Cron + Retry)
- User-Retry in Sales Center und Portal mit Berechtigungspruefung,
  gemeinsames Confirm-Modal; Admin-Retry unveraendert
- Tests: AboMakeOrderOneTimeTest, AboUserRetryTest; Plan-Doku Phase 4

Co-authored-by: Cursor <cursoragent@cursor.com>

dev/2026-06-05/ENTWICKLUNGSPLAN-ABO-EINMALPRODUKTE.md

@@ -230,16 +230,35 @@ Neuer Slug **`abo-onetime-window-days`** (Typ `int`, Default `4`) in der „Abo
 
 ---
 
-### Phase 4 – Ausführung, Retry & Aufräumen · `OFFEN`
+### Phase 4 – Ausführung, Retry & Aufräumen · `ERLEDIGT (2026-06-08)`
 
-- [ ] 4.1 `UserMakeOrder::makeShoppingOrder()`: Einmal-Artikel mit in den Yard; beim Anlegen der `ShoppingOrderItem` `is_abo_addon=true` setzen; Zahlbetrag = kombiniert.
-- [ ] 4.2 Zentrale Purge-Methode bei **Erfolg** aufrufen (Cron-Erfolg **und** `AboRetryPaymentService::markAboSuccess()`); bei Fehler **behalten** (Entscheidung #2/#3).
-- [ ] 4.3 `user_abos.amount` entkoppeln – reiner Abo-Betrag bleibt unverfälscht (Punkt 9.1).
-- [ ] 4.4 User-seitiges Retry: Route + Action im Sales Center (`User\AboController`) und Portal (`Portal\AboController`) → `AboRetryPaymentService::retry()` mit Berechtigungs-Check; Admin-Retry bleibt bestehen.
-- [ ] 4.5 num_comp bei Ausführung zurücksetzen (Einmal-Artikel raus → Kompensationsprodukte neu/zurück).
-- [ ] 4.6 Tests: Cron setzt `is_abo_addon` korrekt; Purge nur bei Erfolg; Behalten bei Fehler; User-Retry inkl. Einmal-Artikel; `amount` unverfälscht.
+- [x] 4.1 `UserMakeOrder::makeShoppingOrder()`: Einmal-Artikel mit in den Yard; beim Anlegen der `ShoppingOrderItem` `is_abo_addon=true` setzen; Zahlbetrag = kombiniert.
+- [x] 4.2 Zentrale Purge-Methode bei **Erfolg** aufrufen (Cron-Erfolg **und** `AboRetryPaymentService::markAboSuccess()`); bei Fehler **behalten** (Entscheidung #2/#3).
+- [x] 4.3 `user_abos.amount` entkoppeln – reiner Abo-Betrag bleibt unverfälscht (Punkt 9.1).
+- [x] 4.4 User-seitiges Retry: Route + Action im Sales Center (`User\AboController`) und Portal (`Portal\AboController`) → `AboRetryPaymentService::retry()` mit Berechtigungs-Check; Admin-Retry bleibt bestehen.
+- [x] 4.5 num_comp bei Ausführung zurücksetzen (Einmal-Artikel raus → Kompensationsprodukte neu/zurück).
+- [x] 4.6 Tests: Cron setzt `is_abo_addon` korrekt; Purge nur bei Erfolg; Behalten bei Fehler; User-Retry inkl. Einmal-Artikel; `amount` unverfälscht.
 
-**Doku:** _(nach Umsetzung ausfüllen)_
+**Doku (2026-06-08):**
+
+- **Ausführung – Einmal-Artikel in die Bestellung (4.1 + 4.3):** `app/Cron/UserMakeOrder.php@makeShoppingOrder()` ruft nach `AboOrderCart::makeOrderYard($this->userAbo)` zusätzlich `AboOrderCart::addOneTimeItemsToYard($this->userAbo)` auf. Da `addOneTimeItemsToYard()` ausschließlich **verbindlich bestätigte** Artikel lädt (`confirmed_at` gesetzt **und** `confirmed_qty === qty`), fließen nur diese in Versand, Gewicht, Comp-Produkte und Abbuchungsbetrag ein. Beim Schreiben der `ShoppingOrderItem` wird `is_abo_addon` aus `options->abo_addon` gesetzt (`(bool) ($item->options->abo_addon ?? false)`).
+- **`amount` entkoppelt (4.3):** Die Reihenfolge ist entscheidend – `makeOrderYard()` setzt `user_abos.amount` auf den **reinen** Abo-Betrag, `addOneTimeItemsToYard()` rührt `amount` nicht an. Ergebnis: gespeicherter Abo-Betrag bleibt unverfälscht, der Zahlbetrag der konkreten Bestellung (`total_shipping`) ist kombiniert (Abo + Einmal).
+- **Purge & Comp-Reset nur bei Erfolg (4.2 + 4.5):** Neue Methode `AboOneTimeService::purgeAfterExecution(UserAbo $userAbo)`:
+  1. Löscht **alle** Einmal-Artikel des Abos endgültig (`UserAboOneTimeItem::withTrashed()->where('user_abo_id', …)->each(forceDelete)` – bestätigt, offen und soft-deleted).
+  2. Bewertet die Kompensationsprodukte des **reinen** Abos neu (Option A): `AboOrderCart::initYard()` + `makeOrderYard()` + `checkNumOfCompProducts()`. Das durch Einmal-Artikel verursachte Zusatzgewicht ist nun weg → überzählige Comp-Artikel werden entfernt.
+  - Aufruf im **Erfolgszweig** von `app/Console/Commands/UserMakeAboOrder.php@updateAbo()` (Cron, nach `IncentiveTracker::trackAboActivated`) und `app/Services/AboRetryPaymentService.php@markAboSuccess()` (nach Incentive-Tracking).
+  - Bei **Zahlungsfehler** bleiben die Einmal-Artikel als offener Entwurf erhalten (Entscheidung #2/#3) – der Fehlerzweig ruft keinen Purge auf.
+  - **Robustheit:** Schlägt das Löschen oder die Comp-Neuberechnung fehl, wird der bereits erfolgreiche Lauf **nicht** zurückgerollt; Fehler landen nur im Log-Channel `abo_order`.
+- **User-Retry (4.4):**
+  - **Sales Center:** `User\AboController@retryPayment($view, $id, AboRetryPaymentService)` – Berechtigung über `checkPermissions($view, $user_abo)`, Redirect auf `user_abos_detail`. Route `POST /user/abos/retry-payment/{view}/{id}` (`user_abos_retry_payment`, `routes/domains/crm.php`).
+  - **Portal:** `Portal\AboController@retryPayment($id, AboRetryPaymentService)` – Berechtigung über `checkPortalPermission($user_abo)` (customers-Guard + `billing_email`-Match), Redirect auf `portal.my_subscriptions`. Route `POST /portal/my-subscriptions/retry-payment/{id}` (`portal_abos_retry_payment`, `routes/domains/portal.php`).
+  - Beide delegieren an `AboRetryPaymentService::retry()` und nutzen damit denselben `makeShoppingOrder`-Pfad → Einmal-Artikel sind im Retry automatisch enthalten, Purge greift bei Erfolg über `markAboSuccess()`. Der **Admin-Retry** bleibt unverändert bestehen.
+  - **UI:** Gemeinsames Confirm-Modal `resources/views/admin/abo/_retry_payment_modal.blade.php` (Trigger-Button + Bestätigungsdialog, nur bei `status === 3 && active`), eingebunden in `user/abo/detail.blade.php` und `portal/abo/my_abo.blade.php` mit der jeweiligen `retryAction`-Route. Beide Detail-Views zeigen zusätzlich nun auch `alert-success` an.
+- **Tests (4.6):**
+  - `tests/Feature/AboMakeOrderOneTimeTest.php` (6 Tests, vollständiges End-to-End-Fixture mit `me`-Abo, Stammkunde, Referenz-Bestellung, Versandland): `is_abo_addon` korrekt gesetzt; kombinierter Zahlbetrag > reiner `amount`; nur bestätigte Artikel landen in der Bestellung; Purge entfernt **alle** Einmal-Artikel (inkl. soft-deleted); Comp-Reduktion nach Purge; reine Bestellerstellung löscht **keine** Einmal-Artikel (Beleg „behalten bei Fehler").
+  - `tests/Feature/AboUserRetryTest.php` (2 Tests): User-Retry für eigenes Abo ruft den Service auf und leitet zur Detailseite zurück; fremdes Abo → 403 (Service wird nicht aufgerufen).
+- **Pint:** ausgeführt (`--dirty`), pass.
+- **Bekannte, gewollte Abweichung:** Der Test `AboOneTimeWindowTest > isOneTimeFeatureVisible außerhalb des Fensters → false` schlägt aktuell fehl, weil die Fensterprüfung in `AboHelper::isOneTimeFeatureVisible()` (Zeilen 224–226) für die Review-Phase **bewusst auskommentiert** bleibt (siehe Review-Gate). Wird beim Zurücksetzen auf reines `isOneTimeWindowOpen()` automatisch wieder grün.
 
 ---
 
@@ -387,3 +406,6 @@ Der bestehende Retry ist Admin-manuell (`AboRetryPaymentService`). Eine **automa
 | 2026-06-05 | UI/Summen | Abo-Split-Liste zeigt neben der Abo-Zwischensumme auch die Endsumme der nächsten Lieferung; kombinierte Summen-Card optisch hervorgehoben; letzte Prüfung: 8 View-Tests / 28 Assertions grün | ERLEDIGT |
 | 2026-06-08 | Onetime/Verbindlichkeit | **Nur Bestätigtes ist verbindlich:** `AboOrderCart::addOneTimeItemsToYard()` lädt nur noch verbindlich bestätigte Einmal-Artikel (`confirmed_at` gesetzt **und** `confirmed_qty === qty`) → Liefer-/Abbuchungsbetrag, Versand, Gewicht und Comp-Produkte basieren ausschließlich auf bestätigten Artikeln (greift automatisch in Phase 4). Unbestätigte Artikel bleiben als offener Entwurf erhalten (Entscheidung „keep_pending"). Neue Service-Helfer `confirmedItems()`/`pendingItems()`/`pendingGross()`. View `_order_onetime_show` zeigt Status-Badge je Position (Bestätigt/Noch zu bestätigen), getrennte Zwischensummen (bestätigt vs. offen) + Hinweis, dass bereits bestätigte Produkte unabhängig versandt werden. 8 neue/angepasste Tests (51 gesamt grün). **Hinweis:** Die in `isOneTimeFeatureVisible()` zwischenzeitlich auskommentierte Fensterprüfung wurde wiederhergestellt | ERLEDIGT |
 | 2026-06-08 | Review-Gate | **Temporäre Live-Sichtbarkeit für Abstimmung:** Einmalprodukte-Feature über `AboHelper::isOneTimeFeatureVisible()` nur für VIP-User (`isVIP()` = `admin>=1`) im Sales Center sichtbar; Endkunden-Portal (customers-Guard, kein VIP) komplett ausgeblendet. Gates in `User\AboController` (detail/update/oneTime/oneTimeDatatable), `Portal\AboController` (myAbo/update/oneTime/oneTimeDatatable/modalLoad), `ModalController` (abo-add-onetime). Reversibel: Methode später auf reines `isOneTimeWindowOpen()` zurücksetzen + Portal reaktivieren. 4 neue Tests (47 gesamt grün) | ERLEDIGT |
+| 2026-06-08 | 4 (Schritt 1) | **Ausführung – Einmal-Artikel in die Bestellung:** `UserMakeOrder::makeShoppingOrder()` lädt nach `makeOrderYard()` zusätzlich `AboOrderCart::addOneTimeItemsToYard()` (nur verbindlich bestätigte Artikel); `ShoppingOrderItem` erhält `is_abo_addon` aus `options->abo_addon`. Reihenfolge sichert: `user_abos.amount` bleibt der **reine** Abo-Betrag, der Abbuchungsbetrag der Bestellung ist kombiniert (Abo + Einmal). 3 neue Tests (`AboMakeOrderOneTimeTest`) | ERLEDIGT |
+| 2026-06-08 | 4 (Schritt 2) | **Purge & Comp-Reset nur bei Erfolg:** Neue Methode `AboOneTimeService::purgeAfterExecution()` löscht nach erfolgreicher Ausführung **alle** Einmal-Artikel des Abos (bestätigt + offen + soft-deleted, `forceDelete`) und bewertet anschließend die Kompensationsprodukte des reinen Abos neu (Option A: `initYard`+`makeOrderYard`+`checkNumOfCompProducts`). Aufruf im Erfolgszweig von `UserMakeAboOrder::updateAbo()` (Cron) und `AboRetryPaymentService::markAboSuccess()`. Bei Zahlungsfehler bleiben die Einmal-Artikel erhalten. Fehler beim Purge rollen den erfolgreichen Lauf nicht zurück (nur Logging). 3 neue Tests (Purge inkl. soft-deleted, Comp-Reduktion, „behalten bei Fehler") | ERLEDIGT |
+| 2026-06-08 | 4 (Schritt 3) | **User-Retry (Sales Center + Portal):** Neue Methoden `User\AboController::retryPayment($view,$id)` (Permission via `checkPermissions`) und `Portal\AboController::retryPayment($id)` (Permission via `checkPortalPermission`), delegieren an `AboRetryPaymentService::retry()` (nutzt denselben `makeShoppingOrder`-Pfad → Einmal-Artikel automatisch enthalten). Routen `user_abos_retry_payment` (CRM) und `portal_abos_retry_payment` (Portal). Gemeinsames Confirm-Modal `_retry_payment_modal` (nur bei `status===3 && active`) in `user/abo/detail` und `portal/abo/my_abo` inkl. Erfolgsmeldung. 2 neue Tests (Erfolg + 403 bei fremdem Abo). **Hinweis:** Ein bestehender Test (`isOneTimeFeatureVisible außerhalb des Fensters → false`) schlägt erwartungsgemäß fehl, da die Fensterprüfung für die Review-Phase bewusst auskommentiert bleibt | ERLEDIGT |