Credit-Wallet + Ledger + Tier-Preisableitung (Fundament)

Echte Credit-Wallet (1 Credit = 1 EUR) mit append-only Ledger als Basis fuer
die Credit-Oekonomie aus dem Decision-Update (Rev. 4):

- credit_wallets (denormalisierter Saldo) + credit_transactions (Ledger,
  vorzeichenbehaftet, balance_after, polymorphe reference)
- CreditWalletService: einziger Schreibpfad, atomar mit Row-Lock,
  InsufficientCreditsException mit shortfall fuer den Mini-Checkout
- Tier-Enum (Einzel/Starter/Business/Pro/Agency) + User::currentTier()
- CreditPricingService: tier-gestaffelte Ableitung aus config/credits.php
  (Extra-PM 19/15/12/10/8, Boost 12/20/35, PDF 3, Depublish 25, Pruef-Quota)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/Enums/CreditTransactionType.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Buchungsart im Wallet-Ledger. `Topup`/`Grant` schreiben gut, `Spend`
+ * belastet, `Refund` erstattet eine vorherige Belastung.
+ */
+enum CreditTransactionType: string
+{
+    case Topup = 'topup';
+    case Spend = 'spend';
+    case Refund = 'refund';
+    case Grant = 'grant';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Topup => 'Aufladung',
+            self::Spend => 'Verbrauch',
+            self::Refund => 'Erstattung',
+            self::Grant => 'Gutschrift',
+        };
+    }
+
+    /**
+     * Schreibt die Buchung dem Saldo gut (statt ihn zu belasten)?
+     */
+    public function isCredit(): bool
+    {
+        return in_array($this, [self::Topup, self::Refund, self::Grant], true);
+    }
+}

app/Enums/Tier.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Abrechnungs-Tier laut Decision-Update (Rev. 4). `Einzel` ist der Fall ohne
+ * aktives Abo (Pay-per-Release); die übrigen entsprechen den `plans.slug`.
+ * Treuelogik: höheres Tier = günstigere Extra-PM und mehr Freiprüfungen.
+ */
+enum Tier: string
+{
+    case Einzel = 'einzel';
+    case Starter = 'starter';
+    case Business = 'business';
+    case Pro = 'pro';
+    case Agency = 'agency';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Einzel => 'Einzel',
+            self::Starter => 'Starter',
+            self::Business => 'Business',
+            self::Pro => 'Pro',
+            self::Agency => 'Agency',
+        };
+    }
+
+    /**
+     * Leitet das Tier aus einem `plans.slug` ab; unbekannt/kein Abo → Einzel.
+     */
+    public static function fromPlanSlug(?string $slug): self
+    {
+        return self::tryFrom((string) $slug) ?? self::Einzel;
+    }
+}

