feat(category): add banner functionality to categories with related resource and migration tests

app/Domains/Commerce/Catalog/Controllers/CatalogController.php

@@ -15,6 +15,7 @@ use App\Domains\Commerce\Catalog\Resources\CatalogFeaturedGroupResource;
 use App\Domains\Commerce\Catalog\Resources\CatalogItemDetailResource;
 use App\Domains\Commerce\Catalog\Resources\CatalogSearchItemResource;
 use App\Domains\Commerce\Catalog\Resources\CatalogVariantOptionsResource;
+use App\Domains\Commerce\Catalog\Resources\CategoryResource;
 use App\Domains\Commerce\Catalog\Services\CatalogItemAllowanceService;
 use App\Domains\Commerce\Catalog\Services\CatalogService;
 use App\Domains\Commerce\Catalog\Services\FeaturedGroupService;
@@ -78,11 +79,7 @@ class CatalogController extends Controller
         $allowances->attach($items->getCollection(), $this->userId($request));
 
         return CatalogSearchItemResource::collection($items)->additional([
-            'category' => [
+            'category' => CategoryResource::make($category)->resolve($request),
-                'id' => $category->id,
-                'nombre' => $category->nombre,
-                'categoria_id' => $category->categoria_id,
-            ],
             'layout' => $tenant->search_product_layout->value,
             'group_layout' => $tenant->search_group_layout->value,
         ]);

app/Domains/Commerce/Catalog/Models/Category.php

@@ -4,6 +4,7 @@ namespace App\Domains\Commerce\Catalog\Models;
 
 use App\Domains\Core\Auth\Models\User;
 use App\Domains\Core\Tenant\Models\Tenant;
+use App\Shared\Attachable\Models\Attachment;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -16,6 +17,8 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
     'categoria_id',
     'nombre',
     'is_enabled',
+    'banner_id',
+    'banner_enabled',
 ])]
 class Category extends Model
 {
@@ -25,6 +28,7 @@ class Category extends Model
 
     protected $attributes = [
         'is_enabled' => true,
+        'banner_enabled' => false,
     ];
 
     /**
@@ -35,6 +39,8 @@ class Category extends Model
         return [
             'categoria_id' => 'integer',
             'is_enabled' => 'boolean',
+            'banner_id' => 'integer',
+            'banner_enabled' => 'boolean',
         ];
     }
 
@@ -59,6 +65,12 @@ class Category extends Model
         return $this->belongsTo(self::class, 'categoria_id');
     }
 
+    /** @return BelongsTo<Attachment, $this> */
+    public function banner(): BelongsTo
+    {
+        return $this->belongsTo(Attachment::class, 'banner_id');
+    }
+
     /**
      * @return HasMany<Category, $this>
      */

app/Domains/Commerce/Catalog/Resources/CategoryResource.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace App\Domains\Commerce\Catalog\Resources;
+
+use App\Domains\Commerce\Catalog\Models\Category;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin Category */
+class CategoryResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'nombre' => $this->nombre,
+            'categoria_id' => $this->categoria_id,
+            'banner_url' => $this->banner_enabled
+                ? $this->banner?->getTemporaryUrl(1440)
+                : null,
+        ];
+    }
+}

database/migrations/2026_10_01_000000_add_banner_to_categorias_table.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::table('categorias', function (Blueprint $table): void {
+            $table->foreignId('banner_id')
+                ->nullable()
+                ->constrained('attachments')
+                ->nullOnDelete();
+            $table->boolean('banner_enabled')->default(false);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::table('categorias', function (Blueprint $table): void {
+            $table->dropConstrainedForeignId('banner_id');
+            $table->dropColumn('banner_enabled');
+        });
+    }
+};

tests/Feature/Catalog/CategoryDetailTest.php

@@ -8,6 +8,8 @@ use App\Domains\Commerce\Catalog\Models\CatalogItem;
 use App\Domains\Commerce\Catalog\Models\Category;
 use App\Domains\Commerce\Catalog\Models\Inventory;
 use App\Domains\Core\Tenant\Models\Tenant;
+use App\Shared\Attachable\Models\Attachment;
+use App\Shared\Storage\Services\TemporaryUrlService;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Tests\TestCase;
 
@@ -72,6 +74,39 @@ class CategoryDetailTest extends TestCase
             ->assertJsonCount(0, 'data');
     }
 
