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
@@ -3,10 +3,48 @@
 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;

+/**
+ * Never calls the real KBZ refund API in tests.
+ */
+class FakeCancelApiRefundGateway implements PaymentGatewayInterface
+{
+    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: RefundStatus::Completed, gatewayRefundId: 'REFUND123', gatewayPayload: []);
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
 beforeEach(function () {
-    Permission::findOrCreate('manage_bookings', 'web');
+    foreach (['manage_bookings', 'process_refunds'] as $permission) {
+        Permission::findOrCreate($permission, 'web');
+    }
+
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeCancelApiRefundGateway::class);

    $this->owner = User::factory()->create();
    $this->token = $this->owner->createToken('test-token')->plainTextToken;
@@ -23,10 +61,43 @@ test('the owner can cancel their own pending_payment booking', function () {
    expect($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
 });

-test('cancelling a confirmed booking surfaces as 422 and leaves it untouched', function () {
+test('the owner cannot cancel their own confirmed booking without process_refunds', function () {
    $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed]);

    $this->withHeader('Authorization', "Bearer {$this->token}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
+        ->assertForbidden();
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+});
+
+test('staff with process_refunds can cancel a confirmed booking, which refunds it in full', function () {
+    $staff = User::factory()->create()->givePermissionTo('process_refunds');
+    $staffToken = $staff->createToken('staff-token')->plainTextToken;
+
+    $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-CANCEL-API-1',
+    ]);
+
+    $this->withHeader('Authorization', "Bearer {$staffToken}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
+        ->assertSuccessful()
+        ->assertJsonPath('data.status', BookingStatus::Cancelled->value);
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
+});
+
+test('cancelling a confirmed booking with no completed payment surfaces as 422 and leaves it untouched', function () {
+    $staff = User::factory()->create()->givePermissionTo('process_refunds');
+    $staffToken = $staff->createToken('staff-token')->plainTextToken;
+
+    $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed]);
+
+    $this->withHeader('Authorization', "Bearer {$staffToken}")
        ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
        ->assertStatus(422);

@@ -7,15 +7,18 @@ use Modules\Booking\Filament\Resources\Bookings\Pages\ListBookings;
 use Modules\Booking\Filament\Resources\Bookings\Pages\ViewBooking;
 use Modules\Booking\Models\Booking;
 use Modules\Booking\Models\BookingVehicleOption;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Enums\PaymentStatus;
+use Modules\Payment\Models\Payment;
 use Modules\Shared\Enums\VehicleOption;
 use Spatie\Permission\Models\Permission;

 beforeEach(function () {
-    foreach (['view_bookings', 'manage_bookings'] as $permission) {
+    foreach (['view_bookings', 'manage_bookings', 'process_refunds'] as $permission) {
        Permission::findOrCreate($permission, 'web');
    }

-    $this->admin = User::factory()->create()->givePermissionTo(['view_bookings', 'manage_bookings']);
+    $this->admin = User::factory()->create()->givePermissionTo(['view_bookings', 'manage_bookings', 'process_refunds']);
    $this->actingAs($this->admin);
 });

@@ -114,6 +117,29 @@ test('can view a booking\'s detail page', function () {
        ->assertSee($booking->dropoff_address);
 });

+test('the booking detail page shows its related payments', function () {
+    $booking = Booking::factory()->create();
+
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'gateway_transaction_id' => 'EVB-INFOLIST-TEST-1',
+    ]);
+
+    Livewire::test(ViewBooking::class, ['record' => $booking->getRouteKey()])
+        ->assertOk()
+        ->assertSee('EVB-INFOLIST-TEST-1')
+        ->assertSee(PaymentStatus::Completed->value);
+});
+
+test('the booking detail page shows a placeholder when there are no payments yet', function () {
+    $booking = Booking::factory()->create();
+
+    Livewire::test(ViewBooking::class, ['record' => $booking->getRouteKey()])
+        ->assertOk()
+        ->assertSee('No payment attempts yet.');
+});
+
 test('the assign driver action is visible for a confirmed booking and hidden otherwise', function () {
    $confirmed = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
    $pending = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);
@@ -4,35 +4,84 @@ use Modules\Booking\Actions\CancelBookingAction;
 use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Exceptions\BookingCannotBeCancelledException;
 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;

-test('it cancels a pending_payment booking', function () {
+/**
+ * Never calls the real KBZ refund API in tests.
+ */
+class FakeCancelRefundGateway implements PaymentGatewayInterface
+{
+    public static ?string $lastAmount = 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;
+
+        return new RefundResultData(status: RefundStatus::Completed, gatewayRefundId: 'REFUND123', gatewayPayload: []);
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
+beforeEach(function () {
+    FakeCancelRefundGateway::$lastAmount = null;
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeCancelRefundGateway::class);
+});
+
+test('it cancels a pending_payment booking directly', function () {
    $booking = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);

-    $cancelled = (new CancelBookingAction)->handle($booking);
+    $cancelled = app(CancelBookingAction::class)->handle($booking);

    expect($cancelled->status)->toBe(BookingStatus::Cancelled)
        ->and($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
 });

-test('it guards against cancelling a confirmed booking', function () {
-    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
+test('it cancels a confirmed booking by refunding it in full', 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-CANCEL-TEST-1',
+    ]);

-    expect(fn () => (new CancelBookingAction)->handle($booking))
-        ->toThrow(BookingCannotBeCancelledException::class);
+    $cancelled = app(CancelBookingAction::class)->handle($booking);

-    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+    expect($cancelled->status)->toBe(BookingStatus::Cancelled)
+        ->and(FakeCancelRefundGateway::$lastAmount)->toBe('15000.00');
 });

 test('it guards against cancelling an already cancelled booking', function () {
    $booking = Booking::factory()->create(['status' => BookingStatus::Cancelled]);

-    expect(fn () => (new CancelBookingAction)->handle($booking))
+    expect(fn () => app(CancelBookingAction::class)->handle($booking))
        ->toThrow(BookingCannotBeCancelledException::class);
 });

 test('it guards against cancelling an expired booking', function () {
    $booking = Booking::factory()->create(['status' => BookingStatus::Expired]);

-    expect(fn () => (new CancelBookingAction)->handle($booking))
+    expect(fn () => app(CancelBookingAction::class)->handle($booking))
        ->toThrow(BookingCannotBeCancelledException::class);
 });