# HƯỚNG DẪN SỬ DỤNG BOT MORETECH

> Bản chia sẻ nội bộ cho nhân viên và Sale. Cập nhật theo source ngày 16/09/2026.

## 1. Quy ước chung

- Prefix hiện tại của bot là dấu chấm: `.`
- Nội dung trong `< >` là bắt buộc phải thay, ví dụ `<mã sản phẩm>`.
- Nội dung trong `[ ]` là không bắt buộc.
- Mã sản phẩm không phân biệt chữ hoa/chữ thường. Khi tìm kiếm, bot chuẩn hóa dấu cách, `_` và `-`.
- Các ví dụ dùng mã `chatgpt`; hãy thay bằng mã thực tế lấy từ `.mua`.
- Nếu bot báo thao tác quá nhanh, chờ 1-3 giây rồi gửi lại. Không gửi liên tục cùng một lệnh.
- Hầu hết câu trả lời của bot kết thúc bằng khối `👉 Bước tiếp theo`: đó là lệnh nên dùng tiếp theo đúng quy trình, copy và sửa phần trong `< >` là dùng được.

## 2. Bản rút gọn để ghim trong nhóm Sale

```text
🛍 LỆNH BÁN HÀNG MORETECH

.menu                         Xem menu bán hàng
.mua                          Xem danh sách mã sản phẩm
.mua <mã>                    Xem các gói của sản phẩm
.mua <mã> <gói>              Chọn một gói cụ thể
.bg                            Xem bảng giá trang 1
.bg next                       Sang trang tiếp theo
.bg <trang>                    Mở trang bất kỳ
.bg <mã>                       Tìm bảng giá sản phẩm
.km [mã]                       Xem khuyến mãi
.stk <số tiền> [nội dung]     Tạo QR thanh toán

⚡ MẪU TRẢ LỜI DÀNH CHO SALE

.mau                           Xem danh sách mẫu
.mau xem <mẫu> [tham số]      Xem trước, không gửi khách
.mau chao                      Chào khách
.mau bg <mã> [gói]            Báo giá
.mau tt <số tiền> [nội dung]  Gửi QR và hướng dẫn
.mau xn [số tiền]              Xác nhận thanh toán
.mau xl                        Báo đang xử lý
.mau giao                      Báo đã bàn giao
.mau bh                        Tiếp nhận bảo hành
.mau gh <mã> <gói>            Mời gia hạn
.mau hh <mã> [gói]            Báo tạm hết hàng
.mau km [mã]                   Gửi khuyến mãi
.mau ct                        Cảm ơn khách

Mẹo: Reply đúng tin nhắn của khách trước khi dùng .mau.
```

## 3. Bảng lệnh dùng hằng ngày

| Lệnh | Chức năng | Mục đích sử dụng | Ví dụ |
|---|---|---|---|
| `.menu` | Mở menu bán hàng. | Bắt đầu khi chưa nhớ lệnh. | `.menu` |
| `.menu shop` | Mở menu bán hàng; `sale` và `banhang` cũng hợp lệ. | Gửi menu hướng dẫn cho khách hoặc team. | `.menu shop` |
| `.mua` | Liệt kê mã của toàn bộ sản phẩm. | Tìm đúng mã trước khi tư vấn. | `.mua` |
| `.mua <mã>` | Hiện các gói của một sản phẩm. | Xem giá và trạng thái còn bán hoặc tạm ngưng. | `.mua chatgpt` |
| `.mua <mã> <gói>` | Hiện chi tiết một gói. | Lấy giá và cú pháp QR được bot gợi ý. | `.mua chatgpt 2` |
| `.mua<mã>` | Dạng viết nhanh của `.mua <mã>`. | Tra nhanh một mã sản phẩm. | `.muachatgpt` |
| `.bg` | Mở trang đầu của bảng giá. | Duyệt bảng giá mà không vượt giới hạn tin nhắn Zalo. | `.bg` |
| `.bg next` | Mở trang tiếp theo của riêng người đang xem. | Tiếp tục duyệt bảng giá. Có thể dùng `tiep` hoặc `tiếp`. | `.bg next` |
| `.bg <trang>` | Mở trực tiếp một trang. | Quay lại hoặc nhảy đến trang cần xem. | `.bg 2` |
| `.bg page <trang>` | Buộc bot hiểu số nhập vào là số trang. | Dùng khi có mã sản phẩm dạng số. Có thể thay `page` bằng `trang`. | `.bg page 2` |
| `.bg <mã>` | Hiện bảng giá riêng của một sản phẩm. | Tìm nhanh mà không cần lật từng trang. | `.bg chatgpt` |
| `.km` | Hiện tất cả khuyến mãi còn hiệu lực. | Kiểm tra ưu đãi trước khi tư vấn hoặc chốt đơn. | `.km` |
| `.km <mã>` | Lọc khuyến mãi theo sản phẩm. | Xác nhận sản phẩm cụ thể có ưu đãi hay không. | `.km chatgpt` |
| `.stk` | Hiện thông tin thanh toán đã cấu hình, không tạo QR động. | Kiểm tra thông tin nhận tiền. | `.stk` |
| `.stk <số tiền> [nội dung]` | Tạo ảnh QR VietQR có số tiền và mã tham chiếu riêng. | Gửi QR đúng đơn hàng cho khách. | `.stk 100k CHATGPT-2` |

