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

app/Domains/Ticket/Services/AdminAppTicketService.php

@@ -9,12 +9,15 @@ use App\Domains\Ticket\Models\Ticket;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
 
 class AdminAppTicketService
 {
     private const RELATIONS = [
         ...TicketValidityResolver::RELATIONS,
         ...TicketPresentationResolver::RELATIONS,
+        'tenant',
         'user',
         'scannerUser',
         'sourceCatalogItem.category',
@@ -87,6 +90,70 @@ class AdminAppTicketService
         return $ticket->refresh()->load(self::RELATIONS);
     }
 
+    public function refund(Tenant $tenant, int $ticketId, string $refundType): Ticket
+    {
+        $this->ensureRefundIsAllowed($tenant, $refundType);
+
+        return DB::transaction(function () use ($tenant, $ticketId, $refundType): Ticket {
+            $ticket = Ticket::query()
+                ->where('tenant_code', $tenant->codigo)
+                ->lockForUpdate()
+                ->findOrFail($ticketId);
+
+            $purchaseItem = PurchaseItem::query()
+                ->lockForUpdate()
+                ->find($ticket->source_purchase_item_id);
+
+            if ($purchaseItem === null) {
+                throw ValidationException::withMessages([
+                    'ticket' => 'El ticket no tiene un ítem de compra asociado para reembolsar.',
+                ]);
+            }
+
+            $refundAmount = $this->refundAmount($purchaseItem, $tenant, $refundType);
+            $refundedAmount = round((float) $purchaseItem->refunded_amount + $refundAmount, 2);
+
+            if ($refundedAmount > (float) $purchaseItem->total) {
+                throw ValidationException::withMessages([
+                    'refund_type' => 'El importe reembolsado no puede superar el total del ítem de compra.',
+                ]);
+            }
+
+            $ticket->markAsRefunded();
+            $ticket->save();
+
+            $purchaseItem->update([
+                'refunded_amount' => number_format($refundedAmount, 2, '.', ''),
+            ]);
+
+            return $ticket->refresh()->load(self::RELATIONS);
+        });
+    }
+
+    private function ensureRefundIsAllowed(Tenant $tenant, string $refundType): void
+    {
+        $isAllowed = match ($refundType) {
+            'partial' => $tenant->allow_partial_refund(),
+            'total' => (bool) $tenant->allow_ticket_total_refund,
+        };
+
+        if (! $isAllowed) {
+            throw ValidationException::withMessages([
+                'refund_type' => 'El tipo de reembolso solicitado no está habilitado para este tenant.',
+            ]);
+        }
+    }
+
+    private function refundAmount(PurchaseItem $purchaseItem, Tenant $tenant, string $refundType): float
+    {
+        $ticketAmount = (float) $purchaseItem->precio_unitario;
+
+        return match ($refundType) {
+            'partial' => round($ticketAmount * (float) $tenant->ticket_partial_refund_percentage / 100, 2),
+            'total' => $ticketAmount,
+        };
+    }
+
     /**
      * @param  array{q?: string|null, category?: string|null, product?: string|null, type?: string|null, date?: string|null, size?: string|null, status?: string|null, page?: int, per_page?: int}  $filters
      * @return Builder<Ticket>