補 OpenClaw 選單複核報告

docs/openclaw_menu_audit_report.md

@@ -0,0 +1,111 @@
+# OpenClaw Telegram 按鈕盤點報表（2026-05-01；2026-05-13 Codex 複核）
+
+## 總覽
+- 按鈕總數：84（`menu:`/`cmd:`/`await:`/`cmd:catdetail` 等）
+- 自動回歸測試：40 項通過（`pytest -q tests/test_openclaw_bot_menu_keyboards.py tests/test_openclaw_bot_routes_webhook.py tests/test_openclaw_bot_telegram_api.py`，2026-05-13）
+- /menu 顯示與 Callback 編輯流程：已修正為優先編輯原訊息，避免重複傳訊息
+- 重複更新處理：新增 update_id 去重，重複 webhook 會直接 `skip`
+- `message is not modified`：判斷後不再 fallback 重傳
+- V2 callback 盤點再確認：OpenClaw 分類按鈕目前使用 `cmd:catdetail:<cat>:<date>`，不是舊式 `cat_<category>`；`await:date_trend_*` 與 `await:goal_*` 皆有 webhook state handler。
+
+## 主選單（`/menu`）
+| 按鈕 | Callback | 對應子選單 |
+|---|---|---|
+| 📊 業績查詢 | `menu:sales` | `sales` |
+| 🏆 商品廠商 | `menu:products` | `products` |
+| 🎯 目標管理 | `menu:goals` | `goals` |
+| 📈 智能分析 | `menu:analysis` | `analysis` |
+| 📄 簡報報表 | `menu:reports` | `reports` |
+| 🌐 市場情報 | `menu:market` | `market` |
+| 🔍 競品日報 | `menu:competitor` | `competitor` |
+
+## 快速入口（help）
+| 按鈕 | Callback |
+|---|---|
+| 📊 快速查詢 | `menu:sales` |
+| 🏆 熱銷與廠商 | `menu:products` |
+| 🎯 目標管理 | `menu:goals` |
+| 📈 智能分析 | `menu:analysis` |
+| 🧩 報表簡報 | `menu:reports` |
+| 🔍 競品比較 | `menu:competitor` |
+
+## 子選單
+
+### `sales`
+- 今日 / 昨日業績：`cmd:sales:<date>`
+- 每週業績：`cmd:trend:week`
+- 每月業績：`cmd:history:<YYYY/MM>`
+- 每季業績：`cmd:trend:quarter`
+- 近半年：`cmd:trend:half`
+- 趨勢分析：`menu:trend`
+- 同期比較：`cmd:compare:<date>`
+- 分類業績：`cmd:category:<date>`
+- 日期區間輸入：`await:date_range_sales`
+- 月份總覽：`cmd:history`
+
+### `products`
+- 熱銷商品：`cmd:top:<date>`
+- 熱銷廠商：`cmd:vendor:<date>`
+- 商品健康：`cmd:health:<date>`
+- 昨日商品：`cmd:top:<yesterday>`
+- 補貨預測：`cmd:restock`
+- 分類鑽取：`menu:category`
+- 指定日期：`await:date_top`
+
+### `goals`
+- 查看達成率：`cmd:goal`
+- 日/月/季/半年/年目標設定：`await:goal_*`
+
+### `analysis`
+- 商品策略：`cmd:strategy:<date>`
+- 業績趨勢：`menu:trend`
+- 商品健康：`cmd:health:<date>`
+- 分類業績：`cmd:category:<date>`
+- 促銷追蹤：`await:promo_range`
+- 補貨預測：`cmd:restock`
+- 趨勢圖表：`cmd:chart`
+- 同期比較：`cmd:compare:<date>`
+- 指定日期：`await:date_analysis`
+
+### `trend`
+- 近7日 / 近1個月：`cmd:trend:7`, `cmd:trend:month`
+- 近3個月 / 近半年：`cmd:trend:quarter`, `cmd:trend:half`
+- 本年度：`cmd:trend:year`
+- 指定月份：`await:date_trend_month`
+- 指定年份：`await:date_trend_year`
+- 指定季度：`await:date_trend_quarter`
+
+### `reports`
+- 日報 / 週報 / 月報：`cmd:ppt:daily`, `cmd:ppt:weekly`, `cmd:ppt:monthly`
+- 下載報表：`cmd:report`
+- 策略（日/週/月/季/半年/年）：`cmd:ppt:strategy` 及 `cmd:ppt:strategy <range>`
+- 促銷效益：`await:promo_range`
+- 競品比較：`menu:competitor`
+- 指定日報 / 指定月報：`await:date_ppt_daily`, `await:date_ppt_monthly`
+
+### `market`
+- 電商新聞 / 天氣：`cmd:news`, `cmd:weather`
+- Google 熱搜 / Dcard：`cmd:trends`, `cmd:dcard`
+- 台銀匯率 / 電商節慶：`cmd:exchange`, `cmd:calendar`
+- YouTube / AI 狀態：`cmd:youtube`, `cmd:learn`
+- 關鍵字比價 / 圖片比價說明：`await:search_compare`, `cmd:photo_search_help`
+
+### `competitor`
+- 今日 / 昨日簡報：`cmd:ppt:competitor <today/yesterday>`
+- 本週 / 本月 / 本季 / 指定日期比較：`cmd:ppt:competitor <period>`、`await:date_competitor`
+- 進入競品長週期：`menu:competitor_ppt`
+
+### `competitor_ppt`
+- 半年 / 年比較：`cmd:ppt:competitor half`, `cmd:ppt:competitor yearly`
+- 返回：`menu:competitor`
+
+### `category`
+- 固定 L1 分類：`cmd:catdetail:<cat>:<date>`
+- 全分類清單：`cmd:category:<date>`
+
+## 補充狀態
+1. ✅ 所有回傳 `menu:` 的 callback 都有對應 `_SUBMENUS`。
+2. ✅ `/menu`、回呼選單、`await:` 狀態機都已有回歸測試。
+3. ✅ 簡報快取：同參數請求先讀 DB，命中則直接回傳既有 PPT，未命中才生成並寫入 DB。
+4. ✅ 重複 /callback 重送與 Telegram 「message is not modified」重複訊息已降噪。
+5. ✅ `cmd:catdetail`、`await:date_trend_*`、`await:goal_*` 已由回歸測試與程式碼路徑覆蓋；若未來新增 callback prefix，需同步補 handler 與 `tests/test_openclaw_bot_*`。