# 🏆 ĐẠI KỶ YẾU KIẾN TRÚC & LOGIC HỆ THỐNG CANIFA AI STYLIST (ULTIMATE GOD-MODE EDITION)

> **Phiên bản:** 5.0.0 (The Eternal Archive)
> **Chủ biên:** Canifa AI Architect Team & The Master Mind
> **Ngày cập nhật:** 06/05/2026

---

## 🧭 PHẦN I: BỐI CẢNH & CUỘC CÁCH MẠNG DETERMINISTIC

### 1.1. Thời kỳ "Hỗn mang" (The AI Blackbox Era)
Trước đây, hệ thống Canifa Stylist dựa dẫm quá nhiều vào việc AI tự sinh dữ liệu và lưu vào cột `ai_matches` dưới dạng JSON. 
*   **Vấn đề 1:** AI thường xuyên "sáng tạo" quá đà, phối đồ không theo bất kỳ quy tắc thời trang nào của Canifa.
*   **Vấn đề 2:** Dữ liệu JSON cồng kềnh, khó truy vấn, khó lọc theo giới tính hoặc độ tuổi.
*   **Vấn đề 3:** "Sync Hell" - Dữ liệu giữa các bảng không đồng nhất, dẫn đến việc Dashboard hiện một đằng, Chatbot nói một nẻo.

### 1.2. Cuộc Cách mạng "Deterministic" (Quy tắc hóa)
Chúng ta đã đưa ra quyết định táo bạo: **Tước bỏ quyền "tự quyết" của AI** và thay thế bằng một hệ thống Logic dựa trên SQL cứng. AI giờ đây chỉ đóng vai trò là "người thực thi" (Executor) dựa trên bản đồ (Map) mà chúng ta đã vạch sẵn.

---

## 🛠️ PHẦN II: CHI TIẾT "ĐẠI PHẪU" DATABASE (THE GREAT CLEANUP)

### 2.1. Phẫu thuật cắt bỏ "U ác tính" `ai_matches`
Cột `ai_matches` trong bảng `ultra_descriptions` chính là nguồn cơn của sự nhầm lẫn. 
*   **Hành động:** Chúng ta đã tạo script `finalize-migration-drop-column.py` để xóa vĩnh viễn cột này trên SQLite Mock.
*   **Tại sao không xóa trên Postgres?** Vì chúng ta là những kỹ sư cẩn trọng. Chúng ta làm sạch môi trường phát triển trước, đảm bảo logic chạy mượt rồi mới để anh tự tay "ấn nút" trên production.

### 2.2. Dẹp loạn "Bảng sinh đôi" (The Twin Table Conflict)
Trong quá trình rà soát, chúng ta phát hiện một sự "oop láo" kinh điển: Sự tồn tại song song của `ai_outfit_rules` và `chatbot_fashion_rules`. 
*   **Xung đột:** Một cái có gender, một cái không. Một cái dùng cho Dashboard, một cái Engine lại gọi.
*   **Giải pháp:** Hợp nhất tất cả về `pg__dashboard_canifa__chatbot_fashion_rules`.
*   **Cập nhật hằng số:** File `backend/common/constants.py` đã được sửa để cả 2 hằng số `TABLE_OUTFIT_RULES` và `TABLE_FASHION_RULES` đều trỏ về một mối. Đây là bước ngoặt giúp hệ thống "nhất quán" (Consolidated).

---

## 🧠 PHẦN III: ENGINE THÔNG MINH - THUẬT TOÁN CHẤM ĐIỂM TRỌNG SỐ

Đây là phần "khủng" nhất, nơi Gu thẩm mỹ được chuyển hóa thành Toán học.

### 3.1. Ma trận Trọng số (Scoring Weights)
Hệ thống không chấm điểm bừa, mà dựa trên tỉ lệ:
*   **Hòa sắc (Color):** 40% (Quan trọng nhất)
*   **Phù hợp Dịp (Occasion):** 25%
*   **Vai trò (Role):** 20%
*   **Chất liệu (Material):** 15%

