# ADR-014: PPT 簡報系統 V2 — 原生圖表 + 9 種報告類型

**狀態**: Accepted  
**日期**: 2026-04-20  
**提案者**: 統帥

---

## 背景與問題

PPT 簡報系統 V1（2026-04-20 v1）只有 6 種報告，其中 weekly/monthly/promo/strategy 頁面為「空殼」——資料庫的數字完全沒有視覺化呈現，只有 AI 純文字。  
同時缺少對應網站核心圖表（growth_analysis / monthly_summary_analysis）的報告類型。

---

## 決策

升級為 V2（2026-04-20 v2），做以下改動：

### 1. 現有 6 種報告大幅升級

| 類型 | 舊頁數 | 新頁數 | 新增內容 |
|------|-------|-------|---------|
| daily | 3 | **4** | P3 近7日業績柱狀圖 |
| weekly | 2 | **5** | P2 KPI、P3 7日走勢圖、P4 TOP10商品表 |
| monthly | 2 | **5** | P2 KPI、P3 品類橫條圖、P4 TOP10商品表 |
| strategy | 3 | **5** | P3 策略矩陣柱狀圖、P4 彩色策略行動清單 |
| promo | 2 | **5** | P2 雙層KPI+升降幅、P3 雙柱業績對比、P4 TOP商品 |
| competitor | 4 | **4** | 架構不變，已是最完整 |

### 2. 新增 3 種報告

| 類型 | 頁數 | 對應網站頁面 | 資料來源 |
|------|------|------------|---------|
| **growth** 成長趨勢 | 6 | growth_analysis | `realtime_sales_monthly` |
| **vendor** 廠商業績 | 5 | monthly_summary_analysis vendorRankingChart | `monthly_summary_analysis` |
| **bcg** 品牌矩陣 | 5 | monthly_summary_analysis bcgMatrixChart | `monthly_summary_analysis` |

### 3. 圖表技術方案

- 使用 python-pptx 原生 Chart API（`_add_column_chart` / `_add_horiz_chart`）
- 對應前端使用的 Chart.js (daily_sales) / ECharts (monthly_summary)
- 每種圖表 fallback 至空白提示，不 crash

### 4. Telegram 新按鈕

`_submenu_reports()` 新增 2 列：
```
[📈 成長趨勢報告] [🏭 廠商業績報告]
[🎯 BCG 品牌矩陣] [📅 指定月份廠商]
```

### 5. 新增 Query 函數

- `query_growth_data()` — 複用 growth_analysis 路由邏輯
- `query_vendor_bcg_data(yr, mo)` — 直接 raw SQL 查 monthly_summary_analysis

---

## 架構圖（完整 PPT 流程）

```
Telegram 按鈕點擊
  ↓ callback_data: cmd:ppt:TYPE [ARG]
handle_cmd('ppt', 'TYPE ARG', chat_id, reply_to)
  ↓
_ppt_background() [threading.Thread daemon]
  ↓ 發送「⏳ 正在生成...」
_generate_ppt_cmd(sub_type, sub_arg, chat_id, target)
  ↓ query_xxx_data()  →  DB (realtime_sales_monthly / monthly_summary_analysis)
  ↓ _ppt_ai_analysis()  →  Gemini 2.0 Flash / NVIDIA DeepSeek 備援
  ↓ generate_xxx_ppt()  →  /app/data/reports/ocbot_TYPE_XXXXXXXX.pptx
send_document(chat_id, ppt_path, caption)
  ↓ os.unlink(ppt_path)
```

---

## 相關檔案

| 檔案 | 角色 |
|------|------|
| `services/ppt_generator.py` | 9 種 PPT 生成函數 + 圖表 helper |
| `routes/openclaw_bot_routes.py` | query 函數、_generate_ppt_cmd、按鈕、type_labels |
| `routes/sales_routes.py` | growth_analysis 路由（資料來源參考）|
| `routes/monthly_routes.py` | monthly_summary API（資料來源參考）|

---

## 支援的 callback_data 格式

```
cmd:ppt:daily [YYYY/MM/DD]
cmd:ppt:weekly
cmd:ppt:monthly [YYYY/MM]
cmd:ppt:strategy [daily/weekly/monthly/quarterly/half/yearly]
cmd:ppt:competitor [daily/weekly/monthly/quarterly/half/yearly]
cmd:ppt:promo  → await:promo_range
cmd:ppt:growth
cmd:ppt:vendor [YYYY/MM]
cmd:ppt:bcg [YYYY/MM]
```