feat(ticket): implement ticket generation service, model, and exception handling with tests

app/Domains/Ticket/Exceptions/TicketGenerationException.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Domains\Ticket\Exceptions;
+
+use App\Domains\Catalog\Models\CatalogItem;
+use RuntimeException;
+
+class TicketGenerationException extends RuntimeException
+{
+    public static function invalidQuantity(): self
+    {
+        return new self('La cantidad de tickets a generar debe ser mayor a cero.');
+    }
+
+    public static function emptyBundle(CatalogItem $bundle): self
+    {
+        return new self("El bundle {$bundle->id} no tiene componentes.");
+    }
+
+    public static function ticketsDisabled(CatalogItem $catalogItem): self
+    {
+        return new self("El producto {$catalogItem->id} no tiene tickets habilitados.");
+    }
+
+    public static function maximumUseDateReached(CatalogItem $catalogItem): self
+    {
+        return new self("El producto {$catalogItem->id} alcanzó su fecha máxima de uso.");
+    }
+}

app/Domains/Ticket/Models/Ticket.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Domains\Ticket\Models;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Tenant\Models\Tenant;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+#[Fillable([
+    'tenant_code',
+    'ticket',
+    'name',
+    'description',
+    'starts_at',
+    'expires_at',
+    'used_at',
+    'user_id',
+])]
+class Ticket extends Model
+{
+    use HasFactory;
+
+    public $timestamps = false;
+
+    protected $appends = [
+        'is_valid',
+        'is_expired',
+        'is_used',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'starts_at' => 'datetime',
+            'expires_at' => 'datetime',
+            'used_at' => 'datetime',
+            'user_id' => 'integer',
+        ];
+    }
+
+    /** @return BelongsTo<Tenant, $this> */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class, 'tenant_code', 'codigo');
+    }
+
+    /** @return BelongsTo<User, $this> */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function isValid(): bool
+    {
+        $now = now();
+
+        return $this->used_at === null
+            && ($this->starts_at === null || $this->starts_at->lessThanOrEqualTo($now))
+            && ($this->expires_at === null || $this->expires_at->greaterThan($now));
+    }
+
+    public function getIsValidAttribute(): bool
+    {
+        return $this->isValid();
+    }
+
+    public function getIsExpiredAttribute(): bool
+    {
+        return $this->used_at === null
+            && $this->expires_at !== null
+            && $this->expires_at->lessThanOrEqualTo(now());
+    }
+
+    public function getIsUsedAttribute(): bool
+    {
+        return $this->used_at !== null;
+    }
+}

