newsletter: jeden Empfänger genau einmal, atomarer Start, Wiederanlauf (Audit Block 2, Deploy B)

F05: chunkById hinter der created_at-Sortierung der Vorschau las ab der
zweiten Seite Empfänger doppelt und ließ die übrigen aus. Auf der Dev-
Kopie erreichte eine Kampagne an 59.705 Nutzer 500 Adressen, davon 480
doppelt. Die Sortierung wird vor dem ID-Chunking verworfen (E4: die
Versandreihenfolge hat keine fachliche Bedeutung), ein Unique-Index auf
(Kampagne, User) fängt jede weitere Doppelung ab; die Migration räumt
vorhandene Doppelungen vorher weg (auf der Dev-Kopie 470 Zeilen).

F14: Der Start übernimmt den Entwurf per bedingtem UPDATE draft→sending;
nur der Gewinner friert Empfänger ein (insertOrIgnore) und plant Jobs
aus dem Protokoll ein. Abbruch beim Einfrieren gibt den Entwurf frei.

F15: Der Versandjob beansprucht die Zeile pending→sending, schreibt
Empfängerstatus, Zähler und Kampagnenabschluss in einer Transaktion und
gibt den Claim bei Versandfehler zurück. Tries und Backoff am Job.
Zusatzbefund: Adressen auf der Sperrliste galten als „gesendet“, weil der
Rückgabewert von Mail::send nicht ausgewertet wurde — jetzt Status
„suppressed“ ohne Zähler.

Neu: php artisan newsletter:resume {kampagne} [--failed]
[--stuck-minutes=30] plant ausstehende Empfänger einer laufenden
Kampagne neu ein; der Circuit-Breaker-Hinweis nennt ihn statt
queue:retry, das Newsletter-Empfänger nicht nachholt.

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

app/Console/Commands/MailCircuitCommand.php

