Complete Payment module: initiate/webhook/confirm/refund actions, Filament resources (T5.8-T5.13)

- InitiatePaymentAction + POST /api/v1/payments/{booking}/initiate
- Generic KBZ webhook (POST /api/v1/webhooks/{method}/{encryptBookingId?}),
  signature verification per KBZ's real callback spec, PaymentGatewayInterface::handleWebhook()
- ConfirmPaymentAction: idempotent confirmation, PaymentCompleted/PaymentFailed events,
  MarkBookingPaid listener
- RefundBookingAction + POST /api/v1/bookings/{booking}/refund: partial refunds validated
  against remaining balance, RefundProcessed event, MarkBookingRefunded listener
- CancelBookingAction now refunds confirmed bookings instead of rejecting; BookingPolicy::cancel
  requires process_refunds for confirmed bookings
- PaymentPlugin + PaymentResource/RefundResource Filament admin UI (read-only payments,
  refund list + Process action)
- Booking detail page now shows related payments
- Fix CACHE_STORE mismatch (database -> redis) so tagged route caching works
- CLAUDE.md: never run migrate:fresh/migrate:refresh/db:wipe on dev without being asked

app-modules/payment/tests/Feature/RefundBookingApiTest.php

@@ -0,0 +1,136 @@
+<?php
+
+use App\Models\User;
+use Modules\Booking\Enums\BookingStatus;
+use Modules\Booking\Models\Booking;
+use Modules\Payment\Contracts\PaymentGatewayInterface;
+use Modules\Payment\Data\PaymentRequestData;
+use Modules\Payment\Data\PaymentResultData;
+use Modules\Payment\Data\RefundResultData;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Enums\RefundStatus;
+use Modules\Payment\Factories\PaymentGatewayFactory;
+use Modules\Payment\Models\Payment;
+use Spatie\Permission\Models\Permission;
+
+class FakeRefundApiGateway implements PaymentGatewayInterface
+{
+    public static RefundStatus $resultStatus = RefundStatus::Completed;
+
+    public function initiate(PaymentRequestData $data): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function verify(string $gatewayTransactionId): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function refund(string $gatewayTransactionId, string $amount, string $reason): RefundResultData
+    {
+        return new RefundResultData(
+            status: self::$resultStatus,
+            gatewayRefundId: self::$resultStatus === RefundStatus::Completed ? 'REFUND123' : null,
+            gatewayPayload: [],
+            message: self::$resultStatus === RefundStatus::Failed ? 'Refund failed at gateway' : null,
+        );
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
+beforeEach(function () {
+    FakeRefundApiGateway::$resultStatus = RefundStatus::Completed;
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeRefundApiGateway::class);
+
+    Permission::findOrCreate('process_refunds', 'web');
+
+    $this->staff = User::factory()->create()->givePermissionTo('process_refunds');
+    $this->staffToken = $this->staff->createToken('staff-token')->plainTextToken;
+});
+
+test('staff with process_refunds can refund a confirmed booking', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-API-REFUND-1',
+    ]);
+
+    $this->withHeader('Authorization', "Bearer {$this->staffToken}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/refund", [
+            'amount' => 15000,
+            'reason' => 'customer requested cancellation',
+        ])
+        ->assertCreated()
+        ->assertJsonPath('data.status', RefundStatus::Completed->value);
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
+});
+
+test('a customer without process_refunds cannot refund their own booking', function () {
+    $owner = User::factory()->create();
+    $token = $owner->createToken('customer-token')->plainTextToken;
+
+    $booking = Booking::factory()->create(['user_id' => $owner->id, 'status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-API-REFUND-2',
+    ]);
+
+    $this->withHeader('Authorization', "Bearer {$token}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/refund", [
+            'amount' => 15000,
+            'reason' => 'customer requested cancellation',
+        ])
+        ->assertForbidden();
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+});
+
+test('refunding a pending_payment booking surfaces as 422', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);
+
+    $this->withHeader('Authorization', "Bearer {$this->staffToken}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/refund", [
+            'amount' => 5000,
+            'reason' => 'reason',
+        ])
+        ->assertStatus(422);
+});
+
+test('a failed gateway refund surfaces the gateway message as 422 and leaves the booking confirmed', function () {
+    FakeRefundApiGateway::$resultStatus = RefundStatus::Failed;
+
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-API-REFUND-3',
+    ]);
+
+    $this->withHeader('Authorization', "Bearer {$this->staffToken}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/refund", [
+            'amount' => 15000,
+            'reason' => 'reason',
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath('message', 'Refund failed at gateway');
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+});
+
+test('unauthenticated requests are rejected', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
+
+    $this->postJson("/api/v1/bookings/{$booking->booking_ref}/refund", ['amount' => 100, 'reason' => 'x'])
+        ->assertUnauthorized();
+});