📖 Hướng Dẫn Sử Dụng Hằng Ngày

Dành cho: Nhân viên Vận hành, Account Manager, Team Lead — những người cần lấy báo cáo gửi khách hàng mà không cần biết lập trình.

Hệ thống hoạt động như thế nào? (30 giây)

Hằng ngày lúc 2h sáng:
  Hệ thống tự mở trình duyệt (ẩn) 
  → Đăng nhập vào Shopee/TikTok/Lazada bằng Cookie đã lưu
  → Tải báo cáo Excel/CSV về thư mục data/
  → Nếu có lỗi → Gửi cảnh báo Telegram

Bạn chỉ cần làm 3 việc:

🗂️ Lấy file báo cáo từ thư mục data/ gửi khách hàng
➕ Thêm/bớt khách hàng khi có thay đổi hợp đồng
🔐 Đăng nhập lại khi hệ thống báo "session expired"

1. 🗂️ Lấy Báo Cáo Cho Khách Hàng

Cách 1: Mở thư mục bằng Finder (Đơn giản nhất)

Mở Finder (trên Mac) hoặc File Explorer (trên Windows)
Tìm đến thư mục dự án gbs-crawler
Vào thư mục data/
Chọn thư mục tên khách hàng (VD: Vita Dairy, Hara)
Bên trong sẽ có file .xlsx hoặc .csv — file mới nhất là báo cáo ngày hôm qua

Cấu trúc thư mục:

gbs-crawler/
└── data/
    ├── Vita Dairy/          ← File báo cáo của Vita Dairy
    │   ├── shopee_income_2026-05-13.xlsx
    │   ├── shopee_wallet_2026-05-13.csv
    │   └── ...
    ├── Hara/                ← File báo cáo của Hara  
    │   └── ...
    └── Dutch Lady/          ← File báo cáo của Dutch Lady
        └── ...

Cách 2: Dùng câu lệnh (Nhanh hơn)

Mở Terminal (trên Mac: tìm "Terminal" trong Spotlight), rồi gõ:

bash

cd /đường/dẫn/tới/gbs-crawler
uv run scripts/gbs_ops.py report get --client "Vita Dairy"

Kết quả sẽ hiện ra:

Top 5 most recent reports for 'Vita Dairy':
 - shopee_income_2026-05-13.xlsx (Modified: 2026-05-13 02:15:30, Size: 45.20 KB)
   Path: data/Vita Dairy/shopee_income_2026-05-13.xlsx
 - shopee_wallet_2026-05-13.csv (Modified: 2026-05-13 02:16:05, Size: 12.30 KB)
   Path: data/Vita Dairy/shopee_wallet_2026-05-13.csv

💡 Mẹo: Bạn chỉ cần thay "Vita Dairy" bằng tên khách hàng muốn tìm. Hệ thống tự tìm cả tên gần giống (viết hoa/thường đều được).

2. ➕ Thêm Khách Hàng Mới

Khi ký hợp đồng với thương hiệu mới, bạn cần tạo "hồ sơ" (Profile) cho họ trong hệ thống.

Bước 1: Tạo Profile

Mở Terminal và chạy:

bash

cd /đường/dẫn/tới/gbs-crawler
uv run scripts/gbs_ops.py client add --name "Vinamilk"

Hệ thống sẽ tạo thư mục profiles/Vinamilk/ để chứa thông tin đăng nhập riêng.

Bước 2: Đăng nhập lần đầu

Để hệ thống có thể tự động tải báo cáo, bạn cần đăng nhập 1 lần duy nhất:

bash

gbs login -c vinamilk -m shopee

Trình duyệt Chrome sẽ tự động mở lên trang đăng nhập Shopee Seller Center
Bạn nhập tài khoản/mật khẩu và OTP như bình thường
Khi đăng nhập thành công → đóng trình duyệt hoặc nhấn Ctrl+C trong Terminal
Hệ thống tự động lưu phiên đăng nhập — không cần làm lại cho đến khi bị văng

⚠️ Làm tương tự cho từng sàn: Nếu khách hàng bán trên cả Shopee, TikTok và Lazada thì bạn cần chạy gbs login cho mỗi sàn.

Bước 3: Thêm vào danh sách cấu hình

Nhờ kỹ thuật viên thêm thông tin khách hàng vào 2 file:

config/customers.csv — thông tin tài khoản
config/crawl_jobs.csv — những báo cáo cần tải

(Xem chi tiết ở tài liệu Cấu hình chi tiết)

