From 9862edeb44944bda456edddc2244ede1243f970e Mon Sep 17 00:00:00 2001 From: OoO Date: Sun, 3 May 2026 12:41:12 +0800 Subject: [PATCH] docs(adr): ADR-025 PPT Wave 3 (new_product + market_intel_weekly) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 3 完成 2 種橫向資訊整合型報表： - new_product (95a74c3) — 30 天追蹤，PostgreSQL CTE 識別新品 - market_intel_weekly (fe3cba8) — 8 個外部 API 彙整，fail-safe 設計 累計報表清單：13 種有效 + 2 種 DEPRECATED + 4 種待資料層支援。 Wave 3 餘項（受資料層限制）： - clv (需 user_id) - price_elasticity (需長期定價歷史) - competitor v4 五力 (需外部 SKU/品牌力資料) Wave 4 待辦（依資料層 schema）： - inventory / operations / finance Co-Authored-By: Claude Opus 4.7 (1M context) --- ...stem-wave3-new-product-and-market-intel.md | 113 ++++++++++++++++++ docs/adr/README.md | 1 + 2 files changed, 114 insertions(+) create mode 100644 docs/adr/ADR-025-ppt-system-wave3-new-product-and-market-intel.md diff --git a/docs/adr/ADR-025-ppt-system-wave3-new-product-and-market-intel.md b/docs/adr/ADR-025-ppt-system-wave3-new-product-and-market-intel.md new file mode 100644 index 0000000..168d4ed --- /dev/null +++ b/docs/adr/ADR-025-ppt-system-wave3-new-product-and-market-intel.md @@ -0,0 +1,113 @@ +# ADR-025: PPT 系統 Wave 3 — 新品追蹤 + 市場情報週報 + +- **Status**: Accepted +- **Date**: 2026-05-03 +- **Deciders**: 統帥 +- **Related**: 延續 ADR-023/024，補上 Wave 3 兩種 PM/CEO 級報表 +- **Affects**: `services/ppt_generator.py`、`routes/openclaw_bot_routes.py`、`services/openclaw_bot/menu_keyboards.py` +- **Commit chain**: `95a74c3` (new_product) → `fe3cba8` (market_intel) + +## Context + +Wave 3 鎖定「橫向資訊整合」型報表： +1. **new_product** — PM 剛需，從現有資料層用 PostgreSQL CTE 抽出新品 +2. **market_intel_weekly** — 把 `mcp_collector_service` 所有外部 API 彙整成一份對外可分享的內部簡報 + +Wave 3 餘下三項受限於資料層或外部依賴： +- clv 客戶終身價值 — 需 user_id（無 PII 資料層） +- price_elasticity — 需要長期定價歷史 +- competitor v4 五力升級 — 需要外部 SKU/品牌力資料 + +## Decision + +### A. new_product 30 天追蹤 + +**核心算法**： +```sql +WITH recent AS (近 30 天有銷售商品), + early AS (31-90 天前有銷售商品) +SELECT recent.* FROM recent +LEFT JOIN early ON recent.id = early.id +WHERE early.id IS NULL -- 排除「過去也賣過」的商品 +ORDER BY rev DESC LIMIT 50 +``` + +**新品力定位**（業界基準）： +| 業績佔比 | 標籤 | 顏色 | +|---|---|---| +| ≥ 8% | 新品力強勁 | 綠 | +| 3-8% | 新品力穩健 | 黃 | +| 1-3% | 新品力偏弱 | 橘 | +| < 1% | 新品力疲弱 | 紅 | + +**輸出 9 頁**：封面 / KPI / 整體日業績曲線（爬榜軌跡）/ 品類分佈 / TOP 50 / AI / 附錄。 + +### B. market_intel_weekly 外部彙整 + +**整合 8 個外部資料源**： +1. 節慶日曆（靜態台灣電商節日） +2. 季節情境（春/夏/秋/冬消費主題） +3. 電商產業新聞（Gemini Grounding） +4. Google Trends 台灣熱搜 +5. Dcard 熱門討論 +6. YouTube 爆紅商品 +7. 台灣天氣 +8. 台幣匯率 + +**Fail-safe 設計**：每個 API 用 `_safe()` wrapper，失敗時填「（本次擷取失敗或無資料）」，不阻塞報告生成。 + +**輸出 7 頁**：封面三句話 / 節慶+季節（雙卡）/ 新聞+熱搜（雙卡）/ Dcard+YouTube（雙卡）/ 天氣+匯率（雙卡）/ AI 整合洞察 / 附錄。 + +### C. AI Prompt 角色化（延續 v3 設計） + +| 報表 | AI 角色 | max_tokens | +|---|---|---| +| new_product | PM 商品經理 + 採購主管 | 1800 | +| market_intel | 行銷情報分析師 + BU 主管 | 2000 | + +兩種都引用 `MARKET_TREND_2026` 共用知識基底。 + +## Consequences + +### Positive + +1. **PM 戰術閉環**：new_product 給出「誰值得加碼/觀察/下架」的具體 SMART 行動 +2. **CEO/BU 主管的市場視野**：market_intel_weekly 把零散的外部資料變成可決策的單一檔案 +3. **資料層 0 擴充**：兩種報表都基於現有資料，無需新建 schema +4. **Fail-safe 整合**：market_intel 容錯設計，單一 API 失敗不影響整份報告 + +### Negative + +1. **new_product 對小品類失準**：CTE 對僅有 < 5 個 SKU 的小品類可能誤判（30 天前才開的小品類所有商品都「新進榜」） +2. **market_intel 依賴 Gemini 配額**：電商新聞、Trends 等需要 Gemini Grounding，配額耗盡時整段填 placeholder +3. **資料新鮮度受限**：mcp_collector 是 on-demand 抓，每次生成報告都會 hit 外部 API，無快取 + +### 風險與緩解 + +- **CTE 跨年判斷**：CURRENT_DATE - INTERVAL '90 days' 在閏年 2/29 會略微偏移，但 momo 業務不需要日級精準度 +- **外部 API rate limit**：`_safe()` 已防呆，連續失敗時整份報告仍能產出（只是內容稀疏） +- **市場情報資料外流風險**：本報告整合多個外部公開資料，無 PII 風險，可對內公開 + +## Wave 3 餘項與 Wave 4 待辦（下次接力） + +剩餘未做（依資料層）： + +| 報表 | 障礙 | 預估工程 | +|---|---|---| +| clv 客戶終身價值 | 需 user_id（PII 限制） | 需先建會員系統 | +| price_elasticity | 需長期定價歷史 | 中（4 小時，可從 competitor_price_history 抽） | +| competitor v4 五力 | 需 SKU 數 / 品牌力外部資料 | 大（8-12 小時，需擴充 mcp_collector） | +| inventory 庫存健康 | 需 stock 表 | 大（需資料層 schema） | +| operations 訂單履約 | 需 fulfillment 表 | 大（需資料層 schema） | +| finance P&L | 需 finance 表 | 大（需資料層 schema） | + +## 累計報表清單（v3 戰役至今 18 commits 完成 17 種報表中的 13 種） + +✅ **可用 13 種**：daily / weekly / monthly / strategy / competitor / promo / vendor / quarterly / half_yearly / annual / ttm / category / customer / forecast_pre_event / promo_compare / new_product / market_intel +❌ **DEPRECATED 2 種**：bcg / growth +⏸ **待 Wave 4 / 資料層** 4 種：clv / price_elasticity / competitor v4 / inventory / operations / finance + +## References + +- 對應 memory：`reference_ppt_system.md`（v3.1++ 含 Wave 3）、新建 `project_ppt_wave3_intel_20260503.md` +- ADR-022/023/024（前期） diff --git a/docs/adr/README.md b/docs/adr/README.md index 637a17f..f4fcc58 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -46,6 +46,7 @@ | [022](ADR-022-ppt-system-v3-redesign.md) | PPT v3 — 暖紙風 + matplotlib 專業圖表 + 模板版本快取 | Accepted | 2026-05-02/03 | | [023](ADR-023-ppt-system-expansion-wave1.md) | PPT 系統 Wave 1 擴展 — 廠商 / 期間回顧 / 品類深度 / 客戶分析（8 種新報表） | Accepted | 2026-05-03 | | [024](ADR-024-ppt-system-wave2-forecast-and-deprecations.md) | PPT 系統 Wave 2 — 檔期前瞻 / 多活動比較 + bcg/growth 廢除 | Accepted | 2026-05-03 | +| [025](ADR-025-ppt-system-wave3-new-product-and-market-intel.md) | PPT 系統 Wave 3 — 新品 30 天追蹤 + 市場情報週報 | Accepted | 2026-05-03 | ## 規範