📋 Cấu Hình Chi Tiết

Dành cho: Kỹ thuật viên hoặc Team Lead cần thêm/sửa khách hàng và loại báo cáo trong hệ thống.

Tổng Quan Các File Cấu Hình

GBS Crawler sử dụng 2 file CSV và 1 file .env để cấu hình toàn bộ hệ thống:

config/
├── customers.example.csv ← File mẫu danh sách khách hàng
├── crawl_jobs.example.csv← File mẫu cấu hình báo cáo
├── customers.csv         ← (Tạo từ file mẫu) Ai là khách hàng?
└── crawl_jobs.csv        ← (Tạo từ file mẫu) Cần tải báo cáo gì?

.env                      ← Thông tin Telegram Bot (cảnh báo lỗi)

⚠️ Bảo mật: Các file customers.csv, crawl_jobs.csv và .env đã được chặn không cho push lên GitHub thông qua .gitignore để tránh lộ thông tin. Bạn phải luôn copy từ file .example.csv ra để sử dụng thực tế.

1. File `customers.csv` — Danh Sách Khách Hàng

Mẫu đầy đủ

csv

customer_id,customer_name,marketplace,seller_url,username,password,extra_params,notes,profile_name
vita_dairy,Vita Dairy,shopee,https://banhang.shopee.vn,,,,,Vita Dairy
vita_dairy,Vita Dairy,lazada,https://sellercenter.lazada.vn,,,,,Vita Dairy
vita_dairy,Vita Dairy,tiktok,https://seller-vn.tiktok.com,,,,,Vita Dairy
dutch_lady,Dutch Lady,shopee,https://banhang.shopee.vn,,,,,Dutch Lady

Quy tắc quan trọng

Mỗi dòng = 1 tài khoản sàn. Nếu Vita Dairy bán trên 3 sàn → cần 3 dòng.
customer_id phải nhất quán giữa customers.csv và crawl_jobs.csv.
- ✅ Đúng: vita_dairy (viết thường, gạch dưới)
- ❌ Sai: Vita Dairy, vitadairy, VD
profile_name nên giống nhau cho tất cả sàn của cùng 1 khách hàng. Điều này giúp tổ chức thư mục profiles/ gọn gàng.
Không lưu mật khẩu trong file CSV. Hệ thống sử dụng Cookie từ browser profile, không cần username/password.

URL Seller Center chuẩn

Sàn	URL
Shopee VN	`https://banhang.shopee.vn`
Lazada VN	`https://sellercenter.lazada.vn`
TikTok Shop VN	`https://seller-vn.tiktok.com`

2. File `crawl_jobs.csv` — Cấu Hình Báo Cáo

Mẫu đầy đủ

csv

customer_id,marketplace,report_type,frequency,priority,enabled,date_range_type,notes
vita_dairy,shopee,income,monthly,high,true,last_month,Thu nhập sàn
vita_dairy,shopee,statement,monthly,high,true,last_month,Sao kê PDF
vita_dairy,shopee,wallet,monthly,high,true,last_month,Số dư ví
vita_dairy,shopee,ads_onsite,daily,medium,true,yesterday,Quảng cáo nội sàn
vita_dairy,shopee,ads_wallet,monthly,high,true,last_month,Lịch sử ví ads
vita_dairy,shopee,affiliate_bill,monthly,medium,true,last_month,Đối soát affiliate
vita_dairy,shopee,affiliate_product,daily,medium,true,yesterday,Affiliate theo SP

Danh Sách Các Loại Báo Cáo Hiện Có

Shopee

`report_type`	Mô tả	Tần suất phổ biến
`income`	Thu nhập tổng hợp (trang Tài Chính → Xuất)	monthly
`statement`	Sao kê thu nhập (PDF/Excel)	monthly
`wallet`	Số dư ví ShopeePay	monthly
`ads_onsite`	Quảng cáo nội sàn (CPC) — xuất 2 loại	daily
`ads_wallet`	Lịch sử giao dịch ví quảng cáo	monthly
`affiliate_bill`	Đối soát tiếp thị liên kết (quy trình 2 bước)	monthly
`affiliate_product`	Báo cáo affiliate theo sản phẩm	daily

TikTok Shop

`report_type`	Mô tả	Tần suất phổ biến
`income`	Giao dịch đã quyết toán	monthly
`wallet`	Lịch sử rút tiền	monthly
`affiliate_orders`	Đơn hàng affiliate	daily
`ads_dashboard`	Dashboard quảng cáo shop	daily
`ads_cost`	Chi phí ads (Business Center)	monthly
`ads_revenue`	Thanh toán ads (Business Center)	monthly
`affiliate_invoice`	Hoá đơn hoa hồng affiliate	monthly

