🤖 Hermes-Agent-Shopee (Notion to BigSeller Excel Auto Sync Bot)

Hệ thống tự động hóa đồng bộ sản phẩm từ Notion Database sang BigSeller Excel bằng AI thế hệ mới, tích hợp Telegram Bot cảnh báo thời gian thực và cơ chế hoạt động bền bỉ (resiliency) cấp chuyên nghiệp.

---

🧭 Luồng Làm Việc Của Hệ Thống (Workflow)

Hệ thống hoạt động theo mô hình khép kín tự động hóa giữa Notion, Google Drive, AI API, BigSeller Excel và Telegram:

graph TD
    A[Nhân viên Content] -- Chuẩn bị mô tả & ảnh --> B[Notion Database]
    B -- Tích chọn 'Bài viết' = True --> C{Bot Quét Ngầm Notion}
    C -- 2 phút/lần: Phát hiện bài mới --> D[Cảnh báo Telegram Quản lý]
    
    E[Quản lý gửi lệnh /sync] --> F[Notion Sync Module]
    F -- Đọc dữ liệu sản phẩm --> G[Google Drive Image Converter]
    G -- Lấy Direct Link Ảnh --> H[AI Generator: OpenAI/Gemini]
    H -- Viết bài chuẩn SEO theo Insight --> I[Tách biến thể & Tạo Excel BigSeller]
    I -- Tải lên Telegram & Trả file --> J[Người Quản lý tải về]
    J -- Cập nhật Notion: Trạng thái đăng shopee = True --> K[Ghi log Nội dung đăng dạng chunk]
    J -- Tự động xóa file Excel tạm cục bộ --> L[Dọn dẹp đĩa cứng]

Chi tiết các bước xử lý:

1. Quét ngầm & Cảnh báo: Luồng quét ngầm định kỳ chạy mỗi 2 phút. Nếu có sản phẩm mới (có tên, ô Bài viết đã tích, ô Trạng thái đăng shopee chưa tích), bot sẽ gửi thông báo: "Shopee MCP Server xin thông báo: CÓ SẢN PHẨM MỚI CHỜ ĐĂNG SHOPEE!" tới Quản lý.
2. Kích hoạt đồng bộ: Quản lý gửi tin nhắn /sync qua Telegram. Bot tiến hành tải dữ liệu Notion của các sản phẩm thỏa mãn điều kiện.
3. Xử lý hình ảnh: Link thư mục Google Drive của sản phẩm được phân tích tự động, chuyển đổi toàn bộ ảnh bên trong thành link download trực tiếp (Direct Link) tương thích với Shopee CDN.
4. Sinh bài viết bằng AI: Đối với mỗi dòng Insight trong cột Insight Library, AI (tự động nhận diện Gemini hoặc OpenAI) sẽ sinh một phiên bản tiêu đề và mô tả sản phẩm chuẩn SEO marketing chuyên nghiệp, bám sát insight khách hàng và tự động dọn dẹp các từ khóa bị Shopee VN cấm (đặc trị, dứt điểm, tốt nhất...).
5. Xuất bản Excel: Tách phân loại giá từ cột Biến thể & giá, tạo SKU phụ tương ứng, để trống cột SKU sản phẩm (SKU cha) theo tiêu chuẩn BigSeller và xuất file Excel.
6. Báo cáo & Dọn dẹp: Gửi file Excel qua Telegram, cập nhật cột Nội dung đăng và tích chọn Trạng thái đăng shopee = True trên Notion. Đồng thời xóa file Excel tạm trong thư mục output/ để bảo vệ tài nguyên máy chủ.

---

✨ Tính Năng Nổi Bật

