# Tự Động Đánh Giá Đơn Hàng (Rating Order)

## Tổng quan

Chức năng **Tự Động Đánh Giá Đơn Hàng** cho phép người bán Shopee tự động đánh giá 5 sao cho tất cả đơn hàng đã hoàn thành (trạng thái "Completed"). Ngoài ra, có thể kèm theo gửi tin nhắn chat đến khách hàng sau khi đánh giá.

**Đường dẫn:** `Shopee > Seller > Auto > Đánh giá đơn hoàn thành`

**Route:** `/shopee/seller/auto/rating-order`

**Yêu cầu:** Tài khoản trả phí (Premium). Gói VIP Plus cho phép đánh giá không giới hạn; gói thường sẽ bị dừng sau lần đánh giá đầu tiên.

---

## Quy trình sử dụng

Quy trình gồm **3 bước chính**:

```
1. Nhập nội dung đánh giá → 2. Chọn trang bắt đầu → 3. Chạy tự động
```

### Bước 1: Nhập nội dung đánh giá

Điền nội dung đánh giá vào ô **"Nội dung đánh giá"**. Mặc định hệ thống sẽ điền sẵn:

> Shop chân thành cảm ơn quý khách

Nội dung này sẽ được gửi kèm đánh giá 5 sao cho mỗi đơn hàng.

### Bước 2: Nhập tin nhắn gửi khách hàng (tùy chọn)

Điền nội dung vào ô **"Tin nhắn gửi khách hàng"**. Đây là tin nhắn chat sẽ được gửi đến khách hàng sau khi đánh giá đơn hàng. Nếu để trống, hệ thống sẽ bỏ qua bước gửi tin nhắn.

### Bước 3: Chọn trang bắt đầu và chạy

- Chọn **trang bắt đầu** quét đơn hàng (mặc định là trang 1). Số trang tối đa được tính dựa trên tổng số đơn hoàn thành chia cho 40 (số đơn mỗi trang).
- Nhấn nút **"Chạy tự động"** để bắt đầu.

### Quy trình xử lý tự động

Khi nhấn "Chạy tự động", hệ thống thực hiện:

1. Lấy danh sách đơn hàng hoàn thành theo từng trang (mỗi trang 40 đơn)
2. Lọc các đơn hàng có thể đánh giá (`is_order_ratable = true`)
3. Với mỗi đơn hàng hợp lệ:
   - Gửi đánh giá 5 sao kèm nội dung đã nhập
   - Gửi tin nhắn chat cho khách hàng (nếu có nhập nội dung tin nhắn)
   - Ghi log kết quả (thành công hoặc lỗi)
   - Chờ 200ms trước khi xử lý đơn tiếp theo
4. Sau mỗi trang, chờ 15 giây trước khi chuyển sang trang kế tiếp
5. Dừng khi không còn đơn hàng nào hoặc đã quét hết

Kết quả được hiển thị realtime trong phần **"Tiến trình"** kèm theo số đơn đã đánh giá thành công.

---

## Cấu hình

### Thông số giao diện

| Thông số | Mô tả | Giá trị |
|----------|-------|---------|
| **Nội dung đánh giá** | Nội dung comment kèm đánh giá | Mặc định: "Shop chân thành cảm ơn quý khách" |
| **Tin nhắn gửi khách hàng** | Tin nhắn chat gửi sau đánh giá | Tùy chọn, để trống = không gửi |
| **Trang bắt đầu** | Trang đơn hàng bắt đầu quét | Mặc định: 1, tối đa tùy tổng đơn |

### Thông số hệ thống (cố định)

| Thông số | Giá trị | Mô tả |
|----------|---------|-------|
| `ratingOrder.star` | 5 | Luôn đánh giá 5 sao |
| `queryOrder.limit` | 40 | Số đơn hàng mỗi trang |
| `ratingHandler.sleepPerList` | 15000ms (15s) | Thời gian chờ giữa mỗi trang |
| `ratingHandler.sleepPerRating` | 200ms | Thời gian chờ giữa mỗi đơn hàng |
| Concurrency | 1 | Xử lý tuần tự, không song song |

---

## Cấu trúc dữ liệu

### ratingOrder - Cấu hình đánh giá

```
- text: Nội dung comment đánh giá (string)
- star: Số sao đánh giá (number, cố định = 5)
```

### chatOrder - Cấu hình tin nhắn

```
- text: Nội dung tin nhắn gửi khách hàng (string, để trống = không gửi)
```

### ratingHandler - Trạng thái xử lý

```
- loading: Đang chạy hay không (boolean)
- log: Danh sách log tiến trình (string[])
- sent: Số đơn đã đánh giá thành công (number)
- sleepPerList: Thời gian chờ giữa mỗi trang, ms (number)
- sleepPerRating: Thời gian chờ giữa mỗi đơn, ms (number)
```

### queryOrder - Tham số phân trang

```
- limit: Số đơn mỗi trang (number, = 40)
- page: Trang hiện tại (number)
- setensel: Sentinel token phân trang (string)
- total: Tổng số đơn hoàn thành (number)
- isStopped: Đã dừng do hết đơn (boolean)
- isError: Có lỗi khi fetch (boolean)
```

### API sử dụng

| API | Endpoint | Mô tả |
|-----|----------|-------|
| `getListOrderIndex` | `POST /api/v3/order/search_order_list_index` | Lấy danh sách index đơn hàng hoàn thành (tabId = 500) |
| `getListOrderCard` | `POST /api/v3/order/get_order_list_card_list` | Lấy chi tiết đơn hàng từ index |
| `ratingOrderCompleted` | `POST /api/v3/order/rate_order/` | Gửi đánh giá cho đơn hàng |
| `sendChatMessage` | Chat API | Gửi tin nhắn chat đến khách hàng |

### Payload đánh giá (rate_order)

```json
{
  "order_id": 123456789,
  "rate_star": 5,
  "rate_comment": "Shop chân thành cảm ơn quý khách"
}
```

### Điều kiện lọc đơn hàng

Chỉ đánh giá đơn hàng thỏa mãn:
- Thuộc tab "Completed" (tabId = 500)
- Có `order_ext_info.is_order_ratable = true`

---

## Lưu ý quan trọng

1. **Yêu cầu gói VIP Plus:** Nếu tài khoản không phải gói VIP Plus, hệ thống sẽ dừng sau lần đánh giá đầu tiên và hiển thị cảnh báo.
2. **Đánh giá cố định 5 sao:** Hiện tại hệ thống chỉ hỗ trợ đánh giá 5 sao, không thể thay đổi số sao từ giao diện.
3. **Giới hạn Shopee:** Đánh giá quá nhiều đơn trong thời gian ngắn có thể bị Shopee hạn chế. Hệ thống đã tích hợp delay 200ms/đơn và 15s/trang để giảm thiểu rủi ro.
4. **Không thể hoàn tác:** Sau khi đánh giá, không thể xóa hoặc thay đổi nội dung đánh giá trên Shopee.
5. **Tin nhắn chat tùy chọn:** Tin nhắn gửi khách hàng là tùy chọn. Nếu không cần gửi tin nhắn, để trống ô "Tin nhắn gửi khách hàng".
6. **Phân trang tự động:** Hệ thống sử dụng sentinel token để phân trang, đảm bảo quét đúng thứ tự và không bỏ sót đơn hàng.
7. **Log tiến trình:** Theo dõi tiến trình qua phần "Tiến trình" với các ký hiệu trạng thái rõ ràng (thành công / lỗi / bỏ qua).
