{
    "title": "Ultra Description Pipeline",
    "description": "Tìm hiểu quy trình 2 giai đoạn (Vision + Enrichment) để tạo ra các bản mô tả sản phẩm siêu chi tiết từ hình ảnh và dữ liệu tồn kho.",
    "diagram": "diagrams/ultra-desc-pipeline.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Ultra Description là module sinh mô tả sản phẩm tự động chuẩn SEO và phục vụ RAG cho Chatbot. Khác với cách dùng 1 prompt đơn giản, hệ thống này chia thành nhiều giai đoạn (Multi-stage Pipeline) để phân tích ảnh (Vision) rồi mới dùng Text LLM để viết văn (Enrichment). Điều này giúp tránh bị \"ảo giác\" màu sắc hoặc thiết kế."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (Data Flow)",
            "type": "text",
            "content": "Quá trình sinh mô tả 1 sản phẩm tốn khoảng 5-10s, gồm các bước:<br><br><b>1. Vision Analysis:</b> Model Vision nhận link ảnh sản phẩm, bóc tách ra 28 trường dữ liệu kỹ thuật (Kiểu cổ, Loại tay, Độ dài, Chất liệu...).<br><b>2. Semantic Check:</b> Đối chiếu dữ liệu Vision với Master Data từ ERP (Ví dụ: Vision bảo màu đỏ, nhưng ERP mã màu là Xanh thì ưu tiên ERP).<br><b>3. Enrichment (Copywriting):</b> Truyền 28 trường kỹ thuật này vào Text Model (Gemini Flash-Lite hoặc Llama) để sinh ra văn phong tư vấn Stylist (Mix-match, FAQ, Dip mac...).<br><b>4. Persistance:</b> Dữ liệu được lưu vào bảng <code>ultra_descriptions</code> với trạng thái <i>Pending</i> (Chờ Admin duyệt trên UI)."
        },
        {
            "title": "3. Core Logic: Seasonal Tagging",
            "type": "text",
            "content": "Một trong những cải tiến lớn là <b>Deterministic Seasonal Tagging</b>. Thay vì để LLM tự đoán mùa (dễ sai), hệ thống mapping cứng trường <code>season</code> từ Database sang tags (Ví dụ: `Spring-Summer` -> `Mùa Hè, Thoáng mát`). LLM bị ép (Enforced) phải dùng các tags này."
        },
        {
            "title": "4. Danh sách API Quản lý Mô tả",
            "type": "api",
            "endpoints": [
                { "method": "GET", "path": "/api/product-desc/overview", "description": "Lấy tỷ lệ Coverage: Bao nhiêu SP đã có mô tả AI." },
                { "method": "POST", "path": "/api/product-desc/n8n-generate", "description": "Trigger từ n8n để sinh mô tả thô trước khi public." },
                { "method": "POST", "path": "/api/product-desc/batch-generate", "description": "Đẩy danh sách ID vào RabbitMQ/Redis Queue để xử lý ngầm." }
            ]
        },
        {
            "title": "5. Code Snippet Thực Tế (n8n API Hook)",
            "type": "code",
            "language": "python",
            "code": "from fastapi import APIRouter\nfrom schemas.product import N8nDescRequest\n\n@router.post(\"/n8n-generate\")\nasync def n8n_generate_description(req: N8nDescRequest):\n    \"\"\"Endpoint được gọi từ n8n Workflow khi có SP mới tải lên Google Sheets\"\"\"\n    # 1. Map season tags cứng\n    deterministic_tags = map_season_tags(req.season)\n    \n    # 2. Gọi AI sinh content\n    prompt = build_ultra_prompt(req.name, req.image_urls, deterministic_tags)\n    ai_response = await llm.ainvoke(prompt)\n    \n    # 3. Trả về cho n8n để nó tự động điền vào Sheets\n    return {\"status\": \"success\", \"data\": ai_response.content}"
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi Timeout khi Batch Generate:</b><br>Khi nhấn Generate cho 50 SP cùng lúc, nếu không dùng Background Task (RabbitMQ/Celery) mà bắt API chờ, thì Frontend sẽ bị 504 Gateway Timeout. Giải pháp là API chỉ trả về `job_id`, và Worker chạy ngầm.<br><br><b>🚫 Lỗi Rate Limit (429) với Gemini API:</b><br>Gemini API có giới hạn RPM (Requests Per Minute) rất gắt. Trong file <code>product-desc.js</code> và Backend phải cài đặt Retry <b>Exponential Backoff</b> với thư viện <code>tenacity</code>."
        }
    ]
}
