wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
bb65ba71ba91bbdfd703bef3d1ac3e87e3b65fbc
ewoooc/docs/adr/ADR-023-ppt-system-expansion-wave1.md
OoO 5461c92cf8 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>
2026-05-03 02:20:05 +08:00

6.3 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink