# Spy / Phân Tích Thị Trường

## Tổng quan

Chức năng **Spy** (Phân tích thị trường) cho phép người dùng nghiên cứu và theo dõi đối thủ cạnh tranh trên Shopee. Công cụ cung cấp khả năng phân tích sản phẩm, shop, danh mục và toàn bộ thị trường để đưa ra quyết định kinh doanh dựa trên dữ liệu thực tế.

**Tính năng chính:**
- Theo dõi (tracker) sản phẩm đối thủ và ghi nhận biến động bán hàng theo ngày
- Phân tích chi tiết sản phẩm: phân loại, giá, tồn kho, lượt bán
- Phân tích shop đối thủ: danh sách sản phẩm, thống kê bán hàng theo nhóm
- Phân tích danh mục: sản phẩm bán chạy, shop Mall trong danh mục
- Duyệt cây danh mục Shopee để khám phá thị trường
- Xuất dữ liệu ra Excel và sao chép URL hàng loạt

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

**Hỗ trợ đa nền tảng:** Ngoài Shopee, tính năng phân tích thị trường cũng khả dụng trên TikTok với cây danh mục và phân tích danh mục riêng.

---

## Dashboard

**Đường dẫn:** `Shopee > Spy > Dashboard`

Dashboard là trang quản lý danh sách các sản phẩm đang được theo dõi (tracker). Người dùng có thể thêm sản phẩm vào danh sách theo dõi từ trang phân tích sản phẩm, sau đó theo dõi biến động bán hàng theo thời gian.

### Bảng danh sách theo dõi

| Cột | Mô tả |
|-----|-------|
| Tên sản phẩm | Tên sản phẩm kèm link đến trang sản phẩm trên Shopee |
| Hình ảnh | Ảnh đại diện sản phẩm |
| Ngày tạo | Thời điểm sản phẩm được đăng bán |
| Tên shop | Tên shop kèm link đến trang shop trên Shopee |
| Giá | Giá bán hiện tại |
| Giảm giá | Mức giảm giá đang áp dụng |
| Đã bán | Tổng số lượng đã bán (global) |
| Tăng trưởng | Số lượng bán tăng thêm so với lúc bắt đầu theo dõi (`soldInc = sold - soldStart`) |
| Doanh thu | Tổng doanh thu ước tính (`sold x price`) |

### Thao tác

| Nút | Chức năng |
|-----|-----------|
| **Cập nhật** (Fetch) | Lấy dữ liệu mới nhất của sản phẩm từ Shopee và cập nhật các chỉ số bán hàng |
| **Xóa** (Remove) | Xóa sản phẩm khỏi danh sách theo dõi (có xác nhận) |

### Cơ chế cập nhật dữ liệu

Khi nhấn **Cập nhật**, hệ thống:
1. Gọi API lấy thông tin sản phẩm từ Shopee (`getShopeeProductId`)
2. Nếu không lấy được, tự động mở tab sản phẩm trên Shopee rồi thử lại
3. Ghi log bán hàng theo ngày vào `ShopeeSpyLog` (mỗi ngày chỉ ghi 1 lần)
4. Cập nhật số liệu `sold`, `sale`, `soldInc` vào `ShopeeSpyList`

### Đồng bộ dữ liệu

Khi khởi tạo, Dashboard tự động đồng bộ dữ liệu từ PouchDB local lên CouchDB remote cho cả `ShopeeSpyList` và `ShopeeSpyLog`.

---

## Phân tích danh mục

**Đường dẫn:** `Shopee > Spy > Category > :id`

Trang phân tích danh mục hiển thị toàn bộ sản phẩm trong một danh mục Shopee, kèm theo danh sách shop Mall thuộc danh mục đó.

### Tìm kiếm sản phẩm trong danh mục

Hệ thống tự động quét tối đa **500 sản phẩm** trong danh mục (mỗi lần lấy 50 sản phẩm, phân trang tự động). Sản phẩm trùng lặp được loại bỏ tự động.

### Bảng sản phẩm

