Phase 9D: Tarif-Datenmodell, Cashier und hybride Rechnungskreise STR-/MAN-

Tarif-Datenmodell (Decision-Update):
- plans: Starter/Business/Pro/Agency mit Monats-/Jahrespreis (Jahres =
  10 x Monat), PM-Kontingent, Tageslimit, Stripe-IDs; idempotenter Seeder
- single_purchases: Einzel-PM, Extra-PM, Boost, PDF-Nachweis mit
  Status-Lifecycle und Stripe-Checkout-Referenzen
- laravel/cashier ^16.5 installiert (freigegeben); User ist Billable,
  Cashier-Migrationen published + ausgefuehrt; lokale invoices()-Relation
  ueberschreibt bewusst die Cashier-Methode

Hybride Rechnungskreise (Entscheidung 12.06.2026):
- invoice_number_sequences + InvoiceNumberGenerator: atomare fortlaufende
  Nummern pro Kreis (STR- fuer den neuen Stripe-Shop, MAN- fuer den
  manuellen Legacy-Kreis); Alt-Archiv legacy_invoices bleibt unveraendert
- ManualInvoiceService + billing:generate-manual-invoices (Scheduler
  taeglich 04:30): prueft aktive/grandfathered user_payment_options ohne
  Stripe-Subscription auf erreichtes Periodenende, friert die
  Rechnungsadresse als Snapshot ein, stellt die MAN-Rechnung aus
  (Zahlungsziel billing.manual_due_days) und schaltet die Periode weiter;
  Konditions-Overrides via legacy_conditions, sonst Netto-Preis +
  billing.vat_rate; nicht abrechenbare Faelle werden geloggt und
  beim naechsten Lauf erneut geprueft

Submit-Gate:
- User::hasActiveBooking() prueft jetzt echt (hinter
  billing.enforce_booking): Cashier-Abo, bezahlter Einzel-/Extra-PM-Kauf
  oder laufende Legacy-Vereinbarung (MAN-Kreis)

Suite: 468 passed, 4 skipped (17 neue Billing-Tests). Pint clean.
Offen fuer 9E: Stripe-Checkout/Webhooks, STR-Spiegelung, Slot-Logik auf
Plan-Kontingent, Migration der aktiven Legacy-Zahlungen in
user_payment_options.

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

app/Console/Commands/GenerateManualInvoices.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Services\Billing\ManualInvoiceService;
+use Illuminate\Console\Command;
+
+/**
+ * Fälligkeitsprüfung des manuellen Rechnungskreises (MAN-).
+ *
+ * Läuft täglich über den Scheduler und stellt für aktive Legacy-
+ * Zahlungsvereinbarungen (ohne Stripe-Subscription) die fälligen
+ * Rechnungen aus — wie im Legacy-System. Nicht abrechenbare
+ * Vereinbarungen (fehlende Rechnungsadresse o. ä.) werden geloggt und
+ * beim nächsten Lauf erneut geprüft.
+ */
+class GenerateManualInvoices extends Command
+{
+    protected $signature = 'billing:generate-manual-invoices
+                            {--dry-run : Nur anzeigen, was fällig ist}
+                            {--limit=50 : Maximale Anzahl Vereinbarungen pro Lauf}';
+
+    protected $description = 'Stellt fällige Rechnungen des manuellen Legacy-Rechnungskreises (MAN-) aus';
+
+    public function handle(ManualInvoiceService $service): int
+    {
+        $dryRun = (bool) $this->option('dry-run');
+        $limit = max(1, (int) $this->option('limit'));
+
+        $due = $service->duePaymentOptions(limit: $limit);
+
+        if ($due->isEmpty()) {
+            $this->info('Keine fälligen Zahlungsvereinbarungen gefunden.');
+
+            return self::SUCCESS;
+        }
+
+        $created = 0;
+        $skipped = 0;
+
+        foreach ($due as $option) {
+            if ($dryRun) {
+                $this->line(sprintf(
+                    '[dry-run] Fällig: Vereinbarung #%d (User #%s, Periode bis %s)',
+                    $option->id,
+                    $option->user_id,
+                    $option->current_period_end->toDateString(),
+                ));
+
+                continue;
+            }
+
+            $invoice = $service->invoiceFor($option);
+
+            if ($invoice) {
+                $created++;
+                $this->line(sprintf('Rechnung %s für Vereinbarung #%d erstellt.', $invoice->number, $option->id));
+            } else {
+                $skipped++;
+                $this->warn(sprintf('Vereinbarung #%d übersprungen (siehe Log).', $option->id));
+            }
+        }
+
+        if (! $dryRun) {
+            $this->info(sprintf('%d Rechnung(en) erstellt, %d übersprungen.', $created, $skipped));
+        }
+
+        return self::SUCCESS;
+    }
+}