app/Domains/Ticket/Services/TicketGeneratorService.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace App\Domains\Ticket\Services;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Ticket\Exceptions\TicketGenerationException;
+use App\Domains\Ticket\Models\Ticket;
+use Carbon\CarbonInterface;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class TicketGeneratorService
+{
+    /**
+     * @return Collection<int, Ticket>
+     */
+    public function generate(CatalogItem $catalogItem, User $user, int $quantity = 1): Collection
+    {
+        if ($quantity < 1) {
+            throw TicketGenerationException::invalidQuantity();
+        }
+
+        $now = now();
+
+        return DB::transaction(function () use ($catalogItem, $user, $quantity, $now): Collection {
+            $catalogItems = $this->resolveCatalogItems($catalogItem, $quantity, $now);
+
+            return $catalogItems->map(fn (CatalogItem $item): Ticket => Ticket::query()->create([
+                'tenant_code' => $item->tenant_code,
+                'ticket' => (string) Str::uuid(),
+                'name' => $item->nombre,
+                'description' => (string) ($item->descripcion ?? ''),
+                'starts_at' => $item->minimum_use_date,
+                'expires_at' => $item->maximum_use_date,
+                'used_at' => null,
+                'user_id' => $user->getKey(),
+            ]));
+        });
+    }
+
+    /**
+     * @return Collection<int, CatalogItem>
+     */
+    private function resolveCatalogItems(
+        CatalogItem $catalogItem,
+        int $quantity,
+        CarbonInterface $now,
+    ): Collection {
+        if (! $catalogItem->isBundle()) {
+            $this->validateCatalogItem($catalogItem, $now);
+
+            return Collection::times($quantity, fn (): CatalogItem => $catalogItem);
+        }
+
+        $catalogItem->loadMissing('bundleComponents.catalogItem');
+
+        if ($catalogItem->bundleComponents->isEmpty()) {
+            throw TicketGenerationException::emptyBundle($catalogItem);
+        }
+
+        return $catalogItem->bundleComponents
+            ->flatMap(function ($component) use ($quantity, $now): Collection {
+                $componentItem = $component->catalogItem;
+                $this->validateCatalogItem($componentItem, $now);
+
+                return Collection::times(
+                    $quantity * $component->quantity,
+                    fn (): CatalogItem => $componentItem,
+                );
+            })
+            ->values();
+    }
+
+    private function validateCatalogItem(CatalogItem $catalogItem, CarbonInterface $now): void
+    {
+        if (! $catalogItem->has_tickets) {
+            throw TicketGenerationException::ticketsDisabled($catalogItem);
+        }
+
+        if ($catalogItem->maximum_use_date?->lessThanOrEqualTo($now)) {
+            throw TicketGenerationException::maximumUseDateReached($catalogItem);
+        }
+    }
+}

database/migrations/2026_07_21_000000_create_tickets_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('tickets', function (Blueprint $table): void {
+            $table->id();
+            $table->string('tenant_code');
+            $table->uuid('ticket');
+            $table->string('name');
+            $table->text('description');
+            $table->dateTime('starts_at')->nullable();
+            $table->dateTime('expires_at')->nullable();
+            $table->dateTime('used_at')->nullable();
+            $table->foreignId('user_id')->constrained()->cascadeOnUpdate()->restrictOnDelete();
+
+            $table->foreign('tenant_code')
+                ->references('codigo')
+                ->on('tenants')
+                ->cascadeOnUpdate()
+                ->restrictOnDelete();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('tickets');
+    }
+};

tests/Feature/Ticket/TicketGeneratorServiceTest.php