### Cách nhập số tiền

Bot hỗ trợ các dạng phổ biến:

```text
100000
100.000
100,000
100k
1.5tr
```

Khi tạo QR, bot tự chuẩn hóa nội dung chuyển khoản và thêm mã tham chiếu bắt đầu bằng `MT`. Không xóa hoặc tự sửa mã này khi hướng dẫn khách chuyển khoản.

## 4. Mẫu trả lời nhanh dành cho Sale

Lệnh `.mau` chỉ dành cho tài khoản Sale hoặc Admin đã được cấu hình quyền.

| Lệnh | Chức năng | Mục đích sử dụng |
|---|---|---|
| `.mau` | Hiện các mẫu đang bật. | Xem nhanh danh sách mẫu trả lời. |
| `.mau ds` | Hiện toàn bộ mẫu; `list` cũng hợp lệ. | Tra cứu lệnh mẫu. |
| `.mau ds <nhóm>` | Lọc mẫu theo nhóm. | Chỉ xem mẫu bán hàng, thanh toán, đơn hàng hoặc hậu mãi. |
| `.mau xem <mẫu> [tham số]` | Xem trước nội dung, không gửi vào tin khách và không tạo QR. | Kiểm tra câu chữ trước khi gửi. `preview` cũng hợp lệ. |
| `.mau <mẫu> [tham số]` | Gửi mẫu thật. | Trả lời khách theo đúng giai đoạn bán hàng. |

Các nhóm mẫu hợp lệ: `ban_hang`, `thanh_toan`, `don_hang`, `hau_mai`.

| Mẫu | Alias ngắn | Cú pháp | Khi sử dụng |
|---|---|---|---|
| Chào khách | - | `.mau chao` | Mở đầu cuộc tư vấn và hỏi nhu cầu. |
| Báo giá | `bg` | `.mau baogia <mã> [gói]` | Gửi toàn bộ gói hoặc một gói cụ thể. |
| Thanh toán | `tt`, `ck` | `.mau thanhtoan <số tiền> [nội dung]` | Tạo QR và gửi hướng dẫn thanh toán. |
| Xác nhận thanh toán | `xn` | `.mau xacnhan [số tiền]` | Báo đã nhận được tiền của khách. |
| Đang xử lý | `xl` | `.mau dangxuly` | Cập nhật trạng thái đơn đang xử lý. |
| Đã giao | `giao` | `.mau dagiao` | Báo đã kích hoạt hoặc bàn giao sản phẩm. |
| Bảo hành | `bh` | `.mau baohanh` | Thu thập thông tin để tiếp nhận bảo hành. |
| Gia hạn | `gh` | `.mau giahan <mã> <gói>` | Mời khách gia hạn một gói đang bán. |
| Tạm hết hàng | `hh` | `.mau hethang <mã> [gói]` | Báo gói tạm ngưng và hướng khách sang lựa chọn khác. |
| Khuyến mãi | `km` | `.mau khuyenmai [mã]` | Gửi ưu đãi đang còn hiệu lực. |
| Cảm ơn | `ct` | `.mau camon` | Chăm sóc khách sau khi hoàn tất đơn. |

### Cách dùng `.mau` đúng

1. Reply trực tiếp tin nhắn của khách.
2. Nhập lệnh `.mau ...` tương ứng.
3. Bot trả mẫu vào đúng tin nhắn khách đã gửi.

