📊 Phân Tích Mã Nguồn GBS Crawler

Tóm tắt nhanh

Tài liệu này cung cấp cái nhìn tổng quan về hệ thống gbs-crawler, bao gồm các công nghệ được sử dụng, cấu trúc thư mục, và các module nghiệp vụ quan trọng. Hệ thống được thiết kế để tự động hóa việc trích xuất dữ liệu đa nền tảng (Shopee, TikTok) với sự giám sát của AI.

1. Công Nghệ & Nền Tảng

Ngôn ngữ: Python 3.11+
Quản lý gói & môi trường: uv
Automation Browser: Playwright (async)
Xử lý dữ liệu: Pandas
Lập lịch (Scheduling): APScheduler
Thông báo & Alerting: Telegram Bot API (src/core/notifier.py)

2. Cấu Trúc Thư Mục

Hệ thống tuân theo kiến trúc module hóa:

text

gbs-crawler/
├── config/             # Cấu hình hệ thống (YAML, JSON)
├── data/               # Nơi lưu trữ file báo cáo (Excel, CSV) theo khách hàng
├── docs/               # Tài liệu dự án (Docs)
├── profiles/           # Quản lý trình duyệt và biến môi trường theo từng khách hàng
├── scripts/            # Các script CLI tiện ích (VD: gbs_ops.py)
├── src/                # Mã nguồn chính
│   ├── core/           # Quản lý cấu hình, Log, Notifier, Scheduler
│   ├── crawlers/       # Logic crawl cho từng nền tảng (Shopee, TikTok)
│   └── models/         # Định nghĩa các lớp cấu trúc dữ liệu (CrawlResult)
├── tests/              # Test suite (Syntax, API, Logic, Sync, Security)
└── main.py             # Entry point (chạy crawler & scheduler)

3. Luồng Nghiệp Vụ Cốt Lõi

Khởi tạo: Hệ thống đọc danh sách Job (khách hàng, nền tảng) từ cấu hình.
Thực thi: Scheduler gọi BaseCrawler tương ứng (Ví dụ: ShopeeBaseCrawler).
Mô phỏng trình duyệt: Khởi chạy Playwright bằng profile riêng biệt để đảm bảo cô lập dữ liệu.
Kiểm tra an ninh: Xử lý các tình huống Captcha, hết hạn Session thông qua ngoại lệ CrawlerException.
Trích xuất & Tải xuống: Điều hướng tới trang báo cáo, chờ file được tạo, và tải về data/.
Xử lý & Lưu trữ: Pandas đọc file tải về, làm sạch dữ liệu, và xuất ra báo cáo cuối cùng.
Cảnh báo (Alerting): Nếu có lỗi, ném CrawlerException và đẩy cảnh báo đến Telegram (kèm Markdown cho AI).

4. Đặc tả Ngoại lệ (Exception Handling)

Hệ thống được thiết kế để AI dễ dàng can thiệp (AI-Supervised):

SessionExpiredException: Quăng ra khi bị văng đăng nhập.
CaptchaDetectedException: Quăng ra khi bị chặn bởi Captcha cứng.
DataExtractionError: Lỗi khi DOM thay đổi hoặc không tìm thấy element.

5. Test Coverage

Dự án có bộ test suite đầy đủ tại tests/:

test_01_syntax.py: Đảm bảo không có lỗi cú pháp.
test_02_api.py: Mock API responses.
test_03_logic.py: Kiểm thử logic chuẩn hóa dữ liệu.
test_04_sync.py: Đảm bảo đồng bộ hóa tiến trình.
test_05_security.py: Đảm bảo không lộ thông tin nhạy cảm.

📊 Phân Tích Mã Nguồn GBS Crawler ​

1. Công Nghệ & Nền Tảng ​

2. Cấu Trúc Thư Mục ​

3. Luồng Nghiệp Vụ Cốt Lõi ​