# Gửi Tin Nhắn Hàng Loạt (Send Message)

## Tổng quan

Chức năng **Gửi Tin Nhắn Hàng Loạt** cho phép người bán Shopee gửi tin nhắn tự động đến nhiều khách hàng cùng lúc thông qua hệ thống chat Shopee. Đây là công cụ marketing giúp tiếp cận khách hàng cũ, gửi thông báo khuyến mãi, hoặc chăm sóc sau bán hàng.

**Yêu cầu:** Tài khoản trả phí (Premium).

---

## Quy trình sử dụng

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

```
1. Tạo chiến dịch → 2. Thu thập khách hàng → 3. Soạn nội dung & Gửi tin nhắn
```

---

## Bước 1: Tạo chiến dịch

**Đường dẫn:** `Shopee > Seller > Auto > Gửi tin nhắn`

1. Nhấn nút **"Tạo mới"**
2. Nhập tên chiến dịch (ví dụ: "Khuyến mãi tháng 3", "Chăm sóc KH cũ")
3. Nhấn **OK** để tạo

Mỗi chiến dịch được gắn với shop hiện tại và có các trạng thái:

| Trạng thái | Mô tả |
|------------|-------|
| `pending` | Chờ xử lý (mới tạo hoặc đã dừng) |
| `sending` | Đang gửi tin nhắn |
| `completed` | Đã gửi xong tất cả |
| `failed` | Gặp lỗi |

Tại danh sách chiến dịch, mỗi mục hiển thị:
- Tên chiến dịch và tên shop
- Tổng số khách hàng, số đã gửi, số lỗi
- Các nút: **Thu thập KH** | **Gửi tin nhắn** | **Xóa**

---

## Bước 2: Thu thập khách hàng

**Đường dẫn:** Nhấn nút **"Thu thập KH"** từ danh sách chiến dịch

Có **2 cách** thu thập khách hàng:

### Cách 1: Thu thập từ đánh giá đơn hàng

Hệ thống quét danh sách đánh giá (rating) của shop và lấy thông tin người mua.

**Bộ lọc:**
- **Số sao:** Chọn 1-5 sao (có thể chọn nhiều)
- **Tìm kiếm:** Lọc theo từ khóa
- **Thời gian bắt đầu / kết thúc:** Lọc theo khoảng thời gian đánh giá

Nhấn **"Tìm kiếm"** để bắt đầu quét. Hệ thống sẽ:
- Duyệt qua tối đa 100 trang đánh giá (mỗi trang 40 đánh giá)
- Loại bỏ trùng lặp tự động (dựa trên User ID)
- Bỏ qua khách hàng đã có trong chiến dịch

### Cách 2: Nhập thủ công (Import)

Dán danh sách khách hàng vào ô nhập liệu.

**Định dạng:** Mỗi dòng một khách hàng, phân cách bằng Tab, dấu phẩy, hoặc khoảng trắng.

```
UserID1    Tên khách hàng 1
UserID2    Tên khách hàng 2
UserID3
```

- Cột 1 (bắt buộc): User ID của khách hàng
- Cột 2 (tùy chọn): Tên khách hàng (nếu không có sẽ dùng User ID)

### Quản lý danh sách khách hàng

Sau khi thu thập, bảng danh sách hiển thị:

| Cột | Mô tả |
|-----|-------|
| Tên KH | Tên khách hàng |
| User ID | ID người dùng Shopee |
| Shop ID | ID shop đích |
| Kích hoạt | Checkbox bật/tắt (tắt = bỏ qua khi gửi) |
| Trạng thái | pending / sent / failed / skipped |
| Ngày tạo | Thời điểm thêm vào chiến dịch |
| Hành động | Nút xóa |

Popup log hiển thị thống kê: tổng quét, bỏ qua, thêm mới, tổng KH hiện có.

---

## Bước 3: Soạn nội dung & Gửi tin nhắn

**Đường dẫn:** Nhấn nút **"Gửi tin nhắn"** từ danh sách chiến dịch

### 3.1 Tổng quan thống kê

Hiển thị 5 chỉ số:
- **Tổng KH:** Tổng số khách hàng trong chiến dịch
- **Đã gửi:** Số KH đã gửi thành công
- **Bỏ qua:** Số KH bị bỏ qua (trùng lặp hoặc bị tắt)
- **Lỗi:** Số KH gửi thất bại
- **Chờ gửi:** Số KH chưa gửi

Thanh tiến độ hiển thị phần trăm hoàn thành.

### 3.2 Soạn nội dung tin nhắn

Hỗ trợ **5 loại nội dung**, có thể kết hợp nhiều loại trong 1 tin nhắn:

| Loại | Mô tả |
|------|-------|
| **Text** | Văn bản thuần (nhập trực tiếp) |
| **Sticker** | Nhãn dán Shopee (chọn từ bộ sưu tập) |
| **Image** | Hình ảnh (upload lên Shopee) |
| **Product** | Sản phẩm (tìm kiếm và chọn sản phẩm trong shop) |
| **Voucher** | Mã giảm giá (chọn từ danh sách voucher của shop) |

