🤖 Hướng Dẫn Kết Hợp AI Sửa Lỗi Tự Động

Dành cho: Kỹ thuật viên hoặc nhân viên vận hành muốn nhờ AI (Claude, Google Antigravity, Codex) tự động sửa lỗi hệ thống khi sàn TMĐT thay đổi giao diện.

---

Tại sao cần AI?

Các sàn TMĐT (Shopee, TikTok, Lazada) thường xuyên thay đổi giao diện mà không thông báo trước:

• Đổi tên nút bấm ("Xuất" → "Tải báo cáo")
• Đổi vị trí menu
• Thêm popup quảng cáo chặn thao tác
• Thay đổi cấu trúc HTML/CSS

Thay vì nhờ lập trình viên sửa code thủ công, bạn có thể nhờ AI tự đọc giao diện mới và tự sửa code.

---

Các Loại Lỗi Và Cách Xử Lý

🟡 Loại 1: Văng Đăng Nhập (SessionExpiredException)

Nguyên nhân: Sàn bắt đăng nhập lại vì Cookie hết hạn (bình thường, 7-30 ngày/lần).

Cách xử lý: Không cần AI — tự đăng nhập lại là xong.

gbs login -c vita_dairy -m shopee
# → Trình duyệt mở lên → Đăng nhập tay → Đóng trình duyệt

Khi nào cần AI: Chỉ khi form đăng nhập bị đổi hoàn toàn (trường hợp hiếm).

---

🔴 Loại 2: Giao Diện Thay Đổi (DataExtractionError)

Nguyên nhân: Sàn đổi HTML/CSS → Selector của hệ thống không tìm thấy nút bấm nữa.

Tin nhắn Telegram:

🛑 AI Intervention needed
Customer: vita_dairy | Marketplace: shopee
Error: DataExtractionError — Could not find element: 
  button[data-testid="export-btn"]

Cách xử lý với AI:

Bước 1: Copy toàn bộ tin nhắn lỗi từ Telegram.

Bước 2: Mở Claude / Antigravity / Codex, dán đoạn lỗi kèm prompt:

Hệ thống gbs-crawler vừa báo lỗi. Hãy dùng skill @gbs-crawler-ops để tự 
động kiểm tra và fix lỗi này giúp tôi:

[DÁN LOG LỖI VÀO ĐÂY]

Bước 3: AI sẽ tự động:

1. Mở trình duyệt thật lên, load trang Shopee/TikTok
2. Quét HTML mới nhất, tìm selector đúng
3. Sửa code trong file crawler (VD: src/crawlers/shopee/base.py)
4. Chạy test gbs crawl để xác nhận
5. Ghi lại thay đổi vào CHANGELOG.md

Kết quả: Code được cập nhật tự động mà bạn không cần gõ 1 dòng.

---

🟠 Loại 3: Bị Chặn Captcha (CaptchaDetectedException)

Nguyên nhân: Sàn nghi ngờ bot → bắt giải Captcha hình ảnh hoặc kéo puzzle.

Cách xử lý: AI + Người cùng phối hợp.

1. AI sẽ mở trình duyệt sẵn
2. AI sẽ thông báo: "Giao diện bị chặn bởi Captcha. Tôi đã mở sẵn trình duyệt. Bạn vui lòng kéo mảnh ghép Captcha giúp tôi, sau đó chat 'OK' để tôi chạy tiếp."
3. Bạn dùng chuột kéo mảnh ghép Captcha
4. Bạn quay lại chat OK
5. AI tiếp tục crawl

---

🔵 Loại 4: Lỗi Lưu File (FileIOError)

Nguyên nhân: Thư mục data/ bị thiếu, hoặc file đang bị mở bởi Excel.

Cách xử lý:

• Đóng file Excel đang mở
• Kiểm tra thư mục data/[Tên KH]/ có tồn tại không
• Chạy lại gbs crawl

---

Quy Tắc Vàng

┌─────────────────────────────────────────────────────────────────┐
│  LOẠI LỖI                    │  AI tự sửa?  │  Cần bạn làm?   │
├──────────────────────────────┼──────────────┼─────────────────┤
│  Giao diện thay đổi (UI)    │  ✅ 100%     │  Chỉ cần dán log│
│  Captcha / OTP               │  ❌ Một phần │  Bạn giải giúp  │
│  Văng đăng nhập              │  ❌          │  Bạn login lại  │
│  Lỗi file / thư mục         │  ✅          │  Đóng Excel     │
└──────────────────────────────┴──────────────┴─────────────────┘

An Toàn Khi Dùng AI Sửa Code

1. Mọi thay đổi đều có Git quản lý. AI không thể xóa vĩnh viễn bất cứ gì. Bạn luôn có thể git revert để quay lại.

2. AI luôn cập nhật CHANGELOG.md sau mỗi lần sửa — bạn có thể đọc lại xem AI đã làm gì.

3. AI chạy test trước khi hoàn tất. Nếu test fail → AI sẽ tiếp tục sửa hoặc báo cáo lại.

---

📌 Xem thêm: Vibe Coding SOP (quy tắc cho developer khi code cùng AI)