# Product Search Engine: Thuật toán Thác nước (Cascading Waterfall)

---

## 1. Tổng quan (The Search Philosophy)

Tại sao khách hàng tìm gì Canifa AI cũng ra kết quả? Đó là nhờ cơ chế **Cascading Search (Tìm kiếm giật cấp)**. Nếu một bộ lọc quá chặt chẽ không có hàng, hệ thống sẽ tự động nới lỏng các tiêu chí theo một thứ tự ưu tiên nghiêm ngặt để đảm bảo luôn có sản phẩm gợi ý cho khách.

---

## 2. Sơ đồ Luồng tìm kiếm 7 Tầng

![Product Search Waterfall](data/34-data_product-search-tool/product_search_waterfall.svg)

---

## 3. Chiến lược Thác nước (7-Tier Cascading)

Hệ thống sẽ thử chạy SQL theo thứ tự từ trên xuống dưới, dừng lại ngay khi tìm thấy sản phẩm:

| Tầng | Tên cơ chế | Hành động | Mục tiêu |
|:---:|---|---|---|
| **1** | **Keyword Match** | Fixed Filters + Keywords (NGRAMBF) | Tìm đúng chất liệu, họa tiết khách yêu cầu. |
| **2** | **Tag Match** | Fixed Filters + Tags (BITMAP) | Tìm đúng phong cách (thanh lịch, năng động...). |
| **3** | **Fixed Only** | Chỉ lọc theo Category + Giá + Màu | Trả về các mẫu cơ bản nhất của dòng đó. |
| **4** | **Gender Drop** | Bỏ qua bộ lọc giới tính | Hiển thị các mẫu Unisex hoặc mẫu tương đương khác giới. |
| **5-6**| **Price Relax** | Nới lỏng ngân sách (1.5x -> 2.0x) | Cho khách thấy: "Thêm một chút tiền là có hàng xịn". |
| **7** | **Extreme Drop** | Bỏ qua hoàn toàn giá | Gợi ý sản phẩm đẹp nhất bất kể giá (Phương án cuối). |

---

## 4. Cơ chế Dual-Lane Search (Làn kép)

AI không chỉ gửi một mà gửi **hai loại truy vấn** cùng lúc để Tool xử lý:

- **Lane 1: Literal (Nguyên văn)**: Giữ y hệt lời khách nói (VD: "áo 30/4"). Dùng để bắt các Keyword đặc biệt mà Filter không có.
- **Lane 2: Inferred (Suy luận)**: AI bóc tách thành các trường dữ liệu chuẩn (Color: Red, Category: T-shirt). Dùng để truy vấn Database chuyên sâu.

---

## 5. Các cơ chế Override & Guardrails (Gác cổng)

### 🩲 Underwear Override
Khi khách tìm đồ lót/sịp, Tool tự động bỏ qua bộ lọc Giới tính và Độ tuổi. 
*Lý do: Đảm bảo khách hàng nam có thể mua tặng cho nữ, hoặc người lớn xem đồ cho trẻ em mà không bị rào cản filter.*

### 📦 Real-time Stock Verification
Mỗi sản phẩm trước khi trả về đều phải đi qua **Canifa Stock API**:
- **Timeout**: 1.5 giây (đảm bảo không treo chatbot).
- **Hành động**: Chỉ những sản phẩm thực sự còn tồn kho mới được hiển thị. Tránh tình trạng khách ưng nhưng vào web lại hết hàng.

---

## 6. Làm sạch & Nén dữ liệu (Post-Processing)

- **Deduplication**: Nhóm các màu/size cùng một mã gốc (Internal Code) để danh sách kết quả không bị lặp.
- **Description Compression**: Nếu kết quả có nhiều sản phẩm, Tool sẽ tự động nén mô tả lại cực ngắn để tránh làm "tràn" ngữ cảnh của AI, giúp AI đưa ra câu trả lời nhanh hơn.
