ewoooc/docs/guides/pchome_sales_import_automation.md

PChome 後台業績匯出自動化

目的

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

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 通過。
• 失敗檔只告警一次，並被移到 匯入失敗。

來源 Reconciliation 合約

PChomeSalesAcquisitionService 每輪必須把四個授權來源的設定狀態、探測結果、 連續空跑/失敗次數、fallback chain、下一次重試時間與通知去重決策寫入同一張 pchome_sales_acquisition_receipts。正式合約名稱為 pchome_sales_source_reconciliation_v1。

• ready 但無檔：維持 30 分鐘固定重試，並繼續探測所有已啟用 fallback。
• provider 失敗：使用 30、60、120、240 分鐘有界指數退避。
• disabled 來源：必須顯示為 disabled，不得誤報為已探測但沒有候選。
• 相同 stale/error fingerprint：6 小時內抑制重複通知；狀態改變立即通知。
• 低階 Drive importer 由 acquisition controller 呼叫時不直接發 stale 告警，避免雙重通知。
• receipt 與 API 只能輸出 public-safe 狀態，不得回傳 URL、帳號、token 或郵件內容。