# 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（前期）
