# SKU Parsing & Search Logic Deep Dive

Hệ thống tra cứu SKU của CANIFA sử dụng phương pháp **Hybrid SQL + Python Processing** để đảm bảo khả năng tìm kiếm chính xác mã sản phẩm (SKU) và các biến thể màu sắc. Khác với việc chỉ dùng LLM, hệ thống sử dụng Pydantic Model để định tuyến LLM trích xuất `sku_code` và `master_color` (nếu có), sau đó xử lý logic dưới Python.

## Luồng hoạt động (Sequence Diagram)

```mermaid
sequenceDiagram
    actor User
    participant LLM as Agent (LLM)
    participant Tool as SKU Search Tool
    participant DB as StarRocks (DB)

    User->>LLM: "Tìm cho mình áo 6TS25S003 màu đen"
    LLM->>Tool: Gọi tool với sku_code="6TS25S003", master_color="đen"
    
    rect rgb(240, 248, 255)
        Note right of Tool: Bước 1: Tiền xử lý mã SKU
        Tool->>Tool: _parse_code_search_input()<br>Chuẩn hoá khoảng trắng, viết hoa<br>Tách base_code ("6TS25S003") & suffix (None)
    end

    rect rgb(255, 240, 245)
        Note right of Tool: Bước 2: Truy vấn SQL lấy TẤT CẢ biến thể
        Tool->>DB: Truy vấn magento_ref_code & product_color_code<br>(exact match và LIKE base_code-%)
        DB-->>Tool: Trả về danh sách variants (nhiều màu/size)
    end

    rect rgb(240, 255, 240)
        Note right of Tool: Bước 3: Lọc màu bằng Python
        Tool->>Tool: _format_products()<br>Gộp các size, tính % giảm giá
        Tool->>Tool: Tìm master_color="đen" trong color/color_name
        alt Có màu yêu cầu
            Tool-->>LLM: Trả về thông tin variant màu đen
        else Không có màu yêu cầu
            Tool-->>LLM: color_exception (Trả về toàn bộ màu hiện có để AI gợi ý)
        end
    end

    LLM-->>User: Trả lời kết quả chi tiết & chính xác
```

## Các kỹ thuật xử lý chính

### 1. Phân tách SKU và Suffix
Hàm `_parse_code_search_input` sẽ tự động tách mã sản phẩm và phần đuôi (nếu khách hàng cung cấp).
Ví dụ: `6OT24S001-SG055`
- `internal_ref_code` (base code): `6OT24S001`
- `suffix_code`: `SG055`

### 2. Truy vấn SQL gom biến thể
Truy vấn không lọc trực tiếp màu trong SQL. Thay vào đó, nó gom toàn bộ các biến thể của sản phẩm:
```sql
SELECT ... FROM magento_product_dimension_with_text_embedding
WHERE UPPER(magento_ref_code) = %s
   OR UPPER(magento_ref_code) = %s
   OR UPPER(product_color_code) = %s
   OR UPPER(product_color_code) LIKE %s
```
Điều này giúp hệ thống luôn nhận biết được các màu hiện có (`available_colors`) dù người dùng tìm một màu không tồn tại.

### 3. Xử lý ngoại lệ màu sắc (Color Exception)
Đây là tính năng quan trọng để tăng UX. Nếu khách hỏi "mã X có màu đen không?" nhưng mã đó chỉ có màu trắng và xanh, Tool sẽ chủ động phát hiện (match `master_color` bị false) và trả về `color_exception`. Từ đó, LLM biết chính xác lý do không tìm thấy màu để xin lỗi và gợi ý các màu khả dụng thay vì chỉ trả lời cứng nhắc "Không tìm thấy".
