# Cấu hình Crawl cho Shopify Sites

## Tổng quan

Hệ thống hỗ trợ crawl các website chạy trên nền tảng Shopify với 2 modes:
1. **Shopify API mode** (khuyến nghị): Fetch trực tiếp từ Shopify API, nhanh và chính xác
2. **HTML mode**: Parse HTML như các website thông thường

## Cấu hình cơ bản

### 1. Tạo config file

Config file nên đặt tên theo format: `{domain-slug}.yaml` (ví dụ: `themarblecoffee-com.yaml`)

```yaml
website:
  name: Generic E-commerce
  base_url: https://example.com
  type: shopify  # Quan trọng: đặt type = shopify

crawling:
  start_urls:
  - https://example.com
  mode: shopify_api  # Quan trọng: dùng shopify_api mode
  crawl_reviews: true  # Bật crawl reviews nếu cần
  pagination:
    enabled: true
    max_pages: 50

export:
  domain_slug: example-com  # Format: domain với dấu gạch ngang
```

### 2. Các settings quan trọng

#### `type: shopify`
- Bắt buộc phải đặt `type: shopify` để hệ thống nhận diện đây là Shopify site
- Hệ thống sẽ tự động detect platform và sử dụng Shopify-specific logic

#### `mode: shopify_api`
- **Khuyến nghị**: Dùng `shopify_api` mode để fetch trực tiếp từ API
- Ưu điểm:
  - Nhanh hơn (không cần parse HTML)
  - Chính xác hơn (lấy trực tiếp từ API)
  - Hỗ trợ đầy đủ variants và attributes
  - Tự động handle pagination

#### `crawl_reviews: true`
- Bật crawl reviews từ product pages
- Hỗ trợ các review platforms:
  - **Judge.me**: Tự động detect và extract
  - **Yotpo**: Tự động detect và extract
  - **Loox**: Tự động detect và extract từ widget iframe
  - **Shopify native reviews**: Tự động detect và extract
  - **Schema.org markup**: Generic review extraction

### 3. Auto-detect

Nếu chưa có config file, hệ thống sẽ tự động:
1. Detect platform (Shopify, WooCommerce, etc.)
2. Tạo config file với settings phù hợp
3. Tên file: `{domain-slug}.yaml` (ví dụ: `themarblecoffee-com.yaml`)

## Workflow crawl Shopify site

### Bước 1: Check domain (từ WordPress plugin hoặc API)

```bash
# Từ WordPress plugin: Click "Check Domain"
# Hoặc từ API:
curl -X POST http://localhost:8000/api/crawl/check_domain \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

Hệ thống sẽ:
- Tự động detect platform
- Tạo config file nếu chưa có
- Chạy analysis nếu file analysis cũ hơn 24 giờ
- Hiển thị thông tin: platform, số products, collections, etc.

### Bước 2: Cấu hình settings (nếu cần)

Sửa config file tại `configs/{domain-slug}.yaml`:

```yaml
crawling:
  mode: shopify_api  # Đảm bảo dùng shopify_api
  crawl_reviews: true  # Bật nếu cần reviews
```

### Bước 3: Start crawl

Từ WordPress plugin:
1. Vào tab "Crawl"
2. Chọn domain
3. Click "Start Crawl"
4. Settings từ plugin (như `crawl_reviews`) sẽ được merge vào config

Hoặc từ command line:

```bash
scrapy crawl generic -a config_file=configs/example-com.yaml
```

## Các tính năng đặc biệt

### 1. Product Variations

Shopify API mode tự động handle:
- **Parent products**: Variable products (không có price, SKU)
- **Variations**: Các biến thể với price, SKU, attributes riêng
- **Attributes**: Size, Color, Material, etc.

Export format:
- Parent product: `Type = variable`
- Variations: `Type = variation`, `Parent = {parent_sku}`

### 2. Reviews Extraction

Khi `crawl_reviews: true`:
- Tự động detect review platform
- Fetch reviews từ product detail pages
- Export vào CSV column "Reviews" (JSON format)

**Loox Reviews** (đặc biệt):
- Detect Loox widget từ `data-product-id` attribute
- Fetch từ Loox widget iframe URL
- Parse HTML để extract reviews
- Format: `[{"author": "...", "rating": 5, "date": "...", "content": "..."}]`

### 3. Collections

Shopify API mode tự động:
- Fetch collections từ `/collections.json`
- Map products vào collections
- Export collections trong analysis

## Troubleshooting

### Vấn đề: Không crawl được reviews

**Kiểm tra:**
1. Config có `crawl_reviews: true` không?
2. WordPress plugin settings có bật "Crawl Reviews" không?
3. Product page có review widget không?

**Debug:**
```bash
# Check logs khi crawl
scrapy crawl generic -a config_file=configs/example-com.yaml -L DEBUG | grep -i review
```

### Vấn đề: Số lượng products không chính xác

**Giải pháp:**
- Dùng `shopify_api` mode thay vì HTML mode
- Hệ thống sẽ fetch từ `/products.json` API, chính xác hơn

### Vấn đề: Thiếu variations

**Kiểm tra:**
1. Config có `mode: shopify_api` không?
2. Products có variants trong Shopify không?

**Lưu ý:** HTML mode có thể không extract đầy đủ variations.

## Best Practices

1. **Luôn dùng `shopify_api` mode** cho Shopify sites
2. **Đặt `type: shopify`** trong config
3. **Bật `crawl_reviews: true`** nếu cần reviews
4. **Check domain trước** để auto-detect và tạo config
5. **Review analysis** để xác nhận số products và collections

## Ví dụ config hoàn chỉnh

```yaml
website:
  name: Generic E-commerce
  base_url: https://themarblecoffee.com
  type: shopify

crawling:
  start_urls:
  - https://themarblecoffee.com
  mode: shopify_api
  crawl_reviews: true
  pagination:
    enabled: true
    max_pages: 50
  follow_links: true

selectors:
  # Selectors này không dùng khi mode = shopify_api
  # Nhưng vẫn cần có để backward compatibility
  product_container: .product
  title: h2
  price: .price
  image: img
  link: a

rate_limiting:
  delay: 1.5
  download_delay: 1.5
  concurrent_requests: 1

headers:
  User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
  Accept: text/html,application/xhtml+xml

features:
  requires_javascript: false
  api_endpoints: []
  custom_middleware: []

proxies:
  enabled: false
  list: []
  mode: rotate

export:
  domain_slug: themarblecoffee-com
```

## API Endpoints

### Check Domain
```
POST /api/crawl/check_domain
Body: {"domain": "example.com"}
Response: {
  "config_exists": true,
  "config_path": "configs/example-com.yaml",
  "analysis": {...},
  "platform_info": {...}
}
```

### Start Crawl
```
POST /api/crawl/start
Body: {
  "domain": "example.com",
  "config_payload": {
    "crawling": {
      "crawl_reviews": true
    }
  }
}
```

## Tài liệu liên quan

- [Config File Format](../docs/CONFIG_FORMAT.md)
- [Review Extraction](../docs/REVIEW_EXTRACTION.md)
- [Export Formats](../docs/EXPORT_FORMATS.md)

