# PChome 後台業績匯出自動化

## 目的

把目前人工從 PChome 後台匯出業績 Excel 的流程，自動接到既有匯入管線：

```text
PChome 後台業績匯出
  -> Google Drive 當日業績匯入/
  -> momo-scheduler 每 30 分鐘 auto_import
  -> daily_sales_snapshot + realtime_sales_monthly
  -> daily / growth / PPT / AI 分析
```

## 目前已完成

- V10.605 起，`services/import_service.py` 已可自動辨識 PChome 後台匯出的多工作表 Excel。
- 匯入器會掃描所有 worksheet 的前 15 列表頭，優先選擇含日期、商品名稱、總業績或銷售金額的明細工作表。
- 匯入成功後檔案會移到 `已匯入`。
- 格式或日期不合格的檔案會移到 `匯入失敗`，避免每 30 分鐘重複告警。
- `daily_sales_snapshot."商品ID"` 是 PChome 後台業績匯出的商品識別碼，不可預設等於 MOMO `products.i_code`。

## 推薦方案

### 方案 A：PChome 後台排程寄信或固定附件

這是首選。若 PChome 後台能排程寄出報表，或每日寄到 Gmail：

1. PChome 後台每天固定寄出業績 Excel。
2. Gmail / n8n 監聽寄件者、主旨、附件檔名。
3. 驗證附件日期與檔名，例如 `即時業績_當日.xlsx` 或 `pchome_sales_YYYYMMDD.xlsx`。
4. 將附件存到 Google Drive `當日業績匯入/`。
5. 既有 `run_auto_import_task` 自動匯入。

優點：穩定、低維護、無需模擬登入、較不受後台 UI 改版影響。

### 方案 B：受控瀏覽器自動下載

若 PChome 後台只能人工登入後匯出：

1. 在 110 或獨立 browser worker 跑 Playwright / n8n browser step。
2. 使用密鑰管理保存帳密，不寫入 repo。
3. 登入 PChome 後台，選日期範圍，下載業績 Excel。
4. 檢查下載檔大小、sheet、日期最大值。
5. 上傳到 Google Drive `當日業績匯入/`。
6. 交由既有 importer 匯入。

注意：若有 OTP、驗證碼、裝置信任或密碼到期，此方案需要 HITL fallback，不應讓瀏覽器在使用者 Mac 上反覆跳出授權視窗。

### 方案 C：Telegram 上傳備援

若 PChome 後台登入自動化暫時不穩：

1. 使用者將 Excel 直接丟給 Telegram bot。
2. bot 驗證檔案名稱、日期、sheet、欄位。
3. 通過則存到 Google Drive 或直接呼叫 importer。
4. 不通過則回覆可讀錯誤，例如缺欄位、資料過舊、找不到明細 sheet。

此方案不是全自動，但可以把「下載後匯入」從人工操作降到傳檔即可。

## 實作順序

1. 先確認 PChome 後台是否支援排程寄信、Email 附件、FTP、API 或固定下載 URL。
2. 若有 Email / 附件，優先用 n8n / Gmail API 走方案 A。
3. 若沒有，再做方案 B 的 browser worker；worker 不跑在使用者桌面，避免密碼提示與彈窗干擾。
4. 保留方案 C 作為緊急備援。
5. 每次自動取得檔案後，都先跑 importer 的 sheet / 日期 / 欄位 preflight，再進正式匯入。

## 驗收條件

- 不需人工打開後台即可產生或取得當日 PChome 業績 Excel。
- Google Drive `當日業績匯入/` 有新檔後，30 分鐘內自動匯入。
- `daily_sales_snapshot` 與 `realtime_sales_monthly` 最新日期落後不超過 1 天。
- `/daily_sales` 與 `/growth_analysis` 圖表 smoke 通過。
- 失敗檔只告警一次，並被移到 `匯入失敗`。