app/Exceptions/InsufficientCreditsException.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Wird geworfen, wenn eine Wallet-Belastung das verfügbare Guthaben
+ * übersteigt. Trägt benötigtes und verfügbares Guthaben für den
+ * kontextuellen Mini-Checkout („Kostet 15 Credits, du hast 8").
+ */
+class InsufficientCreditsException extends RuntimeException
+{
+    public function __construct(
+        public readonly int $required,
+        public readonly int $available,
+    ) {
+        parent::__construct("Nicht genügend Credits: benötigt {$required}, verfügbar {$available}.");
+    }
+
+    public function shortfall(): int
+    {
+        return max(0, $this->required - $this->available);
+    }
+}

app/Models/CreditTransaction.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\CreditTransactionType;
+use Database\Factories\CreditTransactionFactory;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
+/**
+ * Eine Zeile im Wallet-Ledger. Append-only: bestehende Buchungen werden nie
+ * verändert, Korrekturen erfolgen als Gegenbuchung (Refund).
+ */
+class CreditTransaction extends Model
+{
+    /** @use HasFactory<CreditTransactionFactory> */
+    use HasFactory;
+
+    protected $fillable = [
+        'credit_wallet_id',
+        'user_id',
+        'amount_credits',
+        'balance_after',
+        'type',
+        'description',
+        'reference_type',
+        'reference_id',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'amount_credits' => 'integer',
+            'balance_after' => 'integer',
+            'type' => CreditTransactionType::class,
+        ];
+    }
+
+    public function wallet(): BelongsTo
+    {
+        return $this->belongsTo(CreditWallet::class, 'credit_wallet_id');
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function reference(): MorphTo
+    {
+        return $this->morphTo();
+    }
+}

app/Models/CreditWallet.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Models;
+
+use App\Services\Billing\CreditWalletService;
+use Database\Factories\CreditWalletFactory;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * Credit-Guthaben eines Users. `balance_credits` ist der denormalisierte
+ * Saldo (1 Credit = 1 €); die maßgebliche Wahrheit ist der Ledger in
+ * `transactions`. Schreibzugriffe laufen ausschließlich über
+ * {@see CreditWalletService} (atomar + gesperrt).
+ */
+class CreditWallet extends Model
+{
+    /** @use HasFactory<CreditWalletFactory> */
+    use HasFactory;
+
+    protected $fillable = [
+        'user_id',
+        'balance_credits',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'balance_credits' => 'integer',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function transactions(): HasMany
+    {
+        return $this->hasMany(CreditTransaction::class)->orderByDesc('created_at');
+    }
+}

app/Models/User.php

@@ -4,6 +4,7 @@ namespace App\Models;
 
 use App\Enums\Portal;
 use App\Enums\RegistrationType;
+use App\Enums\Tier;
 use App\Enums\UserPaymentOptionStatus;
 use Database\Factories\UserFactory;
 use Illuminate\Contracts\Auth\MustVerifyEmail;
@@ -140,6 +141,15 @@ class User extends Authenticatable implements MustVerifyEmail
             ->first();
     }
 
+    /**
+     * Abrechnungs-Tier für die Credit-Preisableitung. Ohne aktives Abo gilt
+     * `Tier::Einzel` (Pay-per-Release).
+     */
+    public function currentTier(): Tier
+    {
+        return Tier::fromPlanSlug($this->currentPlan()?->slug);
+    }
+
     /**
      * Hat dieser User ein unbegrenztes PM-Kontingent?
      *
@@ -291,6 +301,25 @@ class User extends Authenticatable implements MustVerifyEmail
         return $this->hasMany(SinglePurchase::class);
     }
 
+    public function creditWallet(): HasOne
+    {
+        return $this->hasOne(CreditWallet::class);
+    }
+
+    public function creditTransactions(): HasMany
+    {
+        return $this->hasMany(CreditTransaction::class);
+    }
+
+    /**
+     * Aktuelles Credit-Guthaben (1 Credit = 1 €). 0, solange keine Wallet
+     * angelegt wurde.
+     */
+    public function creditBalance(): int
+    {
+        return (int) ($this->creditWallet?->balance_credits ?? 0);
+    }
+
     /**
      * Lokale Rechnungen (STR- und MAN-Kreis). Überschreibt bewusst die
      * gleichnamige Cashier-Methode — Stripe-Rechnungen werden beim

app/Services/Billing/CreditPricingService.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Services\Billing;
+
+use App\Enums\Tier;
+use App\Models\User;
+
+/**
+ * Leitet die Credit-Preise laut Decision-Update (Rev. 4) zur Kaufzeit aus
+ * dem aktiven Tier ab — bewusst nicht statisch je Kauf gespeichert. Einzige
+ * Quelle der Preis-Wahrheit ist config/credits.php.
+ */
+class CreditPricingService
+{
+    /**
+     * Extra-PM-Preis (Credits) für das angegebene Tier. Fällt auf den
+     * Einzel-Satz zurück, falls ein Tier nicht konfiguriert ist.
+     */
+    public function extraPmCredits(Tier $tier): int
+    {
+        $table = config('credits.extra_pm', []);
+
+        return (int) ($table[$tier->value] ?? $table[Tier::Einzel->value]);
+    }
+
+    public function extraPmCreditsFor(User $user): int
+    {
+        return $this->extraPmCredits($user->currentTier());
+    }
+
+    /**
+     * Boost-Preis (Credits) für eine Laufzeit in Tagen.
+     */
+    public function boostCredits(int $days): int
+    {
+        $table = config('credits.boost', []);
+
+        if (! isset($table[$days])) {
+            throw new \InvalidArgumentException("Unbekannte Boost-Laufzeit: {$days} Tage.");
+        }
+
+        return (int) $table[$days];
+    }
+
+    /**
+     * Verfügbare Boost-Laufzeiten als [Tage => Credits], aufsteigend.
+     *
+     * @return array<int, int>
+     */
+    public function boostOptions(): array
+    {
+        $table = config('credits.boost', []);
+        ksort($table);
+
+        return $table;
+    }
+
+    public function proofPdfCredits(): int
+    {
+        return (int) config('credits.proof_pdf');
+    }
+
+    public function depublishCredits(): int
+    {
+        return (int) config('credits.depublish');
+    }
+
+    /**
+     * Freie Prüfungen pro Monat für das Tier (Prüfkontingent §4.3).
+     */
+    public function reviewFreeQuota(Tier $tier): int
+    {
+        $table = config('credits.review.free_per_month', []);
+
+        return (int) ($table[$tier->value] ?? $table[Tier::Einzel->value]);
+    }
+
+    public function reviewDailyLimit(): int
+    {
+        return (int) config('credits.review.daily_limit');
+    }
+
+    public function reviewOverflowCost(): int
+    {
+        return (int) config('credits.review.overflow_cost');
+    }
+}

app/Services/Billing/CreditWalletService.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace App\Services\Billing;
+
+use App\Enums\CreditTransactionType;
+use App\Exceptions\InsufficientCreditsException;
+use App\Models\CreditTransaction;
+use App\Models\CreditWallet;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Einziger Schreibpfad in die Credit-Wallet. Jede Buchung läuft in einer
+ * Transaktion mit Row-Lock auf der Wallet, schreibt eine Ledger-Zeile und
+ * aktualisiert den denormalisierten Saldo — so bleiben Saldo und Ledger
+ * konsistent, auch bei parallelen Käufen.
+ */
+class CreditWalletService
+{
+    /**
+     * Liefert (und legt bei Bedarf an) die Wallet eines Users.
+     */
+    public function walletFor(User $user): CreditWallet
+    {
+        return CreditWallet::query()->firstOrCreate(['user_id' => $user->id]);
+    }
+
+    public function balance(User $user): int
+    {
+        return (int) ($user->creditWallet()->value('balance_credits') ?? 0);
+    }
+
+    /**
+     * Schreibt dem User Credits gut (Aufladung, Erstattung oder Gutschrift).
+     */
+    public function credit(
+        User $user,
+        int $credits,
+        CreditTransactionType $type = CreditTransactionType::Topup,
+        ?string $description = null,
+        ?Model $reference = null,
+    ): CreditTransaction {
+        if ($credits <= 0) {
+            throw new \InvalidArgumentException('Gutschrift muss positiv sein.');
+        }
+
+        if (! $type->isCredit()) {
+            throw new \InvalidArgumentException("Buchungsart {$type->value} ist keine Gutschrift.");
+        }
+
+        return $this->post($user, $credits, $type, $description, $reference);
+    }
+
+    /**
+     * Belastet die Wallet. Wirft InsufficientCreditsException, wenn das
+     * Guthaben nicht reicht (Mini-Checkout-Signal).
+     */
+    public function debit(
+        User $user,
+        int $credits,
+        ?string $description = null,
+        ?Model $reference = null,
+    ): CreditTransaction {
+        if ($credits <= 0) {
+            throw new \InvalidArgumentException('Belastung muss positiv sein.');
+        }
+
+        return $this->post($user, -$credits, CreditTransactionType::Spend, $description, $reference);
+    }
+
+    /**
+     * Reicht das Guthaben für eine Belastung?
+     */
+    public function canAfford(User $user, int $credits): bool
+    {
+        return $this->balance($user) >= $credits;
+    }
+
+    private function post(
+        User $user,
+        int $signedAmount,
+        CreditTransactionType $type,
+        ?string $description,
+        ?Model $reference,
+    ): CreditTransaction {
+        return DB::transaction(function () use ($user, $signedAmount, $type, $description, $reference): CreditTransaction {
+            $wallet = CreditWallet::query()->firstOrCreate(['user_id' => $user->id]);
+            $wallet = CreditWallet::query()->lockForUpdate()->find($wallet->id);
+
+            $newBalance = $wallet->balance_credits + $signedAmount;
+
+            if ($newBalance < 0) {
+                throw new InsufficientCreditsException(abs($signedAmount), $wallet->balance_credits);
+            }
+
+            $wallet->update(['balance_credits' => $newBalance]);
+
+            return $wallet->transactions()->create([
+                'user_id' => $user->id,
+                'amount_credits' => $signedAmount,
+                'balance_after' => $newBalance,
+                'type' => $type,
+                'description' => $description,
+                'reference_type' => $reference?->getMorphClass(),
+                'reference_id' => $reference?->getKey(),
+            ]);
+        });
+    }
+}