# Split Query & Cascading Search

Phần lõi kỹ thuật của Lead Agent nằm trong `ProductSearchEngine`. Khi nhận lệnh từ Classifier, Engine áp dụng cơ chế **tách truy vấn làm 2 lane (Split Query)** và lọc qua **7 tầng rớt mạng (Cascading Search)**.

## 1. Logic tách truy vấn (Split Query)

Thay vì ném nguyên câu hỏi dài của khách vào Database (dẫn đến tỷ lệ Zero Results rất cao), Classifier chia câu đó thành 2 luồng song song.

**Ví dụ:** Khách hỏi "Anh muốn mua áo khoác nam mùa đông, form rộng, tầm 5 triệu để đi Sapa"

### Lane 1: Literal Search (Nguyên văn)

```json
{
  "raw_text": "áo khoác nam mùa đông form rộng 5 triệu đi Sapa"
}
```

Dùng Full-text search để khớp từ khóa đặc thù mà Inferred có thể bỏ lỡ (VD: "Sapa", "bụng bia").

### Lane 2: Inferred Search (Suy luận có cấu trúc)

```json
{
  "product_line_vn": ["Áo khoác"],
  "gender_by_product": "men",
  "tags": ["wthr:mua_dong", "fit:oversize", "occ:du_lich"],
  "price_max": 5000000
}
```

Đưa từ lóng, mơ hồ về các hằng số chuẩn mực. VD: "mùa đông" thành `wthr:mua_dong`, "form rộng" thành `fit:oversize`.

### Sơ đồ Split Query

```mermaid
graph TD
    Q["Câu hỏi khách hàng"] --> L["Lane 1: Literal Search"]
    Q --> I["Lane 2: Inferred Search"]
    L --> E["ProductSearchEngine"]
    I --> E
    E --> R["Kết quả gộp + Dedup"]

    style Q fill:#1e293b,stroke:#94a3b8,color:#e2e8f0
    style L fill:#0c4a6e,stroke:#0ea5e9,color:#e0f2fe
    style I fill:#5b21b6,stroke:#8b5cf6,color:#ede9fe
    style E fill:#14532d,stroke:#22c55e,color:#dcfce7
    style R fill:#1e293b,stroke:#94a3b8,color:#e2e8f0
```

## 2. Thuật toán rớt mạng 7 tầng (Cascading Search)

Trong ngành Retail, cấm kỵ nhất là nói câu "Dạ em hết hàng". Để ép AI luôn có đồ trên tay, `ProductSearchEngine` đánh SQL qua 7 tầng nới lỏng dần dần. Nếu tầng trên tìm đủ kết quả (>=3 sản phẩm), dừng ngay và không xuống tầng dưới.

| Tầng | Tên | Hành động | Mục đích |
|---|---|---|---|
| 1 | Exact Match | Khớp 100% tags + giá + giới tính | Tìm đúng ý khách |
| 2 | NGRAM + Bitmap | Full-text search + Bitmap Index | Bắt từ khóa đặc thù |
| 3 | Drop Tags | Bỏ tags chi tiết, giữ loại SP + giá | Mở rộng tập kết quả |
| 4 | Drop Gender | Nới lỏng giới tính, bốc Unisex | Cross-sell thông minh |
| 5 | Upsell 1.5x | Nhân `price_max` lên 1.5 lần | Dụ khách rướn thêm tiền |
| 6 | Upsell 2x | Nhân `price_max` lên 2 lần | Đẩy biên lợi nhuận |
| 7 | Drop Price | Vứt luôn bộ lọc giá | Hail Mary — thà khách chê đắt còn hơn báo hết hàng |

### Sơ đồ Cascading

```mermaid
graph TD
    T1["Tầng 1: Exact Match"] -->|Thiếu kết quả| T2["Tầng 2: NGRAM + Bitmap"]
    T2 -->|Thiếu| T3["Tầng 3: Drop Tags"]
    T3 -->|Thiếu| T4["Tầng 4: Drop Gender"]
    T4 -->|Thiếu| T5["Tầng 5: Upsell 1.5x"]
    T5 -->|Thiếu| T6["Tầng 6: Upsell 2x"]
    T6 -->|Thiếu| T7["Tầng 7: Drop Price (Hail Mary)"]

    style T1 fill:#14532d,stroke:#22c55e,color:#dcfce7
    style T2 fill:#14532d,stroke:#22c55e,color:#dcfce7
    style T3 fill:#0c4a6e,stroke:#0ea5e9,color:#e0f2fe
    style T4 fill:#0c4a6e,stroke:#0ea5e9,color:#e0f2fe
    style T5 fill:#92400e,stroke:#f59e0b,color:#fef3c7
    style T6 fill:#92400e,stroke:#f59e0b,color:#fef3c7
    style T7 fill:#7f1d1d,stroke:#ef4444,color:#fecaca
```

### Chi tiết SQL từng tầng

**Tầng 1 — Exact Match:**

```sql
SELECT * FROM products
WHERE product_line IN (...)
  AND gender = '...'
  AND price <= ...
  AND BITMAP_CONTAINS(tags, ...)
LIMIT 10
```

**Tầng 2 — NGRAM + Bitmap:**

```sql
SELECT * FROM products
WHERE MATCH(description, '...')
  AND BITMAP_CONTAINS(tags, ...)
  AND price <= ...
LIMIT 10
```

**Tầng 5 — Upsell 1.5x:**

```sql
SELECT * FROM products
WHERE product_line IN (...)
  AND price <= (price_max * 1.5)
LIMIT 10
```

**Tầng 7 — Drop Price (Hail Mary):**

```sql
SELECT * FROM products
WHERE product_line IN (...)
-- Không lọc giá, không lọc gì cả
LIMIT 10
```

## 3. Làm giàu dữ liệu (Enrichment)

Sau khi tìm được sản phẩm, Tool bồi thêm 2 bước trước khi gửi cho Stylist:

| Bước | Nguồn dữ liệu | Mục đích |
|---|---|---|
| Check Stock | Canifa Stock API | Vứt sản phẩm hết hàng/hết size. Đảm bảo tư vấn là mua được |
| Outfit Context | SQLite `ai_matches` | Bơm gợi ý phối đồ cho Stylist. VD: "Áo này phối với quần khaki thanh lịch" |

File tham chiếu: `backend/agent/lead_stage_agent/product_search_engine.py`
