408 lines
9.3 KiB
Markdown
408 lines
9.3 KiB
Markdown
# 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. 安裝依賴
|
||
|
||
```bash
|
||
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](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. 測試連接
|
||
|
||
執行測試腳本：
|
||
|
||
```bash
|
||
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` 中已註冊排程：
|
||
|
||
```python
|
||
# 每半小時執行一次 Google Drive 自動匯入任務
|
||
schedule.every(30).minutes.do(run_auto_import_task)
|
||
```
|
||
|
||
### 修改檢查頻率
|
||
|
||
編輯 `app.py`：
|
||
|
||
```python
|
||
# 每 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`：
|
||
|
||
```python
|
||
# 僅存取應用程式建立的檔案
|
||
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` 並重新認證
|
||
|
||
---
|
||
|
||
## 📝 日誌
|
||
|
||
### 查看自動匯入日誌
|
||
|
||
```bash
|
||
tail -f logs/system.log | grep AutoImport
|
||
```
|
||
|
||
### 查看排程統計
|
||
|
||
```bash
|
||
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 設定指南](GOOGLE_DRIVE_SETUP.md)
|
||
- [Docker 部署指南](DEPLOY_README.md)
|
||
- [GCP Cloud Run 部署](deploy_docker_guide.md)
|
||
|
||
---
|
||
|
||
## 🎉 完成！
|
||
|
||
您現在擁有一個完全自動化的當日業績匯入系統！
|
||
|
||
**使用流程：**
|
||
1. 將 Excel 檔案上傳到 Google Drive
|
||
2. 系統每 30 分鐘自動檢查
|
||
3. 自動下載、匯入、刪除
|
||
4. 在網頁介面監控進度
|
||
|
||
**無需手動操作！** 🚀
|