presseportale/app/Services/Newsletter/CampaignSender.php

<?php

namespace App\Services\Newsletter;

use App\Enums\NewsletterCampaignStatus;
use App\Enums\NewsletterRecipientStatus;
use App\Jobs\SendNewsletterCampaignMail;
use App\Models\NewsletterCampaign;
use App\Models\User;

/**
 * Startet den Versand einer Newsletter-Kampagne: friert die Empfängerliste
 * laut Filter als Protokoll-Zeilen ein (Status pending) und stellt pro
 * 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.
 *
 * 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.
 */
class CampaignSender
{
    public function __construct(private readonly CampaignRecipients $recipients) {}

    /**
     * Versand per Konfiguration freigegeben (E9-Schalter).
     */
    public static function sendingEnabled(): bool
    {
        return (bool) config('newsletter.sending_enabled', false);
    }

    /**
     * @return int Anzahl der eingeplanten Empfänger.
     *
     * @throws NewsletterSendingDisabledException Versand gesperrt; der Entwurf
     *                                            bleibt unverändert.
     */
    public function start(NewsletterCampaign $campaign): int
    {
        if (! self::sendingEnabled()) {
            throw new NewsletterSendingDisabledException;
        }

        if (! $this->claimDraft($campaign)) {
            return 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'])
            ->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,
                    'email' => $user->email,
                    'status' => NewsletterRecipientStatus::Pending->value,
                    'created_at' => now(),
                    'updated_at' => now(),
                ])->all();

                $campaign->recipients()->insertOrIgnore($rows);
            });
    }

    /**
     * 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);
    }
}