+    public function test_it_returns_the_banner_url_only_when_a_banner_exists_and_is_enabled(): void
+    {
+        $tenant = $this->createTenant('category-banner');
+        $category = $this->createCategory($tenant, 'Remeras');
+        $banner = Attachment::query()->create([
+            'path' => 'categories/banner.jpg',
+            'filename' => 'banner.jpg',
+            'type' => 'image',
+            'mime_type' => 'image/jpeg',
+            'extension' => 'jpg',
+            'size' => 100,
+        ]);
+        $this->mock(TemporaryUrlService::class, function ($mock): void {
+            $mock->shouldReceive('generate')->once()
+                ->with('categories/banner.jpg', 1440)
+                ->andReturn([
+                    'temporary_url' => 'https://example.com/banner.jpg',
+                    'temporary_url_expires_at' => now()->addDay()->toIso8601String(),
+                ]);
+        });
+        $url = "/api/tenants/{$tenant->codigo}/categories/{$category->id}";
+
+        $category->update(['banner_enabled' => true]);
+        $this->getJson($url)->assertOk()->assertJsonPath('category.banner_url', null);
+
+        $category->update(['banner_id' => $banner->id, 'banner_enabled' => false]);
+        $this->getJson($url)->assertOk()->assertJsonPath('category.banner_url', null);
+
+        $category->update(['banner_enabled' => true]);
+        $this->getJson($url)->assertOk()
+            ->assertJsonPath('category.banner_url', 'https://example.com/banner.jpg');
+    }
+
     public function test_it_includes_products_from_all_descendant_categories(): void
     {
         $tenant = $this->createTenant('category-descendants');

tests/Feature/Migrations/AddBannerToCategoriesTest.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Tests\Feature\Migrations;
+
+use App\Domains\Commerce\Catalog\Models\Category;
+use Illuminate\Database\QueryException;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Tests\TestCase;
+
+class AddBannerToCategoriesTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        Schema::create('attachments', function (Blueprint $table): void {
+            $table->id();
+        });
+        Schema::create('categorias', function (Blueprint $table): void {
+            $table->id();
+            $table->string('nombre');
+            $table->boolean('is_enabled')->default(true);
+            $table->timestamps();
+        });
+        DB::table('categorias')->insert(['nombre' => 'Existente']);
+
+        (require database_path('migrations/2026_10_01_000000_add_banner_to_categorias_table.php'))->up();
+    }
+
+    public function test_existing_categories_default_to_no_banner_and_disabled(): void
+    {
+        $category = Category::query()->firstOrFail();
+
+        $this->assertNull($category->banner_id);
+        $this->assertFalse($category->banner_enabled);
+        $this->assertNull($category->banner);
+    }
+
+    public function test_banner_can_be_assigned_and_deleting_it_preserves_the_category(): void
+    {
+        $bannerId = DB::table('attachments')->insertGetId([]);
+        $category = Category::query()->create([
+            'nombre' => 'Con banner',
+            'banner_id' => $bannerId,
+            'banner_enabled' => true,
+        ])->fresh();
+
+        $this->assertSame($bannerId, $category->banner_id);
+        $this->assertTrue($category->banner_enabled);
+        $this->assertSame($bannerId, $category->banner->id);
+
+        DB::table('attachments')->where('id', $bannerId)->delete();
+
+        $this->assertNull($category->fresh()->banner_id);
+        $this->assertDatabaseHas('categorias', ['id' => $category->id]);
+    }
+
+    public function test_banner_must_reference_an_existing_attachment(): void
+    {
+        $this->expectException(QueryException::class);
+
+        Category::query()->create(['nombre' => 'Inválida', 'banner_id' => 999]);
+    }
+
+    public function test_migration_can_be_rolled_back_without_removing_categories(): void
+    {
+        (require database_path('migrations/2026_10_01_000000_add_banner_to_categorias_table.php'))->down();
+
+        $this->assertFalse(Schema::hasColumn('categorias', 'banner_id'));
+        $this->assertFalse(Schema::hasColumn('categorias', 'banner_enabled'));
+        $this->assertDatabaseHas('categorias', ['nombre' => 'Existente']);
+    }
+}

tests/Unit/Catalog/CategoryResourceTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Tests\Unit\Catalog;
+
+use App\Domains\Commerce\Catalog\Models\Category;
+use App\Domains\Commerce\Catalog\Resources\CategoryResource;
+use App\Shared\Attachable\Models\Attachment;
+use App\Shared\Storage\Services\TemporaryUrlService;
+use Tests\TestCase;
+
+class CategoryResourceTest extends TestCase
+{
+    public function test_it_returns_the_banner_url_only_when_the_banner_exists_and_is_enabled(): void
+    {
+        $category = new Category(['nombre' => 'Remeras', 'banner_enabled' => true]);
+        $category->setRelation('banner', null);
+        $this->assertNull(CategoryResource::make($category)->resolve()['banner_url']);
+
+        $category->setRelation('banner', new Attachment(['path' => 'categories/banner.jpg']));
+        $category->banner_enabled = false;
+        $this->mock(TemporaryUrlService::class, function ($mock): void {
+            $mock->shouldReceive('generate')->once()
+                ->with('categories/banner.jpg', 1440)
+                ->andReturn([
+                    'temporary_url' => 'https://example.com/banner.jpg',
+                    'temporary_url_expires_at' => now()->addDay()->toIso8601String(),
+                ]);
+        });
+        $this->assertNull(CategoryResource::make($category)->resolve()['banner_url']);
+
+        $category->banner_enabled = true;
+        $this->assertSame(
+            'https://example.com/banner.jpg',
+            CategoryResource::make($category)->resolve()['banner_url'],
+        );
+    }
+}