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

config/credits.php

@@ -0,0 +1,79 @@
+<?php
+
+use App\Enums\Tier;
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Credit-Ökonomie (Decision-Update Phase-2-Funktionen, Rev. 4)
+    |--------------------------------------------------------------------------
+    |
+    | 1 Credit = 1 €. Alle Preise sind die zur Kaufzeit aus dem aktiven Tier
+    | abgeleiteten Credit-Beträge (nicht statisch je Kauf gespeichert). Die
+    | zentrale Ableitung erfolgt in App\Services\Billing\CreditPricingService.
+    |
+    */
+
+    /*
+    | Extra-PM (Kontingent-Nachkauf) — tier-gestaffelt. Treuevorteil:
+    | höheres Abo = günstigere Extra-PM (Einzel 19 … Agency 8).
+    */
+    'extra_pm' => [
+        Tier::Einzel->value => 19,
+        Tier::Starter->value => 15,
+        Tier::Business->value => 12,
+        Tier::Pro->value => 10,
+        Tier::Agency->value => 8,
+    ],
+
+    /*
+    | Boost (Platzierung Startseite + Branchenseite) — nach Dauer in Tagen.
+    | Pro-Tag-Preis sinkt mit der Dauer; Einstieg bleibt unter dem PM-Preis.
+    */
+    'boost' => [
+        7 => 12,
+        14 => 20,
+        30 => 35,
+    ],
+
+    /*
+    | Veröffentlichungsnachweis-PDF — pauschal pro PM (Impulskauf).
+    */
+    'proof_pdf' => 3,
+
+    /*
+    | Depublizieren (Magic-Link-Pfad G) — bewusst am teuersten, mit Bedenkzeit.
+    */
+    'depublish' => 25,
+
+    /*
+    | Kostenpflichtige Magic-Link-Pfade C/D (Phase 2, Anker „zu bestätigen").
+    */
+    'paths' => [
+        'correction' => 8, // C – inhaltliche Korrektur
+        'update' => 4,     // D – Update/Ergänzung
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Prüfzähler / Prüfkontingent (Decision-Update §4.2/§4.3)
+    |--------------------------------------------------------------------------
+    |
+    | Eigener Zähler, getrennt von der Wallet. Tier-gestaffelte Freiprüfungen
+    | pro Account/Monat (aggregiert, nicht pro PM). Burst-Schutz per Tageslimit.
+    | Overflow: leerer Zähler → je weitere Prüfung 1 Credit aus der Wallet.
+    */
+    'review' => [
+        'free_per_month' => [
+            Tier::Einzel->value => 4,
+            Tier::Starter->value => 12,
+            Tier::Business->value => 30,
+            Tier::Pro->value => 60,
+            Tier::Agency->value => 120,
+        ],
+        'daily_limit' => 10,
+        'overflow_cost' => 1,
+    ],
+
+];

database/factories/CreditTransactionFactory.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Enums\CreditTransactionType;
+use App\Models\CreditTransaction;
+use App\Models\CreditWallet;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<CreditTransaction>
+ */
+class CreditTransactionFactory extends Factory
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $amount = $this->faker->numberBetween(1, 50);
+
+        return [
+            'credit_wallet_id' => CreditWallet::factory(),
+            'user_id' => User::factory(),
+            'amount_credits' => $amount,
+            'balance_after' => $amount,
+            'type' => CreditTransactionType::Topup,
+            'description' => null,
+            'reference_type' => null,
+            'reference_id' => null,
+        ];
+    }
+}

database/factories/CreditWalletFactory.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\CreditWallet;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<CreditWallet>
+ */
+class CreditWalletFactory extends Factory
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'user_id' => User::factory(),
+            'balance_credits' => 0,
+        ];
+    }
+
+    public function withBalance(int $credits): static
+    {
+        return $this->state(fn (): array => ['balance_credits' => $credits]);
+    }
+}

database/migrations/2026_06_17_141218_create_credit_wallets_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Credit-Wallet laut Decision-Update (Rev. 4): eine Wallet pro User, ein
+ * tier-abhängiger Preis. 1 Credit = 1 €. Der Saldo ist die Summe aller
+ * Buchungen in `credit_transactions` und wird hier denormalisiert geführt,
+ * damit Gate-Checks ohne Aggregat-Query auskommen.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('credit_wallets', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('user_id')->unique()->constrained()->cascadeOnDelete();
+            $table->integer('balance_credits')->default(0);
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('credit_wallets');
+    }
+};