3. ➖ Ngừng Lấy Dữ Liệu Của Một Khách Hàng

Khi khách hàng ngừng dịch vụ:

bash

uv run scripts/gbs_ops.py client remove --name "Vinamilk"

⚠️ Cẩn thận: Lệnh này sẽ xóa toàn bộ Profile (thông tin đăng nhập) của khách hàng. File báo cáo trong data/ vẫn được giữ nguyên.

4. 🔐 Xử Lý Khi Bị Văng Đăng Nhập

Tại sao bị văng?

Shopee, TikTok, Lazada thường tự động đăng xuất tài khoản sau một thời gian dài (7-30 ngày) vì lý do bảo mật. Đây là chuyện bình thường, không phải lỗi hệ thống.

Làm sao biết bị văng?

Bạn sẽ nhận được tin nhắn trên nhóm Telegram với nội dung tương tự:

🛑 AI Intervention needed
Customer: vita_dairy
Marketplace: shopee
Error: SessionExpiredException — Login page detected, session has expired.

Cách xử lý (chỉ mất 2 phút)

Bước 1: Mở Terminal, chạy lệnh đăng nhập lại:

bash

gbs login -c vita_dairy -m shopee

Bước 2: Trình duyệt mở lên → Đăng nhập bằng tay:

Nhập số điện thoại/email
Nhập mật khẩu
Nhập mã OTP (nếu có) từ tin nhắn điện thoại
Kéo Captcha (nếu có)

Bước 3: Khi thấy trang Seller Center hiện lên bình thường → đóng trình duyệt.

Xong! Hệ thống đã tự động lưu lại Cookie đăng nhập. Ngày mai nó sẽ chạy tự động mà không hỏi lại.

5. 📊 Kiểm Tra Trạng Thái Hệ Thống

Để biết hệ thống đang quản lý những khách hàng nào và session còn hoạt động không:

bash

gbs status

Kết quả mẫu:

🔐 Chrome Profiles
┌──────────┬───────────┬─────────────┬─────────────┐
│ Profile  │ Customer  │ Marketplace │ Has Session │
├──────────┼───────────┼─────────────┼─────────────┤
│ Vita..   │ vita_dairy│ shopee      │ ✅          │
│ Vita..   │ vita_dairy│ lazada      │ ✅          │
│ Vita..   │ vita_dairy│ tiktok      │ ❌          │ ← Cần login lại
│ Hara     │ hara_test │ shopee      │ ✅          │
└──────────┴───────────┴─────────────┴─────────────┘

✅ = Session còn hoạt động, hệ thống có thể tự tải báo cáo
❌ = Session hết hạn, cần chạy gbs login lại

6. 🔄 Chạy Thu Thập Dữ Liệu Ngay Lập Tức

Nếu bạn cần lấy báo cáo ngay bây giờ mà không muốn chờ đến 2h sáng:

bash

# Chạy tất cả khách hàng, tất cả sàn
gbs crawl

# Chỉ chạy cho 1 khách hàng cụ thể
gbs crawl -c vita_dairy

# Chỉ chạy báo cáo của sàn Shopee
gbs crawl -c vita_dairy -m shopee

# Xem trước sẽ chạy gì mà không chạy thật (an toàn)
gbs crawl --dry-run

Kết quả mẫu:

📋 Crawl Jobs (5 total)
┌────────────┬─────────────┬────────┬───────────┬──────────┬──────────┐
│ Customer   │ Marketplace │ Report │ Frequency │ Priority │ Status   │
├────────────┼─────────────┼────────┼───────────┼──────────┼──────────┤
│ vita_dairy │ shopee      │ income │ monthly   │ high     │ ✅ Ready │
│ vita_dairy │ shopee      │ wallet │ monthly   │ high     │ ✅ Ready │
│ vita_dairy │ shopee      │ ads..  │ daily     │ medium   │ ✅ Ready │
└────────────┴─────────────┴────────┴───────────┴──────────┴──────────┘

  ✅ shopee/income: 1 files (45s)
  ✅ shopee/wallet: 1 files (30s)
  ❌ shopee/ads_onsite: Timeout — Retrying...
  ✅ shopee/ads_onsite: 2 files (60s)

📊 Summary: 3 success | 0 errors | 0 session expired

7. ⏰ Bật Chế Độ Tự Động (Chạy Hằng Ngày)

Để hệ thống chạy ngầm tự động mỗi ngày vào 2h sáng:

bash

gbs schedule

Kết quả:

🚀 Scheduler started (Daemon Mode)
  - Daily full crawl configured to run at 02:00
  - Press Ctrl+C to exit

