feat(search): implement catalog item search functionality with request validation and resource formatting

app/Domains/Catalog/Controllers/CatalogController.php

@@ -8,16 +8,19 @@ use App\Domains\Catalog\Models\FeaturedGroup;
 use App\Domains\Catalog\Models\FeaturedItem;
 use App\Domains\Catalog\Requests\CatalogItemDetailRequest;
 use App\Domains\Catalog\Requests\FeaturedGroupPageRequest;
+use App\Domains\Catalog\Requests\SearchCatalogItemsRequest;
 use App\Domains\Catalog\Requests\StoreCatalogItemRequest;
 use App\Domains\Catalog\Resources\CatalogFeaturedGroupResource;
 use App\Domains\Catalog\Resources\CatalogFeaturedItemResource;
 use App\Domains\Catalog\Resources\CatalogItemDetailResource;
 use App\Domains\Catalog\Resources\CatalogItemResource;
+use App\Domains\Catalog\Resources\CatalogSearchItemResource;
 use App\Domains\Catalog\Services\CatalogService;
 use App\Domains\Tenant\Models\Tenant;
 use App\Http\Controllers\Controller;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Pagination\LengthAwarePaginator;
 
 class CatalogController extends Controller
@@ -39,6 +42,21 @@ class CatalogController extends Controller
         ));
     }
 
+    public function search(
+        SearchCatalogItemsRequest $request,
+        Tenant $tenant,
+        CatalogService $catalogService,
+    ): AnonymousResourceCollection {
+        return CatalogSearchItemResource::collection(
+            $catalogService->search(
+                $tenant,
+                $request->validated('q'),
+                $tenant->search_items_per_page,
+                (int) $request->validated('page', 1),
+            )
+        );
+    }
+
     public function featuredGroupItems(
         FeaturedGroupPageRequest $request,
         Tenant $tenant,

app/Domains/Catalog/Requests/SearchCatalogItemsRequest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Domains\Catalog\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class SearchCatalogItemsRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /** @return array<string, list<string>> */
+    public function rules(): array
+    {
+        return [
+            'q' => ['required', 'string', 'min:2', 'max:100'],
+            'page' => ['sometimes', 'integer', 'min:1'],
+        ];
+    }
+
+    protected function prepareForValidation(): void
+    {
+        if ($this->has('q') && is_string($this->input('q'))) {
+            $this->merge(['q' => trim($this->string('q')->toString())]);
+        }
+    }
+}

app/Domains/Catalog/Resources/CatalogSearchItemResource.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Domains\Catalog\Resources;
+
+use App\Domains\Catalog\Enums\InventoryPolicy;
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Catalog\Models\Variant;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin CatalogItem */
+class CatalogSearchItemResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        $attachment = $this->attachments->first()
+            ?? $this->variants
+                ->flatMap(fn (Variant $variant) => $variant->attachments)
+                ->first();
+
+        return [
+            'id' => $this->id,
+            'type' => $this->type->value,
+            'nombre' => $this->nombre,
+            'descripcion' => $this->descripcion,
+            'precio' => $this->precio,
+            'image' => $attachment?->getTemporaryUrl(1440),
+            'stock_tecnico' => $this->availableStock(),
+            'variants' => $this->variants
+                ->map(fn (Variant $variant): array => [
+                    'id' => $variant->id,
+                    'stock_tecnico' => $this->inventory_policy === InventoryPolicy::Unlimited
+                        ? null
+                        : $variant->inventory?->availableStock(),
+                    'values' => $variant->definitions
+                        ->mapWithKeys(fn ($definition) => [
+                            $definition->itemAttribute?->attribute?->codigo => $definition->value,
+                        ])
+                        ->filter(fn ($value, $key): bool => $key !== null),
+                ])
+                ->values(),
+        ];
+    }
+}

app/Domains/Catalog/Services/CatalogService.php

@@ -10,6 +10,9 @@ use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Inventory;
 use App\Domains\Catalog\Models\ItemAttribute;
 use App\Domains\Catalog\Models\Variant;
+use App\Domains\Tenant\Models\Tenant;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
 use Illuminate\Validation\ValidationException;
@@ -158,6 +161,55 @@ class CatalogService
         return $catalogItem;
     }
 
