feat: enhance product detail retrieval to support variant selection and fallback image handling

tests/Feature/Catalog/ProductControllerTest.php

@@ -6,6 +6,7 @@ use App\Domains\Attachable\Enums\AttachmentType;
 use App\Domains\Attachable\Models\Attachment;
 use App\Domains\Catalog\Models\Attribute;
 use App\Domains\Catalog\Models\Product;
+use App\Domains\Catalog\Models\ProductAttribute;
 use App\Domains\Catalog\Models\ProductVariant;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Foundation\Testing\RefreshDatabase;
@@ -394,9 +395,8 @@ class ProductControllerTest extends TestCase
         ]);
     }
 
-    public function test_it_returns_product_detail_with_variant_mapping(): void
+    public function test_it_returns_product_detail_with_variant_mapping_and_default_selected_variant(): void
     {
-        // 1. Create a product
         $product = Product::create([
             'tenant_codigo' => $this->tenant->codigo,
             'categoria_id' => 1,
@@ -404,26 +404,17 @@ class ProductControllerTest extends TestCase
             'nombre' => 'Test Product Show',
             'precio' => 100.00,
         ]);
+        $productAttributes = $this->syncVariantAttributes($product);
 
-        // Associate attributes to product
-        $product->attributes()->sync([$this->sizeAttr->id, $this->colorAttr->id]);
-        $sizeProductAttribute = $product->productAttributes()
-            ->where('attribute_id', $this->sizeAttr->id)
-            ->firstOrFail();
-        $colorProductAttribute = $product->productAttributes()
-            ->where('attribute_id', $this->colorAttr->id)
-            ->firstOrFail();
-
-        // 2. Create variants
         $variant = $product->createVariant([
-            'stock' => 10,
+            'stock' => 0,
             'definitions' => [
                 [
-                    'products_attribute_id' => $sizeProductAttribute->id,
+                    'products_attribute_id' => $productAttributes['size']->id,
                     'value' => 'S',
                 ],
                 [
-                    'products_attribute_id' => $colorProductAttribute->id,
+                    'products_attribute_id' => $productAttributes['color']->id,
                     'value' => 'Azul',
                 ],
             ],
@@ -433,26 +424,26 @@ class ProductControllerTest extends TestCase
             'stock' => 4,
             'definitions' => [
                 [
-                    'products_attribute_id' => $sizeProductAttribute->id,
+                    'products_attribute_id' => $productAttributes['size']->id,
                     'value' => '38',
                 ],
                 [
-                    'products_attribute_id' => $colorProductAttribute->id,
+                    'products_attribute_id' => $productAttributes['color']->id,
                     'value' => 'Rojo',
                 ],
             ],
         ]);
+        $variantAttachment = $this->createAttachment('attachments/selected-variant.png');
+        $secondVariant->attachments()->attach($variantAttachment->id);
 
-        // 3. Request product show detail
         $response = $this->getJson("/api/tenants/{$this->tenant->codigo}/productos/{$product->id}");
 
         $response->assertOk();
-
-        // 4. Assert variant mapping structure and data
         $response->assertJsonStructure([
             'data' => [
                 'id',
                 'nombre',
+                'attributes',
                 'variants_map' => [
                     '*' => [
                         'variant_id',
@@ -463,14 +454,18 @@ class ProductControllerTest extends TestCase
                         ],
                     ],
                 ],
+                'variant' => [
+                    'id',
+                    'stock',
+                    'definitions',
+                    'images',
+                ],
             ],
         ]);
 
-        $response->assertJsonMissingPath('data.attributes');
         $response->assertJsonMissingPath('data.variants');
-        $response->assertJsonMissingPath('data.variant');
         $response->assertJsonPath('data.variants_map.0.variant_id', $variant->id);
-        $response->assertJsonPath('data.variants_map.0.stock', 10);
+        $response->assertJsonPath('data.variants_map.0.stock', 0);
         $response->assertJsonPath('data.variants_map.0.attributes.talle', 'S');
         $response->assertJsonPath('data.variants_map.0.attributes.color', 'Azul');
         $response->assertJsonPath('data.variants_map.1.variant_id', $secondVariant->id);
@@ -478,6 +473,133 @@ class ProductControllerTest extends TestCase
         $response->assertJsonPath('data.variants_map.1.attributes.talle', '38');
         $response->assertJsonPath('data.variants_map.1.attributes.color', 'Rojo');
         $response->assertJsonCount(2, 'data.variants_map');
