From 5461c92cf8f0293ef0e60b064aef023b3ddbc648 Mon Sep 17 00:00:00 2001 From: OoO Date: Sun, 3 May 2026 02:20:05 +0800 Subject: [PATCH] docs(adr): ADR-023 PPT system Wave 1 expansion (4 commits, 8 new types) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 紀錄 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) --- .../adr/ADR-023-ppt-system-expansion-wave1.md | 117 ++++++++++++++++++ docs/adr/README.md | 1 + 2 files changed, 118 insertions(+) create mode 100644 docs/adr/ADR-023-ppt-system-expansion-wave1.md diff --git a/docs/adr/ADR-023-ppt-system-expansion-wave1.md b/docs/adr/ADR-023-ppt-system-expansion-wave1.md new file mode 100644 index 0000000..3c3d6d9 --- /dev/null +++ b/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 diff --git a/docs/adr/README.md b/docs/adr/README.md index 8c86814..8791f34 100644 --- a/docs/adr/README.md +++ b/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 | ## 規範