admin: Newsletter mit Abmelde-Liste, Follow-up-Filtern und gedrosseltem Versand

- Unterseite /admin/newsletter/abmeldungen listet Newsletter-Opt-outs mit
  Zeitpunkt, Suche und Link zur User-Detailseite
- Kampagnen-Filter: Empfänger einer früheren Kampagne ausschließen
  (Abgleich per User-ID und E-Mail-Snapshot) für Follow-up-Mailings
- Login-Filter kann Monats-Scheiben (von–bis) abgrenzen, um große
  Listen Monat für Monat abzuarbeiten
- Versand läuft in Wellen (Standard 50 Mails / 15 Min, per .env
  justierbar) gegen SMTP-Limits und Blocklisten; Hinweis im Senden-Modal
- web: Firmen-Website im Newsroom & Co. als absolute URL verlinkt
  (Company::websiteUrl), statt relativ auf /newsroom/www.example.de
- kunde: API-Doku-Button öffnet die /de/api-Seite; OpenAPI-Spezifikation
  als eigener, benannter Download (pressekonto-api-v1.yml)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app/Services/Newsletter/CampaignRecipients.php

@@ -4,17 +4,21 @@ namespace App\Services\Newsletter;
 
 use App\Enums\EmailNotificationType;
 use App\Enums\UserPaymentOptionStatus;
+use App\Models\NewsletterCampaign;
 use App\Models\User;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Query\Builder as QueryBuilder;
 
 /**
  * Empfänger-Auswahl für interne Newsletter-Kampagnen (Admin ▸ Newsletter).
  *
  * Grundmenge sind alle aktiven User mit E-Mail-Adresse, die den Newsletter
  * nicht abbestellt haben. Darauf setzen die Kampagnen-Filter auf:
- * Portal, Legacy-Vertrag (Bestandsschutz-Zahlungsoption) und der
+ * Portal, Legacy-Vertrag (Bestandsschutz-Zahlungsoption), der
  * Login-Zeitraum (eingeloggt innerhalb X Monaten bzw. dessen Komplement:
- * länger nicht oder noch nie eingeloggt).
+ * länger nicht oder noch nie eingeloggt) und optional der Ausschluss aller
+ * Empfänger einer früheren Kampagne (Follow-up an die noch nicht
+ * Angeschriebenen).
  */
 class CampaignRecipients
 {
@@ -24,12 +28,14 @@ class CampaignRecipients
 
     public const LOGIN_NOT_WITHIN = 'not_within';
 
+    public const LOGIN_BETWEEN = 'between';
+
     public const SORT_FIELDS = ['created_at', 'last_login_at'];
 
     /**
      * Filter-Defaults; unbekannte Werte fallen auf diese zurück.
      *
-     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, sort: string, direction: string}
+     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, login_months_from: int, exclude_campaign_id: int, sort: string, direction: string}
      */
     public static function defaultFilters(): array
     {
@@ -38,6 +44,8 @@ class CampaignRecipients
             'legacy_contract' => false,
             'login' => self::LOGIN_ANY,
             'login_months' => 6,
+            'login_months_from' => 0,
+            'exclude_campaign_id' => 0,
             'sort' => 'created_at',
             'direction' => 'desc',
         ];
@@ -48,7 +56,7 @@ class CampaignRecipients
      * Filter-Satz in eine validierte, vollständige Form.
      *
      * @param  array<string, mixed>  $filters
-     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, sort: string, direction: string}
+     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, login_months_from: int, exclude_campaign_id: int, sort: string, direction: string}
      */
     public function normalize(array $filters): array
     {
@@ -56,15 +64,19 @@ class CampaignRecipients
 
         $portal = (string) ($filters['portal'] ?? '');
         $login = (string) ($filters['login'] ?? $defaults['login']);
-        $months = (int) ($filters['login_months'] ?? $defaults['login_months']);
+        $months = max(1, min(120, (int) ($filters['login_months'] ?? $defaults['login_months'])));
+        $monthsFrom = max(0, (int) ($filters['login_months_from'] ?? $defaults['login_months_from']));
         $sort = (string) ($filters['sort'] ?? $defaults['sort']);
         $direction = (string) ($filters['direction'] ?? $defaults['direction']);
 
         return [
             'portal' => in_array($portal, ['presseecho', 'businessportal24', 'both'], true) ? $portal : '',
             'legacy_contract' => (bool) ($filters['legacy_contract'] ?? false),
-            'login' => in_array($login, [self::LOGIN_ANY, self::LOGIN_WITHIN, self::LOGIN_NOT_WITHIN], true) ? $login : self::LOGIN_ANY,
-            'login_months' => max(1, min(120, $months)),
+            'login' => in_array($login, [self::LOGIN_ANY, self::LOGIN_WITHIN, self::LOGIN_NOT_WITHIN, self::LOGIN_BETWEEN], true) ? $login : self::LOGIN_ANY,
+            'login_months' => $months,
+            // Untergrenze der Monats-Scheibe; liegt immer unter der Obergrenze.
+            'login_months_from' => min($monthsFrom, $months - 1),
+            'exclude_campaign_id' => max(0, (int) ($filters['exclude_campaign_id'] ?? 0)),
             'sort' => in_array($sort, self::SORT_FIELDS, true) ? $sort : $defaults['sort'],
             'direction' => $direction === 'asc' ? 'asc' : 'desc',
         ];
@@ -94,6 +106,18 @@ class CampaignRecipients
             $parts[] = sprintf('In den letzten %d Monaten eingeloggt', $filters['login_months']);
         } elseif ($filters['login'] === self::LOGIN_NOT_WITHIN) {
             $parts[] = sprintf('Seit %d Monaten nicht eingeloggt (oder noch nie)', $filters['login_months']);
+        } elseif ($filters['login'] === self::LOGIN_BETWEEN) {
+            $parts[] = $filters['login_months_from'] > 0
+                ? sprintf('Letzter Login vor %d bis %d Monaten', $filters['login_months_from'], $filters['login_months'])
+                : sprintf('In den letzten %d Monaten eingeloggt', $filters['login_months']);
+        }
+
+        if ($filters['exclude_campaign_id'] > 0) {
+            $excluded = NewsletterCampaign::query()->find($filters['exclude_campaign_id'], ['id', 'subject']);
+            $parts[] = sprintf(
+                'Ohne Empfänger der Kampagne „%s“',
+                $excluded->subject ?? sprintf('#%d (gelöscht)', $filters['exclude_campaign_id']),
+            );
         }
 
         $parts[] = sprintf(
@@ -133,6 +157,21 @@ class CampaignRecipients
                 ->where(fn (Builder $inner) => $inner
                     ->whereNull('last_login_at')
                     ->orWhere('last_login_at', '<', $loginCutoff)))
