# ADR-023: PPT 系統 Wave 1 擴展 — 廠商 / 期間回顧 / 品類深度 / 客戶分析

- **Status**: Accepted
- **Date**: 2026-05-03
- **Deciders**: 統帥
- **Related**: 延續 ADR-022（PPT v3 暖紙風 + 模板版本快取機制），擴展 4 + 4 = 8 種新報表類型
- **Affects**: `services/ppt_generator.py`、`routes/openclaw_bot_routes.py`、`services/openclaw_bot/menu_keyboards.py`
- **Commit chain**: `b6fdb4f` (vendor) → `1af96f5` (period_review × 4) → `d8260fc` (category) → `48e3dac` (customer)

## Context

統帥盤點現有 6 種 PPT 報表（daily/weekly/monthly/strategy/competitor/promo）後指出市場上專業 BI 報告還有大量缺口：
1. 季報 / 半年報 / 年報 / TTM 滾動 12 月（時間維度）
2. 廠商業績報告（採購視角）
3. 品類深度報告（PM/採購視角）
4. 客戶/訂單分析（行銷視角）
5. 競業/競品行銷比較（升級 competitor）
6. 市場公開報告彙整週報
7. 等共 17 種

並批准全部執行。Wave 1 聚焦最高 ROI 的 4 種（vendor、period_review、category、customer），優先做完。

## Decision

### A. 共用 Generator 設計（period_review 一份解 4 種）

`generate_period_review_ppt(period_type, period_label, db_data, ai_text)` 用一份程式碼處理：
- `quarterly` (2026 Q1)
- `half_yearly` (2026 H1)
- `annual` (2026)
- `ttm` (TTM 2025-05~2026-04)

差異僅在路由層的時間範圍計算 + 封面徽章顏色。**省 60%+ 程式碼**。

### B. 8 種新報表全部 v3.1.0 上線

| 類型 | 函式 | 頁數 | 角色 | 核心特色 |
|---|---|---|---|---|
| vendor | `generate_vendor_ppt` | 8 | 採購主管 | 集中度警示 + 帕雷托議價優先 |
| quarterly | `generate_period_review_ppt('quarterly')` | 12 | BU 主管 | QoQ + YoY 三段比對 |
| half_yearly | 同上（period_type='half_yearly') | 12 | BU 主管 | HoH + YoY |
| annual | 同上（period_type='annual') | 12 | CEO/CFO | 年度 + 前年比對 |
| ttm | 同上（period_type='ttm') | 12 | 財務 | 滾動 12 月去除季節性 |
| category | `generate_category_deep_ppt` | 12 | PM/採購 | 90 天 + 子品類 + 新進榜（CTE） |
| customer | `generate_customer_analytics_ppt` | 7 | 行銷主管 | 客單分桶 + 星期分佈 + 復購（簡化 RFM） |

### C. AI Prompt 角色化（每種報表配對應角色）

| 報表 | AI 角色 | max_tokens |
|---|---|---|
| vendor | 採購主管 + 供應鏈管理顧問 | 1800 |
| period_review | 策略顧問 + BU 主管 + CFO 三合一 | 2600 |
| category | 採購主管 + PM 商品經理 | 1800 |
| customer | 資深行銷主管（RFM/CRM） | 1500 |

每個角色都引用 `MARKET_TREND_2026` 共用知識基底，跨報表敘事一致。

### D. 資料層擴充（4 個新 query 函式）

| 函式 | 用途 |
|---|---|
| `query_vendor_summary(start, end, lim)` | 廠商業績聚合（含毛利、qty、orders）|
| `query_period_summary(start, end)` | 期間綜合（kpis + monthly_breakdown + top_*）|
| `query_category_deep(category, days)` | 單品類縱向（含 sub_categories L2 + new_products CTE）|
| `query_customer_analytics(start, end)` | 訂單級分析（AOV bucket + DOW + 復購）|

### E. Customer 報表的限制聲明

因 `realtime_sales_monthly` 表無 `user_id` 欄位（PII 法規），無法做完整 RFM。**封面與 prompt 都明確聲明此限制**，並建議「日後接入會員系統 user_id → 可升級完整 R/F/M 11-persona 分群」。

### F. Telegram 按鈕擴充

`_submenu_reports()` 從原 7 顆按鈕擴充到 14 顆：
- 既有：日/週/月、策略 5 種、促銷、競品、指定日期/月份
- 新增：廠商、季報、半年報、年報、TTM、品類深度、客戶分析

## Consequences

### Positive

1. **角色化覆蓋完整**：採購（vendor/category）/ BU 主管（period_review）/ 行銷（customer/promo）/ CEO（annual/ttm）/ PM（category）每個高層都有對應的 BI 報表
2. **共用 Generator 大幅省工**：period_review 用 1 份函式解 4 種，未來新增「半月報」「兩月報」等只需加路由分支
3. **資料層復用**：4 個新 query 函式都基於同一張 `realtime_sales_monthly`，無需新建 table
4. **AI 跨報表敘事一致**：MARKET_TREND_2026 共用常數確保所有 AI 用同一份市場事實基底

### Negative

1. **Cache miss 路徑變慢**：period_review 一次要拉 3 段資料（本期 / 上期 / 去年同期），每段 4 條 SQL，共 12 條
2. **PPT 變大**：12 頁含 3-4 張 matplotlib PNG，每份 200~330KB
3. **菜單按鈕 14 顆**：可能略顯擁擠，未來考慮分子選單

### 風險與緩解

- **vendor 集中度判定誤差**：用前 N 家佔 80% 的比例 / 總家數判斷，極端值（5 家全部 = 100%）會誤判。已加 `if vcount` 防呆。
- **TTM 月份切割**：CURRENT_DATE 在月初與月末判定不同。已用 `replace(day=1)` 對齊月初。
- **customer 復購率失真**：因無 user_id，「商品復購」實為「同商品被多筆訂單購買」，並非「同一客戶重複購買」。已在 prompt 與封面註腳聲明。

## Alternatives Considered

1. **每種報表各寫獨立 generator**：拒絕 — 會產生 4 份高度相似的 600+ 行函式，維護成本高
2. **完整 RFM 11-persona 分群**：拒絕 — 資料層無 user_id 強做會誤導決策；改先做訂單級簡化版 + 註明日後升級路徑
3. **bcg generator 升級到 v3**：拒絕 — 與 strategy 功能重疊（strategy 已含 BCG 思路），保留待 ADR-024 廢除

## Wave 2 / Wave 3 / Wave 4 待辦

依 17 種完整清單，本次完成 Wave 1（4 種）+ period_review 共用解 4 種 = 8 種。剩餘：

- **Wave 2**: competitor v4 五力升級 / promo_compare 多活動比較 / forecast_pre_event 檔期前瞻
- **Wave 3**: market_intel_weekly 外部彙整 / new_product 30 天追蹤 / clv 客戶終身價值 / price_elasticity 價格彈性
- **Wave 4**（依資料層）: inventory 庫存健康 / operations 履約 / finance P&L
- **廢除**: bcg generator（與 strategy 重疊）

## References

- 對應 memory：`reference_ppt_system.md`（v3 → v3.1 擴展）、新建 `project_ppt_v3_wave1_expansion_20260503.md`
- 商業價值排序：vendor > category > customer > period_review（依 ROI）
- 全 14 種 PPT 報表清單：daily / weekly / monthly / quarterly / half_yearly / annual / ttm / strategy / competitor / promo / vendor / category / customer + 廢除中的 bcg