diff --git a/docs/AI_INTELLIGENCE_MODULE_SOT.md b/docs/AI_INTELLIGENCE_MODULE_SOT.md index 96b7760..5775590 100644 --- a/docs/AI_INTELLIGENCE_MODULE_SOT.md +++ b/docs/AI_INTELLIGENCE_MODULE_SOT.md @@ -1,8 +1,8 @@ # MOMO PRO — AI 競價情報模組 Single Source of Truth -> **最後更新**: 2026-05-25 (台北時間) -> **狀態**: 🟢 四 AI Agent 自動化閉環已落地；LLM 路由紅線升級為 Ollama-first 三主機級聯，Gemini 備援預設關閉 -> **適用版本**: V10.473 +> **最後更新**: 2026-06-15 (台北時間) +> **狀態**: 🟢 四 AI Agent 自動化閉環已落地；LLM 路由紅線升級為 Ollama-first 三主機級聯；PChome 後台業績匯入韌性已補強 +> **適用版本**: V10.605 --- @@ -213,19 +213,20 @@ SQL漏斗(~300筆) > ⚠️ **架構限制**: `price_records` **只存 MOMO 自家售價**，無 `source` 欄位，無競品（PChome）價格。 > PChome 比價資料必須由外部爬蟲即時抓取，以 `pchome_prices: dict` 形式注入 `HermesAnalystService.run()`。 -### 2.3 `daily_sales_snapshot` 表（動態表，從 Excel 匯入） +### 2.3 `daily_sales_snapshot` 表（PChome 後台業績匯出，動態表） > **重要**: 此表由 `import_service.py` 使用 `df.to_sql()` 動態建立。 -> 欄位名稱**完全繼承自匯入的 MOMO Excel 報表原始欄位**，加上程式碼追加的 `snapshot_date`。 +> 欄位名稱**完全繼承自 PChome 後台匯出的業績 Excel 原始欄位**，加上程式碼追加的 `snapshot_date`。 +> V10.605 起，匯入器會掃描所有 worksheet 與前 15 列表頭，優先選擇含「日期 / 商品名稱 / 總業績或銷售金額」的明細工作表；格式或日期真的不合格的檔案會移到 Google Drive `匯入失敗`，避免每 30 分鐘重複告警。 -#### 已確認的關鍵欄位（實際 MOMO 報表欄位名稱） +#### 已確認的關鍵欄位（PChome 後台報表欄位名稱） | 欄位 | 型別 | 說明 | 備注 | |------|------|------|------| | `snapshot_date` | Date | 資料所屬日期（程式追加） | 由 `import_service.py` 從「日期」欄位解析 | -| `商品ID` | VARCHAR | **商品識別碼**（= `products.i_code`） | ⚠️ 非 `商品編號`！| +| `商品ID` | VARCHAR | PChome 後台 / 訂單目錄商品識別碼 | ⚠️ 不可假設等於 `products.i_code` | | `商品名稱` | TEXT | 商品名稱 | | -| `銷售金額` | NUMERIC | 銷售業績金額 | 系統以 find_col 模糊比對，優先 `銷售金額` | +| `總業績` / `銷售金額` | NUMERIC | 銷售業績金額 | 匯入器以欄位群組模糊比對，兩者皆可 | | `數量` | NUMERIC | 銷售數量 | | | `總成本` | NUMERIC | 成本 | | | `廠商名稱` | VARCHAR | 廠商名稱 | | @@ -297,9 +298,11 @@ CREATE TABLE IF NOT EXISTS ai_price_recommendations ( --- -## 三、SQL 漏斗設計（已修正欄位名稱） +## 三、SQL 漏斗設計（PChome 業績 ID 邊界） -`hermes_analyst_service.py` → `fetch_candidates()` 的核心 SQL： +`daily_sales_snapshot` 來自 PChome 後台業績匯出，`商品ID` 與 `products.i_code` 不保證同一套 ID。任何跨表分析必須先經過可驗證的 mapping / identity contract，不能只用字串相等把 PChome 後台銷售資料與 MOMO 商品主檔硬接。 + +歷史上曾以如下漏斗概念描述近 7 天銷售額下滑，但此 SQL 只能在 ID 已確認同源時使用： ```sql WITH latest_momo_price AS ( @@ -337,10 +340,10 @@ ORDER BY (rs.sales_7d_curr - rs.sales_7d_prev) / rs.sales_7d_prev ASC LIMIT 300 ``` -**漏斗效果**: 226萬筆 price_records → ~300 筆（近7天銷量跌幅 > 10% 的活躍商品） - -**JOIN 邏輯**: -- `products.i_code` ↔ `daily_sales_snapshot."商品ID"` — 均為 MOMO 商品代碼，格式相同 +**ID 邊界**: +- `products.i_code` 是 MOMO 商品主檔 / 價格爬蟲 SKU。 +- `daily_sales_snapshot."商品ID"` 是 PChome 後台業績匯出中的商品識別碼。 +- 兩者不可被文件、Agent 或報表預設視為相同。需要合併分析時，必須先建立可審核 mapping 或沿用已驗證的 PChome identity / 商品名稱證據。 --- @@ -627,7 +630,8 @@ python3 -m services.competitor_identity_revalidator --limit 500 --apply | ✅ | momo-app 雙網路連線 | 同時連 `momo-network` + `momo-pro_default`（後者含 `momo-db` alias `momo-postgres`）| | P1 | PChome Feeder CronJob | `competitor_price_feeder.py` 每 4 小時排程 (Scheduler 整合) | | P1 | 告警去重 TTL | 同一 SKU 短期內重複告警未防範 | -| P1 | `daily_sales_snapshot` 欄位防禦 | 若 Excel 欄位名變更，JOIN 條件會靜默失效 | +| ✅ | `daily_sales_snapshot` 欄位防禦 | V10.605 已支援多 worksheet / 表頭列掃描 / 格式失敗隔離 | +| P1 | PChome 後台業績匯出前半段自動化 | 現有 importer 已自動吃 Google Drive；仍需接 PChome 後台排程匯出、Email 附件或受控 browser 下載 | | P2 | Scheduler 整合 | 每6小時自動觸發 Hermes→NIM→Telegram 管線 | | P2 | Gemini 備援治理 | 僅保留 ADR-028 鎖定場景與 Ollama 失敗備援，新增 caller 必須走 ADR | @@ -667,7 +671,7 @@ POSTGRES_HOST=momo-db | 日期 | 問題 | 修正 | |------|------|------| -| 2026-04-17 | `fetch_candidates()` SQL 使用 `"商品編號"` | 修正為 `"商品ID"`（與 MOMO Excel 實際欄位名一致） | +| 2026-04-17 | `fetch_candidates()` SQL 使用 `"商品編號"` | 修正為 `"商品ID"`；2026-06-15 追認此欄位來自 PChome 後台業績匯出，不可預設等於 MOMO `products.i_code` | | 2026-04-17 | Hermes gap_pct 由 LLM 計算 → 誤差大 | 改為 Python 預算 `(momo-pchome)/pchome*100` | | 2026-04-17 | 推理時間 52s | 預算 gap_pct 後降至 19.3s (3筆) | | 2026-04-17 | `model_footprint` DB 欄位寫入 `{}` | 分離 `footprint_text`（Telegram 顯示）與 `footprint_data`（DB JSON）| diff --git a/docs/guides/google_drive_setup.md b/docs/guides/google_drive_setup.md index 9cdaa39..c3bd034 100644 --- a/docs/guides/google_drive_setup.md +++ b/docs/guides/google_drive_setup.md @@ -1,11 +1,12 @@ # Google Drive API 設定指南 ## 📋 功能說明 -系統自動化流程： -1. **每 30 分鐘**檢查 Google Drive `當日業績匯入` 資料夾。 -2. **自動下載** `即時業績_當日.xlsx`。 -3. **自動匯入** 至資料庫 `daily_sales_snapshot`。 -4. **歸檔** 原始檔案。 +系統自動化流程（PChome 後台業績匯出）： +1. PChome 後台業績 Excel 先被放入 Google Drive `當日業績匯入` 資料夾。 +2. `momo-scheduler` **每 30 分鐘**檢查待匯入檔案。 +3. 自動下載 `即時業績_當日.xlsx` 或符合設定 pattern 的 Excel。 +4. 自動辨識明細 worksheet / 表頭列，匯入至 `daily_sales_snapshot` 並同步 `realtime_sales_monthly`。 +5. 成功檔案歸檔至 `已匯入`；格式或日期不合格的檔案移至 `匯入失敗`，避免重複告警。 --- @@ -30,3 +31,6 @@ python3 -c "from services.google_drive_service import drive_service; drive_servi ## 📁 資料夾結構要求 Google Drive 根目錄必須存在： `我的雲端硬碟/業績報表/當日業績/` + +> 後續若要把 PChome 後台人工匯出改成全自動，先閱讀 +> `docs/guides/pchome_sales_import_automation.md`。 diff --git a/docs/guides/pchome_sales_import_automation.md b/docs/guides/pchome_sales_import_automation.md new file mode 100644 index 0000000..4b23125 --- /dev/null +++ b/docs/guides/pchome_sales_import_automation.md @@ -0,0 +1,75 @@ +# 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 通過。 +- 失敗檔只告警一次，並被移到 `匯入失敗`。 diff --git a/docs/memory/README.md b/docs/memory/README.md index cf8cb50..9d9a54f 100644 --- a/docs/memory/README.md +++ b/docs/memory/README.md @@ -34,6 +34,9 @@ - `docs/guides/observability_ui_governance.md` 用途：AI 觀測台 `/observability/*` 頁面的 UI/UX 設計治理、禁用事項與巡檢指令。 何時閱讀：新增或修改觀測台頁面、側欄、Chart.js、資料密集卡片/表格、空狀態時。 +- `docs/guides/pchome_sales_import_automation.md` + 用途：PChome 後台業績匯出自動化，銜接 Google Drive auto import、失敗隔離與下游 daily/growth/PPT/AI。 + 何時閱讀：要把 PChome 後台業績匯出從人工下載改成 Email / n8n / browser worker / Telegram 備援自動化時。 ## 新增規則 diff --git a/docs/memory/current_execution_queue_20260524.md b/docs/memory/current_execution_queue_20260524.md index 97eb66c..a920ad0 100644 --- a/docs/memory/current_execution_queue_20260524.md +++ b/docs/memory/current_execution_queue_20260524.md @@ -121,6 +121,7 @@ - 2026-06-02 起，`V10.567` 將 MCP 市場洞察 fallback 收斂為 GCP-A / GCP-B only，不再讓 111 承接非即時市場分析長任務；預設 timeout 25 秒、`num_predict` 500，GCP 不可用時直接保守降級，避免 Elephant Alpha 60 秒 timeout 與 111 負載尖峰。 - 2026-06-02 起，`V10.568` 將價格類 `decision_envelope` 的 Telegram 直送訊息改為專業 brief：標的、價格證據、比對證據、人工下一步四段式；review queue 信封 subject 同步帶 `momo_price` / `competitor_price`，讓 Telegram、PPT、Webcrumbs 與 AI 摘要共用價格證據。 - 2026-06-02 起，`V10.569` 將 Webcrumbs host data 串到 `summarize_review_decision_envelopes()`，payload 新增 `reviewDecisionBrief` 與 review queue / HITL / auto-execute-blocked metadata；共用 UI runtime 讀同一份 PChome 覆核信封摘要，仍只讀 DB、不呼叫 LLM、不抓外站、不寫資料。 +- 2026-06-15 起，`V10.605` 修正 PChome 後台業績 Excel 匯入韌性：auto import 會掃所有 worksheet / 表頭列並選擇 `即時業績明細` 類明細 sheet，欄位或日期不合格的檔案會移至 Drive `匯入失敗` 避免 30 分鐘重複告警；同版修復 scheduler 容器缺 `pg_dump` 的備份告警。Production 匯入任務 #54 成功寫入 12,460 筆，`daily_sales_snapshot` 與 `realtime_sales_monthly` 最新日期皆為 2026-06-14；資料新鮮度 probe 降為 `gap=1 / info / notified=false`，daily/growth chart runtime guard 通過。 ## 3. 12 Agent 決策信封整合 @@ -145,6 +146,7 @@ ## 4. 業績分析資料與圖表修復 - 修正即時業績匯入 `snapshot_date text = date` 類型錯誤。 +- PChome 後台業績匯出前半段仍需自動化：優先確認 PChome 後台是否支援排程寄信 / Email 附件 / FTP / API；若無，改做 110 或獨立 worker 的受控 browser 下載，再把檔案放進 Google Drive `當日業績匯入/`。 - `/daily_sales`、`/growth_analysis` 圖表不得空白；需保留原本圖表並升級成更專業的呈現。 - 圖表需通過 runtime nonblank canvas 檢查與手機版 responsive。 - daily/growth/PPT 必須共用 `competitor_intel_repository` 的比價資料出口，避免價差方向或統計口徑分裂。