> ## Documentation Index
> Fetch the complete documentation index at: https://tomotek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tổng quan

Hệ thống **Mua bán sản phẩm** (Order) trên ILU PET là một phân hệ lõi, đóng vai trò kết nối trực tiếp giữa **Pet Owner** (người mua) và **Merchant** (người bán). Hệ thống cung cấp trải nghiệm mua sắm mượt mà từ khâu tìm kiếm sản phẩm, đặt hàng, thanh toán đến quản lý sau bán hàng, đồng thời tự động hóa việc tính toán tồn kho cho các Merchant.

## Sơ đồ luồng nghiệp vụ (Business Flow)

Luồng mua bán sản phẩm tuân theo một quy trình chặt chẽ giữa 3 phân hệ chính: Ứng dụng Pet Owner, Core System (Backend), và Cổng quản trị Merchant. Đơn hàng yêu cầu thanh toán bắt buộc qua QR Code trước khi chuyển cho Merchant xử lý.

```mermaid theme={null}
sequenceDiagram
    actor PO as Pet Owner
    participant Sys as Hệ thống ILU PET
    participant Pay as Cổng Thanh toán
    actor Mer as Merchant

    PO->>Sys: Tìm kiếm & Xem Sản phẩm
    Sys-->>PO: Hiển thị danh sách & Tồn kho
    PO->>Sys: Thêm vào Giỏ hàng
    PO->>Sys: Chọn mua & Checkout
    Sys->>Sys: Kiểm tra tồn kho (Final Check)
    alt Tồn kho không đủ
        Sys-->>PO: Báo lỗi & Quay lại Giỏ hàng
    else Tồn kho hợp lệ
        PO->>Sys: Xác nhận thanh toán
        Sys->>Sys: Tạo mã đơn hàng (Pending Payment)
        Sys-->>PO: Hiển thị mã QR Thanh toán
        
        PO->>Pay: Quét mã & Chuyển khoản
        Pay-->>Sys: Webhook thông báo thành công
        Sys->>Sys: Cập nhật trạng thái "Đã thanh toán"
        Sys->>Sys: Tách đơn theo Merchant
        Sys->>Sys: Trừ tồn kho (Reserve)
        Sys-->>PO: Đặt hàng thành công
        Sys->>Mer: Thông báo có đơn hàng mới (Chờ xác nhận)
    end

    Mer->>Sys: Xác nhận đơn
    Sys->>Sys: Trừ tồn kho thực tế (Deduct)
    Sys-->>PO: Thông báo "Đang chuẩn bị"
    
    Mer->>Sys: Đóng gói & Bàn giao vận chuyển
    Sys-->>PO: Thông báo "Đang giao"
    
    alt Giao thành công
        PO->>Sys: Nhấn "Đã nhận được hàng"
        Sys->>Sys: Cập nhật "Hoàn tất" & Hạch toán Doanh thu
        Sys-->>Mer: Đơn hàng hoàn tất
    else Giao thất bại / Huỷ
        Mer->>Sys: Huỷ đơn hàng
        Sys->>Sys: Hoàn lại số lượng vào tồn kho (Refund Stock)
        Sys-->>PO: Thông báo Huỷ & Xử lý hoàn tiền
    end
```

***

## Các trạng thái của Đơn hàng

Một đơn hàng sau khi được tạo sẽ trải qua các trạng thái tuần tự. Dưới đây là bảng tổng hợp các trạng thái và ý nghĩa:

| Trạng thái | Ý nghĩa | Vai trò chuyển trạng thái |
| :- | :- | :- |
| `Chờ thanh toán` | Đơn hàng vừa được tạo, đang chờ khách hàng quét mã QR do ILUPET sinh ra để thanh toán (Thời hạn 24 giờ. Hỗ trợ mua trước trả sau). | Hệ thống tự động (khi PO đặt hàng) |
| `Chờ xác nhận` | Đơn hàng đã được thanh toán thành công, chờ Merchant tiếp nhận. | Hệ thống tự động (khi nhận thanh toán) |
| `Đang chuẩn bị` | Merchant đã xác nhận đơn và đang tiến hành đóng gói. | Merchant nhấn "Xác nhận đơn" |
| `Đang giao` | Merchant đã bàn giao hàng cho đơn vị vận chuyển (Shipper). | Merchant nhấn "Đã giao cho Vận chuyển" |
| `Hoàn tất` | Khách đã nhận được hàng và kết thúc giao dịch. | Pet Owner xác nhận hoặc Hệ thống tự động |
| `Đã huỷ` | Đơn hàng bị huỷ do quá hạn thanh toán, khách hàng đổi ý, shop hết hàng, hoặc giao thất bại. | Pet Owner, Merchant, hoặc Hệ thống |

### Sơ đồ chuyển đổi trạng thái (State Machine)

```mermaid theme={null}
stateDiagram-v2
    [*] --> ChoThanhToan : Checkout
    
    ChoThanhToan --> ChoXacNhan : Thanh toán thành công
    ChoThanhToan --> DaHuy : Quá hạn 24 giờ / Khách huỷ
    
    ChoXacNhan --> DangChuanBi : Merchant Xác nhận đơn
    ChoXacNhan --> DaHuy : Pet Owner hoặc Merchant Huỷ
    
    DangChuanBi --> DangGiao : Merchant bàn giao Vận chuyển
    DangChuanBi --> DaHuy : Merchant Huỷ (Hết hàng/Sự cố)
    
    DangGiao --> HoanTat : Giao thành công / Khách xác nhận
    DangGiao --> DaHuy : Giao thất bại (Chuyển hoàn)
    
    DaHuy --> [*]
    HoanTat --> [*]
```

## Quy tắc nghiệp vụ quan trọng

* **Quy trình Thanh toán Bắt buộc:** Hệ thống không hỗ trợ COD. Mọi đơn hàng đều phải hoàn tất thanh toán qua mã QR tĩnh/động trước khi được ghi nhận là thành công và gửi cho Merchant. Nếu đơn hàng chưa thanh toán, giao dịch xem như chưa hoàn tất.
* **Cơ chế tách đơn (Split Order):** Sau khi thanh toán thành công, đối với Giỏ hàng chứa sản phẩm từ nhiều Merchant khác nhau, hệ thống sẽ tự động tách thành nhiều mã đơn hàng độc lập để từng Merchant xử lý riêng biệt.
* **Bảo lưu Tồn kho (Inventory Reservation):** Tồn kho được "Giữ chỗ" (Reserve) ngay khi thanh toán thành công. Tồn kho chính thức bị trừ (Deduct) vào các lô hàng theo nguyên tắc FEFO khi Merchant "Xác nhận đơn". Nếu đơn bị huỷ, tồn kho được hoàn lại ngay lập tức.
* **Chặn quay vòng trạng thái:** Luồng trạng thái của đơn hàng là **tuyến tính**. Tuyệt đối không cho phép quay ngược trạng thái từ `Đang giao` trở về `Đang chuẩn bị`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.