docs(adr-075): 加入實作記錄 + LOGBOOK 更新（Phase 1+2+CR 全完成）

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-12 18:44:57 +08:00
parent 1cb654cf59
commit 079d0e89b9
2 changed files with 185 additions and 1 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -6,7 +6,32 @@

 ---

-## 📍 當前狀態 (2026-04-12 — 層次三+四全部完成，CD 推送中)
+## 📍 當前狀態 (2026-04-12 深夜 — ADR-075 Phase 1+2+CR 全完成，git push gitea main ✅)
+
+**ADR-075 全部完成**（3 commits: 2cef209 → 561c1d8 → 1cb654c）：
+
+Phase 1（4 斷點修復）：
+- ✅ 斷點 A: decision_manager 提取 alert_category → send_approval_card
+- ✅ 斷點 B: send_approval_card 新增參數 → _build_inline_keyboard
+- ✅ 斷點 C: 互動型通知(TYPE-3/4/4D/8M)禁止發 SRE 群組
+- ✅ 斷點 D: k8s_workload → kubernetes + 6 新類按鈕組
+- ✅ classify_alert_early: 13 條規則，7 新分類，52 tests
+
+Phase 2（TYPE-8M）：
+- ✅ send_meta_alert() ⚙️ META SYSTEM 卡片
+- ✅ decision_manager TYPE-8M elif 分支
+
+CR 修補：
+- ✅ P0-2: NotificationType.TYPE_8M 加入 enum + classify_notification 早期回傳
+- ✅ P1-1: 移除 _CATEGORY_BUTTONS 死碼
+- ✅ P1-4: 測試 docstring 更新 13 條規則
+- 664 tests all pass
+
+**下一步**：ADR-075 Phase 3（Prometheus 規則），或評估下一個 ADR
+
+---
+
+## 📍 前次狀態 (2026-04-12 — 層次三+四全部完成，CD 推送中)

 **系統狀態**: ADR-073 Phase 1-4 ✅ | ADR-074 M1-M5 ✅ | ADR-073-C C1-C4 ✅ | git push gitea main ✅

