{
    "title": "Chatbot Core & n8n Pipeline",
    "description": "Khám phá luồng xử lý tin nhắn của Fashion Q&A Agent, từ lúc nhận query đến khi gọi các tool n8n và trả về kết quả cho người dùng.",
    "diagram": "diagrams/chatbot-pipeline.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Chatbot Core là trái tim của hệ thống Canifa AI Stylist. Thay vì chỉ hỏi/đáp LLM thông thường, hệ thống tích hợp sâu với <b>n8n (Workflow Automation)</b> để xây dựng luồng Agentic. AI Agent có khả năng tự động hiểu ngữ cảnh, gọi các tool nội bộ (Check tồn kho, Tìm ảnh sản phẩm, Gợi ý size) và phản hồi theo đúng Persona của một Stylist."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (Data Flow)",
            "type": "text",
            "content": "Quy trình xử lý một câu hỏi của khách hàng đi qua 4 bước:<br><br><b>1. Chat Controller:</b> Tiếp nhận request từ API <code>/api/chat</code>. Kiểm tra Token, Rate Limit và Redis Cache. Nếu cache hit (câu hỏi lặp lại), trả kết quả ngay.<br><b>2. Reasoning Loop (LangGraph/ReAct):</b> Agent bắt đầu vòng lặp suy nghĩ (Thought -> Action -> Observation). Tại bước Action, nó quyết định cần sử dụng công cụ (Tool) nào để giải quyết vấn đề.<br><b>3. Tool Execution (n8n API):</b> Nếu cần dữ liệu, Agent gọi các REST API chuyên dụng do n8n cung cấp (ví dụ: lấy list sản phẩm, check size thực tế).<br><b>4. Response Synthesis:</b> Sau khi gom đủ Observation từ các Tools, LLM tổng hợp lại thành một câu tư vấn hoàn chỉnh, tự nhiên và gán kèm ảnh sản phẩm."
        },
        {
            "title": "3. Core Logic: Guardrails & Prompt Injection",
            "type": "text",
            "content": "Để ngăn chặn các rủi ro bảo mật (như Prompt Injection) hoặc AI bị ảo giác (Hallucination), hệ thống áp dụng các <b>Guardrails</b> khắt khe:<br>- <b>Product Verification:</b> AI không được phép tự bịa ra sản phẩm. Nếu n8n tool trả về rỗng, AI phải báo hết hàng.<br>- <b>Demographic Neutrality:</b> Không thiên vị giới tính, không phán xét dáng người."
        },
        {
            "title": "4. Danh sách API n8n Tools",
            "type": "api",
            "endpoints": [
                { "method": "GET", "path": "/api/agent/n8n/products", "description": "Tìm kiếm sản phẩm theo semantic search hoặc keywords." },
                { "method": "GET", "path": "/api/agent/n8n/stock", "description": "Kiểm tra tồn kho realtime của mã SKU." },
                { "method": "GET", "path": "/api/agent/n8n/stores", "description": "Tìm kiếm danh sách cửa hàng còn hàng theo khu vực." },
                { "method": "GET", "path": "/api/agent/n8n/knowledge", "description": "Tra cứu RAG (Chính sách đổi trả, bảng size...)." }
            ]
        },
        {
            "title": "5. Code Snippet Thực Tế (LangGraph State)",
            "type": "code",
            "language": "python",
            "code": "from typing import TypedDict, Annotated, Sequence\nfrom langchain_core.messages import BaseMessage\nimport operator\n\nclass AgentState(TypedDict):\n    # Lưu trữ lịch sử hội thoại\n    messages: Annotated[Sequence[BaseMessage], operator.add]\n    # Lưu thông tin context user (user_id, intent)\n    user_context: dict\n    # Trạng thái các tool đã gọi\n    tool_history: list[str]\n\ndef reasoning_node(state: AgentState):\n    \"\"\"Node chính gọi LLM để quyết định hành động tiếp theo\"\"\"\n    prompt = system_prompt.format(context=state[\"user_context\"])\n    response = llm.invoke([prompt] + state[\"messages\"])\n    return {\"messages\": [response]}\n"
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi Context Window Quá Dài:</b><br>Nếu user chat quá nhiều, LLM sẽ báo lỗi vượt quá số lượng token cho phép. Hệ thống hiện tại có cơ chế <code>history_limit</code> và <b>Conversation Truncation</b> để cắt bớt các đoạn hội thoại cũ (chỉ giữ lại 15 tin nhắn gần nhất).<br><br><b>🚫 Lỗi Tool Timeout:</b><br>Khi n8n xử lý quá chậm hoặc StarRocks delay, API n8n sẽ timeout. Agent cần có khả năng bắt exception này và trả lời khéo léo (VD: <i>'Hệ thống đang quá tải, anh vui lòng đợi chút nhé'</i>) thay vì văng HTTP 500."
        }
    ]
}
