feat(ticket): implement ticket generation policies and validity time management

- Added `ticket_generation_policy` column to `catalog_items` table to manage ticket generation strategies. - Created `ticket_validity_times` table to allow multiple validity times per ticket. - Introduced `validity_time_id` column in `event_dates` table to associate event dates with validity times. - Established `ticket_validity_groups` and `ticket_validity_group_times` tables to group validity times for tickets. - Updated seeder to set default ticket generation policy for specific tenant. - Enhanced tests to cover new functionality, including ticket generation based on event dates and validity times. - Refactored ticket validity checks to accommodate multiple validity times in a group.
2026-08-11 12:29:32 -03:00
parent 2115d2384d
commit 5197862a62
41 changed files with 950 additions and 102 deletions
--- a/app/Domains/Ticket/Controllers/TicketController.php
+++ b/app/Domains/Ticket/Controllers/TicketController.php
@@ -22,7 +22,7 @@ class TicketController extends Controller
        $tickets = Ticket::query()
            ->where('tenant_code', $tenant->codigo)
            ->where('user_id', $request->user()->getKey())
-            ->with('validityTime', 'sourceVariant.eventDate', 'sourceVariant.catalogItem')
+            ->with('validityGroups.validityTimes', 'sourceVariant.eventDate', 'sourceVariant.catalogItem')
            ->orderByDesc('id')
            ->get();

@@ -36,7 +36,7 @@ class TicketController extends Controller
            ->where('tenant_code', $tenant->codigo)
            ->where('user_id', $request->user()->getKey())
            ->whereIn('id', $ticketIds)
-            ->with('validityTime', 'sourceVariant.eventDate', 'sourceVariant.catalogItem')
+            ->with('validityGroups.validityTimes', 'sourceVariant.eventDate', 'sourceVariant.catalogItem')
            ->orderByDesc('id')
            ->get();

--- a/app/Domains/Ticket/Enums/TicketGenerationPolicy.php
+++ b/app/Domains/Ticket/Enums/TicketGenerationPolicy.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Domains\Ticket\Enums;
+
+enum TicketGenerationPolicy: string
+{
+    case PerEventDate = 'per_event_date';
+    case OnePerUnit = 'one_per_unit';
+
+    /** @return list<string> */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+}
--- a/app/Domains/Ticket/Models/Ticket.php
+++ b/app/Domains/Ticket/Models/Ticket.php
@@ -9,9 +9,12 @@ use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Tenant\Models\Tenant;
 use Carbon\CarbonInterface;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Support\Collection;

 #[Fillable([
    'tenant_code',
@@ -21,7 +24,6 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
    'source_purchase_id',
    'source_catalog_item_id',
    'source_variant_id',
-    'validity_time_id',
    'used_at',
    'scanner_user_id',
    'user_id',
@@ -51,7 +53,6 @@ class Ticket extends Model
            'source_catalog_item_id' => 'integer',
            'source_variant_id' => 'integer',
            'source_purchase_id' => 'integer',
-            'validity_time_id' => 'integer',
            'used_at' => 'datetime',
            'scanner_user_id' => 'integer',
            'user_id' => 'integer',
@@ -94,18 +95,23 @@ class Ticket extends Model
        return $this->belongsTo(Variant::class, 'source_variant_id');
    }