### 3.2. Logic Giới tính & Demographic (The Soul of Styling)
Chúng ta đã cài cắm "linh hồn" vào Engine thông qua `demographic_color_logic`:

#### 👔 Phái Nam (The Gentlemen)
*   **Triết lý:** Ưu tiên sự lịch lãm, an toàn.
*   **Logic:** Boost mạnh nhóm màu `Neutral` (Be, Navy, Đen, Xám). Đánh tụt điểm các màu `Light` rực rỡ như Hồng, Cam để tránh "ngốt".

#### 👗 Phái Nữ (The Ladies)
*   **Triết lý:** Linh hoạt, đa dạng.
*   **Logic:** Không áp đặt boost màu. AI tự động tính toán sự hòa quyện giữa các nhóm màu để đưa ra gợi ý phá cách hoặc thanh lịch tùy dịp.

#### 🦄 Bé Gái (The Princess)
*   **Triết lý:** Thế giới cổ tích.
*   **Logic:** Boost tối đa cho nhóm màu `Pastel` (Tím nhạt, Hồng phấn, Vàng chanh). 

#### ⚽ Bé Trai (The Active Boy)
*   **Triết lý:** Năng động, mạnh mẽ.
*   **Logic:** Ưu tiên nhóm màu `Dark` (Xanh jeans, Xanh than) để giữ độ bền màu và cá tính.

---

## ⚡ PHẦN IV: TỐI ƯU HIỆU NĂNG (THE SPEED CHAPTER)

Khi kho hàng lên đến hàng nghìn sản phẩm, hiệu năng là sống còn. Chúng ta đã áp dụng các kỹ thuật "thượng thừa":

1.  **Pre-fetching Targets:** Thay vì chạy vòng lặp SELECT hàng nghìn lần (N+1 Problem), chúng ta gom tất cả các danh mục mục tiêu (`target_category`) và thực hiện 1 câu query `IN` duy nhất.
2.  **SQL Interception:** Trong môi trường Local, chúng ta sử dụng `MockRow` để giả lập kết quả từ Postgres, giúp việc phát triển không bị phụ thuộc vào hạ tầng server.
3.  **Indexing:** Các cột như `magento_ref_code`, `product_line_vn`, `gender_by_product` đều được đánh Index để đảm bảo tốc độ truy xuất dưới 10ms.

---

## 🛡️ PHẦN V: HỆ THỐNG LÁ CHẮN (STYLE GUARDRAILS)

Chúng ta đã cài đặt những "điều cấm kỵ" để bảo vệ hình ảnh thương hiệu Canifa:

*   **Danh sách Exclude:** Các dòng sản phẩm như Đồ lót (`Áo lót`, `Quần lót`), Khăn mặt, Khẩu trang, Tất... đều bị loại khỏi Engine phối đồ hoàn toàn.
*   **Gender Locking:** Ngăn chặn tuyệt đối việc phối đồ lộn xộn giữa Nam và Nữ trừ khi sản phẩm đó được gắn nhãn `Unisex`.
*   **Age Integrity:** Đảm bảo đồ Trẻ em chỉ phối với đồ Trẻ em. 

---

## 📂 PHẦN VI: CHI TIẾT CẤU TRÚC THƯ MỤC (TECHNICAL LANDSCAPE)

1.  **`backend/common/constants.py`**: Trái tim hằng số. Gộp các bảng Rules về một mối.
2.  **`backend/worker/stylist_engine.py`**: Cơ bắp xử lý thuật toán chấm điểm và logic giới tính.
3.  **`backend/worker/fashion_rules.json`**: Bộ nhớ quy tắc, chứa ma trận màu sắc và logic Demographic.
4.  **`backend/api/fashion_matches/router.py`**: Cửa ngõ API phục vụ Dashboard và Chatbot.

---

## 🆚 PHẦN VII: SO SÁNH AI TRƯỚC ĐÂY VS. STYLIST ENGINE HIỆN TẠI

