product-search-scoring

When to Activate This Skill

• User says "tìm kiếm sản phẩm", "search products", "implement search"
• Task involves search algorithm or keyword matching
• Need to add scoring/ranking to search results
• Improving search relevance or performance
• Implementing Vietnamese text search with accent handling
• Adding search analytics or trending keywords

Core Architecture

3-Component System

Component 1: Text Normalization

• Remove Vietnamese accents (à, á, ả... → a)
• Convert to lowercase
• Strip special characters
• Normalize whitespace

Component 2: Keyword Processing

• Split search input into individual terms
• Filter stop words (từ, của, với, theo, etc.)
• Remove empty terms
• Maintain search index for fast lookup

Component 3: Query Building & Sorting

• Multi-field search (name, brand, type, tags)
• Multiple filter criteria (category, price, tags)
• Relevance-based sorting
• Pagination support

Cache Strategy

Implement caching to prevent repeated searches:

// Generate cache key from filters
protected function makeCacheKey(array $filters): string
{
    return 'product_filter_ids:' . md5(json_encode($filters));
}

// Cache product IDs from filter query
$cacheKey = $this->makeCacheKey($filters);
$cacheTtl = ProductCacheService::SHORT_CACHE_TTL; // e.g., 300 seconds

$allProductIds = Cache::remember($cacheKey, $cacheTtl, function () use ($filters) {
    $idQuery = Product::query()->select('products.id');
    $this->applyFilters($idQuery, $filters);
    $this->applySort($idQuery, $filters['sort']);
    return $idQuery->pluck('products.id')->all();
});

Search Index Field

Maintain a denormalized search_index column on products:

// In Product model migration or observer
$searchIndex = StringHelper::normalizeForSearch(
    implode(' ', [
        $product->name,
        $product->brand,
        $product->type,
        $product->tags->pluck('name')->join(' ')
    ])
);

$product->update(['search_index' => $searchIndex]);

Keyword Highlighting

Display found keywords highlighted in results:

public static function highlightSearchTerm(string $text, string $searchTerm): string
{
    if (empty($searchTerm)) return e($text);

    $searchTerms = self::splitSearchTerms($searchTerm);
    $highlighted = $text;

    foreach ($searchTerms as $term) {
        $pattern = '/(' . preg_quote($term, '/') . ')/i';
        $highlighted = preg_replace($pattern, 
            '<mark class="bg-yellow-200">$1</mark>', 
            $highlighted
        );
    }

    return $highlighted;
}

Common Patterns

Pattern 1: Simple Text Search

User searches "giày nike" → Find products with name containing both terms

Pattern 2: Category Filter + Search

User filters by "Tất, vớ" + searches "cotton" → Show cotton socks/stockings

Pattern 3: Brand Filter + Sort

User selects "Nike" brand + sorts by price ascending → Show Nike products cheapest first

Pattern 4: Multi-filter

User selects type + brand + tags + searches → Combine all filters with AND/OR logic

Key Principles

1. Normalize Vietnamese text - Accent removal essential for accurate matching
2. Filter stop words - Remove common Vietnamese words to improve relevance
3. Use search_index - Denormalize search field for performance
4. Cache aggressively - Cache filter results by normalized filter key
5. Multi-field search - Search across name, brand, type, tags
6. Flexible filtering - Support category, brand, price, tag filters
7. Pagination-friendly - Cache IDs, then fetch only needed records

Scoring Improvements (Advanced)

For production, consider these enhancements:

• Exact match boost: Higher score if full search term matches product name
• Field weighting: Name match worth more than tag match
• Freshness: Newer products ranked higher when relevance is equal
• Popularity: Track search term frequency for trending keywords
• User behavior: Click-through rate and sales indicate relevance

Critical Requirements

• ⚠️ Always normalize Vietnamese text (accents cause 90% of missed matches)
• ⚠️ Update search_index when product name/brand/type changes
• ⚠️ Cache search queries (major performance bottleneck)
• ✅ Support multiple filter combinations
• ✅ Handle pagination efficiently

Related Skills

• image-management: Use for product images in search results
• filament-rules: For admin panel to manage products
• database-backup: Before migrating to add search_index column

Supplementary Resources

For comprehensive implementation guide: read .claude/skills/workflows/product-search-scoring/CLAUDE.md

References

Implementation Steps: read .claude/skills/workflows/product-search-scoring/references/implementation-steps.md