# 01 — Enrich Product Cards với Ultra Description từ SQLite Local

## 📌 Idea
Khi `tag_search_tool` lấy được danh sách sản phẩm từ StarRocks, join thêm `ultra_description`
từ bảng `pg__dashboard_canifa__ultra_descriptions` trong SQLite local (`backend/123.db`)
để AI Responder có ngữ cảnh mô tả phong phú hơn, thay vì chỉ dựa vào `description_text` ngắn.

## 🗂 Codebase Scope
- **Root:** `d:\cnf\chatbot-canifa-feedback\backend`
- **Affected:**
  - `agent/tag_search_agent_v2/tag_search_tool.py` — thêm bước enrich ultra_desc
  - `agent/tag_search_agent_v2/tag_search_graph.py` — Responder nhận thêm context
- **DB:** `backend/123.db` → `pg__dashboard_canifa__ultra_descriptions`
- **Languages:** Python 3.12+
- **Size:** S

## 📊 Current State Analysis

Hiện tại `_format_products()` chỉ trả về các field từ StarRocks:
```
sku, name, price, original_price, discount, color, gender,
product_line, image, url, sizes, stock (nếu checked)
```

Bảng `pg__dashboard_canifa__ultra_descriptions` trong SQLite chứa:
- `magento_ref_code` — khớp với SKU product
- `ultra_description_text` — mô tả chi tiết do AI tạo (chất liệu, phối đồ, occasion...)
- `tags` — JSON array các tags AI đã gán
- `season` — mùa phù hợp

→ Responder hiện tại KHÔNG thấy thông tin này → câu trả lời chỉ liệt kê tên + giá, thiếu chiều sâu tư vấn.

## 🎯 Goal / Definition of Done
- `_format_products()` kèm field `ultra_desc` nếu có trong SQLite
- Field `tags_from_ultra` (list) để Responder biết sản phẩm phù hợp dịp gì
- Responder prompt nhắc dùng `ultra_desc` để viết câu tư vấn tự nhiên hơn
- Không block nếu SQLite không có data (graceful fallback)
- Thời gian thêm < 10ms (SQLite local, không có network)

## 📋 Execution Plan

### Phase 1: Thêm hàm `_enrich_with_ultra_desc()` (30 phút)
- [ ] Viết function đọc SQLite batch theo danh sách magento_ref_code
- [ ] Merge vào products dict: thêm `ultra_desc`, `ultra_tags`, `ultra_season`
- [ ] Đặt sau bước stock check, trước `_format_products()`
- [ ] Try/except graceful — lỗi SQLite không làm crash tool

### Phase 2: Cập nhật `_format_products()` (15 phút)
- [ ] Thêm field `ultra_desc` vào output item nếu có
- [ ] Thêm field `style_tags` (list) từ ultra_tags
- [ ] Giới hạn ultra_desc 200 chars để không làm JSON quá lớn

### Phase 3: Update Responder context (15 phút)
- [ ] Trong `_responder_node` → khi parse products, đọc `ultra_desc` nếu có
- [ ] Thêm vào `tool_context_parts` 1-2 câu key fact từ ultra_desc mỗi SP
- [ ] Responder prompt: "Nếu có ultra_desc, hãy dùng thông tin đó để tư vấn chi tiết hơn"

## ⚠️ Risks & Side Effects
- **JSON size tăng:** ultra_desc có thể dài → giới hạn 200 chars → OK
- **Performance:** SQLite local read batch < 5ms → negligible
- **Mismatch code:** StarRocks dùng `magento_ref_code`, SQLite cũng dùng field này → match chuẩn

## 🔧 Tools / Scripts Needed
- Không cần tool mới
- Pattern đã có sẵn: `_enrich_with_outfit()` trong `tag_search_tool.py` dùng SQLite cùng cách

## ⏱ Effort Estimate
**S** — ~1 giờ. Pattern giống `_enrich_with_outfit()` đã có, chỉ đổi table + fields.

---
_Captured: 2026-04-28 | Type: Codebase-Aware_