database/migrations/2026_06_17_141219_create_credit_transactions_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Append-only Ledger der Credit-Wallet. Jede Auf-/Entladung ist eine Zeile
+ * mit vorzeichenbehaftetem `amount_credits` (+ = Gutschrift, − = Verbrauch)
+ * und dem resultierenden `balance_after` für lückenlose Nachvollziehbarkeit.
+ * `reference` verweist polymorph auf den auslösenden Vorgang (SinglePurchase,
+ * Boost, PressRelease …).
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('credit_transactions', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('credit_wallet_id')->constrained()->cascadeOnDelete();
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->integer('amount_credits');
+            $table->integer('balance_after');
+            $table->string('type');
+            $table->string('description')->nullable();
+            $table->nullableMorphs('reference');
+            $table->timestamps();
+
+            $table->index(['user_id', 'created_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('credit_transactions');
+    }
+};

tests/Feature/CreditPricingServiceTest.php

@@ -0,0 +1,62 @@
+<?php
+
+use App\Enums\Tier;
+use App\Models\Plan;
+use App\Models\User;
+use App\Services\Billing\CreditPricingService;
+
+beforeEach(function (): void {
+    $this->pricing = app(CreditPricingService::class);
+});
+
+test('extra-pm credits follow the tier staffel', function () {
+    expect($this->pricing->extraPmCredits(Tier::Einzel))->toBe(19);
+    expect($this->pricing->extraPmCredits(Tier::Starter))->toBe(15);
+    expect($this->pricing->extraPmCredits(Tier::Business))->toBe(12);
+    expect($this->pricing->extraPmCredits(Tier::Pro))->toBe(10);
+    expect($this->pricing->extraPmCredits(Tier::Agency))->toBe(8);
+});
+
+test('a user without a plan is on the Einzel tier and pays the full extra-pm rate', function () {
+    $user = User::factory()->create();
+
+    expect($user->currentTier())->toBe(Tier::Einzel);
+    expect($this->pricing->extraPmCreditsFor($user))->toBe(19);
+});
+
+test('a subscriber inherits the tier of the plan slug', function () {
+    $user = User::factory()->create();
+    $plan = Plan::factory()->create([
+        'slug' => 'business',
+        'stripe_price_id_monthly' => 'price_biz_'.fake()->unique()->randomNumber(6),
+    ]);
+    subscribeUserToPlan($user, $plan);
+
+    expect($user->currentTier())->toBe(Tier::Business);
+    expect($this->pricing->extraPmCreditsFor($user))->toBe(12);
+});
+
+test('boost credits follow the duration staffel and reject unknown durations', function () {
+    expect($this->pricing->boostCredits(7))->toBe(12);
+    expect($this->pricing->boostCredits(14))->toBe(20);
+    expect($this->pricing->boostCredits(30))->toBe(35);
+    expect($this->pricing->boostOptions())->toBe([7 => 12, 14 => 20, 30 => 35]);
+
+    expect(fn () => $this->pricing->boostCredits(99))
+        ->toThrow(InvalidArgumentException::class);
+});
+
+test('flat prices match the decision update', function () {
+    expect($this->pricing->proofPdfCredits())->toBe(3);
+    expect($this->pricing->depublishCredits())->toBe(25);
+});
+
+test('review free quota follows the tier staffel', function () {
+    expect($this->pricing->reviewFreeQuota(Tier::Einzel))->toBe(4);
+    expect($this->pricing->reviewFreeQuota(Tier::Starter))->toBe(12);
+    expect($this->pricing->reviewFreeQuota(Tier::Business))->toBe(30);
+    expect($this->pricing->reviewFreeQuota(Tier::Pro))->toBe(60);
+    expect($this->pricing->reviewFreeQuota(Tier::Agency))->toBe(120);
+    expect($this->pricing->reviewDailyLimit())->toBe(10);
+    expect($this->pricing->reviewOverflowCost())->toBe(1);
+});

tests/Feature/CreditWalletServiceTest.php

@@ -0,0 +1,67 @@
+<?php
+
+use App\Enums\CreditTransactionType;
+use App\Exceptions\InsufficientCreditsException;
+use App\Models\User;
+use App\Services\Billing\CreditWalletService;
+
+beforeEach(function (): void {
+    $this->service = app(CreditWalletService::class);
+});
+
+test('a credit raises the balance and writes a ledger row', function () {
+    $user = User::factory()->create();
+
+    $tx = $this->service->credit($user, 20, CreditTransactionType::Topup, 'Paket 20');
+
+    expect($this->service->balance($user))->toBe(20);
+    expect($tx->amount_credits)->toBe(20);
+    expect($tx->balance_after)->toBe(20);
+    expect($tx->type)->toBe(CreditTransactionType::Topup);
+});
+
+test('a debit lowers the balance and records the balance after', function () {
+    $user = User::factory()->create();
+    $this->service->credit($user, 20);
+
+    $tx = $this->service->debit($user, 12, 'Extra-PM');
+
+    expect($this->service->balance($user))->toBe(8);
+    expect($tx->amount_credits)->toBe(-12);
+    expect($tx->balance_after)->toBe(8);
+    expect($tx->type)->toBe(CreditTransactionType::Spend);
+});
+
+test('debiting more than the balance throws and keeps the balance untouched', function () {
+    $user = User::factory()->create();
+    $this->service->credit($user, 8);
+
+    $threw = null;
+    try {
+        $this->service->debit($user, 15);
+    } catch (InsufficientCreditsException $e) {
+        $threw = $e;
+    }
+
+    expect($threw)->toBeInstanceOf(InsufficientCreditsException::class);
+    expect($threw->shortfall())->toBe(7);
+    expect($this->service->balance($user))->toBe(8);
+    expect($user->creditTransactions()->count())->toBe(1); // nur die Aufladung
+});
+
+test('balance is zero and canAfford is false without a wallet', function () {
+    $user = User::factory()->create();
+
+    expect($this->service->balance($user))->toBe(0);
+    expect($this->service->canAfford($user, 1))->toBeFalse();
+});
+
+test('a refund credits back a prior spend', function () {
+    $user = User::factory()->create();
+    $this->service->credit($user, 30);
+    $this->service->debit($user, 25, 'Depublizieren');
+
+    $this->service->credit($user, 25, CreditTransactionType::Refund, 'Widerruf Depublizieren');
+
+    expect($this->service->balance($user))->toBe(30);
+});