> ## 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.

# US-MER-13: Xử lý đơn hàng

> Merchant tiếp nhận, cập nhật trạng thái và xử lý các đơn hàng

> [!NOTE]
>
> **Cập nhật v.1.6.0:** Bổ sung luồng Xử lý Yêu cầu Trả hàng & Hoàn tiền vào quy trình Xử lý Đơn hàng E-commerce.

Là một Merchant, tôi muốn theo dõi và xử lý các đơn mua sản phẩm từ khách hàng, từ khâu tiếp nhận đến khi giao hàng thành công, để đảm bảo đơn hàng được hoàn thành chính xác và tồn kho được cập nhật kịp thời.

## Acceptance Criteria (AC)

| Feature | Acceptance Criteria | Ràng buộc & Ghi chú |
| :- | :- | :- |
| **1. Danh sách & Chi tiết đơn hàng** | • Hiển thị danh sách các đơn hàng phân loại theo Tab: Chờ xác nhận, Đang chuẩn bị, Đang giao, Hoàn tất, Đã huỷ. • **Chi tiết hiển thị:** Mã đơn, Ngày tạo, Thông tin người nhận, Danh sách sản phẩm (Tên, Số lượng, Đơn giá) và Lời nhắn từ khách. | • Tự động refresh (hoặc có icon reload) để cập nhật đơn mới. • Tất cả đơn hàng hiển thị cho Merchant đều đã được khách hàng thanh toán thành công qua QR Code. |
| **2. Xác nhận đơn hàng** | • **Chuyển trạng thái:** Từ `Chờ xác nhận` -> `Đang chuẩn bị`. • Hệ thống chốt số lượng và tiến hành trừ tồn kho thực tế (Deduct) trong hệ thống quản lý kho. | • **Nút Action:** "Xác nhận đơn". • Gửi Push Notification cho Pet Owner: "Shop đã xác nhận đơn hàng của bạn". |
| **3. Bàn giao vận chuyển** | • **Kịch bản ViettelPost:** Nhấn `[Tạo mã vận đơn]`. Hệ thống đẩy API gọi bưu tá đến lấy. Từ lúc này, các nút chuyển trạng thái tiếp theo bị **Khóa (Disabled)**. • **Kịch bản Tự giao:** Merchant tự điều phối và nhấn `[Chuyển sang Đang giao]`. | • Không gửi Push Notification khi giao cho Shipper (để tránh rác thông báo theo cấu hình `US-OWN-26`). |
| **4. Hoàn tất đơn hàng** | • **Kịch bản ViettelPost:** Trạng thái đơn hàng tự động chuyển sang `Hoàn tất` dựa trên **API Callback (Webhook)** từ hệ thống ViettelPost trả về. • **Kịch bản Tự giao:** Merchant tự tay nhấn nút `[Xác nhận giao thành công]`. | • Gửi Push Notification cho Pet Owner: "Đơn hàng đã giao thành công". • Kích hoạt quy trình hạch toán doanh thu tạm tính chờ giải ngân. |
| **5. Huỷ đơn hàng** | • Chỉ cho phép huỷ khi đơn ở trạng thái `Chờ xác nhận` hoặc `Đang chuẩn bị`. • Bắt buộc nhập hoặc chọn lý do huỷ (VD: Hết hàng, Sai thông tin giá, Sự cố vận hành). | • **Nút Action:** "Huỷ đơn hàng" (Màu đỏ/Cảnh báo). • Không cho phép huỷ khi đã chuyển sang "Đang giao". |
| **6. Trả hàng / Hoàn tiền** | • Nếu Pet Owner yêu cầu trả hàng trong thời gian quy định (sau khi nhận hàng), đơn hàng sẽ chuyển sang luồng xử lý Trả hàng (`US-MER-31`). • Tiền đang bị giam (Escrow) sẽ không được giải ngân cho Merchant cho đến khi tranh chấp được xử lý. | • Luồng này có sự tham gia của Admin làm Trọng tài (`US-ADM-11`). |

## Luồng ngoại lệ (Exception Flows) & Validations

* **Lỗi đồng bộ kho (Inventory Mismatch):** Nếu khi Merchant nhấn "Xác nhận đơn" nhưng tồn kho trong Database bị âm (do lỗi hệ thống hoặc thao tác trước đó), hệ thống chặn thao tác và báo lỗi: *"Tồn kho không đủ để xác nhận đơn hàng này. Vui lòng cập nhật lại kho hoặc huỷ đơn."*
* **Huỷ đơn hàng (Hoàn tiền):** Nếu Merchant huỷ đơn hàng do lỗi vận hành hoặc hết hàng, hệ thống phải ghi nhận để Admin tiến hành quy trình hoàn tiền (Refund) cho khách hàng. Trạng thái đơn chuyển sang `Đã huỷ (Chờ hoàn tiền)`. Thông báo rõ cho Merchant: *"Đơn hàng đã được thanh toán, hệ thống sẽ tiến hành hoàn tiền cho người mua."*

## Quy tắc nghiệp vụ (Business Rules)

1. **Rule 1: Hoàn tồn kho (Stock Restoration)**: Bất kỳ lúc nào đơn hàng chuyển sang trạng thái `Đã huỷ`, hệ thống **bắt buộc** phải cộng lại số lượng sản phẩm tương ứng vào tổng số lượng tồn kho khả dụng của sản phẩm đó.
2. **Rule 2: Chặn quay vòng trạng thái**: Flow trạng thái là tuyến tính (một chiều). Không cho phép Merchant lùi trạng thái (ví dụ: Không thể chuyển từ `Đang giao` quay ngược về `Đang chuẩn bị`).


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