WooCommerce - Google Sheets Sync Plugin

Plugin WordPress giúp đồng bộ đơn hàng WooCommerce sang Google Sheets theo 2 chế độ:

• Đồng bộ ngay lập tức (real-time) ngay sau khi đơn hàng được khởi tạo.
• Đồng bộ theo lịch trình (WP-Cron), bất kể trạng thái đơn, miễn là chưa đồng bộ.

Tài liệu này dùng làm kế hoạch kỹ thuật + định hướng phát triển cho plugin.

---

1. Mục tiêu

• Tự động đồng bộ dữ liệu đơn hàng WooCommerce sang Google Sheets
• Cho phép quản trị viên cấu hình linh hoạt
• Hoạt động ổn định với số lượng đơn lớn
• Dễ mở rộng (mapping field, nhiều sheet, retry, log)

---

2. Phạm vi chức năng

2.1. Hỗ trợ WooCommerce

• Đơn hàng (Orders)
• Khách hàng
• Sản phẩm trong đơn
• Tổng tiền, phí ship, coupon, trạng thái đơn

2.2. Google Sheets

• Ghi dữ liệu vào Google Spreadsheet
• Tự động tạo header (nếu chưa có)
• Append dòng mới hoặc update theo Order ID

---

3. Các tính năng chính

3.1. Kết nối Google API (OAuth2)

• Kết nối Google bằng OAuth2
• Lưu Access Token & Refresh Token
• Tự động refresh token khi hết hạn

Scopes sử dụng:

https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/drive.file

---

3.2. Chế độ đồng bộ

A. Đồng bộ ngay lập tức (Real-time)

• Trigger khi:

  • Tạo đơn hàng mới
  • Thay đổi trạng thái đơn (tùy chọn, mặc định là OFF)

• Hook sử dụng:

  • woocommerce_new_order
  • woocommerce_update_order

Luồng xử lý:

Woo Event - Prepare Data - Push to Google Sheets

B. Đồng bộ theo lịch (Scheduled Sync)

• Dựa trên WP-Cron
• Tùy chọn lịch chạy:
  • 5 phút
  • 15 phút
  • 30 phút
  • 1 giờ
  • Hàng ngày

Luồng xử lý:

Cron Trigger - Get Unsynced Orders - Push - Mark as Synced

---

3.3. Mapping dữ liệu

Cho phép ánh xạ dữ liệu WooCommerce - Google Sheets:

WooCommerce Field	Google Sheet Column
Order ID	order_id
Order Date	order_date
Status	status
Customer Name	customer_name
Email	email
Phone	phone
Total	total
Payment Method	payment_method

• Có thể mở rộng thêm custom field / meta
• Lưu mapping bằng wp_options

---

3.4. Quản lý Google Sheet

• Nhập Spreadsheet ID
• Chọn Sheet Tab (worksheet)
• Tùy chọn:
  • Append row
  • Update row theo Order ID

---

3.5. Logging & Error Handling

• Lưu log đồng bộ:

  • Thời gian
  • Order ID
  • Trạng thái
  • Message lỗi (nếu có)

• Retry khi lỗi:

  • Timeout
  • Google API error

---

4. Giao diện quản trị (Admin UI)

4.1. Menu Plugin

WooCommerce
 └─ Sync to Google Sheets
     ├─ Google API Settings
     ├─ Sync Settings
     ├─ Field Mapping
     └─ Sync Logs

---

4.2. Google API Settings

• Connect / Disconnect Google Account
• Hiển thị trạng thái kết nối
• Nhập Spreadsheet ID
• Nhập Sheet Name

---

4.3. Sync Settings

• Chọn chế độ đồng bộ:

  • Real-time
  • Scheduled

• Chọn chu kỳ cron

• Chọn trạng thái đơn cần sync (pending, processing, completed...)

---

4.4. Logs

Bảng log: | Time | Order ID | Mode | Status | Message |

---

5. Kiến trúc plugin

5.1. Cấu trúc thư mục

echbay-wc-gsheet-sync/
├─ echbay-wc-gsheet-sync.php    (File chính của plugin)
├─ README.md                     (Tài liệu này)
├─ includes/
│  ├─ class-admin.php            (Quản lý admin UI)
│  ├─ class-google-client.php    (Xử lý Google API, OAuth2)
│  ├─ class-order-mapper.php     (Map dữ liệu WooCommerce sang Sheets)
│  ├─ class-sync-realtime.php    (Đồng bộ real-time)
│  ├─ class-sync-cron.php        (Đồng bộ theo lịch)
│  └─ class-logger.php           (Ghi log)
├─ assets/
│  ├─ css/
│  │  └─ admin.css               (CSS cho trang admin)
│  └─ js/
│     └─ admin.js                (JS cho trang admin)
├─ languages/                    (Thư mục đa ngôn ngữ - tùy chọn)

