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

database/factories/ReviewCheckFactory.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Enums\ReviewCheckSource;
+use App\Models\ReviewCheck;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<ReviewCheck>
+ */
+class ReviewCheckFactory extends Factory
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'user_id' => User::factory(),
+            'press_release_id' => null,
+            'source' => ReviewCheckSource::Free,
+            'charged_credits' => 0,
+        ];
+    }
+}

database/migrations/2026_06_17_141703_create_review_checks_table.php

@@ -0,0 +1,36 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Prüfzähler-Ledger (Decision-Update §4.2): eine Zeile je Prüfung. Der eigene
+ * Zähler ist bewusst von der Credit-Wallet getrennt — „Prüfungen inklusive"
+ * bleibt ein sauberes Versprechen. `source` unterscheidet die aus dem
+ * Monats-Freikontingent gedeckte Prüfung (free) von der per Credit
+ * nachgezogenen Overflow-Prüfung (credit); `charged_credits` hält den
+ * tatsächlich belasteten Betrag fest. Aggregiert wird pro Account/Monat
+ * (nicht pro PM), das Tageslimit dient als Burst-Schutz.
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('review_checks', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->foreignId('press_release_id')->nullable()->constrained()->nullOnDelete();
+            $table->string('source');
+            $table->integer('charged_credits')->default(0);
+            $table->timestamps();
+
+            $table->index(['user_id', 'created_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('review_checks');
+    }
+};

tests/Feature/ReviewCheckServiceTest.php

@@ -0,0 +1,102 @@
+<?php
+
+use App\Enums\ReviewCheckSource;
+use App\Exceptions\InsufficientCreditsException;
+use App\Exceptions\ReviewLimitException;
+use App\Models\User;
+use App\Services\Billing\CreditWalletService;
+use App\Services\PressRelease\ReviewCheckService;
+
+beforeEach(function (): void {
+    $this->service = app(ReviewCheckService::class);
+    $this->wallet = app(CreditWalletService::class);
+});
+
+test('an Einzel user has four free checks per month', function () {
+    $user = User::factory()->create();
+
+    expect($this->service->freeRemaining($user))->toBe(4);
+    expect($this->service->nextCheckCosts($user))->toBeFalse();
+});
+
+test('free checks are consumed from the monthly quota first', function () {
+    $user = User::factory()->create();
+
+    $check = $this->service->recordCheck($user);
+
+    expect($check->source)->toBe(ReviewCheckSource::Free);
+    expect($check->charged_credits)->toBe(0);
+    expect($this->service->freeRemaining($user))->toBe(3);
+    expect($this->service->usedThisMonth($user))->toBe(1);
+});
+
+test('once the free quota is empty the overflow draws one credit per check', function () {
+    $user = User::factory()->create();
+    $this->wallet->credit($user, 5);
+
+    // Vier freie Prüfungen aufbrauchen.
+    for ($i = 0; $i < 4; $i++) {
+        $this->service->recordCheck($user);
+    }
+
+    expect($this->service->freeRemaining($user))->toBe(0);
+    expect($this->service->nextCheckCosts($user))->toBeTrue();
+
+    $overflow = $this->service->recordCheck($user);
+
+    expect($overflow->source)->toBe(ReviewCheckSource::Credit);
+    expect($overflow->charged_credits)->toBe(1);
+    expect($this->wallet->balance($user))->toBe(4);
+});
+
+test('overflow without enough credits throws and records nothing', function () {
+    $user = User::factory()->create();
+    for ($i = 0; $i < 4; $i++) {
+        $this->service->recordCheck($user);
+    }
+
+    expect(fn () => $this->service->recordCheck($user))
+        ->toThrow(InsufficientCreditsException::class);
+
+    expect($this->service->usedThisMonth($user))->toBe(4); // kein Overflow-Eintrag
+});
+
+test('the daily limit is a hard brake that credits cannot bypass', function () {
+    $user = User::factory()->create();
+    $this->wallet->credit($user, 100);
+
+    // 10 Prüfungen heute (Tageslimit) – 4 frei, 6 per Credit.
+    for ($i = 0; $i < 10; $i++) {
+        $this->service->recordCheck($user);
+    }
+
+    expect($this->service->dailyLimitReached($user))->toBeTrue();
+    expect($this->service->canCheck($user))->toBeFalse();
+    expect(fn () => $this->service->recordCheck($user))
+        ->toThrow(ReviewLimitException::class);
+});
+
+test('a higher tier check pool resets with the calendar month', function () {
+    $user = User::factory()->create();
+
+    // Letzten Monat verbrauchte Prüfungen zählen nicht ins aktuelle Kontingent.
+    ReviewCheckFactoryHelper($user, 3, now()->subMonth());
+
+    expect($this->service->usedThisMonth($user))->toBe(0);
+    expect($this->service->freeRemaining($user))->toBe(4);
+});
+
+/**
+ * Legt Prüfungen mit explizitem Datum an (umgeht den Service, der immer
+ * „jetzt" bucht).
+ */
+function ReviewCheckFactoryHelper(User $user, int $count, $at): void
+{
+    for ($i = 0; $i < $count; $i++) {
+        $check = $user->reviewChecks()->create([
+            'source' => ReviewCheckSource::Free,
+            'charged_credits' => 0,
+        ]);
+        $check->forceFill(['created_at' => $at, 'updated_at' => $at])->save();
+    }
+}