Nếu không reply tin khách, bot sẽ trả lời ngay vào tin lệnh của Sale. Riêng `.mau xem ...` luôn chỉ xem trước tại tin lệnh và không tạo QR.

Với mẫu thanh toán, bot tạo QR trước. Nếu QR lỗi, bot không gửi tiếp phần hướng dẫn thanh toán để tránh khách nhận thông tin thiếu.

## 5. Lệnh tra cứu trong nhóm đã được bot duyệt

| Lệnh | Chức năng | Mục đích sử dụng |
|---|---|---|
| `.uid` | Lấy UID của chính mình. | Gửi UID cho Admin khi cần cấp quyền Sale. |
| `.uid @người_dùng` | Lấy UID người đầu tiên được tag. | Hỗ trợ Admin xác định đúng tài khoản cần cấp quyền. |
| `.info [@người_dùng/UID/SĐT]` | Tạo ảnh thông tin tài khoản Zalo. Alias: `.i4`, `.in4`. | Tra cứu thông tin tài khoản khi cần hỗ trợ. |
| `prefix` | Xem prefix hiện tại, không cần dấu chấm. | Kiểm tra khi bot không nhận lệnh. |

Các lệnh trong mục này chỉ hoạt động đúng khi nhóm đã được Admin duyệt, ngoại trừ `prefix`.

## 6. Gửi thông báo hàng loạt dành cho Admin

Lệnh `.thongbao` chỉ dành cho Admin. Bot gửi một ảnh kèm nội dung tuần tự, lưu kết quả sau từng nhóm và không tự gửi lại nhóm đã thành công.

| Lệnh | Chức năng |
|---|---|
| `.thongbao` | Xem hướng dẫn nhanh. |
| Reply ảnh + `.thongbao tao [2-300] <nội dung>` | Tạo chiến dịch; số đầu tiên là thời gian nghỉ, mặc định 5 giây. |
| `.thongbao ds` | Xem tên và ID các nhóm bot đang tham gia. |
| `.thongbao phamvi all` | Chọn toàn bộ nhóm bot đang tham gia. |
| `.thongbao phamvi nhom <ID1,ID2,...>` | Chọn các nhóm cụ thể. |
| `.thongbao nghi <2-300>` | Đổi thời gian nghỉ giữa hai lần gửi. |
| `.thongbao xem` | Xem lại ảnh, nội dung, phạm vi và tiến độ. |
| `.thongbao gui` | Tạo mã xác nhận gửi; chưa gửi ngay. |
| `.thongbao xacnhan <mã>` | Bắt đầu gửi sau khi Admin kiểm tra lần cuối. |
| `.thongbao trangthai` | Xem nhóm thành công, thất bại, bị khóa hoặc chưa rõ kết quả. |
| `.thongbao retry` | Tạo mã xác nhận để thử lại riêng nhóm thất bại chắc chắn. |
| `.thongbao xuly <ID> dagui` | Xác nhận thủ công nhóm chưa rõ đã nhận; bot khóa nhóm này, không gửi lại. |
| `.thongbao xuly <ID> chuagui` | Xác nhận thủ công nhóm chưa rõ chưa nhận; đưa nhóm vào danh sách retry. |
| `.thongbao huy` | Hủy bản nháp hoặc yêu cầu dừng trước nhóm kế tiếp. |

### Quy trình gửi toàn bộ nhóm

```text
Reply ảnh khuyến mãi -> .thongbao tao 10 Nội dung chương trình khuyến mãi
.thongbao phamvi all
.thongbao xem
.thongbao gui
.thongbao xacnhan <mã bot vừa cấp>
```

### Quy trình gửi một số nhóm

```text
.thongbao ds
Reply ảnh khuyến mãi -> .thongbao tao 15 Nội dung chương trình khuyến mãi
.thongbao phamvi nhom 123456789,987654321
.thongbao xem
.thongbao gui
.thongbao xacnhan <mã bot vừa cấp>
```

Bot tự bỏ qua nhóm khóa quyền nhắn tin nếu tài khoản bot không phải chủ nhóm hoặc phó nhóm. Sau mỗi lượt, bot báo tổng thành công, thất bại, bị khóa và chưa rõ kết quả.

Nhóm “chưa rõ kết quả” xuất hiện khi Zalo có thể đã nhận tin nhưng bot không nhận được phản hồi xác nhận. Bot cố ý không retry các nhóm này để tránh khách nhận trùng. Admin phải mở nhóm kiểm tra rồi dùng `dagui` hoặc `chuagui` trước.

