# 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_*`。