feat(ticket): implement validity time management for tickets and catalog items

- Added ValidityTime model and migration to manage ticket validity periods. - Updated TicketGeneratorService to resolve and assign validity times to tickets. - Refactored ticket generation logic to remove legacy date fields and use validity time. - Introduced timezone support for tenants to handle service dates correctly. - Updated migrations to remove deprecated columns and add foreign keys for validity times. - Modified seeders and tests to accommodate new validity time structure. - Enhanced tests to validate ticket generation and validity time behavior.
2026-08-06 15:52:19 -03:00
parent 7f01adab73
commit 448ffb4102
30 changed files with 556 additions and 381 deletions
--- a/app/Domains/Catalog/Models/AttributeOption.php
+++ b/app/Domains/Catalog/Models/AttributeOption.php
@@ -2,6 +2,7 @@

 namespace App\Domains\Catalog\Models;

+use App\Domains\Ticket\Models\ValidityTime;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -9,6 +10,7 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;

 #[Fillable([
    'attribute_id',
+    'validity_time_id',
    'value',
    'label',
    'sort_order',
@@ -26,6 +28,7 @@ class AttributeOption extends Model
    protected function casts(): array
    {
        return [
+            'validity_time_id' => 'integer',
            'sort_order' => 'integer',
            'metadata' => 'array',
        ];
@@ -38,4 +41,10 @@ class AttributeOption extends Model
    {
        return $this->belongsTo(Attribute::class, 'attribute_id');
    }
+
+    /** @return BelongsTo<ValidityTime, $this> */
+    public function validityTime(): BelongsTo
+    {
+        return $this->belongsTo(ValidityTime::class);
+    }
 }
--- a/app/Domains/Catalog/Models/CatalogItem.php
+++ b/app/Domains/Catalog/Models/CatalogItem.php
@@ -10,7 +10,7 @@ use App\Domains\Catalog\Services\CatalogInventoryService;
 use App\Domains\Event\Models\Event;
 use App\Domains\Tenant\Models\Tenant;
 use App\Domains\Ticket\Models\Ticket;
-use Carbon\CarbonInterface;
+use App\Domains\Ticket\Models\ValidityTime;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -32,8 +32,7 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
    'precio',
    'inventory_policy',
    'has_tickets',
-    'maximum_use_date',
-    'minimum_use_date',
+    'validity_time_id',
 ])]
 class CatalogItem extends Model
 {
@@ -61,8 +60,7 @@ class CatalogItem extends Model
            'precio' => 'decimal:2',
            'inventory_policy' => InventoryPolicy::class,
            'has_tickets' => 'boolean',
-            'maximum_use_date' => 'datetime',
-            'minimum_use_date' => 'datetime',
+            'validity_time_id' => 'integer',
        ];
    }

@@ -120,6 +118,12 @@ class CatalogItem extends Model
        return $this->hasMany(Ticket::class, 'source_catalog_item_id');
    }

+    /** @return BelongsTo<ValidityTime, $this> */
+    public function validityTime(): BelongsTo
+    {
+        return $this->belongsTo(ValidityTime::class);
+    }
+
    /** @return BelongsToMany<Attribute, $this> */
    public function attributes(): BelongsToMany
    {
@@ -183,16 +187,6 @@ class CatalogItem extends Model
        return $this->nombre;
    }

-    public function getMinimumUseDate(): ?CarbonInterface
-    {
-        return $this->minimum_use_date;
-    }
-
-    public function getMaximumUseDate(): ?CarbonInterface
-    {
-        return $this->maximum_use_date;
-    }
-
    public function isBundle(): bool
    {
        return $this->type === CatalogItemType::Bundle;
--- a/app/Domains/Catalog/Models/Variant.php
+++ b/app/Domains/Catalog/Models/Variant.php
@@ -5,7 +5,6 @@ namespace App\Domains\Catalog\Models;
 use App\Domains\Attachable\Models\Attachment;
 use App\Domains\Event\Models\EventDate;
 use App\Domains\Ticket\Models\Ticket;
-use Carbon\CarbonInterface;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -17,8 +16,6 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
    'catalog_item_id',
    'event_date_id',
    'inventory_id',
-    'minimum_use_date',
-    'maximum_use_date',
 ])]
 class Variant extends Model
 {
@@ -34,8 +31,6 @@ class Variant extends Model
            'catalog_item_id' => 'integer',
            'event_date_id' => 'integer',
            'inventory_id' => 'integer',
-            'minimum_use_date' => 'datetime',
-            'maximum_use_date' => 'datetime',
        ];
    }