@@ -0,0 +1,183 @@
+<?php
+
+namespace Tests\Feature\Ticket;
+
+use App\Domains\Attachable\Enums\AttachmentType;
+use App\Domains\Attachable\Models\Attachment;
+use App\Domains\Auth\Models\User;
+use App\Domains\Catalog\Enums\CatalogItemType;
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Tenant\Models\Tenant;
+use App\Domains\Ticket\Exceptions\TicketGenerationException;
+use App\Domains\Ticket\Services\TicketGeneratorService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Str;
+use Tests\TestCase;
+
+class TicketGeneratorServiceTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private TicketGeneratorService $service;
+
+    private Tenant $tenant;
+
+    private User $user;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $this->service = app(TicketGeneratorService::class);
+        $this->tenant = $this->createTenant();
+        $this->user = User::factory()->create();
+    }
+
+    protected function tearDown(): void
+    {
+        Carbon::setTestNow();
+
+        parent::tearDown();
+    }
+
+    public function test_it_generates_tickets_from_a_standard_catalog_item(): void
+    {
+        $item = $this->createTicketableItem(
+            'single-day',
+            now()->subHour(),
+            now()->addDay(),
+        );
+
+        $tickets = $this->service->generate($item, $this->user, 2);
+
+        $this->assertCount(2, $tickets);
+        foreach ($tickets as $ticket) {
+            $this->assertTrue(Str::isUuid($ticket->ticket));
+            $this->assertSame($this->tenant->codigo, $ticket->tenant_code);
+            $this->assertSame($this->user->id, $ticket->user_id);
+            $this->assertSame($item->nombre, $ticket->name);
+            $this->assertSame($item->descripcion, $ticket->description);
+            $this->assertTrue($ticket->starts_at->equalTo($item->minimum_use_date));
+            $this->assertTrue($ticket->expires_at->equalTo($item->maximum_use_date));
+        }
+    }
+
+    public function test_it_rejects_an_item_without_tickets_enabled(): void
+    {
+        $item = $this->createTicketableItem('disabled');
+        $item->update(['has_tickets' => false]);
+
+        $this->expectException(TicketGenerationException::class);
+        $this->expectExceptionMessage('no tiene tickets habilitados');
+
+        $this->service->generate($item->fresh(), $this->user);
+    }
+
+    public function test_it_rejects_an_item_when_its_maximum_use_date_was_reached(): void
+    {
+        $item = $this->createTicketableItem('expired', maximumUseDate: now());
+
+        $this->expectException(TicketGenerationException::class);
+        $this->expectExceptionMessage('alcanzó su fecha máxima de uso');
+
+        $this->service->generate($item, $this->user);
+    }
+
+    public function test_it_generates_tickets_for_every_bundle_component_and_quantity(): void
+    {
+        $first = $this->createTicketableItem('first', maximumUseDate: now()->addDay());
+        $second = $this->createTicketableItem('second', maximumUseDate: now()->addDays(2));
+        $bundle = $this->createBundle('bundle');
+        $bundle->bundleComponents()->createMany([
+            ['component_catalog_item_id' => $first->id, 'quantity' => 2],
+            ['component_catalog_item_id' => $second->id, 'quantity' => 1],
+        ]);
+
+        $tickets = $this->service->generate($bundle, $this->user, 2);
+
+        $this->assertCount(6, $tickets);
+        $this->assertCount(4, $tickets->where('name', $first->nombre));
+        $this->assertCount(2, $tickets->where('name', $second->nombre));
+    }
+
+    public function test_bundle_generation_is_rolled_back_when_a_component_is_invalid(): void
+    {
+        $valid = $this->createTicketableItem('valid');
+        $invalid = $this->createTicketableItem('invalid');
+        $invalid->update(['has_tickets' => false]);
+        $bundle = $this->createBundle('invalid-bundle');
+        $bundle->bundleComponents()->createMany([
+            ['component_catalog_item_id' => $valid->id, 'quantity' => 1],
+            ['component_catalog_item_id' => $invalid->id, 'quantity' => 1],
+        ]);
+
+        try {
+            $this->service->generate($bundle, $this->user);
+            $this->fail('La generación debería haber fallado.');
+        } catch (TicketGenerationException) {
+            $this->assertDatabaseCount('tickets', 0);
+        }
+    }
+
+    private function createTicketableItem(
+        string $slug,
+        mixed $minimumUseDate = null,
+        mixed $maximumUseDate = null,
+    ): CatalogItem {
+        return CatalogItem::query()->create([
+            'tenant_code' => $this->tenant->codigo,
+            'slug' => $slug,
+            'nombre' => ucfirst($slug),
+            'descripcion' => "Descripción de {$slug}",
+            'precio' => 10,
+            'has_tickets' => true,
+            'minimum_use_date' => $minimumUseDate,
+            'maximum_use_date' => $maximumUseDate,
+        ]);
+    }
+
+    private function createBundle(string $slug): CatalogItem
+    {
+        return CatalogItem::query()->create([
+            'tenant_code' => $this->tenant->codigo,
+            'type' => CatalogItemType::Bundle,
+            'inventory_policy' => null,
+            'slug' => $slug,
+            'nombre' => ucfirst($slug),
+            'descripcion' => "Descripción de {$slug}",
+            'precio' => 20,
+        ]);
+    }
+
+    private function createTenant(): Tenant
+    {
+        $header = Attachment::query()->create([
+            'path' => 'test/ticket-header.png',
+            'filename' => 'header.png',
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
+        $footer = Attachment::query()->create([
+            'path' => 'test/ticket-footer.png',
+            'filename' => 'footer.png',
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
+
+        return Tenant::query()->create([
+            'codigo' => 'ticket-tenant',
+            'nombre' => 'Ticket Tenant',
+            'dominio' => 'ticket.local',
+            'primary_color' => '#000000',
+            'secondary_color' => '#000000',
+            'danger_color' => '#000000',
+            'success_color' => '#000000',
+            'header_bg_color' => '#000000',
+            'footer_bg_color' => '#000000',
+            'header_logo_id' => $header->id,
+            'footer_logo_id' => $footer->id,
+        ]);
+    }
+}

tests/Unit/Ticket/TicketTest.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace Tests\Unit\Ticket;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Tenant\Models\Tenant;
+use App\Domains\Ticket\Models\Ticket;
+use Illuminate\Support\Carbon;
+use Tests\TestCase;
+
+class TicketTest extends TestCase
+{
+    protected function tearDown(): void
+    {
+        Carbon::setTestNow();
+
+        parent::tearDown();
+    }
+
+    public function test_it_maps_its_dates_and_relations(): void
+    {
+        $ticket = new Ticket;
+        $ticket->setRawAttributes([
+            'starts_at' => '2026-07-21 10:00:00',
+            'expires_at' => '2026-07-22 10:00:00',
+            'used_at' => null,
+            'user_id' => '10',
+        ]);
+
+        $this->assertSame('tickets', $ticket->getTable());
+        $this->assertFalse($ticket->usesTimestamps());
+        $this->assertInstanceOf(Carbon::class, $ticket->starts_at);
+        $this->assertInstanceOf(Carbon::class, $ticket->expires_at);
+        $this->assertNull($ticket->used_at);
+        $this->assertSame(10, $ticket->user_id);
+        $this->assertInstanceOf(Tenant::class, $ticket->tenant()->getRelated());
+        $this->assertInstanceOf(User::class, $ticket->user()->getRelated());
+    }
+
+    public function test_unused_ticket_without_date_restrictions_is_valid(): void
+    {
+        $this->assertTrue((new Ticket)->isValid());
+    }
+
+    public function test_ticket_is_invalid_before_its_start_date(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket(['starts_at' => now()->addSecond()]);
+
+        $this->assertFalse($ticket->isValid());
+    }
+
+    public function test_ticket_is_valid_when_its_start_date_is_reached(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket(['starts_at' => now()]);
+
+        $this->assertTrue($ticket->isValid());
+    }
+
+    public function test_ticket_is_invalid_when_it_expires(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket(['expires_at' => now()]);
+
+        $this->assertFalse($ticket->isValid());
+    }
+
+    public function test_used_ticket_is_invalid(): void
+    {
+        $ticket = new Ticket(['used_at' => now()->subSecond()]);
+
+        $this->assertFalse($ticket->isValid());
+    }
+
+    public function test_it_appends_computed_status_fields(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket([
+            'starts_at' => now()->subHour(),
+            'expires_at' => now()->addHour(),
+        ]);
+
+        $attributes = $ticket->toArray();
+
+        $this->assertTrue($attributes['is_valid']);
+        $this->assertFalse($attributes['is_expired']);
+        $this->assertFalse($attributes['is_used']);
+    }
+
+    public function test_unused_ticket_is_expired_when_its_expiration_date_is_reached(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket(['expires_at' => now()]);
+
+        $this->assertFalse($ticket->is_valid);
+        $this->assertTrue($ticket->is_expired);
+        $this->assertFalse($ticket->is_used);
+    }
+
+    public function test_used_ticket_is_not_reported_as_expired(): void
+    {
+        Carbon::setTestNow('2026-07-21 10:00:00');
+        $ticket = new Ticket([
+            'expires_at' => now()->subHour(),
+            'used_at' => now()->subDay(),
+        ]);
+
+        $this->assertFalse($ticket->is_valid);
+        $this->assertFalse($ticket->is_expired);
+        $this->assertTrue($ticket->is_used);
+    }
+}