+            // Monats-Scheibe [vor Y Monaten, vor X Monaten): Untergrenze
+            // inklusiv, Obergrenze exklusiv — benachbarte Scheiben (z. B.
+            // 0–1 und 1–2) überschneiden sich damit nicht.
+            ->when($filters['login'] === self::LOGIN_BETWEEN, fn (Builder $query) => $query
+                ->where('last_login_at', '>=', $loginCutoff)
+                ->where('last_login_at', '<', now()->subMonths($filters['login_months_from'])))
+            // Follow-up-Ausschluss: wer im Protokoll der gewählten Kampagne
+            // steht (per User-ID oder E-Mail-Snapshot), fällt raus.
+            ->when($filters['exclude_campaign_id'] > 0, fn (Builder $query) => $query
+                ->whereNotExists(fn (QueryBuilder $sub) => $sub
+                    ->from('newsletter_campaign_recipients', 'excluded')
+                    ->where('excluded.newsletter_campaign_id', $filters['exclude_campaign_id'])
+                    ->where(fn (QueryBuilder $match) => $match
+                        ->whereColumn('excluded.user_id', 'users.id')
+                        ->orWhereColumn('excluded.email', 'users.email'))))
             ->orderBy($filters['sort'], $filters['direction'])
             ->orderBy('id');
     }

app/Services/Newsletter/CampaignSender.php

@@ -14,6 +14,10 @@ use App\Models\User;
  * Empfänger einen Queue-Job ein. Der tatsächliche Versand läuft im Worker;
  * dort wird der Opt-out-Stand erneut geprüft, damit eine Abmeldung zwischen
  * Versandstart und Versand sofort greift.
+ *
+ * Große Listen werden gedrosselt: Die Jobs erhalten gestaffelte Delays in
+ * Wellen laut config('newsletter.campaign'), damit das SMTP-Limit des
+ * Providers nicht reißt und die Domain nicht auf Blocklisten landet.
  */
 class CampaignSender
 {
@@ -55,14 +59,43 @@ class CampaignSender
             'recipients_total' => $total,
         ]);
 
+        $batchSize = max(1, (int) config('newsletter.campaign.batch_size'));
+        $intervalSeconds = max(1, (int) config('newsletter.campaign.batch_interval_minutes')) * 60;
+        $position = 0;
+
         $campaign->recipients()
-            ->select(['id'])
-            ->chunkById(500, function ($recipients): void {
-                foreach ($recipients as $recipient) {
-                    SendNewsletterCampaignMail::dispatch($recipient->id);
+            ->toBase()
+            ->select('id')
+            ->chunkById(500, function ($rows) use ($batchSize, $intervalSeconds, &$position): void {
+                foreach ($rows as $row) {
+                    SendNewsletterCampaignMail::dispatch((int) $row->id)
+                        ->delay(intdiv($position, $batchSize) * $intervalSeconds);
+                    $position++;
                 }
             });
 
         return $total;
     }
+
+    /**
+     * Drossel-Hinweis für die Admin-UI, z. B. „max. 50 Mails alle 15 Minuten —
+     * Gesamtdauer ca. 3,5 Stunden“. Null, wenn alles in die erste Welle passt.
+     */
+    public static function throttleSummary(int $total): ?string
+    {
+        $batchSize = max(1, (int) config('newsletter.campaign.batch_size'));
+        $intervalMinutes = max(1, (int) config('newsletter.campaign.batch_interval_minutes'));
+
+        if ($total <= $batchSize) {
+            return null;
+        }
+
+        $durationMinutes = ((int) ceil($total / $batchSize) - 1) * $intervalMinutes;
+
+        $duration = $durationMinutes < 60
+            ? sprintf('%d Minuten', $durationMinutes)
+            : sprintf('%s Stunden', number_format($durationMinutes / 60, 1, ',', '.'));
+
+        return sprintf('max. %d Mails alle %d Minuten — Gesamtdauer ca. %s', $batchSize, $intervalMinutes, $duration);
+    }
 }