# Keyword (Nghien Cuu Tu Khoa)

## Tong quan

Chuc nang **Keyword** cho phep nguoi ban Shopee quan ly bo suu tap tu khoa (Keyword Collection) phuc vu cho viec chay quang cao tu dong (Ads). Nguoi dung co the tao nhieu bo suu tap tu khoa, them tu khoa vao tung bo suu tap, thiet lap gia bid, loai tu khoa va xuat du lieu ra file Excel.

**Tinh nang chinh:**
- Tao va quan ly nhieu bo suu tap tu khoa (Collection)
- Them tu khoa don le hoac hang loat vao bo suu tap
- Thiet lap gia bid, loai tu khoa (chinh xac / mo rong) cho tung tu khoa
- Theo doi gia hien tai, gia toi thieu, gia toi da cua tu khoa
- Xuat danh sach tu khoa ra file Excel
- Nghien cuu tu khoa (Coming Soon)

**Yeu cau:** Tai khoan tra phi (Premium).

---

## Giao dien va cac tab

**Duong dan:** `Shopee > Seller > Keyword`

### Trang chinh (Index)

Hien thi danh sach cac bo suu tap tu khoa da tao. Moi bo suu tap hien thi ten, mo ta, so luong tu khoa va thoi gian tao.

#### Thao tac voi bo suu tap

| Nut | Chuc nang |
|-----|-----------|
| **Xuat (Export)** | Xuat danh sach tu khoa trong bo suu tap ra file Excel |
| **Sua (Edit)** | Chinh sua ten va mo ta bo suu tap |
| **Mo (Open)** | Mo trang chi tiet bo suu tap de quan ly tu khoa |
| **Xoa (Delete)** | Xoa bo suu tap (co xac nhan truoc khi xoa) |

#### Tao bo suu tap moi

Nhan nut **"Tao bo suu tap"** se hien popup voi 2 truong:

| Truong | Mo ta |
|--------|-------|
| **Ten** | Ten cua bo suu tap tu khoa |
| **Mo ta** | Mo ta ngan cho bo suu tap |

Popup nay cung duoc su dung khi chinh sua bo suu tap (tu dong dien thong tin cu).

### Trang chi tiet (Detail)

**Duong dan:** `Shopee > Seller > Keyword > {collectionId}`

Hien thi bang tu khoa cua mot bo suu tap cu the, cho phep them, sua, xoa tu khoa.

### Trang nghien cuu (Research)

**Duong dan:** `Shopee > Seller > Keyword > Research`

Tinh nang nghien cuu tu khoa dang trong giai doan phat trien (**Coming Soon**).

---

## Tinh nang nghien cuu tu khoa

### Them tu khoa don le

Nhap truc tiep tu khoa va gia bid vao form:

| Truong | Mo ta |
|--------|-------|
| **Tu khoa** | Tu khoa can them |
| **Gia bid** | Gia bid cho tu khoa (bat buoc, phai > 0) |

Nhan **"Them tu khoa"** de them vao bang.

### Them tu khoa hang loat

Nhap nhieu tu khoa cung luc vao o textarea. Moi dong mot tu khoa, phan tach tu khoa va gia bang cac ky tu:

| Ky tu phan tach | Vi du |
|-----------------|-------|
| Tab (`\t`) | `ao thun nam	5000` |
| Dau phay (`,`) | `ao thun nam,5000` |
| Cham phay (`;`) | `ao thun nam;5000` |
| Gach dung (`\|`) | `ao thun nam\|5000` |
| Hai cham (`:`) | `ao thun nam:5000` |

Dong nao khong co ca tu khoa va gia se bi bo qua.

### Bang tu khoa

| Cot | Mo ta | Chinh sua |
|-----|-------|-----------|
| **#** | So thu tu | Khong |
| **Tu khoa** | Ten tu khoa | Chi doc |
| **Loai** | Chinh xac (exact) hoac Mo rong (extend) | Co (dropdown) |
| **Gia bid** | Gia bid do nguoi dung thiet lap | Co (input so) |
| **Gia hien tai** | Gia bid hien tai tren Shopee | Khong |
| **Gia toi thieu** | Gia bid thap nhat | Khong |
| **Gia toi da** | Gia bid cao nhat | Khong |
| **Trang thai** | Bat/tat tu khoa | Co (checkbox) |
| **Ghi chu** | Ghi chu tu do | Co (input text) |
| **Thao tac** | Nut xoa tu khoa | - |

### Loai tu khoa

| Loai | Mo ta |
|------|-------|
| **Chinh xac (exact)** | Quang cao chi hien khi nguoi dung tim kiem dung tu khoa |
| **Mo rong (extend)** | Quang cao hien khi nguoi dung tim kiem cac tu khoa lien quan |

