Pruefzaehler + Pruefkontingent (Decision-Update Phase-2 vorgezogen)

Eigener Pruef-Zaehler, getrennt von der Credit-Wallet (Paragraph 4.2/4.3):

- review_checks Ledger (eine Zeile je Pruefung, source free|credit,
  charged_credits), aggregiert pro Account/Monat statt pro PM
- ReviewCheckService: Tageslimit (harte Bremse, nicht freikaufbar) ->
  Monats-Freikontingent (tier-gestaffelt 4/12/30/60/120) -> Overflow
  zieht 1 Credit/Pruefung aus der Wallet
- ReviewLimitException fuer das erreichte Tageslimit

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

app/Enums/ReviewCheckSource.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Herkunft einer Prüfung: aus dem monatlichen Freikontingent (Free) oder als
+ * per Credit nachgezogene Overflow-Prüfung (Credit).
+ */
+enum ReviewCheckSource: string
+{
+    case Free = 'free';
+    case Credit = 'credit';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Free => 'Freikontingent',
+            self::Credit => 'Credit (Overflow)',
+        };
+    }
+}

app/Exceptions/ReviewLimitException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Wird geworfen, wenn das Prüf-Tageslimit (Burst-Schutz) erreicht ist. Anders
+ * als ein leeres Monats-Freikontingent ist das eine harte Bremse: sie lässt
+ * sich nicht per Credit überbrücken, sondern erst am Folgetag wieder lösen.
+ */
+class ReviewLimitException extends RuntimeException
+{
+    public function __construct(
+        public readonly int $dailyLimit,
+    ) {
+        parent::__construct("Prüf-Tageslimit erreicht ({$dailyLimit}/Tag).");
+    }
+}

app/Models/ReviewCheck.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Models;
+
+use App\Enums\ReviewCheckSource;
+use App\Services\PressRelease\ReviewCheckService;
+use Database\Factories\ReviewCheckFactory;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * Eine verbrauchte Prüfung. Schreibzugriffe laufen über
+ * {@see ReviewCheckService}.
+ */
+class ReviewCheck extends Model
+{
+    /** @use HasFactory<ReviewCheckFactory> */
+    use HasFactory;
+
+    protected $fillable = [
+        'user_id',
+        'press_release_id',
+        'source',
+        'charged_credits',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'source' => ReviewCheckSource::class,
+            'charged_credits' => 'integer',
+        ];
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function pressRelease(): BelongsTo
+    {
+        return $this->belongsTo(PressRelease::class);
+    }
+
+    /**
+     * Prüfungen im laufenden Kalendermonat (Aggregat pro Account).
+     */
+    public function scopeThisMonth(Builder $query): Builder
+    {
+        return $query->where('created_at', '>=', now()->startOfMonth());
+    }
+
+    /**
+     * Prüfungen am heutigen Tag (Burst-/Tageslimit).
+     */
+    public function scopeToday(Builder $query): Builder
+    {
+        return $query->where('created_at', '>=', now()->startOfDay());
+    }
+}

app/Models/User.php

@@ -311,6 +311,11 @@ class User extends Authenticatable implements MustVerifyEmail
         return $this->hasMany(CreditTransaction::class);
     }
 
+    public function reviewChecks(): HasMany
+    {
+        return $this->hasMany(ReviewCheck::class);
+    }
+
     /**
      * Aktuelles Credit-Guthaben (1 Credit = 1 €). 0, solange keine Wallet
      * angelegt wurde.

app/Services/PressRelease/ReviewCheckService.php

@@ -0,0 +1,115 @@
+<?php
+
+namespace App\Services\PressRelease;
+
+use App\Enums\ReviewCheckSource;
+use App\Exceptions\ReviewLimitException;
+use App\Models\PressRelease;
+use App\Models\ReviewCheck;
+use App\Models\User;
+use App\Services\Billing\CreditPricingService;
+use App\Services\Billing\CreditWalletService;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Prüfzähler-Logik laut Decision-Update §4.2/§4.3.
+ *
+ * Reihenfolge je Prüfung:
+ *   1. Tageslimit (Burst-Schutz) – harte Bremse, nicht freikaufbar.
+ *   2. Monats-Freikontingent (tier-gestaffelt, aggregiert pro Account).
+ *   3. Overflow – ist das Freikontingent leer, zieht jede weitere Prüfung
+ *      `credits.review.overflow_cost` Credits aus der Wallet.
+ */
+class ReviewCheckService
+{
+    public function __construct(
+        private readonly CreditPricingService $pricing,
+        private readonly CreditWalletService $wallet,
+    ) {}
+
+    /**
+     * Verbrauchte Prüfungen im laufenden Monat (Account-Aggregat).
+     */
+    public function usedThisMonth(User $user): int
+    {
+        return $user->reviewChecks()->thisMonth()->count();
+    }
+
+    public function usedToday(User $user): int
+    {
+        return $user->reviewChecks()->today()->count();
+    }
+
+    /**
+     * Verbleibende Frei-Prüfungen diesen Monat.
+     */
+    public function freeRemaining(User $user): int
+    {
+        $quota = $this->pricing->reviewFreeQuota($user->currentTier());
+
+        return max(0, $quota - $this->usedThisMonth($user));
+    }
+
+    public function dailyLimitReached(User $user): bool
+    {
+        return $this->usedToday($user) >= $this->pricing->reviewDailyLimit();
+    }
+
+    /**
+     * Würde die nächste Prüfung Credits kosten (Freikontingent leer)?
+     */
+    public function nextCheckCosts(User $user): bool
+    {
+        return $this->freeRemaining($user) === 0;
+    }
+
+    /**
+     * Kann der User jetzt eine Prüfung auslösen? Tageslimit nicht erreicht und
+     * entweder Freikontingent übrig oder genug Guthaben für den Overflow.
+     */
+    public function canCheck(User $user): bool
+    {
+        if ($this->dailyLimitReached($user)) {
+            return false;
+        }
+
+        if ($this->freeRemaining($user) > 0) {
+            return true;
+        }
+
+        return $this->wallet->canAfford($user, $this->pricing->reviewOverflowCost());
+    }
+
+    /**
+     * Bucht eine Prüfung. Wirft ReviewLimitException am Tageslimit und
+     * InsufficientCreditsException, wenn der Overflow nicht gedeckt ist.
+     */
+    public function recordCheck(User $user, ?PressRelease $pressRelease = null): ReviewCheck
+    {
+        if ($this->dailyLimitReached($user)) {
+            throw new ReviewLimitException($this->pricing->reviewDailyLimit());
+        }
+
+        return DB::transaction(function () use ($user, $pressRelease): ReviewCheck {
+            $useFree = $this->freeRemaining($user) > 0;
+            $charged = 0;
+
+            if (! $useFree) {
+                $cost = $this->pricing->reviewOverflowCost();
+                $this->wallet->debit(
+                    $user,
+                    $cost,
+                    'Prüfung (Overflow)',
+                    $pressRelease,
+                );
+                $charged = $cost;
+            }
+
+            return $user->reviewChecks()->create([
+                'press_release_id' => $pressRelease?->id,
+                'source' => $useFree ? ReviewCheckSource::Free : ReviewCheckSource::Credit,
+                'charged_credits' => $charged,
+            ]);
+        });
+    }
+}