@@ -97,18 +92,4 @@ class Variant extends Model
    {
        return $this->catalogItem->nombre;
    }
-
-    public function getMinimumUseDate(): ?CarbonInterface
-    {
-        return $this->eventDate?->startsAt()
-            ?? $this->minimum_use_date
-            ?? $this->catalogItem->getMinimumUseDate();
-    }
-
-    public function getMaximumUseDate(): ?CarbonInterface
-    {
-        return $this->eventDate?->endsAt()
-            ?? $this->maximum_use_date
-            ?? $this->catalogItem->getMaximumUseDate();
-    }
 }
--- a/app/Domains/Catalog/Requests/StoreCatalogItemRequest.php
+++ b/app/Domains/Catalog/Requests/StoreCatalogItemRequest.php
@@ -69,8 +69,7 @@ class StoreCatalogItemRequest extends FormRequest
            'precio' => ['required', 'numeric', 'min:0'],
            'inventory_policy' => [Rule::prohibitedIf($isBundle), 'sometimes', Rule::enum(InventoryPolicy::class)],
            'has_tickets' => [Rule::prohibitedIf($isBundle), 'sometimes', 'boolean'],
-            'minimum_use_date' => [Rule::prohibitedIf($isBundle), 'sometimes', 'nullable', 'date'],
-            'maximum_use_date' => [Rule::prohibitedIf($isBundle), 'sometimes', 'nullable', 'date', 'after_or_equal:minimum_use_date'],
+            'validity_time_id' => [Rule::prohibitedIf($isBundle), 'sometimes', 'nullable', 'integer', Rule::exists('validity_times', 'id')],
            'real_stock' => [Rule::prohibitedIf($isBundle), 'sometimes', 'integer', 'min:0'],
            'inventory_id' => ['prohibited'],
            'reserved_stock' => ['prohibited'],
@@ -99,13 +98,6 @@ class StoreCatalogItemRequest extends FormRequest
            'variants.*.inventory_id' => ['prohibited'],
            'variants.*.reserved_stock' => ['prohibited'],
            'variants.*.sold_units' => ['prohibited'],
-            'variants.*.minimum_use_date' => ['sometimes', 'nullable', 'date'],
-            'variants.*.maximum_use_date' => [
-                'sometimes',
-                'nullable',
-                'date',
-                'after_or_equal:variants.*.minimum_use_date',
-            ],
            'variants.*.values' => ['sometimes', 'array'],
            'variants.*.values.*' => ['nullable', 'string'],
            'variants.*.images' => ['sometimes', 'array'],
--- a/app/Domains/Catalog/Resources/CatalogItemDetailResource.php
+++ b/app/Domains/Catalog/Resources/CatalogItemDetailResource.php
@@ -34,8 +34,7 @@ class CatalogItemDetailResource extends JsonResource
            'brand' => $this->brand?->nombre,
            'inventory_policy' => $this->inventory_policy?->value,
            'has_tickets' => $this->has_tickets,
-            'minimum_use_date' => $this->minimum_use_date,
-            'maximum_use_date' => $this->maximum_use_date,
+            'validity_time_id' => $this->validity_time_id,
            'attributes' => $this->itemAttributes
                ->map(fn (ItemAttribute $itemAttribute): array => $this->attributeData($itemAttribute))
                ->values(),
@@ -101,6 +100,7 @@ class CatalogItemDetailResource extends JsonResource
                    'value' => $option->value,
                    'label' => $option->label,
                    'sort_order' => $option->sort_order,
+                    'validity_time_id' => $option->validity_time_id,
                    'metadata' => $option->metadata,
                ])
                ->values(),
@@ -115,14 +115,6 @@ class CatalogItemDetailResource extends JsonResource
            'event_date_id' => $variant->event_date_id,
            'event_date' => $variant->eventDate?->date?->format('Y-m-d'),
            'stock_tecnico' => $this->variantStock($variant),