+    /** @return LengthAwarePaginator<CatalogItem> */
+    public function search(
+        Tenant $tenant,
+        string $term,
+        int $perPage,
+        int $page,
+    ): LengthAwarePaginator {
+        $normalizedTerm = mb_strtolower($term);
+        $containsPattern = "%{$normalizedTerm}%";
+        $startsWithPattern = "{$normalizedTerm}%";
+
+        $paginator = CatalogItem::query()
+            ->where('tenant_code', $tenant->codigo)
+            ->where(function (Builder $query) use ($containsPattern): void {
+                $query
+                    ->whereRaw('LOWER(nombre) LIKE ?', [$containsPattern])
+                    ->orWhereRaw('LOWER(descripcion) LIKE ?', [$containsPattern])
+                    ->orWhereHas(
+                        'brand',
+                        fn (Builder $brandQuery) => $brandQuery
+                            ->whereRaw('LOWER(nombre) LIKE ?', [$containsPattern])
+                    )
+                    ->orWhereHas(
+                        'category',
+                        fn (Builder $categoryQuery) => $categoryQuery
+                            ->whereRaw('LOWER(nombre) LIKE ?', [$containsPattern])
+                    );
+            })
+            ->with([
+                'attachments',
+                'inventory',
+                'variants.inventory',
+                'variants.attachments',
+                'variants.definitions.itemAttribute.attribute',
+                'bundleComponents.catalogItem',
+                'bundleComponents.variant.catalogItem',
+            ])
+            ->orderByRaw(
+                'CASE WHEN LOWER(nombre) = ? THEN 0 WHEN LOWER(nombre) LIKE ? THEN 1 ELSE 2 END',
+                [$normalizedTerm, $startsWithPattern],
+            )
+            ->orderBy('nombre')
+            ->paginate(perPage: $perPage, pageName: 'page', page: $page);
+
+        return $paginator->withPath(route('catalog-items.index', [
+            'tenant' => $tenant->codigo,
+        ]));
+    }
+
     public function delete(CatalogItem $catalogItem): void
     {
         DB::transaction(function () use ($catalogItem): void {

app/Domains/Catalog/routes/api.php

@@ -7,6 +7,8 @@ Route::prefix('tenants/{tenant:codigo}')->group(function (): void {
     Route::get('catalog', [CatalogController::class, 'index']);
     Route::get('catalog/featured-groups/{featuredGroup}/items', [CatalogController::class, 'featuredGroupItems'])
         ->name('catalog.featured-groups.items.index');
+    Route::get('catalog-items', [CatalogController::class, 'search'])
+        ->name('catalog-items.index');
     Route::get('catalog-items/{catalogItem}', [CatalogController::class, 'show']);
     Route::post('catalog-items', [CatalogController::class, 'store']);
 });

app/Domains/Tenant/Models/Tenant.php

@@ -3,6 +3,8 @@
 namespace App\Domains\Tenant\Models;
 
 use App\Domains\Attachable\Models\Attachment;
+use App\Domains\Catalog\Enums\GroupLayout;
+use App\Domains\Catalog\Enums\ProductLayout;
 use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Menu\Models\Menu;
 use App\Domains\Menu\Models\TenantMenu;
@@ -27,11 +29,20 @@ use Illuminate\Database\Eloquent\Relations\HasMany;
     'footer_logo_id',
     'hero_config',
     'event_config',
+    'search_product_layout',
+    'search_group_layout',
+    'search_items_per_page',
 ])]
 class Tenant extends Model
 {
     use HasFactory;
 
+    protected $attributes = [
+        'search_product_layout' => ProductLayout::ColumnWithImage->value,
+        'search_group_layout' => GroupLayout::Paginated->value,
+        'search_items_per_page' => 12,
+    ];
+
     public function getRouteKeyName(): string
     {
         return 'codigo';
@@ -47,6 +58,9 @@ class Tenant extends Model
         return [
             'hero_config' => 'array',
             'event_config' => 'array',
+            'search_product_layout' => ProductLayout::class,
+            'search_group_layout' => GroupLayout::class,
+            'search_items_per_page' => 'integer',
         ];
     }
 

app/Domains/Tenant/Requests/StoreTenantRequest.php

@@ -2,6 +2,8 @@
 
 namespace App\Domains\Tenant\Requests;
 
+use App\Domains\Catalog\Enums\GroupLayout;
+use App\Domains\Catalog\Enums\ProductLayout;
 use App\Domains\Shared\Rules\ImageOrBase64Rule;
 use App\Domains\Tenant\Support\TenantDomainNormalizer;
 use Closure;
@@ -82,6 +84,9 @@ class StoreTenantRequest extends FormRequest
             'event_config.location' => ['nullable', 'string'],
             'event_config.dates' => ['nullable', 'array'],
             'event_config.dates.*' => ['required', 'string'],
+            'search_product_layout' => ['sometimes', Rule::enum(ProductLayout::class)],
+            'search_group_layout' => ['sometimes', Rule::enum(GroupLayout::class)],
+            'search_items_per_page' => ['sometimes', 'integer', 'min:4', 'max:48'],
         ];
     }
 }

app/Domains/Tenant/Requests/UpdateTenantRequest.php

@@ -2,6 +2,8 @@
 
 namespace App\Domains\Tenant\Requests;
 
+use App\Domains\Catalog\Enums\GroupLayout;
+use App\Domains\Catalog\Enums\ProductLayout;
 use App\Domains\Shared\Rules\ImageOrBase64Rule;
 use App\Domains\Tenant\Models\Tenant;
 use App\Domains\Tenant\Support\TenantDomainNormalizer;
@@ -93,6 +95,9 @@ class UpdateTenantRequest extends FormRequest
             'event_config.location' => ['nullable', 'string'],
             'event_config.dates' => ['nullable', 'array'],
             'event_config.dates.*' => ['required', 'string'],
+            'search_product_layout' => ['sometimes', Rule::enum(ProductLayout::class)],
+            'search_group_layout' => ['sometimes', Rule::enum(GroupLayout::class)],
+            'search_items_per_page' => ['sometimes', 'integer', 'min:4', 'max:48'],
         ];
     }
 }

app/Domains/Tenant/Resources/TenantResource.php

@@ -40,6 +40,9 @@ class TenantResource extends JsonResource
             'footer_logo' => $this->footerLogo?->getTemporaryUrl(1440),
             'hero_config' => $heroConfig,
             'event_config' => $this->event_config,
+            'search_product_layout' => $this->search_product_layout->value,
+            'search_group_layout' => $this->search_group_layout->value,
+            'search_items_per_page' => $this->search_items_per_page,
             'main_carousel_images' => $this->whenLoaded(
                 'mainCarouselImages',
                 fn () => $this->mainCarouselImages