---

6. Cron & Performance

6.1. Custom Cron Schedule

• Tạo custom cron interval tùy chỉnh
• Hook: cron_schedules

6.2. Batch Processing

• Giới hạn: Sync tối đa 20-50 đơn mỗi lần chạy cron
• Tránh timeout và quá tải API
• Sử dụng pagination khi query orders

6.3. Tránh trùng lặp

• Lưu meta _gsheet_synced = 1 khi đã sync
• Lưu meta _gsheet_synced_time = timestamp
• Cho phép retry khi cần (xóa meta để sync lại)

6.4. Cache & Optimization

• Cache Google token
• Batch API calls khi có thể
• Sử dụng transients cho dữ liệu tạm

---

7. Bảo mật

7.1. Quyền truy cập

• Check quyền manage_woocommerce cho tất cả trang admin
• Chỉ admin mới được cấu hình plugin

7.2. Form Security

• Sử dụng wp_nonce_field() và wp_verify_nonce() cho tất cả form
• Validate và sanitize mọi input

7.3. API Credentials

• KHÔNG expose access token ra frontend
• Lưu credentials trong wp_options với tên có prefix _ (private)
• Sử dụng wp_remote_post() thay vì CURL trực tiếp

7.4. Google OAuth Setup

Bước 1: Tạo Google Cloud Project

1. Truy cập https://console.cloud.google.com
2. Tạo project mới
3. Enable Google Sheets API
4. Tạo OAuth 2.0 Client ID (Web Application)
5. Thêm Redirect URI: https://your-site.com/wp-admin/admin.php?page=wc-gsheet-sync-oauth-callback

Bước 2: Copy Client ID & Client Secret vào plugin settings

---

8. Kế hoạch phát triển (Roadmap)

Phase 1 (MVP)

• Sync đơn hàng
• OAuth2 Google
• Real-time + Cron
• Basic mapping

Phase 2

• Sync sản phẩm
• Multi-sheet
• Filter nâng cao

Phase 3 (PRO)

• Webhook Google
• Backfill dữ liệu cũ
• Dashboard thống kê

---

9. Yêu cầu hệ thống

• WordPress: >= 6.0
• WooCommerce: >= 7.0
• PHP: >= 8.0
• PHP Extensions: cURL, JSON
• Google Cloud Project: Với Sheets API được bật
• OAuth 2.0 Credentials: Client ID & Client Secret từ Google Console

---

10. Ví dụ dữ liệu sync

10.1. Ví dụ dòng dữ liệu trong Google Sheets

order_id	order_date	status	customer_name	email	phone	total	payment_method
1001	2026-01-24 10:30:00	processing	Nguyễn Văn A	a@example.com	0909123456	500000	cod
1002	2026-01-24 11:15:00	completed	Trần Thị B	b@example.com	0908234567	750000	bank_transfer

10.2. Meta keys sử dụng

• _gsheet_synced: Giá trị 1 = đã sync, chưa có = chưa sync
• _gsheet_synced_time: Timestamp lần sync cuối
• _gsheet_sync_error: Message lỗi nếu sync thất bại

---

11. Ghi chú kỹ thuật

11.1. Code Standards

• Plugin không sử dụng thư viện bên ngoài ở frontend
• Sử dụng WordPress Coding Standards
• Comment code bằng tiếng Việt cho dễ hiểu

11.2. Google API

• Có thể dùng REST API trực tiếp (wp_remote_post)
• Hoặc sử dụng Google PHP Client (nếu cần tính năng phức tạp)
• Ưu tiên REST API để giảm dependency

11.3. Database

• Không tạo custom table
• Sử dụng post_meta cho order data
• Sử dụng wp_options cho settings
• Có thể dùng transients cho cache ngắn hạn

11.4. Nguyên tắc phát triển

• Code dễ đọc, dễ bảo trì
• Dễ mở rộng thêm tính năng
• Tuân thủ hướng dẫn trong .github/copilot-instructions.md
• Nhớ tăng version khi sửa CSS/JS để clear cache

---

12. API Endpoints (Nếu cần)

Có thể tạo REST API endpoints cho các tác vụ:

• POST /wp-json/wc-gsheet/v1/sync-order/{order_id} - Sync thủ công 1 đơn
• POST /wp-json/wc-gsheet/v1/sync-all - Sync tất cả đơn chưa sync
• GET /wp-json/wc-gsheet/v1/status - Kiểm tra trạng thái kết nối

---

Author: Internal Dev Team
License: GPLv2 hoặc cao hơn
Version: 1.0.0 (MVP)