-    /** @return BelongsTo<ValidityTime, $this> */
-    public function validityTime(): BelongsTo
+    /** @return HasMany<TicketValidityGroup, $this> */
+    public function validityGroups(): HasMany
    {
-        return $this->belongsTo(ValidityTime::class);
+        return $this->hasMany(TicketValidityGroup::class);
    }

    public function isValid(): bool
    {
-        return $this->used_at === null
-            && (
-                $this->validityTime === null
-                || $this->validityTime->isValid()
+        if ($this->used_at !== null) {
+            return false;
+        }
+
+        $validityGroups = $this->resolvedValidityGroups();
+
+        return $validityGroups->isEmpty()
+            || $validityGroups->contains(
+                fn (TicketValidityGroup $group): bool => $group->isValid()
            );
    }

@@ -116,11 +122,13 @@ class Ticket extends Model

    public function getIsExpiredAttribute(): bool
    {
-        $expiresAt = $this->getEffectiveExpiresAt();
+        $validityGroups = $this->resolvedValidityGroups();

        return $this->used_at === null
-            && $expiresAt !== null
-            && $expiresAt->lessThanOrEqualTo(now());
+            && $validityGroups->isNotEmpty()
+            && $validityGroups->every(
+                fn (TicketValidityGroup $group): bool => $group->isExpired()
+            );
    }

    public function getIsUsedAttribute(): bool
@@ -143,11 +151,50 @@ class Ticket extends Model

    public function getEffectiveStartsAt(): ?CarbonInterface
    {
-        return $this->validityTime?->startsAt();
+        return $this->resolvedValidityGroups()
+            ->map(fn (TicketValidityGroup $group): ?CarbonInterface => $group->effectiveStartsAt())
+            ->filter()
+            ->sortBy(fn (CarbonInterface $startsAt): int => $startsAt->getTimestamp())
+            ->first();
    }

    public function getEffectiveExpiresAt(): ?CarbonInterface
    {
-        return $this->validityTime?->expiresAt();
+        return $this->resolvedValidityGroups()
+            ->map(fn (TicketValidityGroup $group): ?CarbonInterface => $group->effectiveExpiresAt())
+            ->filter()
+            ->sortByDesc(fn (CarbonInterface $expiresAt): int => $expiresAt->getTimestamp())
+            ->first();
+    }
+
+    /** @return Collection<int, ValidityTime> */
+    public function allValidityTimes(): Collection
+    {
+        return $this->resolvedValidityGroups()
+            ->flatMap(fn (TicketValidityGroup $group): EloquentCollection => $group->resolvedValidityTimes())
+            ->unique(
+                fn (ValidityTime $validityTime): int => $validityTime->getKey()
+                    ?? spl_object_id($validityTime)
+            )
+            ->values();
+    }
+
+    /** @return EloquentCollection<int, TicketValidityGroup> */
+    public function resolvedValidityGroups(): EloquentCollection
+    {
+        if ($this->relationLoaded('validityGroups')) {
+            return $this->getRelation('validityGroups');
+        }
+
+        if (! $this->exists) {
+            return new EloquentCollection;
+        }
+
+        $validityGroups = $this->validityGroups()
+            ->with('validityTimes')
+            ->get();
+        $this->setRelation('validityGroups', $validityGroups);
+
+        return $validityGroups;
    }
 }
