# Google Drive API 設定指南

本指南說明如何設定 Google Drive API，讓系統能夠自動從 Google Drive 下載、匯入並刪除當日業績 Excel 檔案。

## 功能說明

系統會：
1. **每 30 分鐘**自動檢查 Google Drive 指定資料夾
2. **自動下載** Excel 檔案到本地
3. **自動匯入**資料到資料庫
4. **自動刪除** Google Drive 上的原始檔案
5. **追蹤進度**並提供網頁介面查看匯入狀態

---

## 步驟 1：建立 Google Cloud 專案

### 1.1 前往 Google Cloud Console

開啟 [Google Cloud Console](https://console.cloud.google.com/)

### 1.2 建立新專案

1. 點擊上方的專案選擇器
2. 點擊「新增專案」
3. 輸入專案名稱（例如：`momo-auto-import`）
4. 點擊「建立」

---

## 步驟 2：啟用 Google Drive API

### 2.1 啟用 API

1. 在 Google Cloud Console 中，前往「API 和服務」→「程式庫」
2. 搜尋「Google Drive API」
3. 點擊「Google Drive API」
4. 點擊「啟用」

---

## 步驟 3：建立 OAuth 2.0 憑證

### 3.1 建立 OAuth 同意畫面

1. 前往「API 和服務」→「OAuth 同意畫面」
2. 選擇「外部」（如果只有自己使用，選擇「內部」需要 Google Workspace）
3. 點擊「建立」
4. 填寫必要資訊：
   - **應用程式名稱**：`Momo Pro System`
   - **使用者支援電子郵件**：您的 Gmail 地址
   - **開發人員聯絡資訊**：您的 Gmail 地址
5. 點擊「儲存並繼續」
6. **範圍（Scopes）**：點擊「新增或移除範圍」
   - 搜尋並勾選：`https://www.googleapis.com/auth/drive`（完整 Drive 存取權限）
   - 點擊「更新」
7. 點擊「儲存並繼續」
8. **測試使用者**：新增您的 Gmail 地址
9. 點擊「儲存並繼續」

### 3.2 建立 OAuth 2.0 用戶端 ID

1. 前往「API 和服務」→「憑證」
2. 點擊「建立憑證」→「OAuth 用戶端 ID」
3. 應用程式類型選擇：**桌面應用程式**
4. 名稱輸入：`Momo Desktop Client`
5. 點擊「建立」
6. 會顯示「用戶端 ID」和「用戶端密鑰」
7. 點擊「下載 JSON」

### 3.3 放置憑證檔案

1. 將下載的 JSON 檔案重新命名為：`google_credentials.json`
2. 放置到專案的 `config/` 目錄中：
   ```
   /Users/ogt/momo_pro_system/config/google_credentials.json
   ```

---

## 步驟 4：首次認證

### 4.1 執行認證流程

首次使用時需要進行認證：

```bash
cd /Users/ogt/momo_pro_system

# 執行認證腳本
python3 -c "
from services.google_drive_service import drive_service
drive_service.authenticate()
"
```

### 4.2 完成授權

1. 瀏覽器會自動開啟 Google 授權頁面
2. 選擇您的 Google 帳號
3. 系統會顯示：「Google 尚未驗證此應用程式」
   - 點擊「繼續」（因為這是您自己的應用程式）
4. 點擊「允許」授予 Google Drive 存取權限
5. 看到「授權流程已完成」即表示成功

### 4.3 Token 檔案

授權完成後，系統會自動建立 `config/google_token.pickle`，此檔案包含您的存取權杖，下次使用時不需重新授權。

**安全提示**：此檔案包含敏感資訊，請勿分享或上傳到公開儲存庫。

---

## 步驟 5：設定 Google Drive 資料夾

### 5.1 在 Google Drive 建立資料夾結構

建議的資料夾結構：

```
我的雲端硬碟/
└── 業績報表/
    └── 當日業績/
        └── 即時業績_當日_20260113.xlsx
```

### 5.2 在系統中配置路徑

1. 開啟瀏覽器，前往：http://localhost/auto_import
2. 在「匯入配置」區域設定：
   - **Google Drive 資料夾路徑**：`業績報表/當日業績`
   - **檔案名稱模式**：`即時業績_當日`（選填，用於過濾檔案）
3. 點擊「儲存配置」
4. 點擊「測試連接」確認連接正常
5. 點擊「列出檔案」查看該資料夾中的檔案

---

## 步驟 6：測試自動匯入

### 6.1 上傳測試檔案

1. 將當日業績 Excel 檔案上傳到 Google Drive 的指定資料夾
2. 檔案名稱範例：`即時業績_當日_20260113.xlsx`

### 6.2 手動測試

1. 在自動匯入頁面點擊「立即匯入」
2. 觀察「匯入任務歷史」區域，應該會看到新的任務記錄
3. 任務狀態會從「等待中」→「下載中」→「匯入中」→「已完成」
4. 完成後，Google Drive 上的檔案會被自動刪除

### 6.3 驗證匯入結果

```bash
# 查詢匯入的資料
python3 -c "
from services.import_service import import_service
jobs = import_service.get_recent_jobs(limit=1)
for job in jobs:
    print(f'任務 ID: {job[\"id\"]}')
    print(f'狀態: {job[\"status\"]}')
    print(f'檔案: {job[\"drive_file_name\"]}')
    print(f'成功: {job[\"success_rows\"]} 筆')
"
```

---

## 步驟 7：自動排程

系統已自動設定每 30 分鐘檢查一次 Google Drive：

- 排程任務會在背景自動執行
- 無需手動觸發
- 可在「匯入任務歷史」查看執行記錄
- 每次檢查到新檔案就會自動匯入

---

## 常見問題

### Q1: 認證失敗，顯示「找不到認證檔案」

**A:** 確認 `config/google_credentials.json` 檔案存在且路徑正確。

### Q2: 授權時顯示「應用程式未經驗證」

**A:** 這是正常的，因為這是您自己的應用程式。點擊「繼續」即可。

### Q3: 找不到 Google Drive 資料夾

**A:** 確認：
1. 資料夾路徑正確（區分大小寫）
2. 資料夾確實存在於「我的雲端硬碟」中
3. 使用的 Google 帳號有該資料夾的存取權限

### Q4: 檔案沒有被自動刪除

**A:** 確認：
1. 匯入任務狀態為「已完成」（不是「失敗」）
2. 檢查日誌檔案：`logs/system.log`

### Q5: 如何重新授權？

**A:** 刪除 `config/google_token.pickle` 檔案，然後重新執行步驟 4。

### Q6: 可以使用 Service Account 嗎？

**A:** 可以，但需要修改程式碼。Service Account 適合在伺服器上無人值守運行，但需要手動分享 Drive 資料夾給 Service Account 的電子郵件地址。

---

## 安全建議

1. **不要分享憑證檔案**
   - `google_credentials.json`
   - `google_token.pickle`
   - 這些檔案已加入 `.gitignore`

2. **定期檢查授權**
   - 前往 [Google 帳戶安全性](https://myaccount.google.com/permissions)
   - 檢查「Momo Pro System」的授權狀態

3. **限制 API 存取範圍**
   - 目前使用完整 Drive 存取權限
   - 如需更嚴格控制，可修改為 `drive.file` scope（僅存取應用程式建立的檔案）

4. **備份重要資料**
   - 在刪除 Google Drive 檔案前，系統會先匯入到本地資料庫
   - 建議定期備份資料庫

---

## 進階設定

### 修改檢查頻率

編輯 `app.py`，找到：

```python
schedule.every(30).minutes.do(run_auto_import_task)
```

修改為您想要的頻率：
- 每 15 分鐘：`schedule.every(15).minutes.do(...)`
- 每小時：`schedule.every(1).hours.do(...)`
- 每天早上 8 點：`schedule.every().day.at("08:00").do(...)`

### 保留 Google Drive 檔案

如果不想自動刪除 Google Drive 檔案，修改 `services/import_service.py` 中的 `auto_import_from_drive` 方法，註解掉刪除部分：

```python
# if drive_service.delete_file(file_id):
#     logger.info(f"已刪除 Google Drive 檔案: {file_name}")
```

---

## 監控和日誌

### 查看即時日誌

```bash
tail -f logs/system.log | grep AutoImport
```

### 查看匯入統計

前往網頁介面：http://localhost/auto_import

### 查詢排程統計

```bash
cat data/scheduler_stats.json | grep auto_import_task
```

---

## 故障排除

### 檢查服務狀態

```python
python3 -c "
from services.google_drive_service import drive_service
from services.import_service import import_service

# 測試 Google Drive 連接
if drive_service.authenticate():
    print('✅ Google Drive 連接正常')
else:
    print('❌ Google Drive 連接失敗')

# 查詢最近的任務
jobs = import_service.get_recent_jobs(limit=5)
print(f'\\n📋 最近 {len(jobs)} 個任務:')
for job in jobs:
    print(f'  - 任務 {job[\"id\"]}: {job[\"status\"]} ({job[\"progress_percent\"]}%)')
"
```

---

## 參考資料

- [Google Drive API 文檔](https://developers.google.com/drive/api/guides/about-sdk)
- [Python Quickstart](https://developers.google.com/drive/api/quickstart/python)
- [OAuth 2.0 說明](https://developers.google.com/identity/protocols/oauth2)

---

**完成！** 🎉

您的 Google Drive 自動匯入功能已設定完成，系統會每 30 分鐘自動檢查並匯入新的業績檔案。