48804553cd
All checks were successful
CD Pipeline / deploy (push) Successful in 1m15s
- ppt_generator.py: 新增 generate_growth_ppt(6頁)、generate_vendor_ppt(5頁)、generate_bcg_ppt(5頁) - openclaw_bot_routes.py: 新增 query_growth_data()、query_vendor_bcg_data()、_generate_ppt_cmd 三路分支、_submenu_reports 4顆新按鈕、type_labels、await:date_ppt_vendor 流程 - ADR-014: 記錄 V2 完整架構（9種報告類型、圖表技術方案、callback_data 格式） - CLAUDE.md: 新增 PPT 簡報系統索引表 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# 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]
|
||
```
|