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

Pipeline hoạt động dựa trên cơ chế StateGraph (LangGraph), mỗi node thực hiện một nhiệm vụ chuyên biệt nhằm kiểm soát độ chính xác của AI.

```mermaid
sequenceDiagram
    participant n8n as n8n / Dashboard
    participant API as Ultra Desc API
    participant LangGraph as Agent (LangGraph)
    participant SR as StarRocks (Ground Truth)
    participant Vision as Vision LLM (Gemini/Llama)
    participant Writer as Writer LLM (GPT-OSS-120B)
    participant DB as PostgreSQL (dashboard_canifa)

    n8n->>API: POST /api/product-desc/generate (hoặc /batch-generate)
    API->>LangGraph: run_ultra_description_agent(magento_code)
    
    rect rgb(240, 248, 255)
        note right of LangGraph: Phase 1: Fetch Ground Truth
        LangGraph->>SR: Lấy thông tin SP, Màu, Tuổi, Bảng Size, Mô tả gốc
        SR-->>LangGraph: Dữ liệu thực tế (Không ảo giác)
    end
    
    rect rgb(240, 255, 240)
        note right of LangGraph: Phase 2: Vision Analysis
        LangGraph->>Vision: Phân tích ảnh sản phẩm (base64)
        Vision-->>LangGraph: JSON (Thiết kế, họa tiết, hình thức)
    end
    
    rect rgb(255, 250, 240)
        note right of LangGraph: Phase 3: Writing & Size Guide
        LangGraph->>Writer: Prompt tổng hợp (DB + Vision)
        Writer-->>LangGraph: JSON mô tả siêu chi tiết (28 fields)
        LangGraph->>Writer: Sinh `luu_y_size` từ bảng Size thực tế
        Writer-->>LangGraph: Lời khuyên Size chuẩn xác
    end

    rect rgb(255, 240, 245)
        note right of LangGraph: Phase 4: Self-Review
        LangGraph->>Writer: Kiểm tra lại tên, giới tính, chất liệu
        Writer-->>LangGraph: JSON đã được sửa lỗi
    end

    LangGraph->>DB: Upsert vào `ultra_descriptions`
    DB-->>LangGraph: Trạng thái (Pending / Approved)
    LangGraph-->>API: Kết quả cuối cùng (JSON + Clean Text)
    API-->>n8n: Thành công
```