app/Enums/SinglePurchaseStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Enums;
+
+enum SinglePurchaseStatus: string
+{
+    case Pending = 'pending';
+    case Paid = 'paid';
+    case Consumed = 'consumed';
+    case Refunded = 'refunded';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Pending => 'Ausstehend',
+            self::Paid => 'Bezahlt',
+            self::Consumed => 'Eingelöst',
+            self::Refunded => 'Erstattet',
+        };
+    }
+}

app/Enums/SinglePurchaseType.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Enums;
+
+enum SinglePurchaseType: string
+{
+    case SinglePm = 'single_pm';
+    case ExtraPm = 'extra_pm';
+    case Boost = 'boost';
+    case ProofPdf = 'proof_pdf';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::SinglePm => 'Einzel-Pressemitteilung',
+            self::ExtraPm => 'Extra-PM',
+            self::Boost => 'Boost / Platzierung',
+            self::ProofPdf => 'Veröffentlichungsnachweis (PDF)',
+        };
+    }
+
+    /**
+     * Käufe, die zum Einreichen/Veröffentlichen einer PM berechtigen
+     * (relevant für das Submit-Gate und den Slot-Verbrauch).
+     */
+    public function grantsSubmission(): bool
+    {
+        return in_array($this, [self::SinglePm, self::ExtraPm], true);
+    }
+}

app/Models/Plan.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+/**
+ * Tarif-Katalog laut Decision-Update (Starter/Business/Pro/Agency).
+ *
+ * Der Jahrespreis entspricht 10 Monatsbeiträgen und wird als
+ * „2 Monate gratis" kommuniziert. `press_release_quota` ist das
+ * monatliche PM-Kontingent, `daily_limit` der Flut-Schutz (null = ohne).
+ */
+class Plan extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'slug',
+        'name',
+        'monthly_price_cents',
+        'yearly_price_cents',
+        'currency',
+        'press_release_quota',
+        'daily_limit',
+        'stripe_product_id',
+        'stripe_price_id_monthly',
+        'stripe_price_id_yearly',
+        'is_active',
+        'sort_order',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'monthly_price_cents' => 'integer',
+            'yearly_price_cents' => 'integer',
+            'press_release_quota' => 'integer',
+            'daily_limit' => 'integer',
+            'is_active' => 'boolean',
+            'sort_order' => 'integer',
+        ];
+    }
+
+    public function scopeActive(Builder $query): Builder
+    {
+        return $query->where('is_active', true)->orderBy('sort_order');
+    }
+}

app/Models/SinglePurchase.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\SinglePurchaseStatus;
+use App\Enums\SinglePurchaseType;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Einmalkauf laut Decision-Update: Einzel-PM sowie die Launch-Credit-Posten
+ * Extra-PM, Boost und Veröffentlichungsnachweis-PDF. Ein bezahlter, noch
+ * nicht eingelöster Kauf mit `grantsSubmission()`-Typ erfüllt das
+ * Submit-Gate (`User::hasActiveBooking()`).
+ */
+class SinglePurchase extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'user_id',
+        'type',
+        'status',
+        'price_cents',
+        'currency',
+        'press_release_id',
+        'stripe_checkout_session_id',
+        'stripe_payment_intent_id',
+        'paid_at',
+        'consumed_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'type' => SinglePurchaseType::class,
+            'status' => SinglePurchaseStatus::class,
+            'price_cents' => 'integer',
+            'paid_at' => 'datetime',
+            'consumed_at' => 'datetime',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function pressRelease(): BelongsTo
+    {
+        return $this->belongsTo(PressRelease::class);
+    }
+
+    /**
+     * Bezahlte, noch nicht eingelöste Käufe, die zum Einreichen berechtigen.
+     */
+    public function scopeGrantingSubmission(Builder $query): Builder
+    {
+        return $query
+            ->where('status', SinglePurchaseStatus::Paid->value)
+            ->whereIn('type', [
+                SinglePurchaseType::SinglePm->value,
+                SinglePurchaseType::ExtraPm->value,
+            ]);
+    }
+}

