# 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`
