awoooi/docs/adr/ADR-035-telegram-alert-chain-enforcement.md

# ADR-035: Telegram 告警鏈路強制驗證

> **狀態**: 已批准
> **建立日期**: 2026-03-29 (台北時間)
> **建立者**: Claude Code (首席架構師)
> **觸發事故**: 2026-03-29 Telegram 告警失效 (K8s Secrets 未注入)

---

## 1. 問題背景

### 1.1 事故時間線

| 日期 | 事件 | 影響 |
|------|------|------|
| 2026-03-23 | Telegram Token 災難 (logOut) | Token 永久失效 |
| 2026-03-26 | Alertmanager 路徑錯誤 | 2 天無告警 |
| **2026-03-29** | **K8s Secrets 未注入** | **長時間無告警** |

### 1.2 根本原因

1. **CD workflow 未自動注入 K8s Secrets**
   - `kustomization.yaml` 註釋說「secrets 由 CI/CD 單獨處理」
   - 但 CD 實際上沒有處理
   - 導致 `OPENCLAW_TG_BOT_TOKEN` 保持為模板值 `"CHANGE_ME"`

2. **缺乏 E2E 驗證機制**
   - 部署後沒有驗證告警鏈路是否正常
   - 問題可能數天後才被發現

3. **Memory 鐵律未完整執行**
   - 已有 `feedback_alertchain_e2e_validation.md` 記錄
   - 但 CD workflow 沒有實際實施驗證

---

## 2. 決策

### 2.1 CD Secrets 自動注入 (強制)

每次部署 **必須** 同步 K8s Secrets：

```yaml
- name: "Sync K8s Secrets (ADR-035)"
  run: |
    kubectl patch secret awoooi-secrets -n awoooi-prod --type='merge' -p="{
      \"stringData\": {
        \"OPENCLAW_TG_BOT_TOKEN\": \"${{ secrets.OPENCLAW_TG_BOT_TOKEN }}\",
        \"OPENCLAW_TG_CHAT_ID\": \"${{ secrets.OPENCLAW_TG_CHAT_ID }}\"
      }
    }"
```

### 2.2 Pre-flight Secrets 檢查 (強制)

部署前 **必須** 驗證 Telegram Secrets 存在：

```yaml
- name: "Check Required Secrets"
  run: |
    if [ -z "${{ secrets.OPENCLAW_TG_BOT_TOKEN }}" ]; then
      echo "❌ 缺少 OPENCLAW_TG_BOT_TOKEN"
      exit 1
    fi
```

### 2.3 部署後 E2E 驗證 (強制)

部署完成後 **必須** 發送測試告警驗證：

```yaml
- name: "Verify Telegram Alert Chain (ADR-035)"
  run: |
    # 發送測試告警
    # 驗證 API 回應 success: true
    # 失敗則直接發送告警到 Telegram
```

---

## 3. 實施檢查清單

### 3.1 CD Workflow 修改

| 項目 | 狀態 | 檔案 |
|------|:----:|------|
| Pre-flight Secrets 檢查 | ✅ | `.github/workflows/cd.yaml` |
| K8s Secrets 自動注入 | ✅ | `.github/workflows/cd.yaml` |
| 部署後 E2E 驗證 | ✅ | `.github/workflows/cd.yaml` |

### 3.2 GitHub Secrets 必要項目

| Secret 名稱 | 用途 | 必須 |
|-------------|------|:----:|
| `OPENCLAW_TG_BOT_TOKEN` | Telegram Bot Token | 🔴 是 |
| `OPENCLAW_TG_CHAT_ID` | Telegram Chat ID | 🔴 是 |
| `DATABASE_URL` | PostgreSQL 連線 | 🔴 是 |
| `REDIS_URL` | Redis 連線 | 🔴 是 |
| `SENTRY_DSN` | Sentry 錯誤追蹤 | 🟡 建議 |

### 3.3 Memory/文檔更新

| 項目 | 狀態 | 檔案 |
|------|:----:|------|
| ADR-035 | ✅ | `docs/adr/ADR-035-*.md` |
| Feedback Memory | ✅ | `feedback_telegram_secrets_injection.md` |
| CLAUDE.md 規則 | ✅ | `CLAUDE.md` |
| Skills 更新 | ✅ | `.agents/skills/04-awoooi-devops-commander.md` |

---

## 4. 防止再次發生

### 4.1 自動化防護層

```
┌─────────────────────────────────────────────────────────────────┐
│                     告警鏈路防護機制                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Layer 1: Pre-flight                                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ GitHub Secrets 存在性檢查                                │    │
│  │ - OPENCLAW_TG_BOT_TOKEN 必須存在                        │    │
│  │ - 缺少則 CI 失敗 (exit 1)                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                              ▼                                   │
│  Layer 2: Deploy                                                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ K8s Secrets 自動注入                                     │    │
│  │ - 每次部署都 patch secret                               │    │
│  │ - 確保 Token 永遠是最新的                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│                              ▼                                   │
│  Layer 3: Post-Deploy                                           │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ E2E 驗證 (實際發送測試告警)                              │    │
│  │ - 發送測試告警到 API                                    │    │
│  │ - 驗證回應 success: true                                │    │
│  │ - 失敗則繞過 API 直接告警                               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 4.2 Claude Code 強制規則

修改 CLAUDE.md 或 CD workflow 時 **必須**：

1. 確保 `Sync K8s Secrets` 步驟存在
2. 確保 `Verify Telegram Alert Chain` 步驟存在
3. 確保所有 Telegram Secrets 在 Pre-flight 中檢查

---

## 5. 相關文件

- [feedback_alertchain_e2e_validation.md](../../.claude/projects/-Users-ogt-awoooi/memory/feedback_alertchain_e2e_validation.md)
- [feedback_telegram_token_disaster.md](../../.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_token_disaster.md)
- [feedback_telegram_secrets_injection.md](../../.claude/projects/-Users-ogt-awoooi/memory/feedback_telegram_secrets_injection.md)

---

**審查者**: 統帥 (待簽核)
**生效日期**: 2026-03-29