feat(scanner): implement ticket scanning functionality with controller, service, and routes

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

@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Domains\Ticket\Controllers\Scanner;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Ticket\Resources\Scanner\ScannedTicketResource;
+use App\Domains\Ticket\Resources\TicketResource;
+use App\Domains\Ticket\Services\ScannerTicketService;
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+
+class TicketController extends Controller
+{
+    public function __construct(private readonly ScannerTicketService $ticketService) {}
+
+    public function index(Request $request): AnonymousResourceCollection
+    {
+        /** @var User $scanner */
+        $scanner = $request->user();
+
+        return ScannedTicketResource::collection(
+            $this->ticketService->scannedBy($scanner)
+        );
+    }
+
+    public function show(Request $request, string $ticketUuid): TicketResource
+    {
+        /** @var User $scanner */
+        $scanner = $request->user();
+
+        return TicketResource::make(
+            $this->ticketService->detail($scanner, $ticketUuid)
+        );
+    }
+
+    public function scan(Request $request, string $ticketUuid): TicketResource
+    {
+        /** @var User $scanner */
+        $scanner = $request->user();
+
+        return TicketResource::make(
+            $this->ticketService->scan($scanner, $ticketUuid)
+        );
+    }
+}

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

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Domains\Ticket\Resources\Scanner;
+
+use App\Domains\Ticket\Models\Ticket;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin Ticket */
+class ScannedTicketResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        return [
+            'product' => $this->name,
+            'id' => $this->id,
+            'expires_at' => $this->getEffectiveExpiresAt(),
+            'status' => $this->status,
+        ];
+    }
+}

app/Domains/Ticket/Services/ScannerTicketService.php

@@ -0,0 +1,117 @@
+<?php
+
+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\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class ScannerTicketService
+{
+    /** @return Collection<int, Ticket> */
+    public function scannedBy(User $scanner): Collection
+    {
+        return $this->baseQuery()
+            ->where('tenant_code', $scanner->tenant_codigo)
+            ->where('scanner_user_id', $scanner->getKey())
+            ->orderByDesc('used_at')
+            ->orderByDesc('id')
+            ->get();
+    }
+
+    public function detail(User $scanner, string $ticketUuid): Ticket
+    {
+        $categoryIds = $this->scannerCategoryIds($scanner);
+
+        return $this->baseQuery()
+            ->where('tenant_code', $scanner->tenant_codigo)
+            ->where('ticket', $ticketUuid)
+            ->where(function (Builder $query) use ($scanner, $categoryIds): void {
+                $query
+                    ->where('scanner_user_id', $scanner->getKey())
+                    ->orWhereHas(
+                        'sourceCatalogItem',
+                        fn (Builder $catalogItemQuery): Builder => $catalogItemQuery
+                            ->whereIn('category_id', $categoryIds)
+                    );
+            })
+            ->firstOrFail();
+    }
+
+    public function scan(User $scanner, string $ticketUuid): Ticket
+    {
+        return DB::transaction(function () use ($scanner, $ticketUuid): Ticket {
+            $ticket = $this->baseQuery()
+                ->where('tenant_code', $scanner->tenant_codigo)
+                ->where('ticket', $ticketUuid)
+                ->lockForUpdate()
+                ->firstOrFail();
+
+            if (! $this->scannerCanScan($scanner, $ticket)) {
+                throw ValidationException::withMessages([
+                    'ticket' => __('api.ticket.scanner_category_forbidden'),
+                ]);
+            }
+
+            if ($ticket->is_used) {
+                throw ValidationException::withMessages([
+                    'ticket' => __('api.ticket.already_scanned'),
+                ]);
+            }
+
+            if (! $ticket->is_valid) {
+                throw ValidationException::withMessages([
+                    'ticket' => $ticket->is_expired
+                        ? __('api.ticket.expired_for_scan')
+                        : __('api.ticket.not_valid_for_scan'),
+                ]);
+            }
+
+            $ticket->forceFill([
+                'used_at' => now(),
+                'scanner_user_id' => $scanner->getKey(),
+            ])->save();
+
+            return $ticket->refresh()->load($this->relations());
+        });
+    }
+
+    /** @return Builder<Ticket> */
+    private function baseQuery(): Builder
+    {
+        return Ticket::query()->with($this->relations());
+    }
+
+    /** @return array<int, string> */
+    private function relations(): array
+    {
+        return [
+            'validityGroups.validityTimes',
+            'sourceCatalogItem',
+            'sourceVariant.eventDate',
+            'sourceVariant.catalogItem',
+        ];
+    }
+
+    /** @return array<int, int> */
+    private function scannerCategoryIds(User $scanner): array
+    {
+        return $scanner->scanCategories()
+            ->pluck('categorias.id')
+            ->map(fn (mixed $id): int => (int) $id)
+            ->all();
+    }
+
+    private function scannerCanScan(User $scanner, Ticket $ticket): bool
+    {
+        $categoryId = $ticket->sourceCatalogItem?->category_id;
+
+        return $categoryId !== null
+            && $scanner->scanCategories()
+                ->where('categorias.id', $categoryId)
+                ->exists();
+    }
+}

app/Domains/Ticket/routes/api.php

@@ -9,3 +9,5 @@ Route::prefix('tenants/{tenant:codigo}')
         Route::get('tickets', [TicketController::class, 'index']);
         Route::post('tickets/pdf', [TicketController::class, 'downloadPdf']);
     });
+
+require __DIR__.'/scanner.php';

app/Domains/Ticket/routes/scanner.php

@@ -0,0 +1,14 @@
+<?php
+
+use App\Domains\Ticket\Controllers\Scanner\TicketController;
+use Illuminate\Support\Facades\Route;
+
+Route::prefix('v1/scanner/tickets')
+    ->middleware(['auth:sanctum', 'scanner.tenant'])
+    ->group(function (): void {
+        Route::get('/', [TicketController::class, 'index']);
+        Route::get('{ticketUuid}', [TicketController::class, 'show'])
+            ->whereUuid('ticketUuid');
+        Route::post('{ticketUuid}/scan', [TicketController::class, 'scan'])
+            ->whereUuid('ticketUuid');
+    });