# ADR-091: Telegram 子系統全景審計與 UX 黑洞修復（Phase 7 Round 3）

**日期**: 2026-04-19
**狀態**: ✅ 已實施（commits `877c847` → `4b8be32`，git tag `v7.3.0`）
**上游**: [ADR-090 監控盲區治理](./ADR-090-monitoring-blindspot-governance.md)、[MASTER Blueprint §7.1](../superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md)
**Memory**: `project_phase7_round3_telegram_subsystem.md`

## Context（背景）

2026-04-18 深夜統帥連續截圖 Telegram 卡片異常：按鈕按了無反應、卡片永遠顯示「執行中」、responsibility 欄位顯示「未知」、drift 卡片內文與 description 互相矛盾。統帥原話：「**根本他媽的沒有盤查過所有的 Telegram 的按鈕！你就是做爽的而已！**」

過往每遇 Telegram bug 都是點對點補丁，從未做過**全景 × 全按鈕型別 × handler 覆蓋矩陣**的完整盤查。本 Round 強制要求：先做全景矩陣，再批次修。

## Decision（決策）

### 1. 建立 Telegram callback 按鈕 × Handler 覆蓋矩陣

11 個按鈕型別 vs handler 覆蓋現況：

| 按鈕型別 | Callback 格式 | Handler 狀態（修前） | 修後 |
|---------|--------------|--------------------|------|
| approve / reject / tune / silence | 4-part nonce | ✅ 原有 | ✅ |
| view | 2-part INFO | 🔴 未在 INFO_ACTIONS 白名單 | ✅ 加入（TG-1） |
| drift_view | 4-part nonce | 🔴 無 handler（UX 黑洞） | ✅ 專屬分派（TG-2） |
| drift_adopt | 4-part nonce | 🔴 無 handler | ✅ 呼叫 `drift_adopt_service` |
| drift_revert | 4-part nonce | 🔴 無 handler | ✅ 呼叫 `drift_remediator.revert` |
| scale / secops_authorize / secops_isolate | 4-part nonce | 🔴 定義但無 handler | ⏸ 下輪補 spec 或移除 |

### 2. 鐵律：新增按鈕前必通過三缺一檢查

由 `feedback_no_ghost_buttons.md` 升級為 ADR 層級規範：

> **發送任何 Telegram callback 按鈕前，必須通過：**
> 1. callback_data 格式在 `parse_callback_data` 支援（nonce or INFO）
> 2. 有對應 handler 分支
> 3. handler 所需能力（MCP / service）真實存在
>
> **三缺一，絕不發送**。沒有 handler 的按鈕 = UX 黑洞 = 用戶認為系統當機。

### 3. callback_data 雙格式正式認定

| 語義 | 格式 | 範例 | 適用 |
|------|------|------|------|
| 寫操作 | `{action}:{approval_id}:{timestamp}:{random}` | `approve:abc:1234:xyz` | 防重放（nonce） |
| 讀操作 | `{action}:{incident_id}` | `view:inc_123` | INFO_ACTIONS 白名單 |
| **特例：drift** | 走 nonce 格式，語義讀/寫混合 | `drift_view:abc:1234:xyz` | handle_callback Step 1.85 專屬分派 |

INFO_ACTIONS 白名單位於 [`security_interceptor.py`](../../apps/api/src/services/security_interceptor.py) line 438。新增讀操作按鈕必須加入此集合。

### 4. Long Polling 正式採用（非 Webhook）

- `getWebhookInfo` 回 URL=空是 **by design**
- 單 Pod Leader Election（Redis lock）避免多 Pod 搶 getUpdates 409
- `/api/v1/telegram/webhook` endpoint 已標註 `[已棄用]`，保留作退路

### 5. Approval 執行完成三戳鐵律

approval 執行完後必須同時完成三件事，否則卡片永遠「執行中」：

1. `editMessageReplyMarkup` 移除按鈕
2. `editMessageText` 加上 ✅/❌ 結果 + KM/Playbook 增量戳
3. `approval_records.telegram_message_id` 寫入 DB（不只 Redis）

### 6. NO_ACTION 不是 FAILED

OpenClaw 決策為 `NO_ACTION`（調查用）時走 noop 分支標 `SUCCESS`，不進 verifier FAILED path，救 MASTER §7.1 #11 auto_execute 成功率。

### 7. Responsibility 正規化

primary_responsibility 欄位不可留空/None/invalid；空值一律 fallback `INFRA` 或 `BE`。

## Consequences（後果）

### 正面

- **9 bugs 中 7 修**（TG-1/2/4 + AP-1/2/3 + Extra NO_ACTION），2 延後（TG-3 refactor、TG-5 by-design）
- **全景盤點成為標準工作流**：未來新增按鈕/handler 必先畫矩陣
- **UX 黑洞鐵律上 ADR**：三缺一絕不發送，防止下次再出現無 handler 按鈕
- **NO_ACTION 真實率可測**：MASTER §7.1 #11 不再被誤標污染

### 負面 / 未完

- `scale / secops_authorize / secops_isolate` 按鈕仍在定義但無 handler，下輪補 action spec 或移除
- TG-3 handler 重複分派（approve 邏輯散落 4 處）為純 refactor，本輪跳過
- Webhook endpoint 標註棄用但未刪除（保留退路）

### 需觀察（24h 真實 traffic）

```sql
-- 三條閉環驗證
SELECT COUNT(*) FROM notification_outcomes;
SELECT COUNT(*) FROM approval_records WHERE telegram_message_id IS NOT NULL;
SELECT COUNT(*) FROM automation_operation_log WHERE operation_type='notification_formatted';
```

## 5 Commits 時序

1. [`877c847`](https://gitea.wooo.work/owen/awoooi/commit/877c847) feat(telegram): drift 按鈕 3 handler + drift card message_id Redis 存（TG-2 + TG-4）
2. [`2e988bd`](https://gitea.wooo.work/owen/awoooi/commit/2e988bd) fix: drift 執行結果 reply_to 原卡片 + audit log
3. [`fdce0a3`](https://gitea.wooo.work/owen/awoooi/commit/fdce0a3) fix(approval): NO_ACTION 走 noop 分支標 SUCCESS
4. [`68a42a3`](https://gitea.wooo.work/owen/awoooi/commit/68a42a3) refactor(openclaw): 幻覺驗證抽成 helper，sweeper + webhook 雙路徑呼叫
5. [`4b8be32`](https://gitea.wooo.work/owen/awoooi/commit/4b8be32) fix: TG-1 INFO_ACTIONS view + AP-1/2/3 approval 三修

**Git tag**: `v7.3.0` at `4b8be32`

## 相關文件

- MASTER §8 Changelog 2026-04-19 條目：`docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md`
- Memory 全彙總：`~/.claude/projects/-Users-ogt-awoooi/memory/project_phase7_round3_telegram_subsystem.md`
- 鬼魂按鈕鐵律（feedback）：`feedback_no_ghost_buttons.md`
- 上一輪修復：`project_phase7_round2_flywheel_fixes.md`（ADR-090 實施 Round 2）
