# 2. Kiến trúc & Luồng dữ liệu (Data Flow)

Kiến trúc của Stylist Engine tách biệt phần tính toán (Worker) và phần truy xuất (API). Luồng dữ liệu chính đi qua các bước: lấy thông tin sản phẩm nguồn (Anchor), tải luật từ Database, lọc, chấm điểm và xếp hạng.

## Luồng xử lý chi tiết (Sequence Diagram)

```mermaid
sequenceDiagram
    autonumber
    participant API as API Route (router.py)
    participant Engine as StylistEngine
    participant SR as StarRocks (Catalog)
    participant PG as PostgreSQL (Rules/Desc)

    API->>Engine: compute_dynamic_rule_matches(code)
    Engine->>SR: Lấy Product Catalog (Mã, Tên, Màu, Dòng SP, Giới tính)
    Engine->>PG: Lấy Ultra Descriptions (Tags: Phong cách, Dịp, Mùa, Vật liệu)
    Engine->>PG: Fetch Rules (Dựa vào Anchor Category & Gender)
    PG-->>Engine: Trả về danh sách Target Categories hợp lệ theo Occasion & Role
    
    loop Duyệt từng sản phẩm trong Catalog (Candidate)
        Engine->>Engine: 1. Hard Filter (Trẻ em vs Người lớn, Blacklist)
        Engine->>Engine: 2. Match Role & Rule (Candidate thuộc Target Cat?)
        Engine->>Engine: 3. Scoring (Color 30đ, Occasion 20đ, Material 10đ, Role 15đ)
    end
    
    Engine->>Engine: Deduplication (Top 3 per Role, đảm bảo đa dạng màu/kiểu)
    Engine->>PG: Lưu kết quả ai_matches (JSONB) vào ultra_descriptions
    Engine-->>API: Trả về Outfit Matches theo Occasion & Role
```

## Các thành phần chính
1. **StarRocks Catalog (`magento_product_dimension_with_text_embedding`)**: Chứa metadata cơ bản (màu sắc gốc, giá, tên).
2. **PostgreSQL Rules (`chatbot_fashion_rules`)**: Nơi định nghĩa các luật cứng, ví dụ: "Áo Polo (Nam)" có thể phối với "Quần Khaki" trong dịp "Đi làm".
3. **Ultra Descriptions**: Bảng lưu trữ mô tả NLP và `ai_matches` đã được tính toán.