+        $response->assertJsonPath('data.variant.id', $secondVariant->id);
+        $response->assertJsonPath('data.variant.stock', 4);
+        $response->assertJsonPath('data.variant.definitions.talle', '38');
+        $response->assertJsonPath('data.variant.definitions.color', 'Rojo');
+        $response->assertJsonCount(1, 'data.variant.images');
+        $this->assertStringContainsString($variantAttachment->path, $response->json('data.variant.images.0'));
+    }
+
+    public function test_it_returns_requested_variant_in_product_detail(): void
+    {
+        $product = Product::create([
+            'tenant_codigo' => $this->tenant->codigo,
+            'categoria_id' => 1,
+            'slug' => 'test-product-requested-variant',
+            'nombre' => 'Test Product Requested Variant',
+            'precio' => 100.00,
+        ]);
+        $productAttributes = $this->syncVariantAttributes($product);
+
+        $firstVariant = $product->createVariant([
+            'stock' => 5,
+            'definitions' => [
+                [
+                    'products_attribute_id' => $productAttributes['size']->id,
+                    'value' => 'S',
+                ],
+            ],
+        ]);
+        $secondVariant = $product->createVariant([
+            'stock' => 7,
+            'definitions' => [
+                [
+                    'products_attribute_id' => $productAttributes['size']->id,
+                    'value' => '38',
+                ],
+            ],
+        ]);
+
+        $response = $this->getJson("/api/tenants/{$this->tenant->codigo}/productos/{$product->id}?variant_id={$firstVariant->id}");
+
+        $response->assertOk();
+        $response->assertJsonPath('data.variant.id', $firstVariant->id);
+        $response->assertJsonPath('data.variant.stock', 5);
+        $response->assertJsonPath('data.variants_map.1.variant_id', $secondVariant->id);
+    }
+
+    public function test_it_rejects_product_detail_variant_id_from_another_product(): void
+    {
+        $product = Product::create([
+            'tenant_codigo' => $this->tenant->codigo,
+            'categoria_id' => 1,
+            'slug' => 'test-product-invalid-variant',
+            'nombre' => 'Test Product Invalid Variant',
+            'precio' => 100.00,
+        ]);
+        $otherProduct = Product::create([
+            'tenant_codigo' => $this->tenant->codigo,
+            'categoria_id' => 1,
+            'slug' => 'test-product-other-variant',
+            'nombre' => 'Test Product Other Variant',
+            'precio' => 100.00,
+        ]);
+
+        $otherVariant = $otherProduct->variants()->create(['stock' => 3]);
+
+        $response = $this->getJson("/api/tenants/{$this->tenant->codigo}/productos/{$product->id}?variant_id={$otherVariant->id}");
+
+        $response->assertNotFound();
+    }
+
+    public function test_selected_variant_images_fall_back_to_product_images(): void
+    {
+        $product = Product::create([
+            'tenant_codigo' => $this->tenant->codigo,
+            'categoria_id' => 1,
+            'slug' => 'test-product-fallback-images',
+            'nombre' => 'Test Product Fallback Images',
+            'precio' => 100.00,
+        ]);
+        $productAttributes = $this->syncVariantAttributes($product);
+        $productAttachment = $this->createAttachment('attachments/product-fallback.png');
+        $product->attachments()->attach($productAttachment->id);
+
+        $variant = $product->createVariant([
+            'stock' => 6,
+            'definitions' => [
+                [
+                    'products_attribute_id' => $productAttributes['size']->id,
+                    'value' => 'S',
+                ],
+            ],
+        ]);
+
+        $response = $this->getJson("/api/tenants/{$this->tenant->codigo}/productos/{$product->id}");
+
+        $response->assertOk();
+        $response->assertJsonPath('data.variant.id', $variant->id);
+        $response->assertJsonCount(1, 'data.variant.images');
+        $this->assertStringContainsString($productAttachment->path, $response->json('data.variant.images.0'));
+    }
+
+    /**
+     * @return array{size: ProductAttribute, color: ProductAttribute}
+     */
+    private function syncVariantAttributes(Product $product): array
+    {
+        $product->attributes()->sync([$this->sizeAttr->id, $this->colorAttr->id]);
+
+        return [
+            'size' => $product->productAttributes()
+                ->where('attribute_id', $this->sizeAttr->id)
+                ->firstOrFail(),
+            'color' => $product->productAttributes()
+                ->where('attribute_id', $this->colorAttr->id)
+                ->firstOrFail(),
+        ];
+    }
+
+    private function createAttachment(string $path): Attachment
+    {
+        return Attachment::create([
+            'key' => (string) Str::uuid(),
+            'path' => $path,
+            'filename' => basename($path),
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
     }
 
     protected function createTenant(string $codigo, string $nombre, string $dominio): Tenant