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/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(),
+            ]);
+        });
+    }
+}