awoooi/docs/adr/ADR-020-e2e-verification-framework.md

ADR-020: E2E 驗證框架規範

欄位	值
狀態	Accepted
建立日期	2026-03-26
決策者	首席架構師 (Claude Code)
相關 ADR	ADR-016 (K8s 資源命名), ADR-018 (LLM 測試)

---

背景

Phase 18 建立了完整的 E2E Tool Call 驗證流程：

• Alert → AI 分析 → Approval 建立 → 執行
• 需要標準化腳本規範，確保持續維護與擴展

決策

1. E2E 驗證腳本架構

apps/api/scripts/
├── e2e_tool_call_verification.py  # 主驗證腳本 (v2.0)
└── __init__.py                    # 模組入口

2. 驗證步驟標準

Step	名稱	驗證內容	超時
1	發送測試告警	Webhook 回應成功	120s
2	驗證 AI 分析	目標資源正規化、風險評估	60s
3	檢查 Approval 建立	ID 存在、狀態 pending	30s
4	動態簽署驗證	根據風險等級決定簽署數	60s
5	執行結果檢查	狀態更新、無錯誤	30s

3. Safe Label 防護

所有 E2E 測試告警必須包含：

{
  "labels": {
    "env": "e2e-test",
    "safe_mode": "true"
  }
}

執行層應檢測 safe_mode=true 並跳過實際 K8s 操作。

4. Daily Health Check 排程

欄位	值
Workflow	.github/workflows/daily-e2e-health.yaml
排程	每日 00:30 UTC (08:30 台北)
Runner	self-hosted (harbor, k8s)
失敗通知	Telegram (OPENCLAW_TG_*)

5. 目標資源驗證 (Phase 18.1)

E2E 腳本必須驗證 AI 產生的 kubectl 指令：

def verify_action_target(action: str, expected_resource: str) -> bool:
    """確保 AI 沒有殺錯人"""
    return expected_resource in action

後果

正面

• 自動化驗證完整 Tool Call 鏈路
• 早期發現 AI 產生無效指令
• 持續監控系統健康

負面

• 需維護測試腳本與 Daily Health Check workflow
• Telegram 通知依賴外部服務

相關檔案

檔案	功能
scripts/e2e_tool_call_verification.py	E2E 驗證腳本 v2.0
.github/workflows/daily-e2e-health.yaml	Daily Health Check
src/utils/k8s_naming.py	資源名稱正規化
ADR-016	K8s 資源命名契約

---

審查紀錄

日期	審查者	結果
2026-03-26	Claude Code	Accepted