### Cap nhat tu khoa

Khi thay doi **loai**, **gia bid**, **ghi chu** hoac **trang thai** cua tu khoa, he thong tu dong luu thay doi len server (khong can nhan nut luu).

### Xoa tu khoa

Nhan nut **"Xoa"** tren dong tu khoa, xac nhan trong popup de xoa. Tu khoa bi xoa khoi ca giao dien va server.

### Xuat Excel

Nhan nut **"Xuat"** tai trang danh sach bo suu tap. File Excel chua cac cot:

| Cot | Mo ta |
|-----|-------|
| Tu khoa | Ten tu khoa |
| Gia bid | Gia bid thiet lap |
| Gia hien tai | Gia bid hien tai |
| Gia toi thieu | Gia bid thap nhat |
| Gia toi da | Gia bid cao nhat |
| Ghi chu | Ghi chu |

---

## Cau truc du lieu

### Keyword Collection

Bo suu tap tu khoa, luu tren AutoShopee server.

```
- _id: ID cua bo suu tap
- name: Ten bo suu tap
- description: Mo ta
- count: So luong tu khoa trong bo suu tap
- timeCreate: Thoi gian tao
```

### Keyword Collection Item

Tu khoa trong bo suu tap.

```
- _id: ID cua tu khoa
- userRef: ID nguoi dung
- collectionRef: ID bo suu tap chua tu khoa
- keyword: Tu khoa
- type: Loai tu khoa ('exact' | 'extend')
- algorithm: Thuat toan ('kwrcmdv3' mac dinh)
- price: Gia bid thiet lap
- priceCurrent: Gia bid hien tai
- priceMin: Gia bid toi thieu
- priceMax: Gia bid toi da
- active: Trang thai bat/tat
- note: Ghi chu
```

### API Endpoints

| Method | Endpoint | Chuc nang |
|--------|----------|-----------|
| POST | `/extension/shopee/ads/keyword/create` | Tao bo suu tap moi |
| GET | `/extension/shopee/ads/keyword/list` | Lay danh sach bo suu tap |
| POST | `/extension/shopee/ads/keyword/remove/{id}` | Xoa bo suu tap |
| POST | `/extension/shopee/ads/keyword/update/{id}` | Cap nhat bo suu tap |
| GET | `/extension/shopee/ads/keyword/item/list/{collectionId}` | Lay danh sach tu khoa trong bo suu tap |
| POST | `/extension/shopee/ads/keyword/item/add/{collectionId}` | Them tu khoa vao bo suu tap |
| POST | `/extension/shopee/ads/keyword/item/remove/{id}` | Xoa tu khoa |
| POST | `/extension/shopee/ads/keyword/item/update/{id}` | Cap nhat tu khoa |

### Vuex Store

| Action | Chuc nang |
|--------|-----------|
| `ShopeeKeywordFetch` | Lay danh sach bo suu tap va luu vao store |
| `ShopeeKeywordAdd` | Them tu khoa moi vao bo suu tap |
| `ShopeeKeywordGet` | Lay danh sach tu khoa cua mot bo suu tap |
| `ShopeeKeywordExport` | Xuat tu khoa ra file Excel |

---

## Luu y quan trong

1. **Kiem tra trung lap:** Khi them tu khoa, he thong kiem tra tu khoa da ton tai trong bo suu tap chua. Neu trung se hien thong bao loi va khong them.
2. **Tu dong luu:** Thay doi loai tu khoa, gia bid, ghi chu, trang thai duoc luu tu dong len server khi nguoi dung chinh sua, khong can nhan nut luu.
3. **Gia bid bat buoc:** Khi them tu khoa don le, ca tu khoa va gia bid deu bat buoc va gia phai lon hon 0.
4. **Them hang loat:** Ho tro nhieu dinh dang phan tach (tab, dau phay, cham phay, gach dung, hai cham). Moi dong khong hop le se bi bo qua.
5. **Thuat toan mac dinh:** Tu khoa moi duoc tao voi thuat toan `kwrcmdv3` va loai `exact` (chinh xac) mac dinh.
6. **Xuat Excel:** Chi xuat duoc tu trang danh sach bo suu tap (Index), khong xuat tu trang chi tiet.
7. **Nghien cuu tu khoa:** Tinh nang Research hien dang trong giai doan phat trien (Coming Soon), chua co chuc nang cu the.
8. **Yeu cau Premium:** Tat ca tinh nang Keyword deu yeu cau tai khoan tra phi (wrap-require-paid).