--- a/app/Domains/Ticket/Models/TicketValidityGroup.php
+++ b/app/Domains/Ticket/Models/TicketValidityGroup.php
@@ -0,0 +1,117 @@
+<?php
+
+namespace App\Domains\Ticket\Models;
+
+use App\Domains\Ticket\Enums\ValidityTimeType;
+use Carbon\CarbonInterface;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+
+#[Fillable(['ticket_id'])]
+class TicketValidityGroup extends Model
+{
+    public $timestamps = false;
+
+    /** @return BelongsTo<Ticket, $this> */
+    public function ticket(): BelongsTo
+    {
+        return $this->belongsTo(Ticket::class);
+    }
+
+    /** @return BelongsToMany<ValidityTime, $this> */
+    public function validityTimes(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            ValidityTime::class,
+            'ticket_validity_group_times',
+            'ticket_validity_group_id',
+            'validity_time_id',
+        );
+    }
+
+    public function isValid(?CarbonInterface $at = null): bool
+    {
+        $at ??= now();
+        $validityTimes = $this->resolvedValidityTimes();
+
+        return $validityTimes->isNotEmpty()
+            && $validityTimes->every(
+                fn (ValidityTime $validityTime): bool => $validityTime->isValid($at)
+            );
+    }
+
+    public function isExpired(?CarbonInterface $at = null): bool
+    {
+        $at ??= now();
+        $expiresAt = $this->effectiveExpiresAt($at);
+
+        return $expiresAt !== null && $expiresAt->lessThanOrEqualTo($at);
+    }
+
+    public function effectiveStartsAt(?CarbonInterface $at = null): ?CarbonInterface
+    {
+        $at ??= now();
+        $anchor = $this->dateAnchor() ?? $at;
+
+        return $this->resolvedValidityTimes()
+            ->map(fn (ValidityTime $validityTime): ?CarbonInterface => $validityTime->startsAt($anchor))
+            ->filter()
+            ->sortByDesc(fn (CarbonInterface $startsAt): int => $startsAt->getTimestamp())
+            ->first();
+    }
+
+    public function effectiveExpiresAt(?CarbonInterface $at = null): ?CarbonInterface
+    {
+        $at ??= now();
+        $anchor = $this->dateAnchor() ?? $at;
+
+        return $this->resolvedValidityTimes()
+            ->map(function (ValidityTime $validityTime) use ($anchor): ?CarbonInterface {
+                $startsAt = $validityTime->startsAt($anchor);
+                $expiresAt = $validityTime->expiresAt($anchor);
+
+                if (
+                    $startsAt !== null
+                    && $expiresAt !== null
+                    && $expiresAt->lessThanOrEqualTo($startsAt)
+                ) {
+                    return $expiresAt->addDay();
+                }
+
+                return $expiresAt;
+            })
+            ->filter()
+            ->sortBy(fn (CarbonInterface $expiresAt): int => $expiresAt->getTimestamp())
+            ->first();
+    }
+
+    /** @return EloquentCollection<int, ValidityTime> */
+    public function resolvedValidityTimes(): EloquentCollection
+    {
+        if ($this->relationLoaded('validityTimes')) {
+            return $this->getRelation('validityTimes');
+        }
+
+        if (! $this->exists) {
+            return new EloquentCollection;
+        }
+
+        $validityTimes = $this->validityTimes()->get();
+        $this->setRelation('validityTimes', $validityTimes);
+
+        return $validityTimes;
+    }
+
+    private function dateAnchor(): ?CarbonInterface
+    {
+        return $this->resolvedValidityTimes()
+            ->filter(fn (ValidityTime $validityTime): bool => $validityTime->type === ValidityTimeType::FixedWindow)
+            ->map(fn (ValidityTime $validityTime): ?CarbonInterface => $validityTime->fixed_starts_at)
+            ->filter()
+            ->sortByDesc(fn (CarbonInterface $startsAt): int => $startsAt->getTimestamp())
+            ->first();
+    }
+}
--- a/app/Domains/Ticket/Models/ValidityTime.php
+++ b/app/Domains/Ticket/Models/ValidityTime.php
@@ -4,13 +4,16 @@ namespace App\Domains\Ticket\Models;

 use App\Domains\Catalog\Models\AttributeOption;
 use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Event\Models\EventDate;
 use App\Domains\Ticket\Enums\ValidityTimeType;
 use Carbon\CarbonImmutable;
 use Carbon\CarbonInterface;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;

 #[Fillable([
    'type',
@@ -44,10 +47,21 @@ class ValidityTime extends Model
        return $this->hasMany(AttributeOption::class);
    }

