# 6. Troubleshooting & Gotchas

## Zero Results dù catalog có hàng nghìn mẫu

**Triệu chứng:** AI trả "Em tìm thấy 1 sản phẩm phù hợp" hoặc cả 7 tầng đều trống.

**Kiểm tra:**
1. Log `[SEARCH]` — xem mỗi tầng trả bao nhiêu kết quả
2. Kiểm tra `InferredSearchArgs` — tags có quá hẹp không?
3. Kiểm tra bảng StarRocks có cột BITMAP tương ứng với tag mới không?

**Sửa:** Thêm tags mới vào BITMAP index hoặc nới lỏng tags trong `ClassifierOutput`.

## Canifa Stock API timeout

**Triệu chứng:** Response chậm > 5 giây, log báo `stock_check_timeout`.

**Nguyên nhân:** Canifa API không phản hồi kịp (server load cao, mạng chậm).

**Sửa:**
- Tăng timeout từ 2s → 3s (chỉ khi cần)
- Implement cache stock: cache 5 phút, serve from cache nếu API chậm
- Fallback: Bỏ qua stock check, gửi SP mà không confirm tồn kho (kèm disclaimer)

## Trùng lặp sản phẩm giữa 2 Lane

**Triệu chứng:** Stylist nhận 6 SP nhưng thực ra chỉ có 3 SP (mỗi SP xuất hiện 2 lần từ 2 Lane).

**Nguyên nhân:** Dedup bước gộp bị lỗi hoặc không chạy.

**Sửa:** Kiểm tra hàm merge results — dedup PHẢI theo `sku` (unique key), không dedup theo `product_name` (có thể trùng tên nhưng khác SKU).

## Tags mapping sai

**Triệu chứng:** Khách hỏi "áo đi biển" nhưng AI trả về áo mùa đông.

**Nguyên nhân:** Classifier map "đi biển" → tag sai (VD: `wthr:mua_dong` thay vì `occ:di_bien`).

**Sửa:**
1. Mở `prompts.py` → `CLASSIFIER_SYSTEM_PROMPT`
2. Thêm ví dụ mapping rõ ràng cho Classifier
3. Bổ sung tag mới nếu chưa có: `occ:di_bien`

## Upsell quá aggressive (toàn show đồ đắt)

**Triệu chứng:** Khách budget 300k nhưng AI chỉ giới thiệu đồ 600k+.

**Nguyên nhân:** Tầng 1-4 không có kết quả → nhảy thẳng tầng 5-7 (Upsell).

**Sửa:**
1. Kiểm tra catalog: Có SP nào thực sự dưới 300k không? Nếu không → đúng behavior
2. Nếu có mà không tìm thấy → kiểm tra tags + BITMAP index
3. Chỉnh hệ số Upsell: 1.5x → 1.2x nếu muốn nhẹ hơn