-            'minimum_use_date' => $variant->minimum_use_date,
-            'maximum_use_date' => $variant->maximum_use_date,
-            'effective_minimum_use_date' => $variant->eventDate?->startsAt()
-                ?? $variant->minimum_use_date
-                ?? $this->minimum_use_date,
-            'effective_maximum_use_date' => $variant->eventDate?->endsAt()
-                ?? $variant->maximum_use_date
-                ?? $this->maximum_use_date,
            'values' => $variant->definitions
                ->mapWithKeys(fn ($definition) => [
                    $definition->itemAttribute?->attribute?->codigo => $definition->value,
--- a/app/Domains/Catalog/Resources/CatalogItemResource.php
+++ b/app/Domains/Catalog/Resources/CatalogItemResource.php
@@ -25,8 +25,7 @@ class CatalogItemResource extends JsonResource
            'precio' => $this->precio,
            'inventory_policy' => $this->inventory_policy?->value,
            'has_tickets' => $this->has_tickets,
-            'minimum_use_date' => $this->minimum_use_date,
-            'maximum_use_date' => $this->maximum_use_date,
+            'validity_time_id' => $this->validity_time_id,
            'real_stock' => $this->whenLoaded('inventory', fn () => $this->inventory?->real_stock),
            'images' => $this->whenLoaded('attachments', fn () => $this->attachments
                ->map(fn ($attachment) => $attachment->getTemporaryUrl(1440))
@@ -37,14 +36,6 @@ class CatalogItemResource extends JsonResource
                    'event_date_id' => $variant->event_date_id,
                    'event_date' => $variant->eventDate?->date?->format('Y-m-d'),
                    'real_stock' => $variant->inventory?->real_stock,
-                    'minimum_use_date' => $variant->minimum_use_date,
-                    'maximum_use_date' => $variant->maximum_use_date,
-                    'effective_minimum_use_date' => $variant->eventDate?->startsAt()
-                        ?? $variant->minimum_use_date
-                        ?? $this->minimum_use_date,
-                    'effective_maximum_use_date' => $variant->eventDate?->endsAt()
-                        ?? $variant->maximum_use_date
-                        ?? $this->maximum_use_date,
                    'values' => $variant->definitions
                        ->mapWithKeys(fn ($definition) => [
                            $definition->itemAttribute?->attribute?->codigo => $definition->value,
--- a/app/Domains/Catalog/Services/CatalogService.php
+++ b/app/Domains/Catalog/Services/CatalogService.php
@@ -83,8 +83,6 @@ class CatalogService
                $data['inventory_id'] = null;
                $data['inventory_policy'] = null;
                $data['has_tickets'] = false;
-                $data['minimum_use_date'] = null;
-                $data['maximum_use_date'] = null;
            } elseif ($hasVariants) {
                $data['inventory_id'] = null;
            } else {
@@ -381,8 +379,7 @@ class CatalogService
            'attribute_codes',
            'variants',
            'has_tickets',
-            'minimum_use_date',
-            'maximum_use_date',
+            'validity_time_id',
        ] as $field) {
            if (array_key_exists($field, $data)) {
                throw ValidationException::withMessages([
@@ -508,13 +505,9 @@ class CatalogService
        $variant = $catalogItem->variants()->create([
            'inventory_id' => $inventory->id,
            'event_date_id' => $eventDateId,
-            'minimum_use_date' => $data['minimum_use_date'] ?? null,
-            'maximum_use_date' => $data['maximum_use_date'] ?? null,
        ]);
        $variant->setRelation('catalogItem', $catalogItem);

-        $this->validateVariantUseDates($variant, $index);
-
        foreach ($data['values'] ?? [] as $attributeCode => $value) {
            $itemAttribute = $itemAttributes[$attributeCode] ?? null;

@@ -567,24 +560,6 @@ class CatalogService
        }
    }

-    private function validateVariantUseDates(Variant $variant, int $index): void
-    {
-        $minimumUseDate = $variant->getMinimumUseDate();
-        $maximumUseDate = $variant->getMaximumUseDate();
-
-        if (
-            $minimumUseDate !== null
-            && $maximumUseDate !== null
-            && $maximumUseDate->lessThan($minimumUseDate)
-        ) {
-            throw ValidationException::withMessages([
-                "variants.{$index}.maximum_use_date" => [
-                    __('api.catalog.invalid_effective_date_range'),
-                ],
-            ]);
-        }
-    }
-
    /**
     * @param  array<string, mixed>  $data
     * @param  array<int, array<string, mixed>>  $variants
--- a/app/Domains/Tenant/Models/Tenant.php
+++ b/app/Domains/Tenant/Models/Tenant.php
@@ -21,6 +21,7 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
    'codigo',
    'nombre',
    'dominio',
+    'timezone',
    'primary_color',
    'secondary_color',
    'danger_color',
--- 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('sourceVariant.eventDate', 'sourceVariant.catalogItem')
+            ->with('validityTime', 'tenant', '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('sourceVariant.eventDate', 'sourceVariant.catalogItem')
+            ->with('validityTime', 'tenant', 'sourceVariant.eventDate', 'sourceVariant.catalogItem')
            ->orderByDesc('id')
            ->get();

--- a/app/Domains/Ticket/Enums/ValidityTimeType.php
+++ b/app/Domains/Ticket/Enums/ValidityTimeType.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Domains\Ticket\Enums;
+
+enum ValidityTimeType: string
+{
+    case ServiceDateWindow = 'service_date_window';
+    case FixedWindow = 'fixed_window';
+
+    /** @return list<string> */
+    public static function values(): array
+    {
+        return array_column(self::cases(), 'value');
+    }
+}
--- a/app/Domains/Ticket/Exceptions/TicketGenerationException.php
+++ b/app/Domains/Ticket/Exceptions/TicketGenerationException.php
@@ -24,9 +24,9 @@ class TicketGenerationException extends RuntimeException
        return new self(__('api.ticket.disabled', ['product' => $catalogItem->id]));
    }

-    public static function maximumUseDateReached(CatalogItem $catalogItem): self
+    public static function ambiguousValidityTime(CatalogItem $catalogItem): self
    {
-        return new self(__('api.ticket.expired', ['product' => $catalogItem->id]));
+        return new self("Catalog item {$catalogItem->id} resolves more than one validity time.");
    }

    public static function variantNotFound(
--- a/app/Domains/Ticket/Models/Ticket.php
+++ b/app/Domains/Ticket/Models/Ticket.php
@@ -21,8 +21,8 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
    'source_purchase_id',
    'source_catalog_item_id',
    'source_variant_id',
-    'starts_at',
-    'expires_at',
+    'validity_time_id',
+    'service_date',
    'used_at',
    'scanner_user_id',
    'user_id',
@@ -45,8 +45,8 @@ class Ticket extends Model
            'source_catalog_item_id' => 'integer',
            'source_variant_id' => 'integer',
            'source_purchase_id' => 'integer',
-            'starts_at' => 'datetime',
-            'expires_at' => 'datetime',
+            'validity_time_id' => 'integer',
+            'service_date' => 'date',
            'used_at' => 'datetime',
            'scanner_user_id' => 'integer',
            'user_id' => 'integer',
@@ -89,6 +89,12 @@ class Ticket extends Model
        return $this->belongsTo(Variant::class, 'source_variant_id');
    }

+    /** @return BelongsTo<ValidityTime, $this> */
+    public function validityTime(): BelongsTo
+    {
+        return $this->belongsTo(ValidityTime::class);
+    }
+
    public function isValid(): bool
    {
        $now = now();
@@ -121,13 +127,17 @@ class Ticket extends Model

    public function getEffectiveStartsAt(): ?CarbonInterface
    {
-        return $this->sourceVariant?->getMinimumUseDate()
-            ?? $this->starts_at;
+        return $this->validityTime?->startsAt(
+            $this->service_date,
+            $this->tenant?->timezone ?? config('app.timezone'),
+        );
    }

    public function getEffectiveExpiresAt(): ?CarbonInterface
    {
-        return $this->sourceVariant?->getMaximumUseDate()
-            ?? $this->expires_at;
+        return $this->validityTime?->expiresAt(
+            $this->service_date,
+            $this->tenant?->timezone ?? config('app.timezone'),
+        );
    }
 }
--- a/app/Domains/Ticket/Models/ValidityTime.php
+++ b/app/Domains/Ticket/Models/ValidityTime.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace App\Domains\Ticket\Models;
+
+use App\Domains\Catalog\Models\AttributeOption;
+use App\Domains\Catalog\Models\CatalogItem;
+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\HasMany;
+
+#[Fillable([
+    'type',
+    'start_time',
+    'end_time',
+    'fixed_starts_at',
+    'fixed_expires_at',
+    'active',
+])]
+class ValidityTime extends Model
+{
+    use HasFactory;
+
+    protected function casts(): array
+    {
+        return [
+            'type' => ValidityTimeType::class,
+            'fixed_starts_at' => 'datetime',
+            'fixed_expires_at' => 'datetime',
+            'active' => 'boolean',
+        ];
+    }
+
+    /** @return HasMany<CatalogItem, $this> */
+    public function catalogItems(): HasMany
+    {
+        return $this->hasMany(CatalogItem::class);
+    }
+
+    /** @return HasMany<AttributeOption, $this> */
+    public function attributeOptions(): HasMany
+    {
+        return $this->hasMany(AttributeOption::class);
+    }
+
+    /** @return HasMany<Ticket, $this> */
+    public function tickets(): HasMany
+    {
+        return $this->hasMany(Ticket::class);
+    }
+
+    public function startsAt(?CarbonInterface $serviceDate, string $timezone): ?CarbonInterface
+    {
+        if ($this->type === ValidityTimeType::FixedWindow) {
+            return $this->fixed_starts_at;
+        }
+
+        return $this->atServiceDate($serviceDate, $this->start_time, $timezone);
+    }
+
+    public function expiresAt(?CarbonInterface $serviceDate, string $timezone): ?CarbonInterface
+    {
+        if ($this->type === ValidityTimeType::FixedWindow) {
+            return $this->fixed_expires_at;
+        }
+
+        return $this->atServiceDate($serviceDate, $this->end_time, $timezone);
+    }
+
+    private function atServiceDate(
+        ?CarbonInterface $serviceDate,
+        ?string $time,
+        string $timezone,
+    ): ?CarbonInterface {
+        if ($serviceDate === null || $time === null) {
+            return null;
+        }
+
+        return CarbonImmutable::parse(
+            $serviceDate->format('Y-m-d').' '.$time,
+            $timezone,
+        )->utc();
+    }
+}
--- a/app/Domains/Ticket/Services/TicketGeneratorService.php
+++ b/app/Domains/Ticket/Services/TicketGeneratorService.php
@@ -5,8 +5,10 @@ namespace App\Domains\Ticket\Services;
 use App\Domains\Auth\Models\User;
 use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Variant;
+use App\Domains\Ticket\Enums\ValidityTimeType;
 use App\Domains\Ticket\Exceptions\TicketGenerationException;
 use App\Domains\Ticket\Models\Ticket;
+use App\Domains\Ticket\Models\ValidityTime;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
@@ -39,7 +41,8 @@ class TicketGeneratorService
                $user,
            ): Ticket {
                $item = $target['catalog_item'];
-                $selectedItem = $target['variant'] ?? $item;
+                $variant = $target['variant'];
+                $validityTime = $this->resolveValidityTime($item, $variant);

                return Ticket::query()->create([
                    'tenant_code' => $item->tenant_code,
@@ -48,9 +51,11 @@ class TicketGeneratorService
                    'description' => (string) ($item->descripcion ?? ''),
                    'source_purchase_id' => $sourcePurchaseId,
                    'source_catalog_item_id' => $item->getKey(),
-                    'source_variant_id' => $target['variant']?->getKey(),
-                    'starts_at' => $selectedItem->getMinimumUseDate(),
-                    'expires_at' => $selectedItem->getMaximumUseDate(),
+                    'source_variant_id' => $variant?->getKey(),
+                    'validity_time_id' => $validityTime?->getKey(),
+                    'service_date' => $validityTime?->type === ValidityTimeType::ServiceDateWindow
+                        ? ($variant?->eventDate?->date ?? now($item->tenant->timezone)->toDateString())
+                        : null,
                    'used_at' => null,
                    'user_id' => $user->getKey(),
                ]);
@@ -134,12 +139,37 @@ class TicketGeneratorService
            throw TicketGenerationException::ticketsDisabled($catalogItem);
        }

