feat(ticket): implement refund functionality and expose allow_refund flag

tests/Feature/Ticket/AdminAppTicketControllerTest.php

@@ -73,6 +73,7 @@ class AdminAppTicketControllerTest extends TestCase
             ->assertJsonPath('data.0.values.id', $ticket->id)
             ->assertJsonPath('data.0.values.status', Ticket::STATUS_ACTIVE)
             ->assertJsonPath('data.0.status_label', 'Activo')
+            ->assertJsonPath('data.0.allow_refund', false)
             ->assertJsonMissingPath('data.0.values.ticket')
             ->assertJsonPath('data.0.values.date', '-')
             ->assertJsonPath('data.0.values.size', '-')
@@ -80,6 +81,45 @@ class AdminAppTicketControllerTest extends TestCase
             ->assertJsonPath('meta.total', 1);
     }
 
+    public function test_it_exposes_allow_refund_flag_in_tickets_list(): void
+    {
+        $tenant = $this->createTenant('ticket-allow-refund');
+        $admin = $this->createAdminAppUser($tenant);
+        $this->grantTicketsMenu($tenant);
+        Sanctum::actingAs($admin);
+
+        $this->createTicket($tenant, $admin);
+
+        // Default: neither total nor partial refund allowed
+        $this->getJson('/api/v1/adminapp/tenant/tickets')
+            ->assertOk()
+            ->assertJsonPath('data.0.allow_refund', false);
+
+        // Total refund allowed
+        $tenant->update(['allow_ticket_total_refund' => true]);
+        $this->getJson('/api/v1/adminapp/tenant/tickets')
+            ->assertOk()
+            ->assertJsonPath('data.0.allow_refund', true);
+
+        // Partial refund allowed with percentage set
+        $tenant->update([
+            'allow_ticket_total_refund' => false,
+            'allow_ticket_partial_refund' => true,
+            'ticket_partial_refund_percentage' => 20.00,
+        ]);
+        $this->getJson('/api/v1/adminapp/tenant/tickets')
+            ->assertOk()
+            ->assertJsonPath('data.0.allow_refund', true);
+
+        // Partial refund enabled but percentage is 0
+        $tenant->update([
+            'ticket_partial_refund_percentage' => 0,
+        ]);
+        $this->getJson('/api/v1/adminapp/tenant/tickets')
+            ->assertOk()
+            ->assertJsonPath('data.0.allow_refund', false);
+    }
+
     public function test_it_cancels_a_ticket_from_the_authenticated_tenant(): void
     {
         $tenant = $this->createTenant('ticket-cancellation');
@@ -112,6 +152,82 @@ class AdminAppTicketControllerTest extends TestCase
         $this->assertNull($ticket->fresh()->cancelled_at);
     }
 
