"description":"Cái nhìn tổng quan về kiến trúc 5 lớp của Canifa AI Platform, từ giao diện người dùng đến các module API và hạ tầng dữ liệu.",
"diagram":"diagrams/platform-architecture.svg",
"sections":[
{
"title":"Cấu trúc 5 lớp (5-Layer Stack)",
"type":"text",
"content":"Hệ thống được thiết kế theo mô hình micro-modular monolith, cho phép mở rộng nhanh chóng các tính năng AI mà không làm ảnh hưởng đến lõi hệ thống.<br>1. <b>Client Layer:</b> Trình duyệt web chạy <code>main.html</code>, quản lý layout chính và sidebar.<br>2. <b>Interface Layer:</b> Hệ thống iframe cho phép load các module độc lập, giúp cô lập CSS/JS.<br>3. <b>Gateway Layer:</b> FastAPI Router đóng vai trò điều phối tất cả các request API.<br>4. <b>Module Layer:</b> 36+ module nghiệp vụ (AI Agents, Product, Social, v.v.) xử lý logic cụ thể.<br>5. <b>Data Layer:</b> Kết hợp SQLite (local dev), StarRocks (olap), và các dịch vụ external."
},
{
"title":"Danh sách API Modules chính",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/auth/me","description":"Lấy thông tin user hiện tại và settings LLM."},
{"method":"POST","path":"/api/chat","description":"Endpoint chính cho chatbot tương tác với n8n."},
{"method":"GET","path":"/api/live-monitor","description":"Theo dõi các event realtime qua WebSocket."}
]
},
{
"title":"Cấu trúc Thư mục",
"type":"code",
"language":"bash",
"code":"backend/\n├── api/ # Chứa toàn bộ logic router & business\n├── database/ # SQLite files & Migrations\n├── common/ # Shared utilities (db, auth, logs)\n├── static/ # Frontend assets (HTML, CSS, JS)\n└── server.py # Entry point của ứng dụng"
"description":"Chi tiết về cách hệ thống xử lý dữ liệu đồng bộ và bất đồng bộ, cùng cơ chế SQLite Mock để giả lập Postgres trong môi trường phát triển.",
"diagram":"diagrams/database-layer.svg",
"sections":[
{
"title":"Cơ chế SQL Translation",
"type":"text",
"content":"Để hỗ trợ chạy local mà không cần Postgres/StarRocks, module <code>sqlite_mock.py</code> thực hiện đánh chặn các câu lệnh SQL và dịch chúng sang dialect của SQLite thông qua hàm <code>translate_query()</code>. Các quy tắc chính bao gồm:<br>- Chuyển <code>%s</code> thành <code>?</code><br>- Thay thế tên schema (ví dụ: <code>public.users</code> thành <code>pg__public__users</code>)<br>- Giả lập các hàm đặc thù như <code>ANY_VALUE</code>, <code>MAX_BY</code>, <code>ILIKE</code>."
},
{
"title":"Async vs Sync Paths",
"type":"text",
"content":"1. <b>Async Path:</b> Sử dụng <code>aiosqlite</code> cho các API route hiện đại. Luồng này truy cập trực tiếp vào file <code>canifa_ai_dump.sqlite</code>.<br>2. <b>Sync Path:</b> Sử dụng <code>MockCursor</code> để tương thích với các legacy helper classes (như UltraDescDB) mà không cần refactor hàng chục method sang async."
},
{
"title":"Cấu hình Kết nối",
"type":"code",
"language":"python",
"code":"from common.pool_wrapper import get_pooled_connection_compat\n\n# Cách lấy connection tương thích cả Prod (PG) và Dev (SQLite Mock)\nwith get_pooled_connection_compat() as conn:\n with conn.cursor() as cur:\n cur.execute(\"SELECT * FROM public.users WHERE id = %s\", (user_id,))\n user = cur.fetchone()"
"description":"Tìm hiểu cách hệ thống xác thực người dùng bằng JWT và cơ chế điều hướng trang (routing) thông qua Single Sidebar.",
"diagram":"diagrams/auth-routing.svg",
"sections":[
{
"title":"Cơ chế Xác thực (JWT)",
"type":"text",
"content":"Hệ thống sử dụng JWT (JSON Web Token) để quản lý phiên làm việc. Khi login thành công, token được lưu vào <code>localStorage</code> và gửi kèm trong header <code>Authorization: Bearer <token></code> cho mọi request API.<br>Module <code>auth.js</code> phía client chịu trách nhiệm kiểm tra token (guard) mỗi khi trang web được tải lại."
},
{
"title":"Single Sidebar Navigation",
"type":"text",
"content":"Toàn bộ giao diện Platform nằm trong <code>main.html</code>. Khi người dùng click vào một mục trên sidebar, hàm <code>navigateTo(page)</code> sẽ:<br>1. Cập nhật thuộc tính <code>src</code> của Iframe.<br>2. Thêm tham số <code>t=<timestamp></code> để tránh cache trình duyệt.<br>3. Sử dụng <code>history.pushState</code> để cập nhật URL mà không làm tải lại trang."
},
{
"title":"API Authentication Endpoints",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/auth/login","description":"Xác thực user và trả về access_token."},
{"method":"GET","path":"/api/auth/me","description":"Lấy profile và settings của user hiện tại."},
{"method":"PUT","path":"/api/auth/me/settings","description":"Cập nhật Codex Token hoặc OpenAI Key cá nhân."}
"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":"Luồng xử lý (Execution Flow)",
"type":"text",
"content":"1. <b>Chat Controller:</b> Tiếp nhận request, kiểm tra Redis cache. Nếu miss, khởi tạo LangGraph engine.<br>2. <b>LangGraph Agent:</b> Chạy vòng lặp suy nghĩ (Reasoning Loop). Agent quyết định có cần gọi công cụ (tools) hay không.<br>3. <b>Tool Execution:</b> Nếu cần dữ liệu, Agent gọi các API chuyên dụng (n8n API) để lấy thông tin sản phẩm, tồn kho, cửa hàng.<br>4. <b>Response Synthesis:</b> Kết hợp dữ liệu thô từ tools và kiến thức thời trang để tạo câu trả lời tự nhiên."
},
{
"title":"Danh sách API n8n Tools",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/agent/n8n/products","description":"Lấy mẫu sản phẩm hoặc tìm kiếm theo SKU/tên."},
{"method":"GET","path":"/api/agent/n8n/stock","description":"Kiểm tra tồn kho realtime của Canifa."},
{"method":"GET","path":"/api/agent/n8n/stores","description":"Tìm kiếm danh sách cửa hàng theo khu vực."},
{"method":"GET","path":"/api/agent/n8n/knowledge","description":"Tra cứu chính sách đổi trả, bảng size (RAG)."}
]
},
{
"title":"Cấu trúc Request",
"type":"code",
"language":"json",
"code":"{\n\"user_query\": \"Tìm cho mình áo phông nam màu xanh size L còn hàng ở Hà Nội\",\n\"images\": [],\n\"history_limit\": 15\n}"
"description":"Hướng dẫn cách quản lý System Prompt và các Tool Prompt linh hoạt mà không cần khởi động lại server.",
"diagram":"diagrams/prompt-management.svg",
"sections":[
{
"title":"Cơ chế Dynamic Prompt",
"type":"text",
"content":"Hệ thống lưu trữ prompt trong các file <code>.txt</code> tại thư mục <code>backend/agent/</code>. Mỗi khi Admin cập nhật prompt qua UI, server sẽ ghi đè vào file tương ứng và gọi hàm <code>reset_chain_cache()</code> để xóa cache logic của LangChain. Lần truy vấn kế tiếp, Agent sẽ tự động nhận diện sự thay đổi nội dung (via MD5 hash) và nạp lại prompt mới."
},
{
"title":"Phân loại Prompt",
"type":"text",
"content":"1. <b>System Prompt:</b> Định nghĩa nhân cách, kiến thức cốt lõi và phong cách trả lời của Agent.<br>2. <b>Tool Prompts:</b> Định nghĩa chi tiết cách Agent sử dụng từng công cụ (ví dụ: cách tìm sản phẩm, cách tra cứu tồn kho).<br>3. <b>User Insight Template:</b> Định nghĩa các thông tin cần thu thập về người dùng (giới tính, sở thích, size)."
},
{
"title":"API Quản lý Prompt",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/agent/system-prompt","description":"Lấy nội dung System Prompt hiện tại."},
{"method":"POST","path":"/api/agent/system-prompt","description":"Cập nhật System Prompt và làm mới cache."},
{"method":"GET","path":"/api/agent/tool-prompts","description":"Liệt kê danh sách các tool prompt có sẵn."},
{"method":"POST","path":"/api/agent/tool-prompts/{filename}","description":"Cập nhật nội dung một tool prompt cụ thể."}
"description":"Tìm hiểu cách hệ thống phân loại phản hồi từ người dùng và Agent chuyên biệt để tạo sơ đồ kỹ thuật.",
"diagram":"diagrams/feedback-pipeline.svg",
"sections":[
{
"title":"Hệ thống Phân loại Feedback",
"type":"text",
"content":"Mỗi khi người dùng Like/Dislike hoặc để lại bình luận, request được gửi tới <code>/api/feedback</code>. Server phản hồi ngay lập tức và đẩy xử lý vào Background Task:<br>1. Sử dụng <b>GPT-4o-mini</b> để phân tích cảm xúc và phân loại lỗi (sai sản phẩm, lỗi logic, v.v.).<br>2. Đẩy điểm số (score) lên <b>Langfuse</b> gắn với <code>trace_id</code> để theo dõi chất lượng LLM.<br>3. Lưu vào cơ sở dữ liệu local để Admin kiểm tra định kỳ."
},
{
"title":"Diagram Agent",
"type":"text",
"content":"Module Diagram Agent cho phép người dùng mô tả kiến trúc và nhận lại mã <b>Mermaid</b> để hiển thị sơ đồ. Agent sử dụng mô hình 2-Agent (Planner và Responder) để đảm bảo độ chính xác của cú pháp sơ đồ."
"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/platform-architecture.svg",
"sections":[
{
"title":"Quy trình AI Generation",
"type":"text",
"content":"1. <b>Giai đoạn Vision:</b> Sử dụng model <b>Llama-4-Scout</b> để phân tích ảnh sản phẩm, trích xuất 28 trường dữ liệu thô (màu sắc, thiết kế, túi, cổ áo, v.v.).<br>2. <b>Giai đoạn Enrichment:</b> Sử dụng <b>GPT-OSS 120B</b> để viết lại nội dung theo phong cách chuyên gia Stylist, bổ sung hướng dẫn bảo quản và mix-match.<br>3. <b>Persistance:</b> Lưu trữ kết quả vào bảng <code>ultra_descriptions</code> (Postgres) và đánh dấu trạng thái <i>Pending</i> để chờ Admin duyệt."
},
{
"title":"Cấu trúc 28 trường dữ liệu",
"type":"code",
"language":"json",
"code":"{\n\"ten_san_pham\": \"Áo Phông Nam Có Túi\",\n\"chat_lieu\": \"100% Cotton\",\n\"phoi_do\": \"Quần Jean + Sneaker\",\n\"dip_mac\": \"Đi chơi · Đi làm\",\n\"faq_1_q\": \"Áo có bị phai màu không?\",\n\"faq_1_a\": \"Chất liệu Cotton USA cao cấp giúp giữ màu bền bỉ...\"\n}"
},
{
"title":"API Quản lý Mô tả",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/product-desc/overview","description":"Xem thống kê độ phủ của mô tả AI."},
{"method":"POST","path":"/api/product-desc/generate","description":"Sinh mô tả mới cho 1 sản phẩm cụ thể."},
{"method":"POST","path":"/api/product-desc/batch-generate","description":"Đưa danh sách sản phẩm vào queue xử lý hàng loạt."}
"description":"Khám phá thuật toán Stylist AI đằng sau các gợi ý phối đồ (Outfits), dựa trên hệ thống quy tắc thời trang và ma trận phối màu.",
"diagram":"diagrams/fashion-matches.svg",
"sections":[
{
"title":"Cơ chế hoạt động",
"type":"text",
"content":"Engine phối đồ hoạt động theo 5 bước chính:<br>1. <b>Phân tích Anchor:</b> Xác định loại sản phẩm, giới tính và màu sắc của item gốc.<br>2. <b>Tra cứu Quy tắc:</b> Tìm các công thức phối hợp trong bảng <code>chatbot_fashion_rules</code> (ví dụ: Áo Polo nam hợp với Quần Khaki hoặc Quần Jean).<br>3. <b>Ma trận Màu sắc:</b> Tính toán synergy score giữa màu anchor và màu các item ứng viên dựa trên ma trận 16x16 màu.<br>4. <b>Lọc Điều kiện:</b> Loại bỏ các item hết hàng hoặc lệch mùa.<br>5. <b>Xếp hạng:</b> Trả về Top 3 item tốt nhất cho mỗi vị trí (Top, Bottom, Outerwear, Accessory)."
},
{
"title":"Ma trận Phối màu (Color Synergy)",
"type":"text",
"content":"Màu sắc được chia thành 3 nhóm: <b>Neutral</b> (Trắng, Đen, Be, Xám), <b>Light</b> (Hồng, Vàng, Xanh lam), và <b>Dark</b> (Đỏ, Cam, Xanh navy).<br>- Neutral + Any: Điểm cao (An toàn).<br>- Light + Light hoặc Dark + Dark: Điểm trung bình (Cần cân nhắc).<br>- Tương phản mạnh: Điểm cao (Cá tính)."
},
{
"title":"API Phối đồ",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/fashion-matches/{code}","description":"Lấy danh sách các item phối cùng đã tính toán sẵn."},
{"method":"POST","path":"/api/fashion-matches/outfit-suggest","description":"Gợi ý outfit đầy đủ theo dịp (Occasion) cụ thể."},
{"method":"GET","path":"/api/fashion-matches/rules/config","description":"Lấy cấu hình các quy tắc thời trang."}
"description":"Hướng dẫn cách hệ thống truy xuất dữ liệu hiệu năng sản phẩm (KPIs) từ StarRocks và kiểm tra tồn kho realtime qua cơ chế parallel async fetch.",
"diagram":"diagrams/stock-cache.svg",
"sections":[
{
"title":"Product Performance (StarRocks)",
"type":"text",
"content":"Dashboard hiệu năng sử dụng <b>StarRocks</b> làm OLAP engine để tính toán các chỉ số Aggregate (Tổng bán, Tồn kho, Giá trung bình) trên hàng triệu bản ghi Magento trong thời gian thực.<br>Dữ liệu được nhóm theo <code>internal_ref_code</code> để hiển thị cái nhìn tổng quan theo mẫu mã thay vì từng màu/size riêng lẻ."
},
{
"title":"Cơ chế Check Tồn kho Realtime",
"type":"text",
"content":"Vì API tồn kho của Canifa chỉ nhận tối đa 200 SKU/lần, hệ thống triển khai cơ chế <b>Parallel Fetching</b>:<br>1. <b>Expand:</b> Chuyển đổi mã gốc sang toàn bộ bộ SKU (Màu-Size) hợp lệ.<br>2. <b>Chunking:</b> Chia danh sách thành các nhóm nhỏ (50 item/nhóm).<br>3. <b>Async Call:</b> Sử dụng <code>httpx.AsyncClient</code> để gọi đồng thời nhiều request, giảm latency tổng thể xuống dưới 2 giây."
},
{
"title":"API Hiệu năng & Tồn kho",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/products/overview","description":"Lấy các chỉ số KPI tổng quát của toàn bộ kho hàng."},
{"method":"GET","path":"/api/products/list","description":"Danh sách sản phẩm kèm hiệu số bán chạy và tìm kiếm thông minh."},
{"method":"POST","path":"/api/stock/check","description":"Kiểm tra tồn kho realtime cho danh sách sản phẩm."}
"description":"Khám phá kiến trúc 2-Agent chuyên biệt cho việc tư vấn bán hàng và chốt lead, sử dụng LangGraph để điều phối luồng suy nghĩ.",
"diagram":"diagrams/lead-search-agent.svg",
"sections":[
{
"title":"Kiến trúc 2-Agent (Dual-Agent)",
"type":"text",
"content":"Thay vì sử dụng một model duy nhất, Lead Search Agent chia làm 2 giai đoạn:<br>1. <b>Classifier Node (NHẸ):</b> Sử dụng Llama-4-Scout để phân loại ý định người dùng (Intent). Nếu cần dữ liệu, nó sẽ quyết định gọi <code>lead_search_tool</code>. Nếu là câu hỏi xã giao, nó sẽ Early Exit.<br>2. <b>Stylist Node (NẶNG):</b> Sử dụng GPT-OSS 120B để tổng hợp dữ liệu từ tool result, lịch sử chat và User Insight để đưa ra câu trả lời tư vấn chuyên sâu, đồng thời cập nhật lại 12 trường trong <code>InsightJSON</code>."
},
{
"title":"Cơ chế Insight JSON",
"type":"text",
"content":"Hệ thống duy trì một 'bộ nhớ' cấu trúc cho mỗi khách hàng bao gồm:<br>- <b>TARGET:</b> Đối tượng mua hàng (vợ, chồng, con).<br>- <b>GOAL:</b> Mục đích (mua đi làm, đi chơi).<br>- <b>STAGE:</b> Giai đoạn trong phễu bán hàng (BROWSE, COMPARE, COMMIT).<br>- <b>LAST_ACTION:</b> Hành động cuối cùng của Bot để duy trì context."
},
{
"title":"API Lead Flow",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/agent/chat-lead-flow","description":"Endpoint chính cho luồng tư vấn Lead Stage."},
{"method":"POST","path":"/api/agent/lead-stage","description":"Chỉ chạy Classifier để debug logic định tuyến."},
{"method":"GET","path":"/api/lead/history","description":"Lấy lịch sử chat Lead Flow từ Postgres (Persistent)."}
"description":"Hướng dẫn cách hệ thống tìm kiếm sản phẩm thông qua hình ảnh bằng cách kết hợp Vision LLM và Vector Similarity Search.",
"diagram":"diagrams/image-search.svg",
"sections":[
{
"title":"Quy trình Tìm kiếm Đa phương thức",
"type":"text",
"content":"1. <b>Vision Analysis:</b> Khi người dùng tải ảnh lên, Vision LLM (Llama-4 Scout hoặc GPT-4o) sẽ phân tích các thuộc tính thị giác như: loại sản phẩm, màu sắc, họa tiết, chất liệu vải.<br>2. <b>Embedding Generation:</b> Mô tả văn bản từ bước 1 được chuyển thành vector đặc trưng (Embedding).<br>3. <b>StarRocks Vector Search:</b> Thực hiện tìm kiếm láng giềng gần nhất (ANN) trên bảng <code>magento_product_dimension_with_text_embedding</code> để tìm ra các sản phẩm có độ tương đồng cao nhất về mặt ngữ nghĩa.<br>4. <b>Reranking:</b> Stylist Agent sẽ lọc lại danh sách dựa trên giới tính và độ tuổi của khách hàng trước khi trả về kết quả."
},
{
"title":"Kỹ thuật tối ưu",
"type":"text",
"content":"Hệ thống sử dụng hàm <code>approx_cosine_similarity</code> của StarRocks để đảm bảo tốc độ phản hồi dưới 500ms cho hàng chục ngàn sản phẩm."
},
{
"title":"API Image Search",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/image-search/chat","description":"Gửi ảnh (base64) và text query để tìm sản phẩm tương đương."}
"description":"Hướng dẫn chi tiết về cơ chế parse mã sản phẩm (SKU) bằng Regex và thuật toán tìm kiếm cửa hàng theo vị trí địa lý.",
"diagram":"diagrams/sku-store-search.svg",
"sections":[
{
"title":"SKU Parsing Logic",
"type":"text",
"content":"Hệ thống sử dụng biểu thức chính quy (Regex) để nhận diện mã sản phẩm Canifa ngay trong câu chat. Nếu tìm thấy mã khớp định dạng <code>^[0-9][A-Z]{2}[0-9]{2}[A-Z][0-9]{3}</code>, Agent sẽ ưu tiên tra cứu trực tiếp trong database thay vì sử dụng Vector Search, giúp đảm bảo độ chính xác 100% khi khách hàng hỏi về một mã cụ thể."
},
{
"title":"Thuật toán Tìm kiếm Cửa hàng",
"type":"text",
"content":"Engine tìm kiếm cửa hàng thực hiện qua 2 bước:<br>1. <b>Chuẩn hóa:</b> Loại bỏ các tiền tố như 'Quận', 'Huyện', 'TP' để lấy keyword lõi (ví dụ: 'Cầu Giấy').<br>2. <b>Multi-token LIKE:</b> Chia nhỏ địa điểm thành các token và thực hiện câu lệnh SQL <code>LIKE</code> trên nhiều cột (Tên CH, Địa chỉ, Thành phố).<br>3. <b>Schedule Integration:</b> Trả về trạng thái đóng/mở cửa dựa trên thời gian thực hiện tại."
},
{
"title":"API Tra cứu",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/agent/n8n/products?q={sku}","description":"Tra cứu nhanh thông tin sản phẩm theo mã SKU."},
{"method":"GET","path":"/api/agent/n8n/stores?location={city}","description":"Tìm danh sách cửa hàng tại một khu vực nhất định."}
"description":"Tìm hiểu cách hệ thống chuyển đổi ngôn ngữ tự nhiên thành các câu lệnh SQL phức tạp để phân tích dữ liệu bán hàng trên StarRocks.",
"diagram":"diagrams/text-to-sql.svg",
"sections":[
{
"title":"Cơ chế Text-to-SQL",
"type":"text",
"content":"Module sử dụng Agent có khả năng tự nhận diện Schema (Schema Awareness). Thay vì nhét toàn bộ DDL vào prompt, Agent thực hiện qua các bước:<br>1. <b>Table Selection:</b> Chọn các bảng liên quan đến câu hỏi (Sản phẩm, Đơn hàng, Tồn kho).<br>2. <b>SQL Generation:</b> Sinh câu lệnh SQL dialect StarRocks (tương thích MySQL).<br>3. <b>Execution:</b> Chạy query trên database StarRocks và nhận kết quả JSON.<br>4. <b>Self-Correction:</b> Nếu SQL lỗi, Agent sẽ đọc thông báo lỗi và thử sinh lại tối đa 3 lần."
},
{
"title":"AI Data Analyst",
"type":"text",
"content":"Sau khi có dữ liệu thô, Analyst Node sẽ:<br>- <b>Summarization:</b> Tóm tắt các con số quan trọng (Tổng doanh thu, % tăng trưởng).<br>- <b>Insight Extraction:</b> Tìm ra các điểm bất thường hoặc xu hướng (ví dụ: 'Áo phông nam đang bán chậm ở miền Nam').<br>- <b>Visualization Suggestion:</b> Đề xuất loại biểu đồ phù hợp (Cột, Tròn, Đường) để frontend hiển thị."
},
{
"title":"API SQL & Insights",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/sql/chat","description":"Chat với dữ liệu để lấy insight và biểu đồ."},
{"method":"POST","path":"/api/sql/generate","description":"Chỉ sinh code SQL từ ngôn ngữ tự nhiên (cho Admin)."},
{"method":"GET","path":"/api/sql/user-insight/{id}","description":"Lấy hồ sơ insight chi tiết của 1 khách hàng cụ thể."}
"description":"Tìm hiểu cách hệ thống quản lý tin nhắn và bình luận từ đa nền tảng mạng xã hội, phân tích cảm xúc và đưa vào vòng lặp học tập (learning loop).",
"diagram":"diagrams/social-content-flow.svg",
"sections":[
{
"title":"Xử lý Webhook Đa nền tảng",
"type":"text",
"content":"Hệ thống tiếp nhận dữ liệu thời gian thực thông qua các Webhook endpoint chuyên biệt cho Facebook/Instagram và TikTok. Quy trình xử lý bao gồm:<br>1. <b>Signature Verification:</b> Kiểm tra tính hợp lệ của request (X-Hub-Signature-256).<br>2. <b>Normalization:</b> Chuyển đổi payload đặc thù của từng nền tảng về định dạng <code>SocialMessage</code> chung.<br>3. <b>Sentiment Analysis:</b> Sử dụng module <code>analyze_sentiment_detail</code> để phân loại cảm xúc (Tích cực, Tiêu cực, Trung lập)."
},
{
"title":"Vòng lặp Học tập (Learning Loop)",
"type":"text",
"content":"Các bình luận tiêu cực (Negative) sẽ được tự động đẩy vào <code>feedback_tracker</code>. Tại đây, AI sẽ tóm tắt nội dung khiếu nại và gán độ nghiêm trọng (severity). Dữ liệu này giúp Admin nhận diện các điểm yếu trong sản phẩm hoặc dịch vụ để cải thiện prompt cho Chatbot trong tương lai."
},
{
"title":"API Social Inbox",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/social/webhook/facebook","description":"Nhận sự kiện từ Facebook Graph API."},
{"method":"GET","path":"/api/social/messages","description":"Lấy danh sách tin nhắn/bình luận đã lưu kèm phân tích sentiment."},
{"method":"GET","path":"/api/social/messages/stats","description":"Xem thống kê tỷ lệ phản hồi tiêu cực theo platform."}
"description":"Hướng dẫn sử dụng công cụ soạn thảo nội dung AI để tạo bài viết marketing chuẩn Canifa cho các mạng xã hội.",
"diagram":"diagrams/social-content-flow.svg",
"sections":[
{
"title":"Cơ chế Soạn thảo (Composition)",
"type":"text",
"content":"Content Composer sử dụng các <b>Content Templates</b> đã được định nghĩa sẵn để đảm bảo tính nhất quán về brand voice. Người dùng chỉ cần nhập chủ đề (Topic) hoặc mã sản phẩm, AI sẽ tự động:<br>- Tra cứu đặc điểm nổi bật của sản phẩm (từ Ultra Description).<br>- Lồng ghép các chương trình khuyến mãi hiện có.<br>- Thêm các hashtag phổ biến và icon trang trí phù hợp với từng platform (FB vs TikTok)."
},
{
"title":"Tích hợp Media",
"type":"text",
"content":"Hệ thống kết nối trực tiếp với <b>Media Library</b>, cho phép kéo thả hình ảnh sản phẩm Magento hoặc ảnh marketing từ cloud vào bài viết."
},
{
"title":"API Content & Templates",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/content/templates","description":"Liệt kê danh sách các mẫu bài viết (Sale, New Arrival, v.v.)."},
{"method":"POST","path":"/api/content/generate","description":"Yêu cầu AI viết nháp bài đăng dựa trên template và sản phẩm."},
{"method":"GET","path":"/api/content/queue","description":"Xem danh sách các bài viết đang chờ đăng."}
"description":"Quy trình kiểm duyệt nội dung do AI sinh ra trước khi xuất bản lên các kênh chính thức của thương hiệu.",
"diagram":"diagrams/social-content-flow.svg",
"sections":[
{
"title":"Trạng thái Nội dung",
"type":"text",
"content":"Mỗi bản nháp nội dung (Content Draft) sẽ trải qua các trạng thái:<br>1. <b>Draft:</b> Vừa được AI sinh ra.<br>2. <b>Pending:</b> Đang chờ Admin duyệt.<br>3. <b>Approved:</b> Đã duyệt, chuyển vào hàng đợi đăng bài.<br>4. <b>Rejected:</b> Cần sửa lại (Admin có thể để lại comment feedback cho AI viết lại)."
},
{
"title":"API Kiểm duyệt",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/approval/list","description":"Lấy danh sách các yêu cầu kiểm duyệt đang chờ."},
{"method":"POST","path":"/api/approval/{id}/approve","description":"Chấp thuận nội dung và đặt lịch đăng."},
{"method":"POST","path":"/api/approval/{id}/reject","description":"Từ chối nội dung kèm lý do."}
"description":"Kho lưu trữ tập trung các tài nguyên hình ảnh, video phục vụ cho việc tạo nội dung marketing.",
"diagram":"diagrams/social-content-flow.svg",
"sections":[
{
"title":"Phân loại Tài nguyên",
"type":"text",
"content":"Media Library chứa 2 nhóm tài nguyên chính:<br>1. <b>Magento Sync:</b> Toàn bộ ảnh sản phẩm được đồng bộ tự động từ website canifa.com.<br>2. <b>Cloud Marketing:</b> Các bộ sưu tập ảnh chụp lookbook, video quảng cáo do team Creative tải lên."
},
{
"title":"Tối ưu hình ảnh",
"type":"text",
"content":"Hệ thống tự động sinh <b>Thumbnail</b> (ảnh thu nhỏ) để tăng tốc độ tải trang Dashboard và hỗ trợ preview nhanh trong Content Composer."
},
{
"title":"API Media",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/media/search","description":"Tìm kiếm ảnh theo tên sản phẩm hoặc tag."},
{"method":"POST","path":"/api/media/upload","description":"Tải file media mới lên hệ thống."},
{"method":"DELETE","path":"/api/media/{id}","description":"Xóa tài nguyên khỏi thư viện."}
"description":"Hướng dẫn vận hành hệ thống giám sát hoạt động AI thời gian thực thông qua kết nối SSE (Server-Sent Events) và Langfuse REST API.",
"diagram":"diagrams/realtime-monitor.svg",
"sections":[
{
"title":"Cơ chế Live Stream",
"type":"text",
"content":"Thay vì sử dụng Polling liên tục, dashboard Live Monitor sử dụng <b>SSE (Server-Sent Events)</b> để nhận dữ liệu đẩy từ server. Server duy trì một event loop mỗi 4 giây:<br>1. Gọi <b>Langfuse API</b> để lấy snapshot các trace mới nhất.<br>2. Tính toán các chỉ số Aggregate (Latency trung bình, Error Rate, Token Cost).<br>3. Kiểm tra <b>Signature</b> của dữ liệu. Nếu có thay đổi so với lần trước, server sẽ đẩy payload mới xuống client."
},
{
"title":"Các chỉ số Giám sát",
"type":"text",
"content":"Dashboard cung cấp 4 biểu đồ quan trọng:<br>- <b>Traffic:</b> Số lượng request mỗi phút.<br>- <b>Latency:</b> Tốc độ phản hồi của LLM (cảnh báo nếu > 12s).<br>- <b>Cost:</b> Chi phí vận hành ước tính theo thời gian thực.<br>- <b>Error Rate:</b> Tỷ lệ lỗi hệ thống hoặc lỗi từ model provider."
},
{
"title":"API Giám sát",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/live-monitor/bootstrap","description":"Lấy dữ liệu khởi tạo cho dashboard (20 phút gần nhất)."},
{"method":"GET","path":"/api/live-monitor/stream","description":"Mở kết nối SSE để nhận update liên tục."}
"description":"Hướng dẫn sử dụng bộ kiểm thử hồi quy để đảm bảo chất lượng câu trả lời của LLM không bị suy giảm sau mỗi lần cập nhật Prompt hoặc Model.",
"diagram":"diagrams/testing-suite.svg",
"sections":[
{
"title":"Cơ chế Kiểm thử Hồi quy",
"type":"text",
"content":"Regression Test hoạt động bằng cách gửi một danh sách các câu hỏi tiêu chuẩn (Golden Dataset) tới chatbot và thu thập câu trả lời. Admin sẽ review các kết quả này để đánh giá độ chính xác về thông tin sản phẩm, brand voice và khả năng xử lý tình huống.<br>Hệ thống hỗ trợ so sánh song song giữa môi trường <b>Prod</b> và <b>Dev</b> để nhận diện sự khác biệt."
},
{
"title":"API Regression Test",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/regression-test/run","description":"Chạy toàn bộ test cases đối với một endpoint cụ thể."},
{"method":"GET","path":"/api/regression-test/history","description":"Xem lịch sử các lần chạy test và tỷ lệ pass/fail."}
"description":"Hướng dẫn thực hiện kiểm thử tải để xác định giới hạn chịu tải của hệ thống và latency ở mức concurrency cao.",
"diagram":"diagrams/testing-suite.svg",
"sections":[
{
"title":"Stress Test với Locust",
"type":"text",
"content":"Hệ thống tích hợp sẵn <b>Locust</b> để giả lập hàng trăm người dùng truy cập đồng thời. Stress test giúp đo lường:<br>- <b>RPS (Requests Per Second):</b> Số lượng request tối đa hệ thống xử lý được.<br>- <b>P99 Latency:</b> Thời gian phản hồi mà 99% người dùng gặp phải.<br>- <b>Model Rate Limit:</b> Giới hạn từ phía nhà cung cấp LLM (OpenAI/Anthropic)."
},
{
"title":"API Stress Test",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/stress-test/start","description":"Khởi động một worker Locust để bắt đầu spam request."},
{"method":"GET","path":"/api/stress-test/stats","description":"Lấy báo cáo realtime về hiệu năng server dưới tải."}
"description":"Sử dụng AI để đóng vai các 'Persona' khách hàng khác nhau nhằm thực hiện kiểm thử thăm dò (Exploratory Testing).",
"diagram":"diagrams/testing-suite.svg",
"sections":[
{
"title":"Cơ chế Simulator",
"type":"text",
"content":"User Simulator tạo ra các chatbot ảo có tính cách và nhu cầu cụ thể (ví dụ: 'Bà mẹ bỉm sữa khó tính', 'Nam thanh niên săn sale', 'Khách hàng hỏi size cho con'). Các chatbot này sẽ tự động trò chuyện với hệ thống để:<br>- Tìm ra các trường hợp xử lý lỗi hoặc thiếu logic.<br>- Kiểm tra khả năng chốt sale của Agent.<br>- Verify tính nhất quán của User Insight JSON qua nhiều turn chat."
},
{
"title":"API Simulator",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/user-simulator/spawn","description":"Tạo ra một phiên chat giả lập với một persona nhất định."},
{"method":"GET","path":"/api/user-simulator/personas","description":"Liệt kê các thư viện tính cách khách hàng có sẵn."}
"description":"Giả lập hàng loạt phản hồi người dùng (Like/Dislike) để kiểm tra độ chịu tải và độ chính xác của bộ phân loại Feedback.",
"diagram":"diagrams/testing-suite.svg",
"sections":[
{
"title":"Stress Testing Feedback Loop",
"type":"text",
"content":"Vì mỗi feedback sẽ kích hoạt một Background Task gọi LLM để phân loại, việc giả lập reaction giúp verify:<br>1. <b>Queue Depth:</b> Khả năng xếp hàng các task xử lý sentiment.<br>2. <b>Langfuse Rate Limit:</b> Đảm bảo không làm nghẽn API đẩy score lên Langfuse.<br>3. <b>Dashboard Realtime:</b> Kiểm tra khả năng cập nhật biểu đồ thống kê khi có hàng ngàn feedback đổ về."
},
{
"title":"API Reaction Sim",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/reaction-simulator/spam","description":"Gửi ngẫu nhiên N feedback (Like/Dislike) vào hệ thống."}
"description":"Tìm hiểu cơ chế quản lý câu hỏi thường gặp và thuật toán tìm kiếm lai (Hybrid Search) kết hợp BM25 và Fuzzy Matching.",
"diagram":"diagrams/faq-bm25-search.svg",
"sections":[
{
"title":"Thuật toán Hybrid Search",
"type":"text",
"content":"Để đảm bảo tìm đúng câu hỏi ngay cả khi người dùng viết tắt hoặc gõ sai, hệ thống sử dụng thuật toán <b>Simulate Match</b>:<br>1. <b>BM25 (Best Matching 25):</b> Thuật toán xếp hạng dựa trên tần suất từ khóa, ưu tiên các từ hiếm và mang ý nghĩa quan trọng.<br>2. <b>Fuzzy Match:</b> Sử dụng khoảng cách Levenshtein để xử lý các lỗi chính tả nhẹ (ví dụ: 'quan jean' vs 'quần jean').<br>3. <b>Score Fusion:</b> Kết hợp điểm số từ hai thuật toán theo trọng số 70/30 để đưa ra kết quả cuối cùng."
},
{
"title":"AI Variant Generation",
"type":"text",
"content":"Module tích hợp GPT-4.1-mini để tự động sinh ra 20-50 biến thể cho mỗi câu hỏi gốc. Việc này giúp mở rộng bề mặt tìm kiếm, giúp hệ thống nhận diện được nhiều cách đặt câu hỏi khác nhau của khách hàng mà không cần Admin phải nhập liệu thủ công."
},
{
"title":"API FAQ",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/faqs","description":"Lấy danh sách câu hỏi và câu trả lời."},
{"method":"POST","path":"/api/faqs/generate-variants","description":"Sử dụng AI để sinh biến thể cho một FAQ cụ thể."},
{"method":"POST","path":"/api/faqs/simulate-match","description":"Test thử thuật toán search với một câu query bất kỳ."}
"description":"Công cụ sử dụng AI để tự động cải thiện các câu lệnh (Prompts) dựa trên feedback của người dùng.",
"diagram":"diagrams/prompt-management.svg",
"sections":[
{
"title":"Cơ chế Tối ưu",
"type":"text",
"content":"Prompt Optimizer phân tích các <b>Negative Feedback</b> từ Langfuse để tìm ra các trường hợp Agent trả lời sai hoặc không đầy đủ. Sau đó, nó đề xuất các thay đổi trong System Prompt để bổ sung kiến thức hoặc điều chỉnh phong cách trả lời nhằm khắc phục các lỗi đó."
},
{
"title":"API Optimizer",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/prompt-optimizer/analyze","description":"Phân tích feedback và đề xuất hướng tối ưu prompt."},
{"method":"POST","path":"/api/prompt-optimizer/apply","description":"Áp dụng bản sửa đổi vào System Prompt."}
"description":"Hệ thống ghi lại lịch sử các thay đổi và thử nghiệm trên Platform để phục vụ việc truy vết và đánh giá hiệu quả.",
"diagram":"diagrams/platform-architecture.svg",
"sections":[
{
"title":"Ghi nhận Thử nghiệm",
"type":"text",
"content":"Mỗi khi có sự thay đổi lớn (đổi model LLM, cập nhật thuật toán search, thay đổi UI), Admin sẽ tạo một bản ghi Experiment. Hệ thống sẽ theo dõi các chỉ số KPI trước và sau thay đổi để xác định xem thử nghiệm có thành công hay không."
},
{
"title":"API Experiment",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/experiments","description":"Danh sách các thử nghiệm đã và đang diễn ra."},
{"method":"POST","path":"/api/experiments/log","description":"Ghi lại một sự kiện hoặc thay đổi hệ thống."}
"description":"Chi tiết về cơ chế bảo vệ hệ thống khỏi spam và tối ưu chi phí LLM thông qua lớp Cache/Rate Limit.",
"diagram":"diagrams/auth-routing.svg",
"sections":[
{
"title":"Cơ chế Rate Limit",
"type":"text",
"content":"Hệ thống sử dụng middleware <code>CanifaAuthMiddleware</code> để kiểm soát số lượng request từ mỗi user/device. Giới hạn mặc định là 60 request/phút cho các API chat để tránh việc spam gây tốn kém token."
},
{
"title":"LLM Semantic Cache",
"type":"text",
"content":"Đối với các câu hỏi phổ biến, hệ thống sử dụng <b>Redis</b> để cache kết quả trả về từ LLM. Nếu một câu hỏi tương tự xuất hiện, Agent sẽ trả về kết quả từ cache thay vì gọi lại OpenAI/Anthropic, giúp giảm latency xuống < 100ms và tiết kiệm chi phí."
},
{
"title":"API Cache & Limit",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/cache/stats","description":"Xem tỷ lệ Hit/Miss của hệ thống cache."},
{"method":"POST","path":"/api/cache/clear","description":"Xóa toàn bộ cache LLM (dùng khi cập nhật prompt mới)."},
{"method":"GET","path":"/api/limit/status","description":"Kiểm tra trạng thái quota còn lại của user hiện tại."}
"description":"Tìm hiểu cách hệ thống quản lý lịch sử trò chuyện và cơ chế hợp nhất (Merge) dữ liệu khi khách hàng đăng nhập.",
"diagram":"diagrams/history-merge.svg",
"sections":[
{
"title":"Anonymous vs Profile History",
"type":"text",
"content":"Để tối ưu trải nghiệm, hệ thống cho phép khách hàng vãng lai (Guest) trò chuyện ngay lập tức mà không cần login. Lịch sử này được lưu trữ gắn với một <code>device_id</code> duy nhất trong Redis (TTL 24h).<br>Khi người dùng thực hiện đăng nhập, hệ thống sẽ tự động quét các tin nhắn từ <code>device_id</code> hiện tại và hợp nhất chúng vào hồ sơ <code>user_id</code> vĩnh viễn trong Postgres."
},
{
"title":"Chiến lược Hợp nhất (Merge Strategy)",
"type":"text",
"content":"- <b>Timeline Alignment:</b> Các tin nhắn được sắp xếp lại theo thời gian thực (Timestamp) để đảm bảo mạch hội thoại logic.<br>- <b>Deduplication:</b> Loại bỏ các tin nhắn trùng lặp nếu người dùng đăng nhập lại nhiều lần trên cùng một thiết bị.<br>- <b>Context Enrichment:</b> Các thông tin insight thu thập được trong giai đoạn Guest (giới tính, sở thích) cũng được cập nhật vào User Profile mới."
},
{
"title":"API History",
"type":"api",
"endpoints":[
{"method":"GET","path":"/api/history/list","description":"Lấy danh sách các phiên hội thoại của người dùng."},
{"method":"POST","path":"/api/merge-history/preview","description":"Xem trước kết quả hợp nhất trước khi lưu chính thức."},
{"method":"DELETE","path":"/api/history/{id}","description":"Xóa một phiên hội thoại cụ thể."}
"description":"Hướng dẫn chi tiết về cơ chế xác thực người dùng và phân quyền truy cập API trên Canifa AI Platform.",
"diagram":"diagrams/auth-routing.svg",
"sections":[
{
"title":"JWT Lifecycle",
"type":"text",
"content":"Hệ thống sử dụng tiêu chuẩn <b>HS256</b> để ký các token xác thực. Một Access Token bao gồm các thông tin:<br>- <code>user_id</code>: ID định danh duy nhất.<br>- <code>role</code>: Quyền hạn (Admin, Editor, Viewer).<br>- <code>exp</code>: Thời gian hết hạn (mặc định 7 ngày).<br>Khi token hết hạn, người dùng sẽ bị <code>auth.js</code> tự động điều hướng quay lại trang <code>login.html</code>."
},
{
"title":"Cơ chế bảo mật",
"type":"text",
"content":"- <b>Password Hashing:</b> Mật khẩu được mã hóa bằng <code>bcrypt</code> trước khi lưu vào DB.<br>- <b>Middleware Guard:</b> Mọi API route (trừ login/register) đều được bọc bởi <code>CanifaAuthMiddleware</code> để kiểm tra tính hợp lệ của header <code>Authorization</code>."
},
{
"title":"API Auth",
"type":"api",
"endpoints":[
{"method":"POST","path":"/api/auth/login","description":"Đăng nhập và nhận token JWT."},
{"method":"POST","path":"/api/auth/logout","description":"Hủy phiên làm việc hiện tại."},
{"method":"GET","path":"/api/auth/verify","description":"Kiểm tra token còn hiệu lực hay không."}
<textx="480"y="40"font-family="Arial, sans-serif"font-size="22"font-weight="bold"text-anchor="middle"fill="#1e293b">Text-to-SQL & AI Data Analyst Pipeline</text>