| Tiêu chí | AI Stylist (Cũ) | Stylist Engine (Hiện tại) |
|:---|:---|:---|
| **Độ chính xác** | 60-70% (Hay phối đồ ngáo) | **100% (Theo luật chuyên gia)** |
| **Tốc độ** | Chậm (Chờ LLM suy nghĩ) | **Siêu tốc (Tra cứu DB 0.001s)** |
| **Nhất quán** | Kém (Ra kết quả ngẫu nhiên) | **Tuyệt đối (Luôn ra kết quả chuẩn)** |
| **Kiểm soát** | Khó (Hộp đen AI) | **Dễ dàng (Sửa Rule là xong)** |

---

## 🕳️ PHẦN VIII: NHỮNG "BẪY" KỸ THUẬT & CÁCH GIẢI QUYẾT

1.  **Bẫy Encoding Windows:** Khi in tiếng Việt bị crash. Giải quyết bằng `io.TextIOWrapper` UTF-8.
2.  **Bẫy N+1 Query:** Khi SELECT lặp trong vòng lặp. Giải quyết bằng kỹ thuật Pre-fetching targets.
3.  **Bẫy Sync Data:** Giữa Postgres và SQLite. Giải quyết bằng script migration tự động đồng bộ hóa cấu trúc bảng.

---

## 📘 PHẦN IX: CHEAT SHEET CHO DEVELOPER (THE SURVIVAL GUIDE)

*   **Lỗi 404?** Check `server.py` đã đăng ký router chưa.
*   **Dữ liệu rules không ăn?** Check hằng số `TABLE_OUTFIT_RULES`.
*   **Muốn thêm luật?** INSERT trực tiếp vào SQL bảng `chatbot_fashion_rules`.

---

## 🔬 PHẦN X: CHI TIẾT MA TRẬN HÒA SẮC (THE COLOR MATRIX)

| Màu TOP | Màu BOTTOM | Điểm Synergy | Nhận xét Stylist |
|:---|:---|:---|:---|
| Trắng | Đen | 30 | Tương phản tuyệt đối, cực kỳ sang trọng. |
| Be | Xanh navy | 25 | Thanh lịch cho công sở. |
| Xanh Jeans | Trắng | 28 | Năng động cho ngày thường. |

---

## 📜 PHẦN XI: NHẬT KÝ SCRIPT (THE SCRIPT AUDIT)

1.  **`batch-tags.py`**: Gán nhãn Product Line.
2.  **`sync-unified-rules.py`**: Đồng bộ 30+ quy tắc Premium.
3.  **`finalize-migration-drop-column.py`**: Xóa cột rác legacy.
4.  **`outfit_matcher_worker.py`**: Tính toán điểm số phối đồ.

---

## 🌟 PHẦN XII: TẦM NHÌN TƯƠNG LAI (THE NEXT FRONTIER)

1.  **Layering 3 lớp:** Phối 3 món thay vì 2.
2.  **Vòng đời tồn kho:** Tự động loại bỏ gợi ý nếu hết hàng.
3.  **Phối đồ theo thời tiết:** AI tự động đọc API thời tiết để đưa ra gợi ý.

---
**KẾT LUẬN:** 
Đây là pho sử thi đầy đủ nhất về hệ thống Canifa AI Stylist. Nó ghi lại mọi bài học, mọi thành công và mọi quyết định kiến trúc xương máu của chúng ta.

*Tài liệu này được bảo mật cho Canifa AI Team.*


