docs(adr): ADR-023 PPT system Wave 1 expansion (4 commits, 8 new types)

紀錄 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>

docs/adr/ADR-023-ppt-system-expansion-wave1.md

@@ -0,0 +1,117 @@
+# 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

docs/adr/README.md

@@ -44,6 +44,7 @@
 | [020](ADR-020-code-review-full-autoheal.md) | Code Review 全自動修復政策（局部覆寫 ADR-012 HITL） | Accepted | 2026-05-02 |
 | [021](ADR-021-ea-hitl-prefetch-and-alert-impact.md) | EA HITL Pre-fetch + 競價告警必填金額影響量化 | Accepted | 2026-05-03 |
 | [022](ADR-022-ppt-system-v3-redesign.md) | PPT v3 — 暖紙風 + matplotlib 專業圖表 + 模板版本快取 | Accepted | 2026-05-02/03 |
+| [023](ADR-023-ppt-system-expansion-wave1.md) | PPT 系統 Wave 1 擴展 — 廠商 / 期間回顧 / 品類深度 / 客戶分析（8 種新報表） | Accepted | 2026-05-03 |
 
 ## 規範