diff --git a/docs/adr/ADR-026-ppt-system-price-elasticity-and-final-roadmap.md b/docs/adr/ADR-026-ppt-system-price-elasticity-and-final-roadmap.md new file mode 100644 index 0000000..f0b429f --- /dev/null +++ b/docs/adr/ADR-026-ppt-system-price-elasticity-and-final-roadmap.md @@ -0,0 +1,111 @@ +# ADR-026: PPT 系統 — 價格彈性報告 + 完整戰役收尾路線圖 + +- **Status**: Accepted +- **Date**: 2026-05-03 +- **Deciders**: 統帥 +- **Related**: 補完 Wave 3 的 price_elasticity,並收尾整套 v3 PPT 戰役(ADR-022~026) +- **Affects**: `services/ppt_generator.py`、`routes/openclaw_bot_routes.py`、`services/openclaw_bot/menu_keyboards.py` +- **Commit**: `16b169d` (price_elasticity) + +## Context + +ADR-025 後 Wave 3 餘 1 種可從現有資料層做:price_elasticity(簡化版)。本次完成此項,並對整套戰役做最終盤點。 + +剩餘 4 種完全做不了的依賴前置條件: +1. **clv** — 需 user_id(會員系統) +2. **competitor v4 五力** — 需外部 SKU 數 / 品牌力資料整合 +3. **inventory** — 需 stock 表 +4. **operations** — 需 fulfillment 表 +5. **finance** — 需 finance 表 + +## Decision + +### A. price_elasticity 簡化版 + +**核心思路**:用 SKU 級平均售價(總業績/數量)做價位分桶,找出「訂單最多的價位區間」作為**價格甜蜜點**(採購選品的關鍵指標)。 + +**7 個價位桶**: +``` +< NT$200 / 200-500 / 500-1K / 1K-2K / 2K-5K / 5K-10K / > 10K +``` + +**主要洞察維度**: +1. 甜蜜點集中度(>50% 過度集中、30-50% 主流明確、<30% 分布健康) +2. 高價帶業績佔比(業界健康 30-50%) +3. 「斷層」價位(SKU 數明顯偏少 → 補貨機會) + +**簡化限制聲明**: +真正的 price_elasticity 需要「同 SKU 在不同時間的不同售價」做時間序列分析。本版本是「橫斷面分析」(snapshot),告訴採購「該品類目前消費者最常買的價位帶是哪個」。已在 commit message 與 ADR 註明。 + +### B. 整套 v3 PPT 戰役完整成果 + +**18 個 commits(38967ce → 16b169d)**: +| Phase | Commit | 說明 | +|---|---|---| +| v3 重做 | 38967ce..993bdda | 6 種既有報表全升 v3.x(暖紙風 + matplotlib + 模板版本快取 + 共用 2026 市場知識基底)| +| Wave 1 | b6fdb4f..5461c92 | 廠商 + 期間回顧 ×4 + 品類深度 + 客戶分析 | +| Wave 2 | 9f04dc3..af6157f | 檔期前瞻 + 多活動比較 + bcg/growth 廢除 | +| Wave 3 | 95a74c3..16b169d | 新品追蹤 + 市場情報週報 + 價格彈性 | + +**累計 16 種有效報表 + 2 種 DEPRECATED**: +| 角色 | 報表 | +|---|---| +| 戰情/早會 | daily / weekly | +| BU 主管 | monthly / quarterly / half_yearly / forecast / strategy | +| CEO/GM/CFO | annual / ttm / market_intel | +| 採購主管 | vendor / category / new_product / price_elasticity | +| PM 商品經理 | category / new_product / price_elasticity | +| 行銷主管 | promo / promo_compare / customer / market_intel | +| 競品分析 | competitor | + +**DEPRECATED**:bcg(與 strategy 重疊)/ growth(已被 quarterly 取代) + +### C. 待 Wave 4(資料層 / 外部整合擴充後) + +| 報表 | 阻塞於 | 解法路徑 | 預估工程 | +|---|---|---|---| +| clv 客戶終身價值 | 無 user_id | 建會員系統 PII 表 | 大(需 PM 階段性需求) | +| competitor v4 五力 | 外部 SKU/品牌力資料 | 擴 mcp_collector 抓 PChome/蝦皮 SKU API + Dcard 品牌討論度 | 大(8-12h) | +| inventory 庫存健康 | stock 表 | DB schema + ETL pipeline | 大(需採購系統介接) | +| operations 訂單履約 | fulfillment 表 | DB schema + 物流資料 | 大(需物流系統介接) | +| finance P&L | finance 表 | DB schema + ERP 整合 | 大(需財務系統介接) | + +## Consequences + +### Positive + +1. **零售/電商 BI 報表體系完整覆蓋**:16 種報表覆蓋採購/PM/行銷/CEO/CFO/戰術/戰情七大角色 +2. **資料層復用最大化**:所有 16 種報表都基於同一張 `realtime_sales_monthly`(無需新建 schema) +3. **AI 顧問深度跨報表一致**:`MARKET_TREND_2026` 共用知識基底 + 角色化 prompt(每種報表配對應 AI 角色) +4. **模板版本快取機制**:未來任何報表升版只需 bump `TEMPLATE_VERSIONS`,舊快取自動 miss +5. **共用 generator 模式**:period_review 一份解 4 種報表,未來新增報表類型可繼承 + +### Negative + +1. **Telegram 主選單擁擠**:報表選單從原本 7 顆按鈕擴充到 18 顆,視覺密度高 +2. **AI prompt token 成本上升**:高顧問深度 prompt(max_tokens 1500-2600)每生成一份報告 NIM 配額消耗增加 +3. **外部 API 依賴**:market_intel 依賴 Gemini Grounding,配額耗盡時整段 fallback + +### 風險與緩解 + +- **報表選單過載**:未來考慮分層子選單(時間維度 / 角色 / 主題) +- **token 成本**:模板版本快取已實作,同參數秒回不重複呼叫 AI +- **外部 API rate limit**:`_safe()` wrapper + fallback 防呆已實作(market_intel) + +## 結論 + +本戰役歷時 2 天(2026-05-02 ~ 2026-05-03),共 18 commits,從原本 6 種 PPT 報表擴展到 16 種,並完成完整的: +- 視覺全面重做(v3 暖紙風) +- AI prompt 顧問深度升級(含 SMART 框架、市場趨勢、角色化) +- 共用資料層 + matplotlib 圖表 + cache versioning + 中英分軌字型 + 部署排程 + +剩餘 5 種報表(clv / competitor v4 / inventory / operations / finance)受資料層或外部依賴限制,列入 Wave 4 待辦,待相應前置條件具備後接力。 + +## References + +- ADR-022 PPT v3 redesign(戰役起點) +- ADR-023 Wave 1 擴展(廠商/期間/品類/客戶) +- ADR-024 Wave 2(檔期前瞻/多活動比較/廢除) +- ADR-025 Wave 3(新品/市場情報) +- ADR-026 Wave 3 收尾(價格彈性/完整路線圖) +- 對應 memory:`reference_ppt_system.md` / 戰役紀錄:`project_ppt_v3_campaign_20260502.md`、`project_ppt_wave1_expansion_20260503.md`、`project_ppt_wave3_intel_20260503.md` diff --git a/docs/adr/README.md b/docs/adr/README.md index f4fcc58..bb24234 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -47,6 +47,7 @@ | [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 | +| [026](ADR-026-ppt-system-price-elasticity-and-final-roadmap.md) | PPT 系統 — 價格彈性報告 + 完整戰役收尾路線圖 | Accepted | 2026-05-03 | ## 規範