feat(scanner): enhance ticket scanning functionality with search and pagination support

app/Domains/Ticket/Controllers/Scanner/TicketController.php

@@ -3,6 +3,7 @@
 namespace App\Domains\Ticket\Controllers\Scanner;
 
 use App\Domains\Auth\Models\User;
+use App\Domains\Ticket\Requests\ScannerTicketIndexRequest;
 use App\Domains\Ticket\Resources\Scanner\ScannedTicketResource;
 use App\Domains\Ticket\Resources\TicketResource;
 use App\Domains\Ticket\Services\ScannerTicketService;
@@ -14,13 +15,13 @@ class TicketController extends Controller
 {
     public function __construct(private readonly ScannerTicketService $ticketService) {}
 
-    public function index(Request $request): AnonymousResourceCollection
+    public function index(ScannerTicketIndexRequest $request): AnonymousResourceCollection
     {
         /** @var User $scanner */
         $scanner = $request->user();
 
         return ScannedTicketResource::collection(
-            $this->ticketService->scannedBy($scanner)
+            $this->ticketService->scannedBy($scanner, $request->validated())
         );
     }
 

app/Domains/Ticket/Requests/ScannerTicketIndexRequest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Domains\Ticket\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class ScannerTicketIndexRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /** @return array<string, list<string>> */
+    public function rules(): array
+    {
+        return [
+            'q' => ['sometimes', 'nullable', 'string', 'max:255'],
+            'page' => ['sometimes', 'integer', 'min:1'],
+            'per_page' => ['sometimes', 'integer', 'min:1', 'max:100'],
+        ];
+    }
+}

app/Domains/Ticket/Resources/Scanner/ScannedTicketResource.php

@@ -15,6 +15,8 @@ class ScannedTicketResource extends JsonResource
         return [
             'product' => $this->name,
             'id' => $this->id,
+            'ticket' => $this->ticket,
+            'used_at' => $this->used_at,
             'expires_at' => $this->getEffectiveExpiresAt(),
             'status' => $this->status,
         ];

app/Domains/Ticket/Services/ScannerTicketService.php

@@ -5,21 +5,66 @@ namespace App\Domains\Ticket\Services;
 use App\Domains\Auth\Models\User;
 use App\Domains\Ticket\Models\Ticket;
 use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;
 
 class ScannerTicketService
 {
-    /** @return Collection<int, Ticket> */
-    public function scannedBy(User $scanner): Collection
+    /**
+     * @param  array{q?: string|null, page?: int, per_page?: int}  $filters
+     * @return LengthAwarePaginator<Ticket>
+     */
+    public function scannedBy(User $scanner, array $filters = []): LengthAwarePaginator
     {
+        $search = trim((string) ($filters['q'] ?? ''));
+
         return $this->baseQuery()
             ->where('tenant_code', $scanner->tenant_codigo)
             ->where('scanner_user_id', $scanner->getKey())
+            ->when($search !== '', function (Builder $query) use ($search): void {
+                $usedAtDate = $this->parseSearchDate($search);
+
+                $query->where(function (Builder $searchQuery) use ($search, $usedAtDate): void {
+                    $searchQuery->where('ticket', 'like', "%{$search}%");
+
+                    if (ctype_digit($search)) {
+                        $searchQuery->orWhere('id', (int) $search);
+                    }
+
+                    if ($usedAtDate !== null) {
+                        $searchQuery->orWhereDate('used_at', $usedAtDate);
+                    }
+                });
+            })
             ->orderByDesc('used_at')
             ->orderByDesc('id')
-            ->get();
+            ->paginateFromRequest()
+            ->withQueryString();
+    }
+
+    private function parseSearchDate(string $search): ?string
+    {
+        if (preg_match('/^(\d{4})-(\d{2})-(\d{2})$/', $search, $matches) === 1) {
+            [$year, $month, $day] = array_map('intval', array_slice($matches, 1));
+
+            if (checkdate($month, $day, $year)) {
+                return sprintf('%04d-%02d-%02d', $year, $month, $day);
+            }
+        }
+
+        if (preg_match('/^(\d{2})\/(\d{2})\/(\d{2}|\d{4})$/', $search, $matches) === 1) {
+            $day = (int) $matches[1];
+            $month = (int) $matches[2];
+            $year = (int) $matches[3];
+            $year = strlen($matches[3]) === 2 ? 2000 + $year : $year;
+
+            if (checkdate($month, $day, $year)) {
+                return sprintf('%04d-%02d-%02d', $year, $month, $day);
+            }
+        }
+
+        return null;
     }
 
     public function detail(User $scanner, string $ticketUuid): Ticket