記錄 PChome 業績匯出自動化方案
This commit is contained in:
OoO
@@ -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）|
|
||||
|
||||
@@ -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`。
|
||||
|
||||
75
docs/guides/pchome_sales_import_automation.md
Normal file
75
docs/guides/pchome_sales_import_automation.md
Normal file
@@ -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 通過。
|
||||
- 失敗檔只告警一次，並被移到 `匯入失敗`。
|
||||
@@ -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 備援自動化時。
|
||||
|
||||
## 新增規則
|
||||
|
||||
|
||||
@@ -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` 的比價資料出口，避免價差方向或統計口徑分裂。
|
||||
|
||||
Reference in New Issue
Block a user