docs(adr): ADR-025 PPT Wave 3 (new_product + market_intel_weekly)
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) <noreply@anthropic.com>
This commit is contained in:
OoO
@@ -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（前期）
|
||||
@@ -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 |
|
||||
|
||||
## 規範
|
||||
|
||||
|
||||
Reference in New Issue
Block a user