| Cột | Mô tả |
|-----|-------|
| Checkbox | Chọn sản phẩm để sao chép URL |
| # | Số thứ tự |
| Tên sản phẩm | Tên kèm link (có đánh dấu [Video] nếu sản phẩm có video) |
| Hình ảnh | Ảnh đại diện (lazy loading) |
| Danh mục | Tên danh mục của sản phẩm |
| Thương hiệu | Tên thương hiệu |
| Ngày tạo | Thời điểm đăng bán |
| Giá | Giá bán hiện tại |
| Giảm giá | Mức giảm giá |
| Đã bán | Tổng số lượng đã bán (historical) |
| Doanh thu | Doanh thu ước tính (`historical_sold x price`) |
| Thao tác | Link "Spy" để mở trang phân tích chi tiết sản phẩm |

### Thẻ thống kê tổng quan

| Chỉ số | Mô tả |
|--------|-------|
| Tổng sản phẩm | Số lượng sản phẩm trong danh mục |
| Tổng danh mục | Số danh mục con (phân nhóm theo category tree) |
| Tổng thương hiệu | Số thương hiệu khác nhau |
| Tổng đã bán | Tổng lượng bán của tất cả sản phẩm |
| Tổng doanh thu | Tổng doanh thu ước tính |
| Tổng follower | (Chưa triển khai) |

### Báo cáo Top Bán (Top Sell)

Nhấn nút **"Top Sell"** để mở popup phân tích sản phẩm theo các nhóm:

| Nhóm | Mô tả |
|------|-------|
| **Theo thời gian** (Time) | Nhóm sản phẩm theo năm đăng bán |
| **Theo giá** (Price) | Nhóm theo khoảng giá (dưới 10k, 10k-100k, 100k-200k, 200k-300k, 300k-500k, 500k-1tr, trên 1tr) |
| **Theo thương hiệu** (Brand) | Nhóm theo tên thương hiệu |
| **Theo danh mục** (Category) | Nhóm theo cây danh mục |

Mỗi nhóm hiển thị:
- Số sản phẩm (kèm tỷ lệ %)
- Tổng đã bán (kèm tỷ lệ %)
- Tổng doanh thu (kèm tỷ lệ %)

### Shop Mall trong danh mục

Phía dưới phần tìm kiếm sản phẩm, hệ thống hiển thị danh sách **Shop Mall** (shop chính hãng) thuộc danh mục. Mỗi shop hiển thị dạng card với:
- Logo shop
- Tên shop
- Tên thương hiệu
- Link "Spy" để mở trang phân tích shop

### Xuất dữ liệu

| Nút | Chức năng |
|-----|-----------|
| **Xuất Excel** | Xuất toàn bộ danh sách sản phẩm ra file `.xls` |
| **Sao chép URL** | Sao chép URL của các sản phẩm đã chọn (checkbox) |
| **Xuất Excel báo cáo** | Xuất dữ liệu từng nhóm Top Sell ra file Excel riêng |

---

## Phân tích shop

**Đường dẫn:** `Shopee > Spy > Shop > :id`

Trang phân tích shop hiển thị toàn bộ sản phẩm của một shop đối thủ, kèm thống kê tổng quan và báo cáo phân nhóm.

### Thông tin shop

Khi truy cập, hệ thống gọi API lấy thông tin shop (`getShopeeShopId`) để hiển thị tên shop và username.

### Quét sản phẩm shop

Hệ thống tự động quét tối đa **400 sản phẩm** của shop (mỗi lần lấy 40 sản phẩm, phân trang tự động). Sản phẩm trùng lặp được loại bỏ.

### Bảng sản phẩm

Cấu trúc bảng giống với trang phân tích danh mục (cùng sử dụng `tableProductSpy`), bao gồm đầy đủ các cột: tên, hình ảnh, danh mục, thương hiệu, ngày tạo, giá, đã bán, doanh thu, v.v.

### Thống kê và báo cáo