Không thể tạo chiến dịch mới nếu chiến dịch cũ còn nhóm “chưa rõ kết quả”, kể cả sau khi bấm hủy. Quy tắc này ngăn một chiến dịch mới vô tình gửi trùng vào các nhóm chưa được đối chiếu.

Bot không cho hai chiến dịch gửi cùng lúc. Mã xác nhận chỉ dùng một lần và hết hạn sau 10 phút.
Auto restart định kỳ sẽ được tạm hoãn khi chiến dịch đang gửi; nếu Admin chủ động restart bot, dùng `.thongbao trangthai` rồi `.thongbao gui` để tiếp tục các nhóm còn an toàn.

Bot lưu lịch sử và khóa chống gửi trùng trong `modules/cache`. Hosting phải cho phép ghi vào thư mục này; không xóa các file `thongbao_state.json`, `.lock` hoặc `.run.lock` khi chiến dịch đang chạy. Nếu có hai process bot cùng khởi động, chỉ một process được phép gửi `.thongbao` tại một thời điểm.

## 7. Quy trình sử dụng đề xuất

### Tìm sản phẩm và tạo QR

```text
.mua
.mua chatgpt
.mua chatgpt 2
.stk 100k CHATGPT-2
```

Sale cần xác nhận tồn kho, giá cuối cùng và khuyến mãi trước khi gửi QR.

### Xem bảng giá nhiều trang

```text
.bg
.bg next
.bg next
```

Hoặc mở thẳng trang hay sản phẩm:

```text
.bg 2
.bg page 2
.bg chatgpt
```

Vị trí của `.bg next` được lưu riêng cho từng người trong từng cuộc trò chuyện. Người khác xem bảng giá không làm đổi trang của bạn.

### Sale tư vấn và chốt đơn

```text
Reply tin khách -> .mau chao
Reply tin khách -> .mau bg chatgpt 2
Reply tin khách -> .mau tt 100k CHATGPT-2
Reply tin khách -> .mau xn 100k
Reply tin khách -> .mau xl
Reply tin khách -> .mau giao
Reply tin khách -> .mau ct
```

## 8. Xử lý lỗi thường gặp

### Bot không phản hồi

1. Gõ `prefix` để kiểm tra prefix hiện tại.
2. Thử `.menu` để xác nhận bot đang online.
3. Nếu là lệnh nội bộ, báo Admin kiểm tra nhóm đã được duyệt hay chưa.
4. Chờ 1-3 giây rồi thử lại nếu vừa gửi nhiều lệnh liên tiếp.

### Sale không dùng được `.mau`

- Dùng `.uid` để lấy UID của tài khoản Sale.
- Gửi UID cho Admin kỹ thuật để thêm vào danh sách `sales_ids`.
- Source hiện tại đang để `sales_ids` trống, nên bước cấp quyền này cần được thực hiện trước khi toàn bộ Sale dùng `.mau`.

### `.bg next` không sang đúng trang

- Chạy `.bg` để đặt lại về trang 1.
- Chạy `.bg <số trang>` để chọn trực tiếp.
- Nếu có mã sản phẩm dạng số, dùng `.bg page <số trang>`.

### Không tạo được QR bằng `.stk`

- Dùng số tiền hợp lệ, ví dụ `.stk 100000 CHATGPT-2` hoặc `.stk 100k CHATGPT-2`.
- Chờ ít nhất 3 giây giữa hai lần tạo QR.
- Báo Admin kiểm tra kết nối Internet của hosting và cấu hình VietQR.
- TPBank dùng mã ngân hàng `TPB`.
- Không nhập mật khẩu, OTP, cookie hoặc thông tin bí mật vào nội dung chuyển khoản.

### Bot không nhận lệnh `.thongbao`

- Khởi chạy bot từ đúng môi trường: `cd /Users/lechiquochung/Downloads/botzlhung && .venv/bin/python vxkiue.py`.
- Không dùng `/opt/homebrew/bin/python3` nếu môi trường đó chưa cài `Pillow` và `pycryptodome`.
- Chỉ tài khoản nằm trong danh sách Admin mới được dùng lệnh.
- Dùng `.thongbao trangthai` sau khi bot restart; bot giữ lịch sử đã gửi và không tự gửi lại nhóm có kết quả chưa chắc chắn.

