ewoooc/AUTO_IMPORT_README.md

Google Drive 自動匯入功能說明

✨ 功能概述

系統現在支援從 Google Drive 自動匯入當日業績 Excel 檔案！

主要特點

• 🔄 自動化流程：每 30 分鐘自動檢查 Google Drive
• 📥 自動下載：發現新檔案立即下載到本地
• 💾 自動匯入：解析 Excel 並匯入到資料庫
• 🗑️ 自動清理：匯入完成後刪除 Google Drive 原檔
• 📊 進度追蹤：完整的任務狀態與進度顯示
• 🌐 網頁介面：直觀的設定和監控介面

---

📁 新增檔案清單

後端服務

• services/google_drive_service.py - Google Drive API 服務模組
• services/import_service.py - 自動匯入服務邏輯
• database/import_models.py - 匯入任務與配置資料表模型
• auto_import_routes.py - API 路由（Blueprint）

前端介面

• web/auto_import_index.html - 自動匯入管理頁面

配置與文檔

• config/ - 存放 Google Drive API 憑證（需自行設定）
• GOOGLE_DRIVE_SETUP.md - 詳細的設定指南
• AUTO_IMPORT_README.md - 本檔案
• test_google_drive.py - 測試腳本

資料庫

• 新增資料表：import_jobs - 匯入任務記錄
• 新增資料表：import_config - 匯入配置

---

🚀 快速開始

1. 安裝依賴

pip install -r requirements.txt

新增的套件：

• google-auth
• google-auth-oauthlib
• google-auth-httplib2
• google-api-python-client

2. 設定 Google Drive API

請參考：GOOGLE_DRIVE_SETUP.md

簡要步驟：

1. 建立 Google Cloud 專案
2. 啟用 Google Drive API
3. 建立 OAuth 2.0 憑證
4. 下載憑證檔案並放到 config/google_credentials.json
5. 執行首次認證

3. 配置資料夾路徑

1. 在 Google Drive 建立資料夾結構：

   我的雲端硬碟/
   └── 業績報表/
       └── 當日業績/
   

2. 開啟網頁介面：http://localhost/auto_import

3. 設定：

   • Google Drive 資料夾路徑：業績報表/當日業績
   • 檔案名稱模式：即時業績_當日

4. 點擊「儲存配置」

4. 測試連接

執行測試腳本：

python3 test_google_drive.py

或在網頁介面點擊「測試連接」

5. 上傳測試檔案

將當日業績 Excel 檔案上傳到 Google Drive 的 業績報表/當日業績 資料夾

6. 手動測試匯入

在網頁介面點擊「立即匯入」，觀察匯入進度

---

🎯 使用方式

自動模式（推薦）

系統每 30 分鐘自動執行：

1. 檢查 Google Drive 指定資料夾
2. 發現新的 Excel 檔案
3. 自動下載到本地 data/temp/
4. 自動匯入到資料庫
5. 自動刪除 Google Drive 原檔
6. 清理本地暫存檔

手動模式

在網頁介面點擊「立即匯入」可手動觸發匯入流程。

監控進度

開啟：http://localhost/auto_import

可以看到：

• ✅ 匯入配置
• 📋 檔案清單
• 📊 匯入任務歷史
• 🔄 即時進度更新（每 10 秒自動刷新）

---

📊 資料表結構

import_jobs（匯入任務）

欄位	類型	說明
id	INTEGER	任務 ID
job_type	VARCHAR	任務類型（daily_sales, vendor_stockout）
status	VARCHAR	狀態（pending, downloading, importing, completed, failed）
drive_file_id	VARCHAR	Google Drive 檔案 ID
drive_file_name	VARCHAR	檔案名稱
drive_file_size	INTEGER	檔案大小（bytes）
local_file_path	VARCHAR	本地檔案路徑
progress_percent	FLOAT	進度百分比 (0-100)
current_step	VARCHAR	當前步驟描述
total_rows	INTEGER	總行數
processed_rows	INTEGER	已處理行數
success_rows	INTEGER	成功匯入行數
error_rows	INTEGER	錯誤行數
created_at	DATETIME	建立時間
started_at	DATETIME	開始時間
completed_at	DATETIME	完成時間
error_message	TEXT	錯誤訊息
import_summary	TEXT	匯入摘要（JSON）