Tương tự phân tích danh mục:
- Thẻ thống kê tổng quan (tổng sản phẩm, danh mục, thương hiệu, đã bán, doanh thu)
- Báo cáo Top Sell theo 4 nhóm (thời gian, giá, thương hiệu, danh mục)
- Xuất Excel và sao chép URL

### Phân trang

Hỗ trợ phân trang với các tùy chọn kích thước trang: 10, 20, 50, 100, 500, 1000, 5000, 10000 sản phẩm/trang.

---

## Phân tích sản phẩm

**Đường dẫn:** `Shopee > Spy > Product?productId=xxx&shopId=xxx`

Trang phân tích chi tiết một sản phẩm cụ thể của đối thủ.

### Thông tin hiển thị

- **Tên sản phẩm** (tiêu đề trang)
- **Bảng phân loại** (variations): hiển thị tất cả model/variant của sản phẩm

### Bảng phân loại sản phẩm

| Cột | Mô tả |
|-----|-------|
| Tên phân loại | Tên model/variant |
| Hình ảnh | Ảnh phân loại |
| Giá gốc | Giá trước giảm |
| Giá bán | Giá sau giảm |
| Giảm giá | Phần trăm giảm giá |
| Tồn kho | Số lượng tồn kho |
| Đã bán | Số lượng đã bán |
| Doanh thu | Doanh thu ước tính |

Bảng phân loại được **sắp xếp theo số lượng đã bán giảm dần** để dễ nhận biết phân loại bán chạy nhất.

### Thông tin bổ sung

- **Tags**: Danh sách tag/từ khóa của sản phẩm
- **Gallery ảnh**: Bộ sưu tập hình ảnh sản phẩm

### Theo dõi sản phẩm (Tracker)

| Nút | Chức năng |
|-----|-----------|
| **Thêm theo dõi** | Thêm sản phẩm vào danh sách theo dõi trên Dashboard |
| **Đã theo dõi** | Hiển thị khi sản phẩm đã có trong danh sách (nút bị vô hiệu hóa) |
| **Mở danh sách Spy** | Link mở Dashboard trong tab mới |

---

## Phân tích thị trường

**Đường dẫn:** `Shopee > Spy > Market`

Trang phân tích thị trường hiển thị **cây danh mục Shopee** dạng phân cấp (tree), cho phép người dùng duyệt và khám phá toàn bộ cấu trúc danh mục trên Shopee.

### Cây danh mục

- Dữ liệu được lấy từ API Shopee client (`getShopeeCategoryTreeHome`)
- Hiển thị dạng cây phân cấp đa cấp (danh mục cha - con)
- Mỗi danh mục hiển thị: hình ảnh thumbnail, tên danh mục, link đến trang danh mục trên Shopee, nút "Spy"

### Tìm kiếm danh mục

- Ô tìm kiếm cho phép lọc danh mục theo tên
- Kết quả phù hợp được **highlight** (in đậm, màu cam)
- Cây tự động lọc chỉ hiển thị nhánh chứa kết quả

### Thao tác

| Nút | Chức năng |
|-----|-----------|
| **Link danh mục** | Mở trang danh mục trên Shopee (format: `shopee.vn/{slug}-cat.{id}`) |
| **Spy** | Mở trang phân tích danh mục chi tiết |

### Khởi tạo

Khi truy cập trang Market, hệ thống gọi `readyFetchUrlShopeeClient()` để đảm bảo URL API Shopee client đã sẵn sàng trước khi lấy dữ liệu danh mục.

---

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

### Spy List (Sản phẩm theo dõi)

```
- _id: ID tự sinh (format: "product-{shopId}-{productId}")
- type: Loại theo dõi ("product" hoặc "shop")
- productId: ID sản phẩm
- shopId: ID shop
- shopName: Tên shop (username)
- shopMall: Shop có phải Mall không (boolean)
- name: Tên sản phẩm
- time: Thời gian đăng bán
- location: Vị trí shop
- image: URL hình ảnh
- price: Giá bán
- promotion: Giá khuyến mãi
- discount: Phần trăm giảm giá
- stock: Tồn kho
- countRating: Tổng số đánh giá
- countLike: Tổng lượt thích
- countView: Tổng lượt xem
- sold: Tổng đã bán (global_sold)
- sale: Doanh thu ước tính (sold x price)
- variation: Số lượng phân loại
- soldStart: Số đã bán tại thời điểm bắt đầu theo dõi
- soldInc: Số bán tăng thêm (sold - soldStart)
```