## 9. Nguyên tắc an toàn

- Luôn xác nhận lại tồn kho, giá cuối cùng và khuyến mãi trước khi gửi QR.
- Luôn đối chiếu tên người nhận, số tiền và nội dung chuyển khoản.
- Không yêu cầu khách gửi mật khẩu hoặc OTP.
- Khi khách gửi bill, nhắc khách che số dư và thông tin cá nhân không cần thiết.
- Không dùng thử lệnh không có trong tài liệu này trên nhóm đang vận hành.
- Không dùng mô-đun trợ lý AI cũ để hỏi hoặc cung cấp thông tin thanh toán. Nguồn thanh toán chính thức là `.stk` và xác nhận trực tiếp từ Sale.

## 10. Bảo hành tự động `.baohanh`

Khách tự lấy tài khoản bảo hành khi đơn còn hạn. Bot kiểm tra theo UID Zalo của người gõ lệnh, nên Admin phải ghi đơn cho khách trước.

| Lệnh | Ai dùng | Chức năng |
|---|---|---|
| `.baohanh` | Khách | Xem các đơn bảo hành và hạn của mình. |
| `.baohanh <mã>` | Khách | Nhận tài khoản bảo hành, ví dụ `.baohanh capcut`. Trong nhóm, bot gửi tài khoản qua tin nhắn riêng. |
| `.baohanh don <mã> <dd/mm/yyyy> <uid \| @tag \| reply tin khách>` | Admin | Ghi hoặc gia hạn đơn bảo hành cho khách. |
| `.baohanh huydon <mã> <uid \| @tag \| reply tin khách>` | Admin | Hủy đơn bảo hành. |
| `.baohanh gui <mã> [dd/mm/yyyy] <uid \| @tag \| reply tin khách>` | Admin | Gửi tài khoản bảo hành thẳng vào tin nhắn riêng của khách. Có ngày thì bot ghi (hoặc gia hạn) đơn rồi gửi luôn. |
| `.baohanh them <mã> <số đơn> <tài khoản>` | Admin | Nạp tài khoản vào kho; `<số đơn>` là số khách tối đa được cấp chung tài khoản này. |
| `.baohanh sua <id \| mã> <số đơn>` | Admin | Đổi số đơn tối đa của một tài khoản (`sua 1 5`) hoặc mọi tài khoản của một mã (`sua capcut 5`). |
| `.baohanh trangthai loi <id \| email>` | Admin | Báo tài khoản lỗi; bot không gửi tài khoản này nữa, khách đang dùng gõ lại `.baohanh <mã>` sẽ nhận tài khoản khác. Cũng có thể reply tin nhắn chứa tài khoản rồi gõ `.baohanh trangthai loi`. |
| `.baohanh trangthai ok <id \| email>` | Admin | Cho tài khoản bị báo lỗi hoạt động lại. |
| `.baohanh xoa <id> [id...]` | Admin | Xóa hẳn tài khoản khỏi kho (không khôi phục được), ví dụ `.baohanh xoa 3 4`. Chỉ nhận ID; muốn tạm ngừng thì dùng `trangthai loi`. |
| `.baohanh kho [mã]` | Admin | Xem kho, gồm cả tài khoản lỗi; chỉ hiện nội dung tài khoản khi nhắn riêng với bot. |

- Mã sản phẩm có dấu cách thì viết liền hoặc dùng `-`, ví dụ `google-ai-2tb`.
- Khách hỏi lại nhiều lần vẫn nhận đúng tài khoản cũ, không tốn thêm lượt.
- Khách chưa có đơn, đơn hết hạn hoặc kho hết tài khoản: bot báo liên hệ Admin và gửi danh thiếp. Khách chưa có đơn sẽ thấy UID của mình để gửi Admin.
- Nên nạp tài khoản bằng tin nhắn riêng với bot để thành viên nhóm không nhìn thấy.
- Trong nhóm, bot không bao giờ hiện một tài khoản đang dùng chung cho bao nhiêu khách (số đơn, số lượt còn lại). Muốn xem chi tiết kho, số đơn đã cấp và danh sách lệnh quản lý, Admin nhắn riêng `.baohanh` hoặc `.baohanh kho` cho bot.
- Dữ liệu lưu ở `modules/cache/baohanh.json` (có mật khẩu dạng chữ thường); không xóa file này.