Mỗi tin nhắn gửi đi sẽ gửi **lần lượt từng nội dung** với khoảng cách 1 giây giữa mỗi nội dung.

### 3.3 Cấu hình gửi

| Thông số | Mô tả | Mặc định |
|----------|-------|----------|
| **Thời gian chờ giữa mỗi KH** (delayBetweenSeconds) | Số giây chờ giữa mỗi lần gửi cho KH khác nhau | 0 |
| **Tạm dừng sau N tin** (pauseAfterCount) | Sau bao nhiêu KH thì tạm dừng | 1 |
| **Thời gian tạm dừng** (pauseDurationSeconds) | Số giây tạm dừng sau khi đạt số lượng trên | 0 |
| **Thời gian chống trùng** (duplicateCooldownMinutes) | Bỏ qua KH đã nhận tin nhắn trong N phút gần đây | 0 |
| **Giới hạn số lượng gửi** (maxSendCount) | Số KH tối đa gửi trong 1 lần chạy (0 = không giới hạn) | 0 |

**Ví dụ cấu hình:**
> Với `delayBetweenSeconds=5`, `pauseAfterCount=10`, `pauseDurationSeconds=60`, `duplicateCooldownMinutes=1440`:
> Hệ thống gửi 10 KH, mỗi KH cách 5 giây, sau 10 KH nghỉ 60 giây, bỏ qua KH đã nhận tin trong 24 giờ.

### 3.4 Quy trình gửi

Khi nhấn **"Bắt đầu gửi"**, hệ thống:

1. Lưu cấu hình và nội dung
2. Lấy danh sách KH có trạng thái `pending` và `active = true`
3. Với mỗi KH:
   - Kiểm tra điều kiện bỏ qua (inactive, cooldown)
   - Lấy/tạo cuộc hội thoại (conversation) với KH
   - Kích hoạt cuộc hội thoại (set active)
   - Gửi từng nội dung tin nhắn (chờ 1 giây giữa mỗi nội dung)
   - Đóng cuộc hội thoại (set closed)
   - Cập nhật trạng thái KH thành `sent`
   - Lưu cache thời gian gửi (dùng cho chống trùng)
4. Áp dụng delay/pause theo cấu hình
5. Kiểm tra giới hạn maxSendCount

### 3.5 Các nút điều khiển

| Nút | Chức năng |
|-----|-----------|
| **Lưu** | Lưu cấu hình và nội dung (không gửi) |
| **Bắt đầu gửi** | Bắt đầu gửi tin nhắn |
| **Gửi lại KH bị bỏ qua** | Reset trạng thái KH `skipped` về `pending` để gửi lại |
| **Dừng** | Dừng quá trình gửi (hiện khi đang gửi) |

### 3.6 Nhật ký gửi

Hiển thị log realtime gồm:
- Gửi thành công (xanh)
- Gửi thất bại (đỏ)
- Bỏ qua / Chờ (vàng)

Mỗi log ghi nhận thời gian và nội dung chi tiết.

### 3.7 Bảng danh sách KH

Hiển thị chi tiết từng KH với các cột:
- Tên KH, User ID
- Trạng thái (pending/sent/failed/skipped)
- Thời gian gửi
- Nội dung đã gửi
- Log kết quả

---

## Trang Trực tiếp (Direct)

**Đường dẫn:** `Shopee > Seller > Auto > Gửi tin nhắn > Trực tiếp`

Trang này hiển thị kết nối Socket realtime đến hệ thống chat Shopee:
- Trạng thái kết nối (Connected/Disconnected)
- Thời gian kết nối
- Số lượng tin nhắn nhận được
- Log tin nhắn realtime (tên người gửi, nội dung, thời gian)

---

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

### Chiến dịch (Collect)

```
- name: Tên chiến dịch
- shopId: ID shop
- shopName: Tên shop
- status: pending | sending | completed | failed
- totalCustomers: Tổng số KH
- sentCount: Số đã gửi
- failedCount: Số lỗi
- skippedCount: Số bỏ qua
- configSend: Cấu hình gửi
- listContent: Danh sách nội dung tin nhắn
```

### Khách hàng (Customer)

```
- collectId: ID chiến dịch
- toUserId: User ID khách hàng
- toShopId: Shop ID đích
- customerName: Tên khách hàng
- source: Nguồn (orderRating | import)
- active: Kích hoạt (true/false)
- status: pending | sent | failed | skipped
- message: Nội dung đã gửi
- error: Thông tin lỗi
- sentAt: Thời gian gửi
```

---

## Lưu ý quan trọng

1. **Giới hạn Shopee:** Gửi quá nhiều tin nhắn trong thời gian ngắn có thể bị Shopee hạn chế. Nên cấu hình delay hợp lý.
2. **Chống trùng:** Sử dụng `duplicateCooldownMinutes` để tránh spam cùng 1 KH.
3. **Dữ liệu đồng bộ:** Dữ liệu được lưu trên PouchDB local và đồng bộ với CouchDB remote.
4. **Chỉ gửi cho shop hiện tại:** Các nút Thu thập/Gửi chỉ khả dụng khi shop trong chiến dịch trùng với shop đang đăng nhập.