• Tự động hóa hoàn toàn: Chuyển đổi dữ liệu thô từ Notion thành file Excel BigSeller sẵn sàng import lên sàn Shopee.
• AI Copywriter Đa Năng: Hỗ trợ tự động nhận diện cả OpenAI API Key (sk-...) và Gemini API Key (AIzaSy...) để tối ưu hóa chi phí và hiệu năng.
• Resilience & Auto-Reconnect (Chống treo cấp độ dịch vụ):
  • Socket Timeout: Cấu hình mặc định 30 giây tránh treo socket mạng khi truyền tải dữ liệu lớn.
  • Notion API Retry: Bọc toàn bộ các cuộc gọi API Notion bằng thuật toán thử lại tự động (Exponential Backoff) nếu gặp lỗi quá tải hoặc rớt mạng tạm thời.
  • Bot Watchdog: Theo dõi và hồi sinh tự động thread quét Notion ngầm nếu luồng này bị crash đột ngột.
  • Infinity Polling: Giúp bot Telegram liên tục kết nối lại khi internet không ổn định.

---

📋 Cấu Trúc Bảng Notion (Database Schema)

Để bot hoạt động chính xác, bảng Notion của bạn cần cấu hình tối thiểu các cột sau:

Tên Cột Notion	Kiểu Dữ Liệu	Vai Trò
Tên sản phẩm	Title (Mặc định)	Tên gốc của sản phẩm cần xử lý
Bài viết	Checkbox	Content tích chọn khi chuẩn bị xong hình ảnh/mô tả thô
Trạng thái đăng shopee	Checkbox	Bot tích chọn True sau khi đã xuất Excel thành công
Insight Library	Relation hoặc Rich text	Chứa các insight đối tượng mục tiêu để AI viết bài chuẩn xác
Biến thể & giá	Rich text	Định dạng giá đơn lẻ (90.000) hoặc biến thể (Hộp 30v: 90.000 | Hộp 60v: 170.000)
Media sản phẩm	URL	Đường link thư mục Google Drive chứa hình ảnh sản phẩm
Nội dung đăng	Rich text	Bot tự động ghi đè bản tóm tắt bài viết AI sinh ra (giới hạn < 2000 kí tự/chunk)

---

🛠️ Yêu Cầu Hệ Thống & Cài Đặt

1. Yêu cầu hệ thống:

• Python 3.10 trở lên.
• Cài đặt thư viện dependencies:

  pip install -r requirements.txt
  

2. Thiết lập Biến môi trường (.env):

Tạo file .env tại thư mục gốc của dự án và cấu hình đầy đủ các biến sau:

# Notion Credentials
NOTION_TOKEN=secret_your_notion_token_here
NOTION_DATABASE_ID=your_notion_database_page_id_here

# Telegram Bot Credentials
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
MANAGER_CHAT_ID=6295080195  # Chat ID nhận cảnh báo sản phẩm mới

# AI API Credentials (Hỗ trợ OpenAI sk- hoặc Gemini AIzaSy)
GEMINI_API_KEY=your_openai_or_gemini_api_key_here

3. Khởi chạy hệ thống:

Sử dụng script khởi chạy nhanh trên Windows (sử dụng đường dẫn tương đối):

# Chạy file batch
start_bot.bat

# Hoặc khởi chạy trực tiếp bằng python
python -m src.telegram_bot

---

📦 Kiến Trúc Thư Mục Dự Án

shopee-mcp-server/
├── src/
│   ├── __init__.py
│   ├── config.py             # Quản lý cấu hình & đọc biến môi trường
│   ├── telegram_bot.py       # Bot Telegram chính, điều hướng & chạy quét ngầm
│   ├── notion_sync.py        # Module xử lý dữ liệu và đồng bộ Notion
│   ├── ai_generator.py       # Kết nối OpenAI / Gemini sinh content chuẩn SEO
│   ├── convert_zicum.py      # Module cào ảnh Google Drive sang direct link
│   └── notion_to_bigseller.py# Hàm phụ trợ xuất file excel cấu trúc BigSeller
├── import_template_VN.xlsx   # File template mẫu gốc của BigSeller
├── requirements.txt          # Các thư viện phụ thuộc
├── start_bot.bat             # File script chạy nhanh trên Windows
└── README.md                 # Tài liệu hướng dẫn sử dụng

---

🛡️ Bản Quyền & Giấy Phép

Dự án được phát triển nhằm phục vụ tự động hóa quy trình quản lý của hệ thống Hermes Agent. Nghiêm cấm chia sẻ file cấu hình .env chứa API Token nhạy cảm lên các kho lưu trữ công cộng.