+    public function test_it_totally_refunds_a_ticket_when_the_tenant_allows_it(): void
+    {
+        $tenant = $this->createTenant('ticket-total-refund');
+        $tenant->update(['allow_ticket_total_refund' => true]);
+        $admin = $this->createAdminAppUser($tenant);
+        $this->grantTicketsMenu($tenant);
+        Sanctum::actingAs($admin);
+        [$ticket, $purchaseItem] = $this->createRefundableTicket($tenant, $admin, '100.00');
+
+        $this->postJson("/api/v1/adminapp/tenant/tickets/{$ticket->id}/refund", [
+            'refund_type' => 'total',
+        ])
+            ->assertOk()
+            ->assertJsonPath('data.id', $ticket->id)
+            ->assertJsonPath('data.status', Ticket::STATUS_REFUNDED)
+            ->assertJsonPath('data.refunded_amount', '100.00');
+
+        $this->assertNotNull($ticket->fresh()->refunded_at);
+        $this->assertSame('100.00', $purchaseItem->fresh()->refunded_amount);
+    }
+
+    public function test_it_partially_refunds_a_ticket_using_the_tenant_percentage(): void
+    {
+        $tenant = $this->createTenant('ticket-partial-refund');
+        $tenant->update([
+            'allow_ticket_partial_refund' => true,
+            'ticket_partial_refund_percentage' => 25.50,
+        ]);
+        $admin = $this->createAdminAppUser($tenant);
+        $this->grantTicketsMenu($tenant);
+        Sanctum::actingAs($admin);
+        [$ticket, $purchaseItem] = $this->createRefundableTicket($tenant, $admin, '100.00');
+
+        $this->postJson("/api/v1/adminapp/tenant/tickets/{$ticket->id}/refund", [
+            'refund_type' => 'partial',
+        ])
+            ->assertOk()
+            ->assertJsonPath('data.status', Ticket::STATUS_REFUNDED)
+            ->assertJsonPath('data.refunded_amount', '25.50');
+
+        $this->assertSame('25.50', $purchaseItem->fresh()->refunded_amount);
+    }
+
+    public function test_it_does_not_refund_a_ticket_when_the_requested_refund_type_is_disabled(): void
+    {
+        $tenant = $this->createTenant('ticket-refund-disabled');
+        $admin = $this->createAdminAppUser($tenant);
+        $this->grantTicketsMenu($tenant);
+        Sanctum::actingAs($admin);
+        [$ticket, $purchaseItem] = $this->createRefundableTicket($tenant, $admin, '100.00');
+
+        $this->postJson("/api/v1/adminapp/tenant/tickets/{$ticket->id}/refund", [
+            'refund_type' => 'total',
+        ])
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors('refund_type');
+
+        $this->assertNull($ticket->fresh()->refunded_at);
+        $this->assertSame('0.00', $purchaseItem->fresh()->refunded_amount);
+    }
+
+    public function test_it_validates_the_refund_type(): void
+    {
+        $tenant = $this->createTenant('ticket-refund-validation');
+        $admin = $this->createAdminAppUser($tenant);
+        $this->grantTicketsMenu($tenant);
+        Sanctum::actingAs($admin);
+        [$ticket] = $this->createRefundableTicket($tenant, $admin, '100.00');
+
+        $this->postJson("/api/v1/adminapp/tenant/tickets/{$ticket->id}/refund", [
+            'refund_type' => 'invalid',
+        ])
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors('refund_type');
+    }
+
     public function test_it_searches_by_id_and_does_not_search_by_uuid(): void
     {
         $tenant = $this->createTenant('fiesta_futbol_infantil');
@@ -659,6 +775,43 @@ class AdminAppTicketControllerTest extends TestCase
         ]);
     }
 
+    /** @return array{Ticket, PurchaseItem} */
+    private function createRefundableTicket(Tenant $tenant, User $admin, string $amount): array
+    {
+        $catalogItem = CatalogItem::query()->create([
+            'tenant_code' => $tenant->codigo,
+            'slug' => 'ticket-reembolsable-'.Str::uuid(),
+            'nombre' => 'Ticket reembolsable',
+            'precio' => $amount,
+        ]);
+        $purchase = Purchase::query()->create([
+            'tenant_codigo' => $tenant->codigo,
+            'user_id' => $admin->id,
+            'status' => Purchase::STATUS_PAID,
+            'nombre_apellido' => $admin->nombre_apellido,
+            'total' => $amount,
+        ]);
+        $purchaseItem = PurchaseItem::query()->create([
+            'compra_id' => $purchase->id,
+            'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => 'Ticket reembolsable',
+            'descripcion' => '',
+            'slug' => 'ticket-reembolsable',
+            'item_nombre' => 'Ticket reembolsable',
+            'cantidad' => 1,
+            'precio_unitario' => $amount,
+            'total' => $amount,
+        ]);
+
+        return [
+            $this->createTicket($tenant, $admin, [
+                'source_purchase_item_id' => $purchaseItem->id,
+                'source_catalog_item_id' => $catalogItem->id,
+            ]),
+            $purchaseItem,
+        ];
+    }
+
     private function grantTicketsMenu(Tenant $tenant): void
     {
         $menu = Menu::query()->create([