📚 Vibe Coding SOP: GBS Crawler

Tóm tắt nhanh

Tài liệu này là cẩm nang (SOP) dành cho đội ngũ phát triển để hiểu kiến trúc cốt lõi của GBS Crawler (hệ thống tự động tải báo cáo Shopee, Lazada, TikTok qua Playwright) và cách sử dụng Vibe Coding (Agentic AI) một cách an toàn, hiệu quả để bảo trì và mở rộng dự án.

1. Tổng Quan Kiến Trúc Dự Án (Architecture)

Dự án được xây dựng trên Python + Playwright, tập trung vào tính ổn định khi tương tác với các Seller Center.

• src/crawlers/base.py (BaseCrawler): Chứa logic quản lý Context Browser (ẩn danh, profile), xử lý file cơ bản.
• src/crawlers/shopee/base.py (ShopeeBaseCrawler): Kế thừa BaseCrawler. Đóng gói toàn bộ logic đặc thù của Shopee bao gồm:
  • Vượt Security Challenge (nhập mật khẩu tại trang Tài Chính).
  • Đóng Onboarding Modals (Bỏ qua, Để sau).
  • Chọn ngày trên lịch (Date Picker EDS bằng Javascript injection).
• Domain Crawlers: Các class con xử lý từng loại báo cáo (income.py, wallet.py, ads_onsite.py).
• DownloadManager: Chịu trách nhiệm quản lý vòng đời tải file, kiểm tra tính toàn vẹn (MD5, File Size).
• Thư mục tests/: Chứa kịch bản test gate (test_03_logic.py, test_04_sync.py, test_05_security.py).

2. Các Quy Tắc Vibe Coding Cho GBS Crawler

Khi yêu cầu AI (CodyMaster) sửa lỗi hoặc thêm tính năng mới cho dự án này, bạn cần tuân thủ các quy tắc sau để tránh làm gãy kiến trúc:

2.1. Không viết logic dùng chung vào các Domain Crawlers

Sai: Nhờ AI viết code đóng popup quảng cáo ngay trong income.py. Đúng: Nhờ AI thêm logic nhận diện và đóng popup vào hàm dismiss_onboarding_modals hoặc handle_security_challenge trong ShopeeBaseCrawler.

2.2. Xử lý Polling (Chờ tải báo cáo)

Hệ thống Seller Center không tải file ngay lập tức mà cần thời gian gen dữ liệu (Report Generation).

• Prompt mẫu: "Hãy viết crawler cho báo cáo X. Lưu ý trang này gen file bất đồng bộ. Sử dụng vòng lặp polling 5 giây/lần và timeout 3 phút để chờ link tải xuất hiện thay vì click và đợi ngay."

2.3. Cô Lập Profile Khách Hàng (Profile Isolation)

Mỗi khách hàng phải chạy trên một Browser Context riêng rẽ để tránh cookie rác.

• Prompt mẫu: "Khi khởi tạo browser context cho crawler mới, đảm bảo truyền đúng profile_name để hệ thống tải đúng file session của khách hàng đó."

3. Quy Trình Vibe Coding Chuẩn (Workflow)

Thực hiện theo các bước sau khi làm việc cùng AI:

Bước 1: Khảo Sát & Lên Kế Hoạch

Trước khi sửa code, luôn chạy:

/cm-planning

Yêu cầu AI đọc src/crawlers/shopee/base.py và luồng test hiện hành để lập kế hoạch.

Bước 2: Viết Code & TDD

Chỉ định rõ file cần sửa, sử dụng skill cm-execution hoặc cm-tdd. Ví dụ: "Hãy implement src/crawlers/shopee/statement.py dựa theo kiến trúc của income.py. Sau đó thêm test case vào tests/test_03_logic.py."

Bước 3: Xác Thực UI (Test Gate)

Các sàn TMĐT liên tục đổi UI, TUYỆT ĐỐI KHÔNG PUSH CODE nếu chưa chạy test nội bộ:

pytest tests/test_03_logic.py

Nếu có lỗi "Element not found" hoặc Timeout, cung cấp log lỗi lại cho AI thông qua cm-debugging. Không tự đoán bừa selector.

Bước 4: Lưu Bài Học (Automated Retro)

Sàn Shopee vừa có thay đổi về nút bấm (Ví dụ: Đổi "Xuất" thành "Tải báo cáo")? Ngay sau khi AI sửa xong, hãy chạy lệnh sau ở terminal để dặn dò AI cho các lần sau:

cm retro --project . --tool antigravity --note "Shopee đã đổi nút Xuất thành Tải báo cáo ở trang Statement, đã update trong ShopeeBaseCrawler."

---

💡 Lời Khuyên Cho Đội Ngũ

Vibe Coding không có nghĩa là để AI tự làm mọi thứ. Bạn là "Pilot" (phi công chính) và AI là "Co-pilot" (cơ phó). Hãy dùng SOP này làm kim chỉ nam để kiểm tra xem AI có đang viết code tuân thủ đúng nguyên lý BaseCrawler - Polling - Isolation hay không!