import_config（匯入配置）

欄位	類型	說明
id	INTEGER	配置 ID
config_key	VARCHAR	配置鍵
config_value	TEXT	配置值
config_type	VARCHAR	配置類型（string, int, bool, json）
description	VARCHAR	配置說明
created_at	DATETIME	建立時間
updated_at	DATETIME	更新時間

---

🔧 API 端點

查詢任務清單

GET /api/import_jobs?limit=20

查詢單一任務

GET /api/import_jobs/{job_id}

取得配置

GET /api/import_config

設定配置

POST /api/import_config
Content-Type: application/json

{
  "folder_path": "業績報表/當日業績",
  "file_pattern": "即時業績_當日"
}

測試連接

POST /api/test_drive_connection

列出檔案

POST /api/list_drive_files
Content-Type: application/json

{
  "folder_path": "業績報表/當日業績",
  "file_pattern": "即時業績_當日"
}

手動觸發匯入

POST /api/manual_import

---

⚙️ 排程設定

在 app.py 中已註冊排程：

# 每半小時執行一次 Google Drive 自動匯入任務
schedule.every(30).minutes.do(run_auto_import_task)

修改檢查頻率

編輯 app.py：

# 每 15 分鐘
schedule.every(15).minutes.do(run_auto_import_task)

# 每小時
schedule.every(1).hours.do(run_auto_import_task)

# 每天早上 8 點
schedule.every().day.at("08:00").do(run_auto_import_task)

---

🔒 安全性

敏感檔案保護

以下檔案已加入 .gitignore：

• config/google_credentials.json - OAuth 2.0 憑證
• config/google_token.pickle - 存取權杖
• config/*.json - 所有 JSON 配置
• config/*.pickle - 所有 pickle 檔案

OAuth 權限範圍

目前使用：https://www.googleapis.com/auth/drive（完整 Drive 存取）

如需更嚴格控制，可修改 services/google_drive_service.py 中的 SCOPES：

# 僅存取應用程式建立的檔案
SCOPES = ['https://www.googleapis.com/auth/drive.file']

# 僅讀取檔案
SCOPES = ['https://www.googleapis.com/auth/drive.readonly']

授權管理

• 檢查授權：https://myaccount.google.com/permissions
• 撤銷授權：刪除 config/google_token.pickle 並重新認證

---

📝 日誌

查看自動匯入日誌

tail -f logs/system.log | grep AutoImport

查看排程統計

cat data/scheduler_stats.json | jq '.auto_import_task'

---

🐛 故障排除

問題 1：認證失敗

解決方法：

1. 確認 config/google_credentials.json 存在
2. 刪除 config/google_token.pickle 並重新認證
3. 執行：python3 test_google_drive.py

問題 2：找不到資料夾

解決方法：

1. 確認資料夾路徑正確（區分大小寫）
2. 確認使用正確的 Google 帳號
3. 在網頁介面點擊「列出檔案」測試

問題 3：檔案沒有被刪除

解決方法：

1. 檢查任務狀態是否為「已完成」
2. 查看日誌：tail -f logs/system.log
3. 確認 Google Drive API 權限正確

問題 4：匯入失敗

解決方法：

1. 檢查 Excel 檔案格式是否正確
2. 查看任務的錯誤訊息
3. 手動測試：在網頁介面點擊「立即匯入」

---

🔄 工作流程

┌─────────────────┐
│  Google Drive   │
│   新檔案上傳     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  排程任務執行    │
│ (每 30 分鐘)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   檢查檔案清單   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   建立匯入任務   │
│  (import_jobs)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   下載到本地     │
│  data/temp/     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   解析 Excel     │
│   匯入資料庫     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 刪除 Drive 原檔  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   清理本地檔案   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   任務完成       │
│  更新狀態記錄    │
└─────────────────┘

---

📚 相關文檔

• Google Drive API 設定指南
• Docker 部署指南
• GCP Cloud Run 部署

---

🎉 完成！

您現在擁有一個完全自動化的當日業績匯入系統！

使用流程：

1. 將 Excel 檔案上傳到 Google Drive
2. 系統每 30 分鐘自動檢查
3. 自動下載、匯入、刪除
4. 在網頁介面監控進度

無需手動操作！ 🚀