-        // TODO: Reactivar esta validación cuando los pagos con productos vencidos
-        // deban rechazarse nuevamente. Se deja deshabilitada temporalmente.
-        // $selectedItem = $variant ?? $catalogItem;
-        //
-        // if ($selectedItem->getMaximumUseDate()?->lessThanOrEqualTo(now())) {
-        //     throw TicketGenerationException::maximumUseDateReached($catalogItem);
-        // }
+    }
+
+    private function resolveValidityTime(
+        CatalogItem $catalogItem,
+        ?Variant $variant,
+    ): ?ValidityTime {
+        if ($catalogItem->validity_time_id !== null) {
+            return $catalogItem->validityTime;
+        }
+
+        if ($variant === null) {
+            return null;
+        }
+
+        $variant->loadMissing('definitions.itemAttribute.attribute.options.validityTime');
+
+        $validityTimes = $variant->definitions
+            ->map(function ($definition): ?ValidityTime {
+                $option = $definition->itemAttribute?->attribute?->options
+                    ->firstWhere('value', $definition->value);
+
+                return $option?->validityTime;
+            })
+            ->filter()
+            ->unique(fn (ValidityTime $validityTime): int => $validityTime->getKey())
+            ->values();
+
+        if ($validityTimes->count() > 1) {
+            throw TicketGenerationException::ambiguousValidityTime($catalogItem);
+        }
+
+        return $validityTimes->first();
    }
 }