feat(catalog): track variant replacements

app/Domains/Catalog/Models/Inventory.php

@@ -42,10 +42,10 @@ class Inventory extends Model
         return $this->hasOne(CatalogItem::class);
     }
 
-    /** @return HasOne<Variant, $this> */
-    public function variant(): HasOne
+    /** @return HasMany<Variant, $this> */
+    public function variants(): HasMany
     {
-        return $this->hasOne(Variant::class);
+        return $this->hasMany(Variant::class);
     }
 
     /** @return HasMany<StockReservationLine, $this> */

app/Domains/Catalog/Models/Variant.php

@@ -20,6 +20,8 @@ use Illuminate\Support\Str;
     'catalog_item_id',
     'event_date_id',
     'inventory_id',
+    'replaced_by_variant_id',
+    'sales_disabled_at',
     'descripcion',
     'precio',
 ])]
@@ -37,6 +39,8 @@ class Variant extends Model
             'catalog_item_id' => 'integer',
             'event_date_id' => 'integer',
             'inventory_id' => 'integer',
+            'replaced_by_variant_id' => 'integer',
+            'sales_disabled_at' => 'datetime',
             'precio' => 'decimal:2',
         ];
     }
@@ -76,6 +80,24 @@ class Variant extends Model
         return $this->belongsTo(Inventory::class);
     }
 
+    /** @return BelongsTo<Variant, $this> */
+    public function replacement(): BelongsTo
+    {
+        return $this->belongsTo(self::class, 'replaced_by_variant_id');
+    }
+
+    /** @return HasMany<Variant, $this> */
+    public function replacedVariants(): HasMany
+    {
+        return $this->hasMany(self::class, 'replaced_by_variant_id');
+    }
+
+    public function isSellable(): bool
+    {
+        return $this->sales_disabled_at === null
+            && $this->replaced_by_variant_id === null;
+    }
+
     /** @return HasMany<VariantDefinition, $this> */
     public function definitions(): HasMany
     {

database/migrations/2026_09_14_030000_add_variant_replacement_state.php

@@ -0,0 +1,86 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $requiresForeignKeyRecreation = in_array(DB::getDriverName(), ['mysql', 'mariadb'], true);
+
+        Schema::table('variantes', function (Blueprint $table) use ($requiresForeignKeyRecreation): void {
+            if ($requiresForeignKeyRecreation) {
+                $table->dropForeign(['inventory_id']);
+            }
+
+            $table->dropUnique('variantes_inventory_id_unique');
+            $table->index('inventory_id');
+
+            if ($requiresForeignKeyRecreation) {
+                $table->foreign('inventory_id')->references('id')->on('inventories')->restrictOnDelete();
+            }
+
+            $table->foreignId('replaced_by_variant_id')
+                ->nullable()
+                ->after('inventory_id')
+                ->constrained('variantes')
+                ->nullOnDelete();
+            $table->timestamp('sales_disabled_at')
+                ->nullable()
+                ->after('replaced_by_variant_id');
+            $table->index(
+                ['sales_disabled_at', 'replaced_by_variant_id'],
+                'variants_sellable_index',
+            );
+        });
+    }
+
+    public function down(): void
+    {
+        $requiresForeignKeyRecreation = in_array(DB::getDriverName(), ['mysql', 'mariadb'], true);
+
+        DB::table('variantes')
+            ->orderBy('id')
+            ->get()
+            ->groupBy('inventory_id')
+            ->each(function ($variants): void {
+                $variants->skip(1)->each(function (object $variant): void {
+                    $inventory = DB::table('inventories')->where('id', $variant->inventory_id)->first();
+
+                    if ($inventory === null) {
+                        return;
+                    }
+
+                    $inventoryId = DB::table('inventories')->insertGetId([
+                        'sold_units' => $inventory->sold_units,
+                        'reserved_stock' => 0,
+                        'real_stock' => $inventory->real_stock,
+                    ]);
+
+                    DB::table('variantes')->where('id', $variant->id)->update([
+                        'inventory_id' => $inventoryId,
+                    ]);
+                });
+            });
+
+        Schema::table('variantes', function (Blueprint $table) use ($requiresForeignKeyRecreation): void {
+            $table->dropIndex('variants_sellable_index');
+            $table->dropConstrainedForeignId('replaced_by_variant_id');
+            $table->dropColumn('sales_disabled_at');
+
+            if ($requiresForeignKeyRecreation) {
+                $table->dropForeign(['inventory_id']);
+            }
+
+            $table->dropIndex(['inventory_id']);
+            $table->unique('inventory_id');
+
+            if ($requiresForeignKeyRecreation) {
+                $table->foreign('inventory_id')->references('id')->on('inventories')->restrictOnDelete();
+            }
+        });
+    }
+};

tests/Feature/Catalog/CatalogSchemaTest.php

@@ -200,10 +200,12 @@ class CatalogSchemaTest extends TestCase
         ]);
     }
 
-    public function test_variants_can_override_catalog_item_use_dates(): void
+    public function test_variants_support_event_dates_and_commercial_replacements(): void
     {
         $this->assertTrue(Schema::hasColumns('variantes', [
             'event_date_id',
+            'replaced_by_variant_id',
+            'sales_disabled_at',
         ]));
     }
 

tests/Unit/Catalog/CatalogModelsTest.php

@@ -309,7 +309,7 @@ class CatalogModelsTest extends TestCase
         $this->assertSame(2, $inventory->sold_units);
         $this->assertSame(7, $inventory->availableStock());
         $this->assertInstanceOf(CatalogItem::class, $inventory->catalogItem()->getRelated());
-        $this->assertInstanceOf(Variant::class, $inventory->variant()->getRelated());
+        $this->assertInstanceOf(Variant::class, $inventory->variants()->getRelated());
     }
 
     public function test_catalog_item_aggregates_variant_inventory(): void