feat(growth): automate sales source reconciliation

docs/AI_INTELLIGENCE_MODULE_SOT.md

@@ -344,7 +344,7 @@ SQL漏斗(~300筆)
 > **重要**: 此表由 `import_service.py` 使用 `df.to_sql()` 動態建立。
 > 欄位名稱**完全繼承自 PChome 後台匯出的業績 Excel 原始欄位**，加上程式碼追加的 `snapshot_date`。
 > V10.605 起，匯入器會掃描所有 worksheet 與前 15 列表頭，優先選擇含「日期 / 商品名稱 / 總業績或銷售金額」的明細工作表；格式或日期真的不合格的檔案會移到 Google Drive `匯入失敗`，避免每 30 分鐘重複告警。
-> V10.776 起，`pchome_sales_acquisition_service.py` 依序探測 Google Drive、顯式授權 HTTPS、顯式授權 IMAP 與受控落地目錄；所有非 Drive 檔案先做副檔名/魔術碼/大小檢查與 SHA-256 冪等，再由 `import_service.py` 在同一 DB transaction 內 replace、寫入及驗證 `daily_sales_snapshot` 與 `realtime_sales_monthly`。任一步失敗必須整批 rollback，不得留下半同步狀態。每次 run 需把 `trace_id`、OpenTelemetry-compatible `span_id`、`run_id`、`work_item_id`、來源、政策、check、execution、post-verifier 與 terminal 寫入 `pchome_sales_acquisition_receipts`；舊版人工暫停旗標不得停止此 medium-risk controlled-apply lane。正式完成仍要求最新業績 <= 1 天，不能以 source/test/UI 綠燈取代 production freshness closure。
+> V10.776 起，`pchome_sales_acquisition_service.py` 依序探測 Google Drive、顯式授權 HTTPS、顯式授權 IMAP 與受控落地目錄；所有非 Drive 檔案先做副檔名/魔術碼/大小檢查與 SHA-256 冪等，再由 `import_service.py` 在同一 DB transaction 內 replace、寫入及驗證 `daily_sales_snapshot` 與 `realtime_sales_monthly`。任一步失敗必須整批 rollback，不得留下半同步狀態。每次 run 需把 `trace_id`、OpenTelemetry-compatible `span_id`、`run_id`、`work_item_id`、來源、政策、check、execution、post-verifier 與 terminal 寫入 `pchome_sales_acquisition_receipts`；舊版人工暫停旗標不得停止此 medium-risk controlled-apply lane。V10.790 起再以 `pchome_sales_source_reconciliation_v1` 跨 run 累積 provider 空跑/失敗次數，disabled 來源不得冒充 `no_candidate`，ready-empty 走固定重試、provider failure 走有界指數退避，所有已啟用 fallback 仍依序探測；相同狀態 fingerprint 在 cooldown 內抑制重複通知，決策與 `next_retry_at` 一併寫入原 receipt。正式完成仍要求最新業績 <= 1 天，不能以 source/test/UI 綠燈取代 production freshness closure。
 
 #### 已確認的關鍵欄位（PChome 後台報表欄位名稱）
 

docs/guides/pchome_sales_import_automation.md

@@ -73,3 +73,17 @@ PChome 後台業績匯出
 - `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 或郵件內容。