💡 Quan trọng: Bạn cần giữ Terminal này mở (hoặc dùng tmux/screen trên server) để hệ thống tiếp tục chạy. Nếu đóng Terminal, hệ thống sẽ dừng.

📋 Tóm Tắt Nhanh — Cheat Sheet

Tôi muốn...	Làm gì
Lấy file báo cáo	Vào thư mục `data/[Tên khách hàng]/`
Tìm file nhanh qua Terminal	`uv run scripts/gbs_ops.py report get --client "Tên KH"`
Thêm khách hàng mới	`uv run scripts/gbs_ops.py client add --name "Tên KH"`
Đăng nhập lần đầu (Shopee)	`gbs login -c customer_id -m shopee`
Đăng nhập lần đầu (TikTok)	`gbs login -c customer_id -m tiktok`
Xóa khách hàng	`uv run scripts/gbs_ops.py client remove --name "Tên KH"`
Chạy crawl ngay	`gbs crawl`
Bật tự động hằng ngày	`gbs schedule`
Kiểm tra trạng thái	`gbs status`
Bị văng đăng nhập	`gbs login -c customer_id -m marketplace` rồi đăng nhập tay

❓ Gặp Vấn Đề?

Tình huống	Giải pháp
Nhận tin nhắn Telegram báo lỗi `SessionExpired`	Chạy `gbs login` rồi đăng nhập tay (xem Mục 4)
Không thấy file báo cáo mới trong `data/`	Kiểm tra `gbs status` xem session còn ✅ không
Lỗi `Timeout` khi crawl	Thử chạy lại — hệ thống tự retry 1 lần. Nếu vẫn lỗi thì kiểm tra mạng
Lỗi phức tạp hơn (giao diện sàn bị đổi)	Xem Hướng dẫn kết hợp AI để nhờ AI fix tự động
Không biết dùng Terminal	Nhờ kỹ thuật viên hoặc xem phần Cài đặt & Khởi động

📌 Tài liệu này được cập nhật lần cuối: Tháng 5/2026

📖 Hướng Dẫn Sử Dụng Hằng Ngày ​

Hệ thống hoạt động như thế nào? (30 giây) ​

1. 🗂️ Lấy Báo Cáo Cho Khách Hàng ​

Cách 1: Mở thư mục bằng Finder (Đơn giản nhất) ​

Cách 2: Dùng câu lệnh (Nhanh hơn) ​

2. ➕ Thêm Khách Hàng Mới ​

Bước 1: Tạo Profile ​

Bước 2: Đăng nhập lần đầu ​

Bước 3: Thêm vào danh sách cấu hình ​

3. ➖ Ngừng Lấy Dữ Liệu Của Một Khách Hàng ​

4. 🔐 Xử Lý Khi Bị Văng Đăng Nhập ​

Tại sao bị văng? ​

Làm sao biết bị văng? ​

Cách xử lý (chỉ mất 2 phút) ​

5. 📊 Kiểm Tra Trạng Thái Hệ Thống ​

6. 🔄 Chạy Thu Thập Dữ Liệu Ngay Lập Tức ​

7. ⏰ Bật Chế Độ Tự Động (Chạy Hằng Ngày) ​

📋 Tóm Tắt Nhanh — Cheat Sheet ​

❓ Gặp Vấn Đề? ​

📖 Hướng Dẫn Sử Dụng Hằng Ngày

Hệ thống hoạt động như thế nào? (30 giây)

1. 🗂️ Lấy Báo Cáo Cho Khách Hàng

Cách 1: Mở thư mục bằng Finder (Đơn giản nhất)

Cách 2: Dùng câu lệnh (Nhanh hơn)

2. ➕ Thêm Khách Hàng Mới

Bước 1: Tạo Profile

Bước 2: Đăng nhập lần đầu

Bước 3: Thêm vào danh sách cấu hình

3. ➖ Ngừng Lấy Dữ Liệu Của Một Khách Hàng

4. 🔐 Xử Lý Khi Bị Văng Đăng Nhập

Tại sao bị văng?

Làm sao biết bị văng?

Cách xử lý (chỉ mất 2 phút)

5. 📊 Kiểm Tra Trạng Thái Hệ Thống

6. 🔄 Chạy Thu Thập Dữ Liệu Ngay Lập Tức

7. ⏰ Bật Chế Độ Tự Động (Chạy Hằng Ngày)

📋 Tóm Tắt Nhanh — Cheat Sheet

❓ Gặp Vấn Đề?