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

tests/Feature/Ticket/ScannerTicketControllerTest.php

@@ -82,22 +82,73 @@ class ScannerTicketControllerTest extends TestCase
 
         $this->getJson('/api/v1/scanner/tickets')
             ->assertOk()
-            ->assertExactJson([
+            ->assertJsonCount(2, 'data')
-                'data' => [
+            ->assertJsonPath('data.0.id', $newer->id)
-                    [
+            ->assertJsonPath('data.0.ticket', $newer->ticket)
-                        'product' => $newer->name,
+            ->assertJsonPath('data.0.status', Ticket::STATUS_USED)
-                        'id' => $newer->id,
+            ->assertJsonPath('data.1.id', $older->id)
-                        'expires_at' => null,
+            ->assertJsonPath('meta.current_page', 1)
-                        'status' => Ticket::STATUS_USED,
+            ->assertJsonPath('meta.total', 2);
-                    ],
+    }
-                    [
+
-                        'product' => $older->name,
+    public function test_scanner_ticket_history_supports_id_search_and_pagination(): void
-                        'id' => $older->id,
+    {
-                        'expires_at' => null,
+        $matching = $this->createTicket('aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', [
-                        'status' => Ticket::STATUS_USED,
+            'used_at' => now(),
-                    ],
+            'scanner_user_id' => $this->scanner->id,
-                ],
+        ]);
-            ]);
+        $this->createTicket('bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb', [
+            'used_at' => now()->subMinute(),
+            'scanner_user_id' => $this->scanner->id,
+        ]);
+
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson('/api/v1/scanner/tickets?q=aaaaaaaa&per_page=1')
+            ->assertOk()
+            ->assertJsonCount(1, 'data')
+            ->assertJsonPath('data.0.ticket', $matching->ticket)
+            ->assertJsonPath('meta.current_page', 1)
+            ->assertJsonPath('meta.per_page', 1)
+            ->assertJsonPath('meta.total', 1);
+    }
+
+    public function test_scanner_ticket_history_can_be_searched_by_database_id(): void
+    {
+        $matching = $this->createTicket('cccccccc-cccc-4ccc-8ccc-cccccccccccc', [
+            'used_at' => now(),
+            'scanner_user_id' => $this->scanner->id,
+        ]);
+        $this->createTicket('dddddddd-dddd-4ddd-8ddd-dddddddddddd', [
+            'used_at' => now()->subMinute(),
+            'scanner_user_id' => $this->scanner->id,
+        ]);
+
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson("/api/v1/scanner/tickets?q={$matching->id}")
+            ->assertOk()
+            ->assertJsonCount(1, 'data')
+            ->assertJsonPath('data.0.id', $matching->id);
+    }
+
+    public function test_scanner_ticket_history_can_be_searched_by_used_date(): void
+    {
+        $matching = $this->createTicket('eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee', [
+            'used_at' => '2026-08-11 14:30:00',
+            'scanner_user_id' => $this->scanner->id,
+        ]);
+        $this->createTicket('ffffffff-ffff-4fff-8fff-ffffffffffff', [
+            'used_at' => '2026-08-10 14:30:00',
+            'scanner_user_id' => $this->scanner->id,
+        ]);
+
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson('/api/v1/scanner/tickets?q=11%2F08%2F26')
+            ->assertOk()
+            ->assertJsonCount(1, 'data')
+            ->assertJsonPath('data.0.id', $matching->id);
     }
 
     public function test_scanner_can_read_an_authorized_ticket_detail_by_uuid(): void