fix(telegram): clarify automation notification state

docs/LOGBOOK.md

@@ -1,3 +1,23 @@
+## 2026-05-06 | Telegram 事故通知語義收斂與 AwoooP 首頁總覽
+
+**背景**：SRE 戰情室截圖顯示 ACTION REQUIRED、AI 自動修復失敗、Escalation、Code Review、Config Drift 等訊息混在同一條流中；值班者很難快速分辨哪些是 AI 已修復、哪些是 AI 無法修復需要人工、哪些只是報表或治理通知。
+
+**本次修補**：
+- `TelegramMessage` 主卡新增「處置狀態」，在第一屏明確標示 `AI 已提出修復建議，等待人工批准`、`AI 無可安全執行動作，需人工判斷`、`AI 分析超時，需人工排查` 或 `規則建議待審批`。
+- `append_incident_update()` 對同一 `incident_id` 的相同狀態回覆做 5 分鐘 Redis 去重，避免同樣的 `[AUTO] AI 自動修復失敗` 連續洗版。
+- 新增 `docs/awooop/TELEGRAM-INCIDENT-NOTIFICATION-MODEL.md`，定義 Telegram / AwoooP Run Monitor / Approval Queue / Incident Timeline / MCP Audit 的分工。
+- `/zh-TW/awooop` 首頁改為治理總覽，直接顯示租戶、Run、審批、合約與飛輪鏈路狀態；不再只是轉到 work-items 頁。
+- 新增 AwoooP 首頁 `zh-TW` / `en` i18n 字串。
+
+**驗證**：
+- `python -m py_compile apps/api/src/services/telegram_gateway.py apps/api/tests/test_telegram_message_templates.py`
+- `pytest tests/test_telegram_message_templates.py tests/test_telegram_ai_automation_block.py -q` → 19 passed。
+- `pnpm --dir apps/web typecheck` 通過。
+- `NEXT_PUBLIC_API_URL=https://awoooi.wooo.work pnpm --dir apps/web build` 通過。
+
+**注意**：
+- `ruff check src/services/telegram_gateway.py ...` 仍會掃到 `telegram_gateway.py` 既有 import/order、bare except、單行 if 等歷史債；本輪沒有在 6000+ 行 gateway 巨檔做無關機械清理，避免混入額外行為風險。
+
 ## 2026-05-06 | AwoooP Run 監控頁 422 修正
 
 **背景**：Playwright 驗證 `/zh-TW/awooop` 時未再看到 client-side exception，但 `/zh-TW/awooop/runs` 會顯示「無法載入 Run 資料 HTTP 422」。後端 log 顯示 `GET /api/v1/platform/runs/list?page=1&per_page=50` 被回 422。

docs/awooop/TELEGRAM-INCIDENT-NOTIFICATION-MODEL.md

@@ -0,0 +1,47 @@
+# Telegram 事故通知模型
+
+> 目的：讓 SRE 戰情室一眼分辨「AI 已修復」、「AI 可建議但需批准」、「AI 無法安全修復需人工」與「僅通知」，避免告警、執行 log、Code Review、Drift 與審批結果互相洗版。
+
+## 核心判斷
+
+Telegram 不應是完整執行日誌，也不應承載所有 AI 推理細節。Telegram 的職責是把需要人類注意力的決策摘要送到 SRE 戰情室；完整時間線、工具輸出、重試原因、provider fallback 與 audit 交給 AwoooP Run Monitor / Incident Timeline。
+
+## 四種通知狀態
+
+| 狀態 | 意義 | Telegram 行為 | 操作者動作 |
+| --- | --- | --- | --- |
+| AI 已自動修復 | 自動化已完成且驗證通過 | 更新原 incident 卡或回覆一次結果 | 檢查即可，不需批准 |
+| AI 建議待審批 | AI / 規則已提出可執行建議，但被 Trust / Risk gate 擋下 | 發一張 ACTION REQUIRED 主卡 | 批准、拒絕、靜默或看詳情 |
+| AI 無法安全修復 | NO_ACTION、INVALID_TARGET、LLM timeout、MCP 失敗或缺少安全動作 | 發人工接手摘要，不重複刷同一狀態 | 人工排查，或要求重診 |
+| 僅通知 | 心跳、報表、Code Review 完成、低風險治理資訊 | 彙總卡或摘要頻道 | 通常不需即時動作 |
+
+## 專業化訊息規則
+
+1. 同一個 `incident_id` 只應有一張主卡。後續狀態使用原卡回覆、編輯按鈕或 AwoooP timeline，不再每一步都新發卡。
+2. 主卡第一屏必須顯示「處置狀態」，先回答：AI 是否能修、是否已修、是否需要人工。
+3. 同一個 `incident_id` 的相同狀態更新，短時間內要去重。詳細重試與錯誤放到 timeline，不洗 Telegram。
+4. P0 / P1 escalation 可以另發升級卡，但內容必須是「目前影響、已嘗試、卡住原因、需要誰做什麼」，不可重貼所有底層 log。
+5. Code Review、Config Drift、報表、心跳不應和 incident 執行回覆混在同一種語義；它們可以在同一 SRE 群組，但必須以摘要卡與固定前綴區分。
+
+## 與 AwoooP 的分工
+
+| 介面 | 承載內容 |
+| --- | --- |
+| Telegram | 決策摘要、升級、人工批准入口 |
+| AwoooP Run Monitor | 非同步 Run、provider fallback、tool call、retry、latency |
+| Approval Queue | 所有等待批准的高風險動作 |
+| Incident Timeline | 事件完整歷程、AI 嘗試、失敗原因、KM / Playbook 回寫 |
+| MCP Audit | 工具執行、redaction、permission gate、credential 注入 |
+
+## 本輪落地
+
+- `TelegramMessage` 主卡新增「處置狀態」。
+- `append_incident_update()` 對同一 incident 的相同狀態做 5 分鐘 Redis 去重。
+- 既有 `詳情 / 重診 / 歷史` 按鈕保留，讓 Telegram 保持輕量，細節回到控制台。
+
+## 後續建議
+
+1. 將 Telegram 群組升級為 Forum topics 或固定 topic lane：`P0/P1 事故`、`人工審批`、`治理/報表`、`CI/Code Review`。
+2. AwoooP Approval Queue 顯示與 Telegram 相同的「處置狀態」欄位，避免前後端語義分裂。
+3. 將 auto-repair failure 的完整 stdout/stderr 改寫入 Run Timeline，只在 Telegram 顯示最短摘要與詳情連結。
+4. 對 firing 告警做 fingerprint 聚合：同一 alertname + target + namespace 在窗口內只更新卡片，不新增卡片。