5461c92cf8
紀錄 Wave 1 擴展戰役：從 6 種 PPT 報表擴展到 14 種。 新增報表類型： - vendor (b6fdb4f) — 採購主管視角，集中度警示 + 議價優先 - quarterly / half_yearly / annual / ttm (1af96f5) — period_review 共用 generator 一份解 4 種，省 60% 程式碼 - category (d8260fc) — PM/採購視角，90 天縱向 + 子品類 + CTE 新進榜 - customer (48e3dac) — 行銷主管簡化 RFM，受限於無 user_id 做訂單級 技術亮點： - 共用 Generator 模式（period_review 解 4 種） - 期間徽章自動切換 - PostgreSQL CTE 做新進榜判定（recent EXCEPT early） - 限制聲明的誠實設計（customer 無 user_id 註腳） Wave 2-4 待辦清單見 ADR 內文。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
118 lines
6.3 KiB
Markdown
118 lines
6.3 KiB
Markdown
# 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
|