@@ -18,7 +18,7 @@ class MailCircuitCommand extends Command
     {
         if ($this->option('reset')) {
             $breaker->reset();
-            $this->info('Circuit Breaker zurückgesetzt — der Versand läuft wieder. Liegengebliebene Mails: php artisan queue:retry all');
+            $this->info('Circuit Breaker zurückgesetzt — der Versand läuft wieder. Liegengebliebene Mails: php artisan queue:retry all — laufende Newsletter-Kampagnen: php artisan newsletter:resume {kampagne} --failed');
 
             return self::SUCCESS;
         }

app/Console/Commands/ResumeNewsletterCampaign.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Enums\NewsletterCampaignStatus;
+use App\Enums\NewsletterRecipientStatus;
+use App\Models\NewsletterCampaign;
+use App\Services\Newsletter\CampaignSender;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Wiederanlauf einer laufenden Newsletter-Kampagne (Audit F14/F15): plant
+ * alle ausstehenden Empfänger neu ein — nach abgebrochenem Start, nach
+ * einer Pause des Circuit Breakers oder nach einem Worker-Absturz.
+ *
+ * `--failed` setzt fehlgeschlagene Empfänger zurück (z. B. nach behobener
+ * Relay-Störung). Empfänger, die länger als `--stuck-minutes` in „sending“
+ * hängen, gelten als Absturz-Reste: Ob die Mail dort schon raus war, ist
+ * unklar — der Aufrufer entscheidet mit der Frist, ob er das Risiko eines
+ * Doppelversands eingeht.
+ */
+class ResumeNewsletterCampaign extends Command
+{
+    protected $signature = 'newsletter:resume
+        {campaign : ID der Kampagne im Status „sending“}
+        {--failed : Fehlgeschlagene Empfänger zurücksetzen und erneut einplanen}
+        {--stuck-minutes=30 : Empfänger, die länger als X Minuten in „sending“ hängen, zurücksetzen (0 = keine)}';
+
+    protected $description = 'Plant die ausstehenden Empfänger einer laufenden Newsletter-Kampagne erneut ein.';
+
+    public function handle(): int
+    {
+        $campaign = NewsletterCampaign::query()->find((int) $this->argument('campaign'));
+
+        if ($campaign === null) {
+            $this->error('Kampagne nicht gefunden.');
+
+            return self::FAILURE;
+        }
+
+        if ($campaign->status !== NewsletterCampaignStatus::Sending) {
+            $this->error(sprintf('Kampagne #%d ist „%s“, nicht „%s“ — nichts zu tun.', $campaign->id, $campaign->status->label(), NewsletterCampaignStatus::Sending->label()));
+
+            return self::FAILURE;
+        }
+
+        $stuckMinutes = max(0, (int) $this->option('stuck-minutes'));
+        $stuck = 0;
+
+        if ($stuckMinutes > 0) {
+            $stuck = $campaign->recipients()
+                ->where('status', NewsletterRecipientStatus::Sending->value)
+                ->where('updated_at', '<', now()->subMinutes($stuckMinutes))
+                ->update([
+                    'status' => NewsletterRecipientStatus::Pending->value,
+                    'error' => null,
+                    'updated_at' => now(),
+                ]);
+        }
+
+        $failed = 0;
+
+        if ($this->option('failed')) {
+            $failed = DB::transaction(function () use ($campaign): int {
+                $reset = $campaign->recipients()
+                    ->where('status', NewsletterRecipientStatus::Failed->value)
+                    ->update([
+                        'status' => NewsletterRecipientStatus::Pending->value,
+                        'error' => null,
+                        'updated_at' => now(),
+                    ]);
+
+                if ($reset > 0) {
+                    NewsletterCampaign::query()->whereKey($campaign->id)->decrement('failed_count', $reset);
+                }
+
+                return $reset;
+            });
+        }
+
+        $dispatched = CampaignSender::dispatchPending($campaign);
+
+        $this->info(sprintf(
+            'Kampagne #%d: %d Empfänger neu eingeplant (%d hängende zurückgesetzt, %d fehlgeschlagene zurückgesetzt).',
+            $campaign->id,
+            $dispatched,
+            $stuck,
+            $failed,
+        ));
+
+        return self::SUCCESS;
+    }
+}

app/Enums/NewsletterRecipientStatus.php

@@ -4,23 +4,33 @@ namespace App\Enums;
 
 /**
  * Versandstatus eines einzelnen Newsletter-Empfängers (Protokoll).
+ *
+ * Sending ist der Claim des Workers: Bleibt eine Zeile dauerhaft darin,
+ * ist der Worker zwischen Mailserver-Übergabe und Protokollierung
+ * abgestürzt — die Zustellung ist dann unklar; `newsletter:resume`
+ * setzt solche Zeilen bewusst zurück.
  * SkippedOptOut greift, wenn sich der User zwischen Versandstart und
- * tatsächlichem Versand im Worker abgemeldet hat.
+ * tatsächlichem Versand im Worker abgemeldet hat. Suppressed, wenn das
+ * Versand-Gate die Adresse wegen der Sperrliste gestrichen hat.
  */
 enum NewsletterRecipientStatus: string
 {
     case Pending = 'pending';
+    case Sending = 'sending';
     case Sent = 'sent';
     case Failed = 'failed';
     case SkippedOptOut = 'skipped_opt_out';
+    case Suppressed = 'suppressed';
 
     public function label(): string
     {
         return match ($this) {
             self::Pending => 'Ausstehend',
+            self::Sending => 'Wird versendet',
             self::Sent => 'Versendet',
             self::Failed => 'Fehlgeschlagen',
             self::SkippedOptOut => 'Übersprungen (abgemeldet)',
+            self::Suppressed => 'Gesperrt (Sperrliste)',
         };
     }
 
@@ -31,9 +41,22 @@ enum NewsletterRecipientStatus: string
     {
         return match ($this) {
             self::Pending => 'zinc',
+            self::Sending => 'blue',
             self::Sent => 'green',
             self::Failed => 'red',
             self::SkippedOptOut => 'amber',
+            self::Suppressed => 'orange',
         };
     }
+
+    /**
+     * Status, in denen der Versand noch aussteht oder läuft — solange eine
+     * Kampagne solche Zeilen hat, ist sie nicht abgeschlossen.
+     *
+     * @return list<string>
+     */
+    public static function openValues(): array
+    {
+        return [self::Pending->value, self::Sending->value];
+    }
 }

app/Jobs/SendNewsletterCampaignMail.php

@@ -8,8 +8,10 @@ use App\Enums\NewsletterRecipientStatus;
 use App\Mail\NewsletterCampaignMail;
 use App\Models\NewsletterCampaign;
 use App\Models\NewsletterCampaignRecipient;
+use App\Services\Mail\EmailSuppressionService;
 use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Queue\Queueable;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Mail;
 use Illuminate\Support\Str;
 
@@ -20,20 +22,45 @@ use Illuminate\Support\Str;
  *
  * Der Opt-out wird hier — zum tatsächlichen Versandzeitpunkt — erneut
  * geprüft: Wer sich nach Versandstart abmeldet, wird übersprungen.
+ *
+ * Gegen Doppelversand und schiefe Zähler (Audit F15): Der Job übernimmt
+ * die Zeile per bedingtem UPDATE pending → sending; verliert er den Claim,
+ * ist ein anderer Worker dran. Empfängerstatus, Kampagnenzähler und
+ * Kampagnenabschluss werden in einer Transaktion geschrieben. Schlägt der
+ * Mailversand fehl, geht der Claim an „pending“ zurück und der Retry darf
+ * neu zugreifen. Bleibt eine Zeile in „sending“, ist der Worker nach der
+ * Mailserver-Übergabe abgestürzt: Zustellung unklar, kein automatischer
+ * Neuversand — `newsletter:resume --stuck-minutes` entscheidet das bewusst.
  */
 class SendNewsletterCampaignMail implements ShouldQueue
 {
     use Queueable;
 
+    public int $tries = 3;
+
     public function __construct(public readonly int $recipientId) {}
 
+    /**
+     * Wartezeit in Sekunden vor dem zweiten und dritten Versuch.
+     *
+     * @return list<int>
+     */
+    public function backoff(): array
+    {
+        return [30, 120];
+    }
+
     public function handle(): void
     {
+        if (! $this->claim()) {
+            return;
+        }
+
         $recipient = NewsletterCampaignRecipient::query()
             ->with(['campaign', 'user'])
             ->find($this->recipientId);
 
-        if ($recipient === null || $recipient->status !== NewsletterRecipientStatus::Pending) {
+        if ($recipient === null || $recipient->campaign === null) {
             return;
         }
 
@@ -52,7 +79,22 @@ class SendNewsletterCampaignMail implements ShouldQueue
             return;
         }
 
-        Mail::to($recipient->email)->send(new NewsletterCampaignMail($campaign, $user));
+        try {
+            $sent = Mail::to($recipient->email)->send(new NewsletterCampaignMail($campaign, $user));
+        } catch (\Throwable $exception) {
+            $this->release();
+
+            throw $exception;
+        }
+
+        // Ohne SentMessage hat das Versand-Gate die Mail gestrichen. Die
+        // Sperrliste bestätigt das — der Rückgabewert allein trägt nicht,
+        // die Mail-Attrappe der Tests liefert ebenfalls null.
+        if ($sent === null && app(EmailSuppressionService::class)->isSuppressed($recipient->email)) {
+            $this->conclude($recipient, NewsletterRecipientStatus::Suppressed, null, 'Adresse auf der Sperrliste.');
+
+            return;
+        }
 
         $this->conclude($recipient, NewsletterRecipientStatus::Sent, 'sent_count');
     }
@@ -64,42 +106,91 @@ class SendNewsletterCampaignMail implements ShouldQueue
     {
         $recipient = NewsletterCampaignRecipient::query()->find($this->recipientId);
 
-        if ($recipient === null || $recipient->status !== NewsletterRecipientStatus::Pending) {
+        if ($recipient === null || ! in_array($recipient->status->value, NewsletterRecipientStatus::openValues(), true)) {
             return;
         }
 
-        $this->conclude($recipient, NewsletterRecipientStatus::Failed, 'failed_count', $exception->getMessage());
+        $error = $recipient->status === NewsletterRecipientStatus::Sending
+            ? 'Zustellung unklar (Fehler nach Übergabe an den Mailserver): '.$exception->getMessage()
+            : $exception->getMessage();
+
+        $this->conclude($recipient, NewsletterRecipientStatus::Failed, 'failed_count', $error);
     }
 
+    /**
+     * Bedingter Claim pending → sending. Genau ein Worker gewinnt.
+     */
+    private function claim(): bool
+    {
+        return NewsletterCampaignRecipient::query()
+            ->whereKey($this->recipientId)
+            ->where('status', NewsletterRecipientStatus::Pending->value)
+            ->update([
+                'status' => NewsletterRecipientStatus::Sending->value,
+                'updated_at' => now(),
+            ]) === 1;
+    }
+
+    /**
+     * Claim zurückgeben, wenn der Versand nicht stattgefunden hat.
+     */
+    private function release(): void
+    {
+        NewsletterCampaignRecipient::query()
+            ->whereKey($this->recipientId)
+            ->where('status', NewsletterRecipientStatus::Sending->value)
+            ->update([
+                'status' => NewsletterRecipientStatus::Pending->value,
+                'updated_at' => now(),
+            ]);
+    }
+
+    /**
+     * Abschluss in einer Transaktion: Empfängerstatus, Kampagnenzähler und
+     * — wenn keine offene Zeile mehr da ist — Kampagnenabschluss. Die
+     * Kampagnenzeile wird zuerst gesperrt, damit zwei gleichzeitig
+     * endende Jobs den Abschluss nicht gegenseitig übersehen.
+     */
     private function conclude(
         NewsletterCampaignRecipient $recipient,
         NewsletterRecipientStatus $status,
-        string $campaignCounter,
+        ?string $campaignCounter,
         ?string $error = null,
     ): void {
-        $recipient->update([
-            'status' => $status->value,
-            'error' => $error !== null ? Str::limit($error, 480) : null,
-            'sent_at' => $status === NewsletterRecipientStatus::Sent ? now() : null,
-        ]);
+        DB::transaction(function () use ($recipient, $status, $campaignCounter, $error): void {
+            $campaign = NewsletterCampaign::query()
+                ->whereKey($recipient->newsletter_campaign_id)
+                ->lockForUpdate()
+                ->first();
 
-        $campaign = NewsletterCampaign::query()->find($recipient->newsletter_campaign_id);
-
-        if ($campaign === null) {
-            return;
-        }
-
-        $campaign->increment($campaignCounter);
-
-        $hasPending = $campaign->recipients()
-            ->where('status', NewsletterRecipientStatus::Pending->value)
-            ->exists();
-
-        if (! $hasPending && $campaign->status === NewsletterCampaignStatus::Sending) {
-            $campaign->update([
-                'status' => NewsletterCampaignStatus::Sent->value,
-                'sent_at' => now(),
+            $recipient->update([
+                'status' => $status->value,
+                'error' => $error !== null ? Str::limit($error, 480) : null,
+                'sent_at' => $status === NewsletterRecipientStatus::Sent ? now() : null,
             ]);
-        }
+
+            if ($campaign === null) {
+                return;
+            }
+
+            if ($campaignCounter !== null) {
+                NewsletterCampaign::query()->whereKey($campaign->id)->increment($campaignCounter);
+            }
+
+            $hasOpen = $campaign->recipients()
+                ->whereIn('status', NewsletterRecipientStatus::openValues())
+                ->exists();
+
+            if (! $hasOpen) {
+                NewsletterCampaign::query()
+                    ->whereKey($campaign->id)
+                    ->where('status', NewsletterCampaignStatus::Sending->value)
+                    ->update([
+                        'status' => NewsletterCampaignStatus::Sent->value,
+                        'sent_at' => now(),
+                        'updated_at' => now(),
+                    ]);
+            }
+        });
     }
 }

app/Services/Mail/MailCircuitBreaker.php

@@ -14,7 +14,8 @@ use Illuminate\Support\Facades\Cache;
  * Empfängerproblem, sondern ein Absenderproblem — und jede weitere Mail in
  * dem Zustand macht es schlimmer. Ab `threshold` Ablehnungen in
  * `window_minutes` ist der Kreis für `pause_minutes` offen: Queue-Mails
- * schlagen fehl (und lassen sich danach mit `queue:retry` nachholen),
+ * schlagen fehl (und lassen sich danach mit `queue:retry` bzw. für
+ * Newsletter mit `newsletter:resume --failed` nachholen),
  * synchrone Mails werden still verworfen, der Admin bekommt genau eine Mail.
  *
  * Betriebs-Alerts gehen immer durch — sonst erführe niemand vom Stopp.
@@ -47,7 +48,7 @@ class MailCircuitBreaker
             sprintf('Mailversand angehalten bis %s: %d Relay-Ablehnungen in %d Minuten', $until->format('H:i'), $count, $windowMinutes),
             [
                 'last_rejection' => $detail,
-                'hint' => 'Absenderruf/Relay prüfen. Fehlgeschlagene Queue-Mails danach mit `php artisan queue:retry all` nachholen; `php artisan mail:circuit --reset` hebt die Pause vorzeitig auf.',
+                'hint' => 'Absenderruf/Relay prüfen. Fehlgeschlagene Queue-Mails danach mit `php artisan queue:retry all` nachholen, laufende Newsletter-Kampagnen mit `php artisan newsletter:resume {kampagne} --failed`; `php artisan mail:circuit --reset` hebt die Pause vorzeitig auf.',
             ],
         );
     }

app/Services/Newsletter/CampaignSender.php

@@ -15,6 +15,13 @@ use App\Models\User;
  * dort wird der Opt-out-Stand erneut geprüft, damit eine Abmeldung zwischen
  * Versandstart und Versand sofort greift.
  *
+ * Der Start ist atomar (Audit F14): Nur der Aufruf, der den Entwurf per
+ * bedingtem UPDATE auf „sending“ stellt, legt Empfänger an und plant Jobs
+ * ein. Empfänger werden mit insertOrIgnore gegen den Unique-Index
+ * (Kampagne, User) geschrieben, die Jobs anschließend aus dem Protokoll
+ * heraus eingeplant — ein Wiederanlauf nach Abbruch (`newsletter:resume`)
+ * arbeitet auf demselben Stand.
+ *
  * 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.
@@ -28,15 +35,108 @@ class CampaignSender
      */
     public function start(NewsletterCampaign $campaign): int
     {
-        if (! $campaign->isDraft()) {
+        if (! $this->claimDraft($campaign)) {
             return 0;
         }
 
-        $total = 0;
+        try {
+            $this->freezeRecipients($campaign);
+        } catch (\Throwable $exception) {
+            // Abbruch beim Einfrieren: Entwurf bleibt startbar, bereits
+            // angelegte Zeilen werden beim nächsten Start übersprungen.
+            $this->releaseDraft($campaign);
 
+            throw $exception;
+        }
+
+        $total = $campaign->recipients()->count();
+
+        if ($total === 0) {
+            $this->releaseDraft($campaign);
+
+            return 0;
+        }
+
+        $campaign->forceFill(['recipients_total' => $total])->save();
+
+        self::dispatchPending($campaign);
+
+        return $total;
+    }
+
+    /**
+     * Plant für jeden ausstehenden Empfänger einen Versand-Job ein, mit
+     * Drossel-Delay in Wellen. Liest aus dem Protokoll, nicht aus dem
+     * Speicher — so nutzt der Wiederanlauf denselben Weg.
+     *
+     * @return int Anzahl der eingeplanten Jobs.
+     */
+    public static function dispatchPending(NewsletterCampaign $campaign): int
+    {
+        $batchSize = max(1, (int) config('newsletter.campaign.batch_size'));
+        $intervalSeconds = max(1, (int) config('newsletter.campaign.batch_interval_minutes')) * 60;
+        $position = 0;
+
+        $campaign->recipients()
+            ->toBase()
+            ->select('id')
+            ->where('status', NewsletterRecipientStatus::Pending->value)
+            ->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 $position;
+    }
+
+    /**
+     * Bedingtes UPDATE draft → sending: Genau ein Aufrufer gewinnt, auch bei
+     * zwei parallel geladenen Model-Instanzen desselben Entwurfs.
+     */
+    private function claimDraft(NewsletterCampaign $campaign): bool
+    {
+        $claimed = NewsletterCampaign::query()
+            ->whereKey($campaign->id)
+            ->where('status', NewsletterCampaignStatus::Draft->value)
+            ->update([
+                'status' => NewsletterCampaignStatus::Sending->value,
+                'updated_at' => now(),
+            ]);
+
+        if ($claimed !== 1) {
+            return false;
+        }
+
+        $campaign->forceFill(['status' => NewsletterCampaignStatus::Sending->value])->syncOriginal();
+
+        return true;
+    }
+
+    private function releaseDraft(NewsletterCampaign $campaign): void
+    {
+        NewsletterCampaign::query()
+            ->whereKey($campaign->id)
+            ->where('status', NewsletterCampaignStatus::Sending->value)
+            ->update(['status' => NewsletterCampaignStatus::Draft->value]);
+
+        $campaign->forceFill(['status' => NewsletterCampaignStatus::Draft->value])->syncOriginal();
+    }
+
+    /**
+     * Schreibt die Empfängerliste laut Filter ins Protokoll. Die Filter-
+     * Sortierung ist eine UI-Sortierung der Vorschau (E4) — vor dem
+     * ID-Chunking wird sie verworfen, sonst liest chunkById ab der zweiten
+     * Seite Empfänger doppelt und lässt andere aus (Audit F05).
+     */
+    private function freezeRecipients(NewsletterCampaign $campaign): void
+    {
         $this->recipients->query($campaign->filters ?? [])
             ->select(['id', 'email'])
-            ->chunkById(500, function ($users) use ($campaign, &$total): void {
+            ->reorder('id')
+            ->chunkById(500, function ($users) use ($campaign): void {
                 $rows = $users->map(fn (User $user): array => [
                     'newsletter_campaign_id' => $campaign->id,
                     'user_id' => $user->id,
@@ -46,35 +146,8 @@ class CampaignSender
                     'updated_at' => now(),
                 ])->all();
 
-                $campaign->recipients()->insert($rows);
-                $total += count($rows);
+                $campaign->recipients()->insertOrIgnore($rows);
             });
-
-        if ($total === 0) {
-            return 0;
-        }
-
-        $campaign->update([
-            'status' => NewsletterCampaignStatus::Sending->value,
-            '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()
-            ->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;
     }
 
     /**