### Spy Log (Log bán hàng theo ngày)

```
- id: ID sản phẩm theo dõi (_id của Spy List)
- date: Ngày ghi log (format: YYYY-MM-DD)
- type: Loại log ("product-sold")
- sold: Tổng đã bán tại thời điểm ghi
- sale: Doanh thu tại thời điểm ghi
- soldInc: Số bán tăng thêm
```

### Bảng sản phẩm tìm kiếm (renderTableProduct)

```
- productId: ID sản phẩm (itemid)
- shopId: ID shop (shopid)
- categoryId: ID danh mục
- categoryName: Tên danh mục
- categoryTree: Cây danh mục đầy đủ
- productUrl: URL sản phẩm trên Shopee
- videoUrl: URL video sản phẩm (nếu có)
- shopUrl: URL shop trên Shopee
- spyUrl: URL trang Spy sản phẩm
- name: Tên sản phẩm
- location: Vị trí shop
- shopName: Tên shop
- brand: Thương hiệu (mặc định "No Brand")
- image: URL hình ảnh
- price: Giá (đã chia 100000 từ giá API Shopee)
- sale: Doanh thu ước tính (historical_sold x price)
- sold: Tổng đã bán (historical_sold)
- discount: Mức giảm giá
- likeCount: Lượt thích
- commentCount: Lượt bình luận
- ratingCount: Số đánh giá
- ratingStart: Điểm đánh giá trung bình
```

### Database

| Collection | Mô tả |
|------------|-------|
| `shopee_spy_list` | Danh sách sản phẩm/shop đang theo dõi |
| `shopee_spy_log` | Log biến động bán hàng theo ngày |

Cả hai collection đều sử dụng **PouchDB** local và đồng bộ với **CouchDB** remote.

#### Index được tạo

- `shopee_spy_list`: index trên `[type, shopId, productId]`
- `shopee_spy_log`: index trên `[id, date, type]`

---

## Lưu ý quan trọng

1. **Yêu cầu Premium:** Tất cả tính năng Spy đều yêu cầu tài khoản trả phí (bọc trong `wrap-require-paid`).
2. **Giới hạn quét sản phẩm:** Mỗi lần phân tích shop tối đa quét 400 sản phẩm, phân tích danh mục tối đa 500 sản phẩm.
3. **Cơ chế fallback:** Khi không lấy được dữ liệu sản phẩm qua API, hệ thống tự động mở tab Shopee để tạo cookie/session rồi thử lại.
4. **Log theo ngày:** Mỗi sản phẩm chỉ ghi log bán hàng 1 lần/ngày để theo dõi xu hướng mà không bị trùng lặp.
5. **Giá sản phẩm:** Giá từ API Shopee search được chia cho 100000 để ra giá thực tế (VND).
6. **Đồng bộ dữ liệu:** Dữ liệu Spy được lưu trên PouchDB local và tự động đồng bộ lên CouchDB remote khi mở Dashboard.
7. **Sắp xếp và phân trang:** Bảng sản phẩm hỗ trợ sắp xếp theo tất cả các cột số liệu và phân trang linh hoạt.
8. **TikTok Spy:** Tính năng phân tích thị trường cũng hỗ trợ TikTok với cây danh mục (`/tiktok/spy/market`) và phân tích danh mục (`/tiktok/spy/category/:id`), sử dụng cấu trúc tương tự Shopee nhưng dữ liệu từ API TikTok.
9. **Loại bỏ trùng lặp:** Hệ thống tự động loại bỏ sản phẩm trùng lặp (theo `itemid` hoặc `productId`) khi quét nhiều trang.
