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. 安裝依賴

```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. 在網頁介面監控進度

**無需手動操作！** 🚀