# ADR-024: PPT 系統 Wave 2 — 檔期前瞻 / 多活動比較 / bcg & growth 廢除

- **Status**: Accepted
- **Date**: 2026-05-03
- **Deciders**: 統帥
- **Related**: 延續 ADR-023（Wave 1 擴展），補上 Wave 2 的 2 種前瞻型報表，並正式廢除 bcg / growth
- **Affects**: `services/ppt_generator.py`、`routes/openclaw_bot_routes.py`、`services/openclaw_bot/menu_keyboards.py`
- **Commit chain**: `9f04dc3` (forecast) → `958f705` (promo_compare)

## Context

延續 ADR-023 Wave 1 完成 4 種報表後，Wave 2 鎖定「前瞻決策型」報表 — 給 BU 主管在事件**發生前**做戰術部署，而非事後復盤。

兩個 Wave 2 報表：
1. **forecast_pre_event** — 檔期前 14 天的備戰策略
2. **promo_compare** — 多場促銷活動的 ROI 橫向比較（覆盤學習）

同時正式廢除 2 個從未落地或已被取代的 generator。

## Decision

### A. forecast_pre_event 檔期前瞻

**價值**：BU 主管在母親節 / 618 / 雙11 等大檔期前 14 天觸發，得到：
- 預期業績（baseline 日均 × 21 天 × `lift_factor`）
- 去年同檔期實績作為基準線
- 已執行進度（檔期前已過 N 天的累積業績 vs 預期）
- baseline 期 TOP 30 商品作為庫存盤點對象

**核心算法**：
```python
baseline_period = [event_date - 60d, event_date - 30d]  # 去除檔期前期效應
last_year_period = [event_date_LY - 7d, event_date_LY + 7d]
prep_window = [event_date - 14d, event_date + 7d]
expected_revenue = baseline.avg_daily * 21 * lift_factor[event_name]
```

**靜態 lift_factor 知識**（依台灣電商歷史經驗）：
| 檔期 | Lift |
|---|---|
| 雙11 | 1.65× |
| 農曆年 | 1.50× |
| 618 / 黑五 | 1.45× |
| 母親節 / 雙12 | 1.40× |
| 520 / 雙10 / 聖誕 | 1.30× |
| 父親節 / 中秋 | 1.25× |
| 端午 / 婦女節 | 1.20× |
| 勞動節 | 1.15× |

**封面倒數天數徽章**自動切換：備戰期（>7 天）/ 衝刺期（≤7 天）/ 檔期中 / 已結束。

### B. promo_compare 多活動 ROI 比較

**價值**：行銷主管覆盤多場促銷活動，找出成功要素與失敗診斷。

**輸入格式**：`/ppt promo_compare 母親節:2026/05/05-2026/05/14|520:...|618:...`
用 `|` 分多場，每場 `label:start-end`。

**核心輸出**：
- P2 並排 KPI 表（活動/期間/天數/業績/訂單/毛利/業績拉抬/訂單拉抬）8 欄
- P3 業績拉抬橫條圖（按拉抬 % 排序，TOP3 焦糖橘）
- P4 AI 跨活動洞察：勝出活動成功要素 / 失敗活動診斷 / SMART 三層

### C. 正式廢除 bcg / growth generator

**bcg**：
- **理由**：與 strategy 報表功能重疊（strategy 已內含 BCG 加碼/機會/收割/觀察五級分類，且支援日/週/月/季/半年/年六種時間範圍）
- **處理**：函式保留作為 internal helper（避免破壞既有 import），TEMPLATE_VERSIONS 標 DEPRECATED；路由未綁定（從未綁定）；UI 無按鈕

**growth**：
- **理由**：已被 quarterly + half_yearly + annual + ttm 完全取代（period_review 共用 generator）
- **處理**：同 bcg，DEPRECATED 標記但保留函式

**vendor 不廢除**（之前 v2.0 標 DEPRECATED）— 已在 Wave 1 喚醒並升級到 v3.1.0。

## Consequences

### Positive

1. **前瞻型決策補完**：報表體系從「事後復盤」延伸到「事前部署」
2. **檔期戰術可量化**：lift_factor 提供具體預測基準，不再憑感覺備貨
3. **跨活動學習機制**：promo_compare 把「散落的單一活動效益」變成「可橫向學習的策略矩陣」
4. **報表類型清單收斂**：14 種有效 + 2 種 DEPRECATED（清楚標記避免誤用）

### Negative

1. **forecast lift_factor 是靜態知識**：未來如台灣電商檔期生態變化（如雙11 拉抬下降到 1.40），需手動 bump
2. **promo_compare 受 query_promo_comparison 速度限制**：每場活動跑一次 SQL（未做平行），N 場活動 = N 次 query 串行
3. **forecast 跨年判斷邊界**：`event_date.replace(year=year-1)` 在 2/29 會拋例外（已 try/except 處理）

### 風險與緩解

- **新進榜 CTE 在低資料量品類失準**：`recent EXCEPT early` 對小品類可能誤判（如 30 天前才開的新品類所有商品都「新進榜」）。緩解：保留人工審視（不直接觸發自動化決策）
- **forecast confidence 標記**：去年同檔期無資料時 confidence='low'，prompt 內已提醒 AI 降低預測信心

## Wave 3-4 待辦（下次接力）

依 17 種完整清單，本次完成 Wave 2.1 + 2.2 = 11 種有效報表（含 Wave 1 的 8 種、v3 既有的 6 種重做後）+ 2 種 DEPRECATED。剩餘：

**Wave 2.3 (跳過下次做)**:
- competitor v4 五力升級（需要外部資料：商品力/行銷力/品牌力/服務力）

**Wave 3**:
- market_intel_weekly 外部彙整週報（政府零售業營業額、平台法說、Similarweb、Dcard、Trends）
- new_product 30 天追蹤
- clv 客戶終身價值（需 user_id）
- price_elasticity 價格彈性

**Wave 4**（依資料層）:
- inventory 庫存健康（需 stock 表）
- operations 訂單履約（需 fulfillment 表）
- finance P&L（需 finance 表）

## References

- 對應 memory：`reference_ppt_system.md`（v3.1 → v3.1+ 含 Wave 2 的 2 種新報表）、新建 `project_ppt_wave2_forecast_20260503.md`
- ADR-022: PPT v3 redesign（前提）
- ADR-023: Wave 1 擴展（前一波）