-    /** @return HasMany<Ticket, $this> */
-    public function tickets(): HasMany
+    /** @return HasOne<EventDate, $this> */
+    public function eventDate(): HasOne
    {
-        return $this->hasMany(Ticket::class);
+        return $this->hasOne(EventDate::class);
+    }
+
+    /** @return BelongsToMany<TicketValidityGroup, $this> */
+    public function ticketValidityGroups(): BelongsToMany
+    {
+        return $this->belongsToMany(
+            TicketValidityGroup::class,
+            'ticket_validity_group_times',
+            'validity_time_id',
+            'ticket_validity_group_id',
+        );
    }

    public function startsAt(
--- a/app/Domains/Ticket/Resources/TicketResource.php
+++ b/app/Domains/Ticket/Resources/TicketResource.php
@@ -20,8 +20,10 @@ class TicketResource extends JsonResource
            'description' => $this->description,
            'source_catalog_item_id' => $this->source_catalog_item_id,
            'source_variant_id' => $this->source_variant_id,
-            'validity_time_id' => $this->validity_time_id,
-            'validity_time' => ValidityTimeResource::make($this->validityTime),
+            'validity_times' => ValidityTimeResource::collection($this->allValidityTimes()),
+            'validity_groups' => TicketValidityGroupResource::collection(
+                $this->resolvedValidityGroups()
+            ),
            'starts_at' => $this->getEffectiveStartsAt(),
            'expires_at' => $this->getEffectiveExpiresAt(),
            'used_at' => $this->used_at,
--- a/app/Domains/Ticket/Resources/TicketValidityGroupResource.php
+++ b/app/Domains/Ticket/Resources/TicketValidityGroupResource.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Domains\Ticket\Resources;
+
+use App\Domains\Ticket\Models\TicketValidityGroup;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin TicketValidityGroup */
+class TicketValidityGroupResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'validity_times' => ValidityTimeResource::collection($this->resolvedValidityTimes()),
+            'starts_at' => $this->effectiveStartsAt(),
+            'expires_at' => $this->effectiveExpiresAt(),
+            'is_valid' => $this->isValid(),
+            'is_expired' => $this->isExpired(),
+        ];
+    }
+}
--- a/app/Domains/Ticket/Services/TicketGeneratorService.php
+++ b/app/Domains/Ticket/Services/TicketGeneratorService.php
@@ -6,10 +6,12 @@ use App\Domains\Auth\Models\User;
 use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Variant;
 use App\Domains\Event\Models\EventDate;
-use App\Domains\Ticket\Enums\ValidityTimeType;
+use App\Domains\Ticket\Enums\TicketGenerationPolicy;
 use App\Domains\Ticket\Exceptions\TicketGenerationException;
 use App\Domains\Ticket\Models\Ticket;
+use App\Domains\Ticket\Models\TicketValidityGroup;
 use App\Domains\Ticket\Models\ValidityTime;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
@@ -36,25 +38,22 @@ class TicketGeneratorService
                $quantity,
                $sourceVariantId,
            );
-            $fixedValidityTimes = [];

            return $targets->map(function (array $target) use (
-                &$fixedValidityTimes,
                $sourcePurchaseId,
                $user,
            ): Ticket {
                $item = $target['catalog_item'];
                $variant = $target['variant'];
                $eventDate = $target['event_date'];
-                $validityTime = $this->resolveValidityTime($item, $variant);
-                $validityTime = $this->materializeEventDateValidityTime(
+                $validityGroups = $this->buildTicketValidityGroups(
+                    $item,
                    $variant,
                    $eventDate,
-                    $validityTime,
-                    $fixedValidityTimes,
+                    $this->resolveValidityTime($item, $variant),
                );

-                return Ticket::query()->create([
+                $ticket = Ticket::query()->create([
                    'tenant_code' => $item->tenant_code,
                    'ticket' => (string) Str::uuid(),
                    'name' => $this->ticketName($item, $variant, $eventDate),
@@ -62,10 +61,28 @@ class TicketGeneratorService
                    'source_purchase_id' => $sourcePurchaseId,
                    'source_catalog_item_id' => $item->getKey(),
                    'source_variant_id' => $variant?->getKey(),
-                    'validity_time_id' => $validityTime?->getKey(),
                    'used_at' => null,
                    'user_id' => $user->getKey(),
                ]);
+
+                $groups = $validityGroups->map(function (Collection $validityTimes) use ($ticket): TicketValidityGroup {
+                    $group = $ticket->validityGroups()->create();
+                    $group->validityTimes()->attach(
+                        $validityTimes
+                            ->map(fn (ValidityTime $validityTime): int => $validityTime->getKey())
+                            ->all()
+                    );
+                    $group->setRelation(
+                        'validityTimes',
+                        new EloquentCollection($validityTimes->all()),
+                    );
+
+                    return $group;
+                });
+
+                $ticket->setRelation('validityGroups', new EloquentCollection($groups->all()));
+
+                return $ticket;
            });
        });
    }
