diff --git a/docs/adr/ADR-024-ppt-system-wave2-forecast-and-deprecations.md b/docs/adr/ADR-024-ppt-system-wave2-forecast-and-deprecations.md new file mode 100644 index 0000000..0c1b75a --- /dev/null +++ b/docs/adr/ADR-024-ppt-system-wave2-forecast-and-deprecations.md @@ -0,0 +1,118 @@ +# 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 擴展(前一波) diff --git a/docs/adr/README.md b/docs/adr/README.md index 8791f34..637a17f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -45,6 +45,7 @@ | [021](ADR-021-ea-hitl-prefetch-and-alert-impact.md) | EA HITL Pre-fetch + 競價告警必填金額影響量化 | Accepted | 2026-05-03 | | [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 | ## 規範 diff --git a/services/ppt_generator.py b/services/ppt_generator.py index e7c36a8..7865167 100644 --- a/services/ppt_generator.py +++ b/services/ppt_generator.py @@ -50,7 +50,8 @@ TEMPLATE_VERSIONS = { # ── DEPRECATED:以下 type 從未實際落地(依 ADR-014 校正 2026-04-28)。 # 函式 generate_growth_ppt / generate_vendor_ppt / generate_bcg_ppt 仍存在於本檔, # 但路由層未綁定指令;保留版本字串避免如未來重啟時快取 schema 對不上。 - 'growth': 'v2.0', # DEPRECATED — 從未落地 + 'growth': 'v2.0', # DEPRECATED — 從未落地,已由 quarterly/half_yearly/annual/ttm 取代(ADR-023) + 'bcg': 'v2.0', # DEPRECATED — 與 strategy 重疊(strategy 已含 BCG 加碼/機會/收割/觀察五級分類) 'vendor': 'v3.1.0', # 2026-05-03 喚醒 + v3 暖紙風 + matplotlib 雙視圖 + 採購策略 SMART prompt + 集中度警示 'quarterly': 'v3.1.0', # 2026-05-03 季報(period_review 共用 generator) 'half_yearly': 'v3.1.0', # 2026-05-03 半年報 @@ -60,7 +61,6 @@ TEMPLATE_VERSIONS = { 'customer': 'v3.1.0', # 2026-05-03 客戶/訂單分析(簡化 RFM,受資料層 user_id 限制) 'forecast_pre_event': 'v3.1.0', # 2026-05-03 檔期前瞻報(baseline × lift_factor 預測 + 去年同檔期) 'promo_compare': 'v3.1.0', # 2026-05-03 多活動 ROI 並排比較 - 'bcg': 'v2.0', # DEPRECATED — 從未落地 }