app/Models/User.php

@@ -5,6 +5,7 @@ namespace App\Models;
 // use Illuminate\Contracts\Auth\MustVerifyEmail;
 use App\Enums\Portal;
 use App\Enums\RegistrationType;
+use App\Enums\UserPaymentOptionStatus;
 use Database\Factories\UserFactory;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
@@ -14,6 +15,7 @@ use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Illuminate\Support\Str;
+use Laravel\Cashier\Billable;
 use Laravel\Fortify\TwoFactorAuthenticatable;
 use Laravel\Sanctum\HasApiTokens;
 use Spatie\Permission\Traits\HasRoles;
@@ -21,7 +23,7 @@ use Spatie\Permission\Traits\HasRoles;
 class User extends Authenticatable
 {
     /** @use HasFactory<UserFactory> */
-    use HasApiTokens, HasFactory, HasRoles, Notifiable, SoftDeletes, TwoFactorAuthenticatable;
+    use Billable, HasApiTokens, HasFactory, HasRoles, Notifiable, SoftDeletes, TwoFactorAuthenticatable;
 
     /**
      * The attributes that are mass assignable.
@@ -96,10 +98,11 @@ class User extends Authenticatable
      * Submit-Gate aus dem Decision-Update §5.1: Einreichen zur Prüfung
      * erfordert eine aktive Buchung.
      *
-     * Stub bis zum Tarif-Modul (Phase 9D/9E): solange
-     * `billing.enforce_booking` deaktiviert ist (Default), gilt jede:r als
-     * gebucht. Das Tarif-Modul ersetzt den Rumpf durch die echte
-     * Subscription-/Einzelkauf-Prüfung — die Schnittstelle bleibt stabil.
+     * Hybrides Modell: Eine Buchung ist entweder ein aktives Stripe-Abo
+     * (Cashier, STR-Kreis), ein bezahlter Einmalkauf (Einzel-PM/Extra-PM)
+     * oder eine laufende Legacy-Zahlungsvereinbarung (manueller MAN-Kreis).
+     * Solange `billing.enforce_booking` deaktiviert ist, bleibt das Gate
+     * offen (Launch-Schalter).
      */
     public function hasActiveBooking(): bool
     {
@@ -107,7 +110,20 @@ class User extends Authenticatable
             return true;
         }
 
-        return false;
+        if ($this->subscribed()) {
+            return true;
+        }
+
+        if ($this->singlePurchases()->grantingSubmission()->exists()) {
+            return true;
+        }
+
+        return $this->userPaymentOptions()
+            ->whereIn('status', [
+                UserPaymentOptionStatus::Active->value,
+                UserPaymentOptionStatus::Grandfathered->value,
+            ])
+            ->exists();
     }
 
     /**
@@ -169,6 +185,16 @@ class User extends Authenticatable
         return $this->hasMany(UserPaymentOption::class);
     }
 
+    public function singlePurchases(): HasMany
+    {
+        return $this->hasMany(SinglePurchase::class);
+    }
+
+    /**
+     * Lokale Rechnungen (STR- und MAN-Kreis). Überschreibt bewusst die
+     * gleichnamige Cashier-Methode — Stripe-Rechnungen werden beim
+     * Webhook-Sync (9E) in diese Tabelle gespiegelt.
+     */
     public function invoices(): HasMany
     {
         return $this->hasMany(Invoice::class);

app/Services/Billing/InvoiceNumberGenerator.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Services\Billing;
+
+use Illuminate\Support\Facades\DB;
+use InvalidArgumentException;
+
+/**
+ * Vergibt fortlaufende Rechnungsnummern pro Rechnungskreis (hybrides Modell):
+ *
+ * - `STR` — neuer Stripe-Shop-Kreislauf (alle neuen Abschlüsse/Zahlungen)
+ * - `MAN` — manueller Legacy-Kreis ab Relaunch (laufende Alt-Zahlungen
+ *   werden weiter per Rechnung abgerechnet)
+ *
+ * Die Vergabe läuft atomar über einen Row-Lock auf der Sequenz-Tabelle,
+ * damit Nummern auch bei parallelen Prozessen (Webhook + Scheduler)
+ * lückenlos und eindeutig bleiben.
+ */
+class InvoiceNumberGenerator
+{
+    public const CIRCLE_STRIPE = 'STR';
+
+    public const CIRCLE_MANUAL = 'MAN';
+
+    public function nextStripeNumber(): string
+    {
+        return $this->next(self::CIRCLE_STRIPE);
+    }
+
+    public function nextManualNumber(): string
+    {
+        return $this->next(self::CIRCLE_MANUAL);
+    }
+
+    public function next(string $circle): string
+    {
+        if (! in_array($circle, [self::CIRCLE_STRIPE, self::CIRCLE_MANUAL], true)) {
+            throw new InvalidArgumentException("Unbekannter Rechnungskreis: {$circle}");
+        }
+
+        $number = DB::transaction(function () use ($circle): int {
+            $sequence = DB::table('invoice_number_sequences')
+                ->where('circle', $circle)
+                ->lockForUpdate()
+                ->first();
+
+            if (! $sequence) {
+                DB::table('invoice_number_sequences')->insert([
+                    'circle' => $circle,
+                    'next_number' => 2,
+                    'created_at' => now(),
+                    'updated_at' => now(),
+                ]);
+
+                return 1;
+            }
+
+            DB::table('invoice_number_sequences')
+                ->where('id', $sequence->id)
+                ->update(['next_number' => $sequence->next_number + 1, 'updated_at' => now()]);
+
+            return (int) $sequence->next_number;
+        });
+
+        $padding = (int) config('billing.invoice_number_padding', 5);
+
+        return sprintf('%s-%s', $circle, str_pad((string) $number, $padding, '0', STR_PAD_LEFT));
+    }
+}

app/Services/Billing/ManualInvoiceService.php

@@ -0,0 +1,156 @@
+<?php
+
+namespace App\Services\Billing;
+
+use App\Enums\InvoiceStatus;
+use App\Enums\UserPaymentOptionStatus;
+use App\Models\Invoice;
+use App\Models\InvoiceBillingAddress;
+use App\Models\UserPaymentOption;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Manueller Rechnungskreis (MAN-) für laufende Legacy-Zahlungen.
+ *
+ * Aktive Alt-Vereinbarungen leben in `user_payment_options` ohne
+ * `stripe_subscription_id`. Wie im Legacy-System wird im Hintergrund
+ * geprüft, wann eine Rechnung fällig ist (`current_period_end` erreicht),
+ * dann eine Rechnung im MAN-Kreis ausgestellt und die Periode
+ * weitergeschaltet. Neue Abschlüsse laufen ausschließlich über Stripe
+ * (STR-Kreis) und werden hier bewusst ausgeklammert.
+ *
+ * Konditions-Overrides pro Vereinbarung über `legacy_conditions` (JSON):
+ * `amount_cents`, `tax_cents`, `total_cents`, `interval` (monthly|yearly).
+ * Ohne Override gilt der Netto-Preis der `payment_option` plus
+ * `billing.vat_rate`.
+ */
+class ManualInvoiceService
+{
+    public function __construct(private readonly InvoiceNumberGenerator $numbers) {}
+
+    /**
+     * @return Collection<int, UserPaymentOption>
+     */
+    public function duePaymentOptions(?Carbon $asOf = null, int $limit = 50): Collection
+    {
+        $asOf = $asOf ?? today();
+
+        return UserPaymentOption::query()
+            ->whereIn('status', [
+                UserPaymentOptionStatus::Active->value,
+                UserPaymentOptionStatus::Grandfathered->value,
+            ])
+            ->whereNull('stripe_subscription_id')
+            ->whereDate('current_period_end', '<=', $asOf)
+            ->orderBy('current_period_end')
+            ->limit($limit)
+            ->with(['user.billingAddress', 'paymentOption'])
+            ->get();
+    }
+
+    /**
+     * Stellt die fällige Rechnung für eine Vereinbarung aus und schaltet die
+     * Periode weiter. Gibt die Rechnung zurück oder null, wenn die
+     * Vereinbarung (noch) nicht abrechenbar ist — dann bleibt die Periode
+     * unverändert und der nächste Lauf versucht es erneut.
+     */
+    public function invoiceFor(UserPaymentOption $option, ?Carbon $asOf = null): ?Invoice
+    {
+        $asOf = $asOf ?? today();
+
+        $user = $option->user;
+        $interval = $this->billingInterval($option);
+
+        if (! $user) {
+            Log::warning('MAN-Rechnung übersprungen: Vereinbarung ohne User.', ['user_payment_option_id' => $option->id]);
+
+            return null;
+        }
+
+        if (! $interval) {
+            Log::warning('MAN-Rechnung übersprungen: kein abrechenbares Intervall.', ['user_payment_option_id' => $option->id]);
+
+            return null;
+        }
+
+        $billingAddress = $user->billingAddress;
+
+        if (! $billingAddress) {
+            Log::warning('MAN-Rechnung übersprungen: User ohne Rechnungsadresse.', [
+                'user_payment_option_id' => $option->id,
+                'user_id' => $user->id,
+            ]);
+
+            return null;
+        }
+
+        [$amountCents, $taxCents, $totalCents] = $this->resolveAmounts($option);
+
+        return DB::transaction(function () use ($option, $user, $billingAddress, $amountCents, $taxCents, $totalCents, $interval, $asOf): Invoice {
+            // Adresse pro Rechnung einfrieren (Snapshot-Tabelle).
+            $addressSnapshot = InvoiceBillingAddress::query()->create([
+                'salutation_key' => $billingAddress->salutation_key,
+                'title' => $billingAddress->title,
+                'name' => $billingAddress->name,
+                'address1' => $billingAddress->address1,
+                'address2' => $billingAddress->address2,
+                'postal_code' => $billingAddress->postal_code,
+                'city' => $billingAddress->city,
+                'country_code' => $billingAddress->country_code,
+            ]);
+
+            $invoice = Invoice::query()->create([
+                'user_id' => $user->id,
+                'invoice_billing_address_id' => $addressSnapshot->id,
+                'number' => $this->numbers->nextManualNumber(),
+                'status' => InvoiceStatus::Open->value,
+                'amount_cents' => $amountCents,
+                'tax_cents' => $taxCents,
+                'total_cents' => $totalCents,
+                'currency' => $option->paymentOption?->currency ?? 'EUR',
+                'invoice_date' => $asOf,
+                'due_date' => $asOf->copy()->addDays((int) config('billing.manual_due_days', 14)),
+            ]);
+
+            $option->update([
+                'current_period_start' => $option->current_period_end,
+                'current_period_end' => $interval === 'yearly'
+                    ? $option->current_period_end->copy()->addYear()
+                    : $option->current_period_end->copy()->addMonth(),
+            ]);
+
+            return $invoice;
+        });
+    }
+
+    private function billingInterval(UserPaymentOption $option): ?string
+    {
+        $interval = $option->legacy_conditions['interval']
+            ?? $option->paymentOption?->interval;
+
+        return in_array($interval, ['monthly', 'yearly'], true) ? $interval : null;
+    }
+
+    /**
+     * @return array{0: int, 1: int, 2: int} [amount_cents, tax_cents, total_cents]
+     */
+    private function resolveAmounts(UserPaymentOption $option): array
+    {
+        $conditions = $option->legacy_conditions ?? [];
+
+        if (isset($conditions['amount_cents'], $conditions['total_cents'])) {
+            $amount = (int) $conditions['amount_cents'];
+            $total = (int) $conditions['total_cents'];
+
+            return [$amount, (int) ($conditions['tax_cents'] ?? $total - $amount), $total];
+        }
+
+        $amount = (int) ($conditions['amount_cents'] ?? $option->paymentOption?->price_cents ?? 0);
+        $tax = (int) round($amount * (float) config('billing.vat_rate', 0.19));
+
+        return [$amount, $tax, $amount + $tax];
+    }
+}