Refactor attachment cropping functionality to support multiple variants

- Introduced AttachmentCrop model to manage crop variants for attachments.
- Updated Attachment model to remove direct crop fields and establish relationships with AttachmentCrop.
- Modified AttachmentService to handle storing and updating multiple crop variants (desktop and mobile).
- Adjusted validation rules to accommodate new crop structure.
- Updated database migration to create attachment_crops table and migrate existing crop data.
- Refactored tests to ensure compatibility with the new cropping structure and validate multiple crop variants.
- Enhanced documentation to reflect changes in attachment handling and cropping capabilities.

app/Domains/Tenant/Services/WebsiteExtraService.php

@@ -334,8 +334,7 @@ class WebsiteExtraService
             );
         }
 
-        $cropHorizontal = is_array($value) ? $value['crop_horizontal'] ?? null : null;
-        $cropVertical = is_array($value) ? $value['crop_vertical'] ?? null : null;
+        $crops = $this->cropVariants($value);
         $image = is_array($value) ? $value['image'] ?? null : $value;
 
         if (is_string($image) && Str::isUuid($image)) {
@@ -349,19 +348,17 @@ class WebsiteExtraService
                 ]);
             }
 
-            if (is_array($cropHorizontal) && is_array($cropVertical)) {
-                $attachment = $this->attachmentService->updateImageCrop(
+            if ($crops !== null) {
+                $attachment = $this->attachmentService->updateImageCropVariants(
                     $attachment,
-                    $cropHorizontal,
-                    $cropVertical,
+                    $crops,
                 );
             }
-        } elseif (is_array($cropHorizontal) && is_array($cropVertical)) {
-            $attachment = $this->attachmentService->storeCroppedImage(
+        } elseif ($crops !== null) {
+            $attachment = $this->attachmentService->storeCroppedImageVariants(
                 $image,
                 "tenants/{$tenant->codigo}/extras/{$definition->codigo}",
-                $cropHorizontal,
-                $cropVertical,
+                $crops,
             );
         } else {
             $attachment = $this->attachmentService->store(
@@ -386,4 +383,37 @@ class WebsiteExtraService
 
         return $attachment->id;
     }
+
+    /**
+     * Normalize the current variants payload and the original single-crop contract.
+     *
+     * @return array<string, array<string, mixed>>|null
+     */
+    private function cropVariants(mixed $value): ?array
+    {
+        if (! is_array($value)) {
+            return null;
+        }
+
+        if (isset($value['crops']) && is_array($value['crops'])) {
+            return $value['crops'];
+        }
+
+        $horizontal = $value['crop_horizontal'] ?? null;
+        $vertical = $value['crop_vertical'] ?? null;
+
+        if (! is_array($horizontal) || ! is_array($vertical)) {
+            return null;
+        }
+
+        $crop = [
+            'crop_horizontal' => $horizontal,
+            'crop_vertical' => $vertical,
+        ];
+
+        return [
+            'desktop' => $crop,
+            'mobile' => $crop,
+        ];
+    }
 }