{
    "title": "Fashion Matching Engine",
    "description": "Khám phá thuật toán đằng sau các gợi ý phối đồ (Outfits), dựa trên hệ thống quy tắc cứng (Rule-based) kết hợp với LLM reasoning.",
    "diagram": "diagrams/fashion-matches.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Fashion Match Engine là thuật toán gợi ý đồ bộ (Outfit) cho 1 sản phẩm gốc (Anchor Item). Mục tiêu là đảm bảo AI luôn gợi ý ĐÚNG QUY TẮC (Ví dụ: Không bao giờ gợi ý Quần Ống Rộng đi với Áo Oversize cho người thấp). Bằng cách kết hợp giữa SQLite Rules (Logic cứng) và LLM (Ngôn ngữ mềm), hệ thống ngăn chặn triệt để tình trạng AI \"ảo giác\" ra set đồ thảm họa."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (Data Flow)",
            "type": "text",
            "content": "Quy trình phối đồ đi qua 4 bước khắt khe:<br><br><b>1. Phân tích Anchor:</b> Trích xuất Category, Giới tính, Dáng áo (Form), và Màu sắc của sản phẩm khách đang xem.<br><b>2. Truy vấn Rule Base:</b> Query bảng <code>chatbot_fashion_rules</code> (SQLite) để lấy các \"Công thức\" hợp lệ. (Ví dụ: <code>Áo Polo -> Quần Khaki, Quần Jean</code>).<br><b>3. Chấm điểm Màu sắc (Color Matrix):</b> Điểm <code>synergy_score</code> được tính từ ma trận 16x16 màu. (Ví dụ: Trắng + Đen = 10đ, Cam + Xanh lá = 3đ).<br><b>4. Lọc Tồn Kho & Xếp hạng:</b> Gọi sang module Product Stock để loại bỏ những item đã hết hàng, sau đó lấy Top 3 cho từng Slot (Top, Bottom, Outerwear, Accessory)."
        },
        {
            "title": "3. Core Logic: Khung 4-Slot Framework",
            "type": "text",
            "content": "Để tránh việc AI gợi ý lung tung, hệ thống ép toàn bộ Outfit vào một khung 4-Slot cố định:<br>- <b>Top:</b> Áo (Phông, Polo, Sơ mi).<br>- <b>Bottom:</b> Quần/Chân váy.<br>- <b>Set/One-piece:</b> Đồ liền (Váy liền, Jumpsuit).<br>- <b>Accessories:</b> Phụ kiện (Mũ, Tất, Thắt lưng).<br>Ví dụ: Nếu khách đang xem Áo (Top), AI bắt buộc phải tìm Quần (Bottom) và Phụ kiện. AI không được phép gợi ý thêm 1 cái Áo khác trừ khi đó là Áo Khoác (Outerwear)."
        },
        {
            "title": "4. 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 (Cache)." },
                { "method": "POST", "path": "/api/fashion-matches/outfit-suggest", "description": "AI Gen Outfit thời gian thực theo sự kiện (Ví dụ: Đi tiệc)." },
                { "method": "GET", "path": "/api/fashion-matches/rules/config", "description": "Admin API: Tải bộ quy tắc phối đồ từ DB." }
            ]
        },
        {
            "title": "5. Code Snippet Thực Tế (match_algo.py)",
            "type": "code",
            "language": "python",
            "code": "def calculate_color_synergy(anchor_color: str, candidate_color: str) -> int:\n    \"\"\"Tính điểm hợp màu dựa trên ma trận cứng thay vì hỏi LLM\"\"\"\n    # Các màu an toàn (Neutral) luôn hợp mọi thứ\n    neutrals = ['Trắng', 'Đen', 'Be', 'Xám', 'Ghi']\n    \n    if anchor_color in neutrals or candidate_color in neutrals:\n        return 8  # Safe match\n        \n    # Quy tắc tương phản (Tonal/Contrast)\n    if is_complementary(anchor_color, candidate_color):\n        return 10 # High fashion\n        \n    if is_clashing(anchor_color, candidate_color):\n        return 2  # Bad match\n        \n    return 5"
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi AI Gợi ý đồ Hết Hàng:</b><br>Thuật toán Match có thể tìm ra Outfit rất đẹp nhưng tỷ lệ Click sẽ = 0 nếu hàng hết size. LUÔN phải bọc vòng lặp <code>filter(is_in_stock)</code> trước khi nhét vào Prompt cho AI viết văn.<br><br><b>🚫 Lỗi Quá tải Phụ kiện (Over-accessorizing):</b><br>Nếu không ép Slot Framework, LLM có xu hướng khuyên khách hàng mặc 1 cái váy kèm theo mũ, kính, vòng cổ, tất, thắt lưng cùng lúc. Quy tắc cứng: Tối đa 2 item trong slot <code>Accessories</code>."
        }
    ]
}