--- a/docs/adr/ADR-075-telegram-notification-standard.md
+++ b/docs/adr/ADR-075-telegram-notification-standard.md
@@ -0,0 +1,159 @@
+# ADR-075：Telegram 告警通知格式標準化與完整流程修復
+
+> **狀態**: 🟡 批准實作中
+> **建立日期**: 2026-04-12（台北時間）
+> **決策者**: 統帥 ogt + Claude Sonnet 4.6
+> **相關 ADR**: ADR-071（四種通知類型）、ADR-073（飛輪修復）、ADR-074（監控補全）
+
+---
+
+## 背景
+
+ADR-071（2026-04-11）設計了 TYPE-1/2/3/4/4D 五種通知類型，並實作了 `classify_alert_early()`、`_build_inline_keyboard()` 等函數。但在 2026-04-12 的全面盤點中，發現整條資料流存在 **4 個斷點**，導致動態分類按鈕從未真正生效，所有 TYPE-3 告警一律 fallback 到通用的 [批准][拒絕][靜默] 三鍵。
+
+同時，在與 Gemini 的架構討論中，確認了 8 種通知類型矩陣（TYPE-1 到 TYPE-8M）以及雙頻道發送策略。
+
+---
+
+## 問題診斷：4 個斷點
+
+```
+斷點 A：decision_manager._push_decision_to_telegram()
+         呼叫 send_approval_card() 時沒有傳入 alert_category
+
+斷點 B：telegram_gateway.send_approval_card()
+         呼叫 _build_inline_keyboard() 時沒有傳入 alert_category/notification_type
+
+斷點 C：telegram_gateway._send_approval_card_to_group()
+         含 Callback Button 的 TYPE-3 卡片也發到 SRE 群組 → nonce 洩漏安全漏洞
+
+斷點 D：classify_alert_early() 輸出 "kubernetes"
+         但 _build_inline_keyboard 期待 "k8s_workload" → 永遠不命中
+         另有 10 個告警分類錯誤（host_resource/devops_tool/ssl_cert 等全落入 general）
+```
+
+---
+
+## 決策
+
+### D1：統一 Category 命名
+
+- `k8s_workload` → 改為 `kubernetes`（語義更廣，涵蓋 Node/Service/Ingress）
+- `Host*` 告警從 `infrastructure` 分離為 `host_resource`
+- `Docker*` 告警保留 `infrastructure`
+
+### D2：新增 7 個 Category
+
+| Category | 告警 | 說明 |
+|---------|------|------|
+| `alertchain_health` | AlertChainBroken_* / NoAlertsReceived2Hours / AlertChainUnhealthy | meta-monitoring，優先度最高 |
+| `flywheel_health` | AutoRepairLowSuccessRate / PermanentFixRequired / Flywheel* | 飛輪自身健康 |
+| `storage` | MinIODown | 物件儲存 |
+| `devops_tool` | GiteaDown / HarborDown / SignOzDown / OpenClawDown / SentryDown / AlertmanagerDown | DevOps 工具鏈 |
+| `external_site` | MoWoooWorkDown / TsenyangWebsiteDown / StockWoooWorkDown / BitanWoooWorkDown | 外部業務網站 |
+| `ssl_cert` | ExternalSiteSSL* / TLSCert* | SSL 憑證 |
+| `security_tool` | KaliScannerDown | 資安掃描工具 |
+
+### D3：8 種通知類型矩陣（完整版）
+
+| 類型 | 適用場景 | 按鈕 | 發送目標 |
+|-----|---------|------|---------|
+| TYPE-1 | 純資訊、備份成功、心跳 | 無 | SRE 群組 |
+| TYPE-2 | AI 自動修復完成 | 無（結果通知）| 個人 DM + 群組唯讀 |
+| TYPE-3 | 需人工審核（預設）| 依 category 動態 ≤4 個 | 個人 DM 只 |
+| TYPE-4 | AI 無法判斷 | [手動記錄][查面板][忽略] | 個人 DM 只 |
+| TYPE-4D | Config Drift | [查Diff][採納][回滾][忽略] | 個人 DM 只 |
+| TYPE-5S | 資安防禦（未來）| [隔離][封鎖IP][驅逐Pod][確認授權] | 個人 DM 只 |
+| TYPE-6B | 業務/FinOps（未來）| [暫停][查SignOz][忽略] | SRE 群組 |
+| TYPE-7E | 重大事故升級（未來）| [建立戰情室][Postmortem][DR手冊][確認接手] | 個人 DM + 群組 |
+| TYPE-8M | 飛輪/告警鏈路健康 | [觸發診斷][查看面板][靜默] | 個人 DM 只 |
+
+### D4：雙頻道路由規則
+
+```
+含 Callback Button → 只發個人 DM（@tsenyangbot）
+  TYPE-3 / TYPE-4 / TYPE-4D / TYPE-5S / TYPE-7E / TYPE-8M
+
+純資訊展示 → 只發 SRE 群組（-1003711974679）
+  TYPE-1 / TYPE-6B
+
+執行結果 → 兩個都發（群組版唯讀無按鈕）
+  TYPE-2
+
+（TYPE-7E 升級 → 兩個都發，群組版加 @mention）
+```
+
+### D5：Telegram 卡片格式防腐規則
+
+```python
+# telegram_gateway.py 頂部常數（ADR-075 鎖定）
+NOTIFICATION_TYPE_RULES = {
+    "TYPE-1":  "無按鈕，可有 URL Button，嚴禁 Callback Button",
+    "TYPE-2":  "無按鈕，可有 URL Button，嚴禁 Callback Button",
+    "TYPE-3":  "最多 4 個 Callback Button，依 alert_category 動態選擇",
+    "TYPE-4":  "固定 3 個按鈕：[手動記錄][查看面板][忽略]",
+    "TYPE-4D": "固定 4 個按鈕：[查看Diff][採納][回滾][忽略]",
+    "TYPE-5S": "固定 4 個按鈕：[隔離][封鎖IP][驅逐Pod][確認授權]",
+    "TYPE-6B": "最多 3 個按鈕：[暫停][查看SignOz][忽略]",
+    "TYPE-7E": "固定 4 個按鈕：[建立戰情室][Postmortem草稿][DR手冊][確認接手]",
+    "TYPE-8M": "固定 3 個按鈕：[觸發診斷][飛輪面板][靜默]",
+}
+```
+
+---
+
+## 實施計畫
+
+完整計畫書：`docs/superpowers/plans/2026-04-12-adr075-telegram-alert-notification.md`
+
+**Phase 1（斷點修復，同一 PR）**：
+- Task 1-2：重寫 `classify_alert_early()`（斷點 D）
+- Task 3：`_build_inline_keyboard` 字典對齊（斷點 D）
+- Task 4：`send_approval_card()` 接收並傳遞 `alert_category`（斷點 B）
+- Task 5：雙頻道路由修正（斷點 C）
+- Task 6：`decision_manager` 傳入 `alert_category`（斷點 A）
+
+**Phase 2（TYPE-8M 擴充）**：
+- Task 7-8：新增 `send_meta_alert()` + decision_manager 路由
+
+**Phase 3（Prometheus 規則，獨立）**：
+- Task 9：新增 6 個欠缺告警規則
+
+---
+
+## 驗收標準
+
+| 驗收項目 | 驗收方式 |
+|---------|---------|
+| HostHighCpuLoad 出現 [查程序][重啟服務][清Log] | 送測試告警驗收 |
+| KubePodCrashLooping 出現 [重啟][擴容][縮容][回滾] | 送測試告警驗收 |
+| AlertChainBroken_* 出現 [啟動緊急診斷] | 送測試告警驗收 |
+| TYPE-3 卡片不發 SRE 群組 | 確認群組無帶按鈕訊息 |
+| TYPE-1 卡片只發 SRE 群組 | 確認個人 DM 無純資訊通知 |
+| 全部單元測試通過 | pytest >620 passed |
+
+---
+
+## 範疇外（本 ADR 不包含）
+
+- TYPE-5S SecOps 卡片（待 SecOps Prometheus 規則完備後）
+- TYPE-6B Business 卡片（待 MomoScraper metrics 接入後）
+- TYPE-7E Escalation Monitor Service
+- FlywheelPlaybookZero 告警（依賴 ADR-074 Exporter）
+
+
+---
+
+## 實作記錄（2026-04-12）
+
+| Phase | Commit | 內容 |
+|-------|--------|------|
+| Phase 1 | 2cef209 | 4 斷點修復 + classify_alert_early 13 規則 + _CATEGORY_BUTTONS 更新 |
+| Phase 2 | 561c1d8 | send_meta_alert() + decision_manager TYPE-8M elif |
+| CR 修補 | 1cb654c | TYPE_8M 加入 enum + 死碼清理 + docstring 更新 |
+
+**測試覆蓋**：52 classify_alert_early tests + 664 total passed
+
+**CR 評分**：7/10（首席架構師審查通過，P0/P1 全修補）
+
+**Phase 3（Prometheus 規則）**：尚未實作，不阻擋 Phase 1/2 上線