feat(attachments): implement AttachmentService for managing uploads and deletions, add AttachmentStorageException for error handling

app/Domains/Attachable/Exceptions/AttachmentStorageException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace App\Domains\Attachable\Exceptions;
+
+use RuntimeException;
+
+class AttachmentStorageException extends RuntimeException
+{
+}

app/Domains/Attachable/Services/AttachmentService.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Domains\Attachable\Services;
+
+use App\Domains\Attachable\Enums\AttachmentType;
+use App\Domains\Attachable\Exceptions\AttachmentStorageException;
+use App\Domains\Attachable\Models\Attachment;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Storage;
+use Throwable;
+
+class AttachmentService
+{
+    public function store(
+        Model $attachable,
+        UploadedFile $file,
+        string $path,
+        AttachmentType $type,
+    ): Attachment {
+        $this->ensureAttachableExists($attachable);
+
+        $normalizedPath = $this->normalizePath($path);
+
+        if ($normalizedPath === '') {
+            throw new AttachmentStorageException('The attachment path cannot be empty.');
+        }
+
+        $filename = basename($normalizedPath);
+
+        if ($filename === '' || $filename === '.' || $filename === DIRECTORY_SEPARATOR) {
+            throw new AttachmentStorageException('The attachment filename cannot be empty.');
+        }
+
+        $storedPath = Storage::disk('s3')->putFileAs(
+            $this->directoryFromPath($normalizedPath),
+            $file,
+            $filename,
+        );
+
+        if (! is_string($storedPath) || $storedPath === '') {
+            throw new AttachmentStorageException('No se pudo subir el archivo al disco s3.');
+        }
+
+        try {
+            /** @var Attachment $attachment */
+            $attachment = $attachable->attachments()->create([
+                'path' => $storedPath,
+                'filename' => $filename,
+                'type' => $type,
+                'mime_type' => $file->getClientMimeType() ?? $file->getMimeType() ?? 'application/octet-stream',
+                'extension' => $file->extension(),
+                'size' => $file->getSize() ?? 0,
+            ]);
+
+            return $attachment;
+        } catch (Throwable $throwable) {
+            Storage::disk('s3')->delete($storedPath);
+
+            throw $throwable;
+        }
+    }
+
+    public function delete(Attachment $attachment): void
+    {
+        $deleted = Storage::disk('s3')->delete($attachment->path);
+
+        if (! $deleted) {
+            throw new AttachmentStorageException('No se pudo eliminar el archivo del disco s3.');
+        }
+
+        $attachment->delete();
+    }
+
+    protected function ensureAttachableExists(Model $attachable): void
+    {
+        if (! $attachable->exists) {
+            throw new AttachmentStorageException('Cannot manage attachments for an unsaved model.');
+        }
+    }
+
+    protected function normalizePath(string $path): string
+    {
+        return trim($path, '/');
+    }
+
+    protected function directoryFromPath(string $path): string
+    {
+        $directory = dirname($path);
+
+        if ($directory === '.' || $directory === DIRECTORY_SEPARATOR) {
+            return '';
+        }
+
+        return trim($directory, '/');
+    }
+}

app/Domains/Tenant/Models/Tenant.php

@@ -2,6 +2,7 @@
 
 namespace App\Domains\Tenant\Models;
 
+use App\Domains\Attachable\Models\Concerns\HasAttachments;
 use App\Domains\Catalog\Models\Product;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -17,6 +18,7 @@ use LogicException;
 ])]
 class Tenant extends Model
 {
+    use HasAttachments;
     use HasFactory;
 
     /**