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
2026-08-09 16:20:21 +07:00
parent 4737838021
commit d19a14a45e
55 changed files with 2547 additions and 29 deletions
@@ -0,0 +1,154 @@
+<?php
+
+use Illuminate\Support\Facades\Event;
+use Modules\Booking\Enums\BookingStatus;
+use Modules\Booking\Models\Booking;
+use Modules\Payment\Actions\RefundBookingAction;
+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\Events\RefundProcessed;
+use Modules\Payment\Exceptions\RefundFailedException;
+use Modules\Payment\Exceptions\RefundNotAllowedException;
+use Modules\Payment\Factories\PaymentGatewayFactory;
+use Modules\Payment\Models\Payment;
+use Modules\Payment\Models\Refund;
+
+/**
+ * Never calls the real KBZ refund API in tests.
+ */
+class FakeRefundGateway implements PaymentGatewayInterface
+{
+    public static ?RefundStatus $resultStatus = RefundStatus::Completed;
+
+    public static ?string $lastAmount = null;
+
+    public static ?string $lastReason = null;
+
+    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
+    {
+        self::$lastAmount = $amount;
+        self::$lastReason = $reason;
+
+        return new RefundResultData(
+            status: self::$resultStatus,
+            gatewayRefundId: self::$resultStatus === RefundStatus::Completed ? 'REFUND123' : null,
+            gatewayPayload: ['result' => self::$resultStatus->value],
+            message: self::$resultStatus === RefundStatus::Failed ? 'Refund window expired' : null,
+        );
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
+beforeEach(function () {
+    FakeRefundGateway::$resultStatus = RefundStatus::Completed;
+    FakeRefundGateway::$lastAmount = null;
+    FakeRefundGateway::$lastReason = null;
+
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeRefundGateway::class);
+});
+
+function confirmedBookingWithPayment(string $amount = '15000'): Booking
+{
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed, 'price' => $amount]);
+
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => $amount,
+        'gateway_transaction_id' => 'EVB-REFUND-TEST-1',
+    ]);
+
+    return $booking;
+}
+
+test('a full refund on a confirmed booking completes and flips the booking to cancelled', function () {
+    $booking = confirmedBookingWithPayment('15000');
+
+    $refund = app(RefundBookingAction::class)->handle($booking, '15000', 'customer requested cancellation');
+
+    expect($refund->status)->toBe(RefundStatus::Completed)
+        ->and($refund->amount)->toBe('15000.00')
+        ->and($refund->gateway_refund_id)->toBe('REFUND123')
+        ->and($booking->refresh()->status)->toBe(BookingStatus::Cancelled)
+        ->and(FakeRefundGateway::$lastAmount)->toBe('15000')
+        ->and(FakeRefundGateway::$lastReason)->toBe('customer requested cancellation');
+});
+
+test('a partial refund is wired through to the gateway and does not exceed the payment amount', function () {
+    $booking = confirmedBookingWithPayment('15000');
+
+    $refund = app(RefundBookingAction::class)->handle($booking, '8000', 'partial refund');
+
+    expect($refund->status)->toBe(RefundStatus::Completed)
+        ->and($refund->amount)->toBe('8000.00')
+        ->and(FakeRefundGateway::$lastAmount)->toBe('8000');
+});
+
+test('a second partial refund is validated against the remaining refundable balance, not the original total', function () {
+    $booking = confirmedBookingWithPayment('15000');
+
+    app(RefundBookingAction::class)->handle($booking, '10000', 'first partial refund');
+
+    expect(fn () => app(RefundBookingAction::class)->handle($booking, '6000', 'second partial refund'))
+        ->toThrow(RefundNotAllowedException::class);
+});
+
+test('a second partial refund within the remaining balance succeeds', function () {
+    $booking = confirmedBookingWithPayment('15000');
+
+    app(RefundBookingAction::class)->handle($booking, '10000', 'first partial refund');
+    $second = app(RefundBookingAction::class)->handle($booking, '5000', 'second partial refund');
+
+    expect($second->status)->toBe(RefundStatus::Completed);
+});
+
+test('refunding a non-confirmed booking throws RefundNotAllowedException', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);
+
+    expect(fn () => app(RefundBookingAction::class)->handle($booking, '5000', 'reason'))
+        ->toThrow(RefundNotAllowedException::class);
+});
+
+test('refunding a confirmed booking with no completed payment throws RefundNotAllowedException', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
+
+    expect(fn () => app(RefundBookingAction::class)->handle($booking, '5000', 'reason'))
+        ->toThrow(RefundNotAllowedException::class);
+});
+
+test('a failed gateway refund is persisted as failed, leaves the booking untouched, and throws RefundFailedException', function () {
+    Event::fake([RefundProcessed::class]);
+    FakeRefundGateway::$resultStatus = RefundStatus::Failed;
+
+    $booking = confirmedBookingWithPayment('15000');
+
+    try {
+        app(RefundBookingAction::class)->handle($booking, '15000', 'reason');
+        $this->fail('Expected RefundFailedException to be thrown.');
+    } catch (RefundFailedException $exception) {
+        expect($exception->getMessage())->toBe('Refund window expired');
+    }
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed)
+        ->and(Refund::where('status', RefundStatus::Failed)->count())->toBe(1);
+
+    Event::assertNotDispatched(RefundProcessed::class);
+});