# Troubleshooting & Gotchas

Trong quá trình vận hành luồng Product Performance & Stock Cache, hãy lưu ý các điểm sau:

## 1. Lỗi quá tải StarRocks Group Concat
- **Triệu chứng:** API `/api/products/list` trả về 500 hoặc báo lỗi mảng vượt quá kích thước.
- **Nguyên nhân:** Lệnh `GROUP_CONCAT(DISTINCT product_color_code)` có thể sinh ra chuỗi cực lớn nếu DB chưa clean.
- **Cách fix:** Đảm bảo `GROUP BY` theo `internal_ref_code` hoạt động đúng.

## 2. Timeout khi Check Stock (N8N hoặc Stock Route)
- **Triệu chứng:** API `/api/stock/check` hoặc `/api/agent/n8n/stock` báo lỗi `504 Gateway Timeout`.
- **Nguyên nhân:** Hệ thống Canifa Middleware thi thoảng quá tải. Hoặc payload `expand_only` cho ra quá nhiều mã (ví dụ query size của hàng nghìn sản phẩm cùng lúc).
- **Cách fix:** Giảm giá trị `DEFAULT_CHUNK_SIZE` trong `stock_route.py` xuống (ví dụ từ 50 xuống 20), tăng `timeout_sec`, hoặc giới hạn số lượng SKU gửi lên từ Client.

## 3. Khác biệt giữa test_db và shared_source
- **Gotcha:** Hiện tại `product_lookup` (dùng cho Lead popup) đang trỏ vào `test_db.magento_product_dimension...`, trong khi `product_route` thống kê lại trỏ vào `shared_source.magento_product...`.
- Nếu cập nhật schema, hãy lưu ý chạy đồng bộ cả hai Database này, hoặc refactor về 1 connection thống nhất.

## 4. "Sập" RAM vì Dictionary khổng lồ
- Tại `/api/product/lookup`, biến `family` thu thập các variant cho toàn bộ rows. Cần cẩn thận `limit` đầu vào `skus` để không sinh ra payload JSON nặng hàng MB, làm sập React/Vue Frontend khi Parse.