Lazada

`report_type`	Mô tả	Tần suất phổ biến
`income`	Chi tiết thu nhập	monthly
`statement`	Sao kê tháng	monthly
`wallet`	Số dư tài khoản	monthly
`ads_overview`	Tổng quan ads nội sàn	daily
`ads_max`	Tài Trợ Max (theo sản phẩm)	daily
`ads_display`	Tài Trợ Hiển Thị (theo sản phẩm)	daily
`ads_wallet`	Lịch sử giao dịch ads	monthly
`logistics`	Chi tiết phí vận chuyển	monthly

Giá Trị Cho Các Cột

Cột	Giá trị có thể	Mô tả
`frequency`	`daily`, `monthly`	Daily = tải mỗi ngày, Monthly = tải 1 lần/tháng
`priority`	`high`, `medium`, `low`	Job `high` chạy trước
`enabled`	`true`, `false`	Đặt `false` để tạm dừng mà không cần xóa dòng
`date_range_type`	`yesterday`, `last_month`, `last_week`	Khoảng thời gian dữ liệu

3. Các Thao Tác Phổ Biến

Thêm khách hàng mới hoàn chỉnh

Thêm dòng vào customers.csv:

csv

vinamilk,Vinamilk,shopee,https://banhang.shopee.vn,,,,,Vinamilk
vinamilk,Vinamilk,tiktok,https://seller-vn.tiktok.com,,,,,Vinamilk

Thêm các job vào crawl_jobs.csv:

csv

vinamilk,shopee,income,monthly,high,true,last_month,
vinamilk,shopee,wallet,monthly,high,true,last_month,
vinamilk,tiktok,income,monthly,high,true,last_month,

Tạo profile và đăng nhập:

bash

uv run scripts/gbs_ops.py client add --name "Vinamilk"
gbs login -c vinamilk -m shopee
gbs login -c vinamilk -m tiktok

Test:

bash

gbs crawl -c vinamilk --dry-run
gbs crawl -c vinamilk

Tạm dừng 1 loại báo cáo

Đổi enabled từ true → false trong crawl_jobs.csv:

csv

vinamilk,shopee,ads_onsite,daily,medium,false,yesterday,Tạm dừng vì KH chưa chạy ads

Tạm dừng toàn bộ của 1 khách hàng

Đổi tất cả dòng enabled thành false, hoặc đơn giản xóa khỏi crawl_jobs.csv.

4. File `.env` — Biến Môi Trường

env

# === Telegram Bot ===
TELEGRAM_BOT_TOKEN="your_bot_token"
TELEGRAM_CHAT_ID="your_chat_id"

⚠️ File .env đã được thêm vào .gitignore — không bao giờ commit lên Git.

📌 Xem tiếp: Cài đặt & Khởi động | Tham chiếu lệnh CLI

📋 Cấu Hình Chi Tiết ​

Tổng Quan Các File Cấu Hình ​

1. File customers.csv — Danh Sách Khách Hàng ​

Mẫu đầy đủ ​

Quy tắc quan trọng ​

URL Seller Center chuẩn ​

2. File crawl_jobs.csv — Cấu Hình Báo Cáo ​

Mẫu đầy đủ ​

Danh Sách Các Loại Báo Cáo Hiện Có ​

Shopee ​

TikTok Shop ​

Lazada ​

Giá Trị Cho Các Cột ​

3. Các Thao Tác Phổ Biến ​

Thêm khách hàng mới hoàn chỉnh ​

Tạm dừng 1 loại báo cáo ​

Tạm dừng toàn bộ của 1 khách hàng ​

4. File .env — Biến Môi Trường ​

📋 Cấu Hình Chi Tiết

Tổng Quan Các File Cấu Hình

1. File `customers.csv` — Danh Sách Khách Hàng

Mẫu đầy đủ

Quy tắc quan trọng

URL Seller Center chuẩn

2. File `crawl_jobs.csv` — Cấu Hình Báo Cáo

Mẫu đầy đủ

Danh Sách Các Loại Báo Cáo Hiện Có

Shopee

TikTok Shop

Lazada

Giá Trị Cho Các Cột

3. Các Thao Tác Phổ Biến

Thêm khách hàng mới hoàn chỉnh

Tạm dừng 1 loại báo cáo

Tạm dừng toàn bộ của 1 khách hàng

4. File `.env` — Biến Môi Trường