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

Kiến trúc chia làm hai luồng chính: truy vấn dữ liệu hiệu năng từ StarRocks và kiểm tra tồn kho thời gian thực từ ERP.

## Luồng xử lý kiểm tra tồn kho (Stock Check Flow)
Khi user hoặc Agent cần kiểm tra tồn kho của một dòng sản phẩm (base code), hệ thống tự động bung (expand) ra thành các SKU cụ thể (có size) qua StarRocks, sau đó query tồn kho ERP song song.

```mermaid
sequenceDiagram
    participant Client as Client/Agent
    participant API as FastAPI (stock_route.py)
    participant SR as StarRocks (DM)
    participant ERP as Canifa Stock API

    Client->>API: POST /api/stock/check (codes="6ST25W005")
    Note over API: Phân loại: Full SKU hay Base Code?
    API->>SR: SELECT size_scale, product_color_code...
    SR-->>API: Trả về danh sách variants (colors, sizes)
    Note over API: Expand thành list: 6ST25W005-L, 6ST25W005-XL...
    Note over API: Chunk list thành các batch (default 50 SKUs/batch)
    API->>ERP: asyncio.gather( [Chunk 1], [Chunk 2], ... )
    ERP-->>API: Trả về stock data cho từng Chunk
    Note over API: Gộp kết quả, xử lý lỗi từng chunk
    API-->>Client: Trả về Stock JSON Payload
```

## Luồng xử lý Product Performance
```mermaid
sequenceDiagram
    participant Client as Web Dashboard
    participant API as FastAPI (product_route.py)
    participant SR as StarRocks (DM)

    Client->>API: GET /api/products/list?search=ao thun&sort=quantity_sold
    Note over API: Xử lý đồng nghĩa: "ao thun" -> "Áo phông"
    Note over API: Tính toán Relevance Score linh hoạt
    API->>SR: SELECT internal_ref_code, ANY_VALUE(product_name), MAX(quantity_sold)...
    SR-->>API: Kết quả query (siêu tốc)
    API-->>Client: Trả về JSON (products, pagination, stats)
```