{"ten_san_pham": "Áo nỉ bé gái đính patch trang trí", "mo_ta_chinh": "Form áo nỉ có mũ (hoodie) dáng regular fit thoải mái, cho bé tự do vận động mà vẫn giữ được nét năng động, đáng yêu. Thiết kế nhấn nhá với các chi tiết đính patch trang trí và hình in 'Smile' dễ thương, phối màu tươi sáng, hiện đại. Dáng áo suông vừa phải giúp che khuyết điểm nhẹ vùng bụng, tôn lên vẻ ngoài khỏe khoắn và thời trang cho các bé gái.", "chat_lieu": "Nguyên liệu nỉ cào lông cotton pha polyester mềm mại, dày dặn.", "tinh_nang_vai": "Mềm mại, ấm áp, bền đẹp, giữ form tốt, ít nhăn và hạn chế co rút sau khi giặt. Chất liệu nỉ cào lông mang lại cảm giác dễ chịu, ấm áp cho bé trong những ngày se lạnh.", "gioi_tinh": "Nữ", "phong_cach": "Năng động, Dễ thương, Urban Casual, Streetwear nhẹ nhàng cho bé.", "mua": "Thu Đông, Đầu Xuân.", "dip_mac": "Đi học hàng ngày · Dạo phố cuối tuần · Picnic cùng gia đình · Tham gia hoạt động ngoại khóa · Đi chơi cùng bạn bè.", "tags": "áo nỉ bé gái, áo hoodie trẻ em, áo nỉ đính patch, áo nỉ cute, áo nỉ ấm áp, thời trang trẻ em, canifa bé gái, áo nỉ thu đông.", "do_tuoi": "4-12 tuổi", "loi_song": "Dành cho những bé gái có lối sống năng động, thích khám phá, vui chơi ngoài trời và luôn tìm kiếm sự thoải mái nhưng vẫn muốn thể hiện cá tính riêng qua trang phục.", "tinh_cach": "Bé gái tự tin, yêu đời, năng động, có chút tinh nghịch và luôn muốn thể hiện phong cách đáng yêu của mình.", "ly_do_mua": "Giữ ấm hiệu quả và thoải mái tối đa cho bé trong thời tiết se lạnh. Thiết kế đáng yêu, cá tính giúp bé tự tin tỏa sáng. Chất liệu bền đẹp, dễ giặt ủi, mẹ hoàn toàn yên tâm.", "cross_sell": "Quần nỉ bé gái Canifa, Áo giữ nhiệt bé gái Canifa, Mũ len Canifa.", "hook_quang_cao": "Biến hóa phong cách cho bé gái nhà bạn chỉ với một chiếc áo nỉ đính patch siêu xinh!", "tagline": "Tỏa sáng đáng yêu, ấm áp ngày đông."}



==================================================
  BỘ MẶC NHÀ BÉ GÁI TAY XÒE IN HOA TIẾT
==================================================

── 📦 THÔNG TIN CƠ BẢN ──
  Tên sản phẩm: Bộ mặc nhà bé gái tay xòe in hoa tiết
  Tagline: Dễ thương, thoải mái, tràn ngập hoa hồng
  Mô tả chính: Bộ mặc nhà thiết kế dáng cơ bản, áo sát nách và quần đùi mang lại cảm giác thoải mái, thoáng khí cho bé. Họa tiết hoa tươi sáng tạo nên vẻ dễ thương, tràn ngập năng lượng tích cực. Định hình dáng gọn gàng, không gò bó, giúp bé tự tin và tự nhiên trong mọi hoạt động.
  Phong cách: Ngọt ngào, dễ thương
  Tags: bộ mặc nhà bé gái, bộ đồ ngủ trẻ em, bộ mặc nhà trẻ em, đồ ngủ hoa, bộ mặc nhà nữ

── 🧵 CHẤT LIỆU & BẢO QUẢN ──
  Chất liệu: Không xác định
  Tính năng vải: Không xác định
  Hướng dẫn bảo quản: Không xác định

── 🎯 ĐỐI TƯỢNG ──
  Độ tuổi: 3-7 tuổi
  Giới tính: Nữ
  Lối sống: Những bà mẹ quan tâm đến sự thoải mái và phong cách cho con gái, luôn tìm kiếm sản phẩm dễ thương nhưng không kém phần tiện lợi cho các hoạt động hàng ngày.
  Tính cách: Dễ thương, vui vẻ, năng động