@@ -125,8 +142,21 @@ class TicketGeneratorService
            ]);
        }

-        $variant->loadMissing(['eventDates', 'eventDate']);
+        $variant->loadMissing(['eventDates.validityTime', 'eventDate.validityTime']);
        $selectedEventDates = $variant->selectedEventDates();
+
+        if ($catalogItem->ticket_generation_policy === TicketGenerationPolicy::OnePerUnit) {
+            $eventDate = $selectedEventDates->count() === 1
+                ? $selectedEventDates->first()
+                : null;
+
+            return Collection::times($quantity, fn (): array => [
+                'catalog_item' => $catalogItem,
+                'variant' => $variant,
+                'event_date' => $eventDate,
+            ]);
+        }
+
        $eventDates = $selectedEventDates->isEmpty()
            ? collect([null])
            : $selectedEventDates;
@@ -246,52 +276,37 @@ class TicketGeneratorService
        return $catalogItem->nombre.' ('.$properties->implode(', ').')';
    }

-    /**
-     * Convert a recurring time window into the fixed date and time purchased by
-     * the customer. Equal tickets generated together share the same snapshot.
-     *
-     * @param  array<string, ValidityTime>  $fixedValidityTimes
-     */
-    private function materializeEventDateValidityTime(
+    /** @return Collection<int, Collection<int, ValidityTime>> */
+    private function buildTicketValidityGroups(
+        CatalogItem $catalogItem,
        ?Variant $variant,
        ?EventDate $eventDate,
        ?ValidityTime $validityTime,
-        array &$fixedValidityTimes,
-    ): ?ValidityTime {
-        if (
-            $variant === null
-            || $eventDate === null
-        ) {
-            return $validityTime;
-        }
-
-        if ($validityTime !== null && $validityTime->type !== ValidityTimeType::TimeWindow) {
-            return $validityTime;
-        }
-
-        $cacheKey = $eventDate->getKey().':'.($validityTime?->getKey() ?? 'event');
-
-        if (isset($fixedValidityTimes[$cacheKey])) {
-            return $fixedValidityTimes[$cacheKey];
-        }
-
-        $startsAt = $validityTime?->startsAt($eventDate->date) ?? $eventDate->startsAt();
-        $expiresAt = $validityTime?->expiresAt($eventDate->date) ?? $eventDate->endsAt();
+    ): Collection {
+        $eventDates = collect([$eventDate]);

        if (
-            $startsAt !== null
-            && $expiresAt !== null
-            && $expiresAt->lessThanOrEqualTo($startsAt)
+            $catalogItem->ticket_generation_policy === TicketGenerationPolicy::OnePerUnit
+            && $variant !== null
        ) {
-            $expiresAt = $expiresAt->addDay();
+            $variant->loadMissing(['eventDates.validityTime', 'eventDate.validityTime']);
+            $selectedEventDates = $variant->selectedEventDates();
+
+            if ($selectedEventDates->isNotEmpty()) {
+                $eventDates = $selectedEventDates;
+            }
        }

-        return $fixedValidityTimes[$cacheKey] = ValidityTime::query()->create([
-            'type' => ValidityTimeType::FixedWindow,
-            'start_time' => null,
-            'end_time' => null,
-            'fixed_starts_at' => $startsAt,
-            'fixed_expires_at' => $expiresAt,
-        ]);
+        return $eventDates
+            ->map(function (?EventDate $date) use ($validityTime): Collection {
+                $date?->loadMissing('validityTime');
+
+                return collect([$date?->validityTime, $validityTime])
+                    ->filter()
+                    ->unique(fn (ValidityTime $time): int => $time->getKey())
+                    ->values();
+            })
+            ->filter(fn (Collection $group): bool => $group->isNotEmpty())
+            ->values();
    }
 }