── 📅 DỊP MẶC & STYLING ──
  Dịp mặc: Đi ngủ · Thư giãn tại nhà · Cùng bé ăn sáng · Tổ chức tiệc sinh nhật
  Gợi ý phối đồ:
    • Quần soóc + Áo phông → Thông thoáng, dễ di chuyển, phù hợp cho các hoạt động nhẹ nhàng
    • Quần soóc + Áo nỉ → Thêm ấm áp, lý tưởng cho buổi chiều mát
    • Quần soóc + Áo khoác nhẹ → Tăng tính phong cách, thích hợp cho thời tiết thay đổi
  Nguyên tắc phối đồ: Quần soóc giữ được độ thoải mái, không làm cản trở chuyển động; áo phông, áo nỉ và áo khoác nhẹ được phối cùng để tạo độ cân bằng giữa thoáng khí và ấm áp, đồng thời giữ cho bộ trang phục luôn dễ thương và thực dụng.
  Tránh phối cùng: Không phối cùng quần dài, áo khoác nỉ dày hoặc quần legging quá gợi hình; những lựa chọn này sẽ làm mất đi sự ngọt ngào và thoải mái của bộ mặc nhà.
  Gợi ý layering: Mùa chiều mát, thêm áo khoác nhẹ hoặc áo len gilet để giữ ấm mà không làm bé quá nóng.
  Mùa phù hợp: Mùa hè

── ❓ FAQ ──
  💬 Bộ mặc nhà này có vừa vặn cho bé không?
     → Bộ mặc nhà được thiết kế theo dạng basic fit, vừa vặn với phần thân trung bình của bé. Áo sát nách và quần đùi giúp bé cảm thấy thoải mái khi di chuyển mà không bị ràng buộc. Nếu bé có thân hình lớn hơn, bạn có thể chọn size lớn hơn một đơn vị.
  💬 Cách chọn size cho bé 4 tuổi?
     → Đối với bé 4 tuổi, chiều cao thường dao động từ 92-104 cm. Bạn nên chọn size 104 cm để đảm bảo không bị hẹp. Nếu bé có chiều cao ở mức trung bình 100 cm, size 104 cm vẫn là lựa chọn an toàn nhất.
  💬 Có thể phối cùng áo khoác không?
     → Có thể phối với áo khoác nhẹ hoặc áo len gilet để tăng độ ấm áp trong thời tiết mát. Hãy chọn áo khoác có màu pastel hoặc in hoa tương tự để giữ phong cách ngọt ngào và đồng bộ.

── 🛒 HỖ TRỢ BÁN HÀNG ──
  Hook quảng cáo: Bộ mặc nhà bé gái với họa tiết hoa, khiến bé luôn rạng rỡ mỗi ngày!
  Cross-sell: Quần soóc màu pastel, Áo phông in hoa, Bộ mặc nhà bé trai
  Lý do nên mua: Thiết kế dễ thương, màu sắc tươi sáng, thoải mái khi di chuyển và dễ dàng phối đồ với các món phụ kiện khác.
  Lưu ý chọn size: Chọn size dựa trên chiều cao của bé: 92-104 cm cho 3-4 tuổi, 110-122 cm cho 5-6 tuổi, 128-140 cm cho 7-8 tuổi. Nếu bé nằm giữa hai kích cỡ, hãy chọn size lớn hơn một chút để tránh hẹp.



==================================================
  QUẦN SOÓC BÉ TRAI
==================================================

── 📦 THÔNG TIN CƠ BẢN ──
  Chưa có dữ liệu.

── 🧵 CHẤT LIỆU & BẢO QUẢN ──
  Chưa có dữ liệu.

── 🎯 ĐỐI TƯỢNG ──
  Chưa có dữ liệu.

── 📅 DỊP MẶC & STYLING ──
  Chưa có dữ liệu.

── ❓ FAQ ──
  Chưa có dữ liệu.

── 🛒 HỖ TRỢ BÁN HÀNG ──
  Chưa có dữ liệu.
