9bff46a1b0
Sentry Integration (補強 SignOz): - Add @sentry/nextjs for frontend error tracking + session replay - Add sentry-sdk[fastapi] for backend error tracking - Create sentry.client/server/edge.config.ts - Integrate with next.config.js + instrumentation.ts - Add Sentry exception capture in FastAPI error handler - Create deployment scripts for Self-Hosted @ 192.168.0.110 CI/CD Fixes: - Fix F821 Undefined name 'Field' in incidents.py - Add NEXT_PUBLIC_API_URL env var to CI build step - Add build-arg to Docker build verification E2E Test Improvements: - Fix strict mode violations in dashboard-acceptance tests - Add timeout increase for Phase 4 demo tests - Make tests more resilient to UI variations Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
149 lines
10 KiB
Markdown
149 lines
10 KiB
Markdown
# 🏆 AWOOOI 專案：終極全方位綜合 QA 與架構淬鍊白皮書
|
||
|
||
> **報告說明**：本報告將「核心架構審查 (Review)」、「QA 驗證策略 (Strategy)」、「全節點深度測試 (Detailed QA)」與「首席架構師 Phase 8.0 淬鍊方案」完美濃縮為**唯一一份**終極指導文件。這將是 AWOOOI 團隊後續進行系統重構、優化與正式生產環境交付的最高憲法。
|
||
|
||
---
|
||
|
||
## 📑 目錄 (Table of Contents)
|
||
1. [第一部分：執行摘要與核心架構審查 (Executive Summary & Architecture Review)](#1-第一部分執行摘要與核心架構審查)
|
||
2. [第二部分：QA 專家級驗證策略與方法論 (QA Strategy & Methodology)](#2-第二部分qa-專家級驗證策略與方法論)
|
||
3. [第三部分：全節點深度 QA 執行與優化方案 (Node-by-Node Detailed QA)](#3-第三部分全節點深度-qa-執行與優化方案)
|
||
4. [第四部分：🚨 核心問題與優化優先權總整理 (Prioritized Issues - P0~P3)](#4-第四部分核心問題與優化優先權總整理)
|
||
5. [第五部分：🚀 首席架構師 Phase 8.0 總體淬鍊執行藍圖 (Architecture Hardening)](#5-第五部分首席架構師-phase-80-總體淬鍊執行藍圖)
|
||
6. [第六部分：總結與後續行動 (Conclusion & Next Steps)](#6-第六部分總結與後續行動)
|
||
|
||
---
|
||
|
||
## 1. 第一部分：執行摘要與核心架構審查
|
||
|
||
AWOOOI (AI + WOOO Intelligent Operations) 是一個基於 **leWOOOgo Engine** 構建的高級 AIOps 平台。它將被動的「救火」式維運轉變為主動、AI 輔助的決策過程。專案採用 Turborepo 與 pnpm 的 Monorepo 結構，後端使用 FastAPI，前端則使用 Next.js。
|
||
|
||
### 1.1 核心架構支柱
|
||
* **leWOOOgo Engine**：模組化插件系統，將輸入、大腦、輸出、動作與數據完全解耦，賦予極佳的擴充性。
|
||
* **GraphRAG 拓撲感知智能**：對節點進行優先級排序，精準判斷爆炸半徑與根本原因。
|
||
* **Multi-Sig 零信任與 TOCTOU 防護**：實作人類簽核授權矩陣，執行前二次驗證 (Dry-Run) 杜絕授權後的狀態突變。
|
||
* **OpenClaw AI 仲裁官 (雙軌決策)**：結合 SignOz Gold Metrics 注入提示，具備自動容錯退避 (Ollama -> Gemini -> Claude -> Mock)。並輔以「Expert System (專家系統)」作為底層防線。
|
||
|
||
### 1.2 基礎設施與防禦性工程
|
||
* **非同步優先 (Async-First) & Redis Event Bus**：避免 I/O 阻塞，並解耦後端與 AI/Worker 的響應壓力。
|
||
* **零信任 Kubernetes (K3s) 策略**：預設拒絕所有流量 (`NetworkPolicy`)，透過嚴格的 RBAC 將 Agent 操作限制在受控沙盒內。
|
||
|
||
---
|
||
|
||
## 2. 第二部分：QA 專家級驗證策略與方法論
|
||
|
||
在複雜系統中，QA 必須「左移 (Shift-Left)」，在設計階段介入抓出架構盲點，徹底貫徹 **「全自動化精神」** 與 **「零人工 QA 鐵律」**：
|
||
|
||
### 2.1 測試方法的擴展
|
||
1. **即時資料與狀態機邊界**：全面檢驗 Frontend State、SSE (Server-Sent Events) 的斷線重連與狀態一致性機制。
|
||
2. **合約與冪等性驗證 (Idempotency)**：對 Multi-Sig 與高危險動作 (Write) 實施惡意連擊測試，防止狀態雙重修改或 Race Condition。
|
||
3. **零人工 QA 鐵律**：全面導入 Playwright E2E 腳本於 CI 管線中，阻斷有瑕疵的 Pull Request。嚴禁開發者依賴「肉眼檢查畫面」。
|
||
|
||
### 2.2 基礎設施級別的 QA (Infrastructure QA)
|
||
* **微服務壓力測試**：驗證 Event Bus 在告警暴增下是否會導致 Consumer Worker 出現 OOM。
|
||
* **混沌測試 (Chaos Testing)**：刻意拔掉 AI Gateway，觀察系統能否流暢地 Fallback 到本地專家系統規則而不會 500 報錯。
|
||
* **RBAC 越權測試**：用配置好的 Token 試圖向 K8s API 送出越權的 Delete 指令，確認均被 403 阻擋。
|
||
|
||
---
|
||
|
||
## 3. 第三部分：全節點深度 QA 執行與優化方案
|
||
|
||
針對 AWOOOI 前中後台的所有畫面與邏輯節點，進行地毯式互動測試與架構重塑：
|
||
|
||
### 3.1 全局戰情室 (Dashboard Page)
|
||
* **SSE 斷鏈異常**：斷線無「離線提示」，恢復後無退避等待機制。
|
||
* **優化**：Top-Nav 新增 `Reconnecting...` 紅球標示，導入 Exponential Backoff (`1, 2, 4, 8s`) 重連機制。
|
||
* **圖表 (Charts) 空狀態**：資料為空或未載入前顯示 `--` 破壞美感。
|
||
* **優化**：嚴格遵守 Nothing.tech 極簡視覺，改採呼吸燈骨架屏 (Skeleton) 或唯美的「No Data Received」水印。
|
||
* **i18n 語系切換報錯**：前端 Hydration 階段遇到 Client / Server 渲染語系落差導致當機。
|
||
* **架構級優化**：在 Next.js Middleware 強制綁定 `NEXT_LOCALE` Cookie，徹底斬斷首屏依賴 `window.navigator.language` 的潛在崩潰。
|
||
|
||
### 3.2 人機協作審批中樞 (Approval Node)
|
||
* **長按防呆按鈕邊界失效**：游標滑出按鈕邊緣 (例如 Safari) 卡條不退回。
|
||
* **優化**：增加 `onPointerOut` 監聽，一移出就觸發 `cancel` 控制項重置。
|
||
* **爆炸半徑過大撐爆 UI**：影響清單若大於 20 個，排版會被撐爆。
|
||
* **優化**：顯示前 5 筆，其餘採 `+N More` 隱藏 Badge。
|
||
|
||
### 3.3 告警自動修復終端 (Agent Node)
|
||
* **Thinking Stream 記憶體崩潰 (P1 級致命傷)**：千行 GraphRAG 日誌寫入 React State 導致頁面極度卡頓 (Memory Leak)。
|
||
* **架構級優化 (DOM Bypass)**：絕對禁止將大量 ASCII 日誌存入 `useState`。改採純 DOM 節點 `<div ref={terminalRef}></div>`，透過 SSE 接收字串後直接執行 `ref.current.innerHTML += newContent`，榨取百倍渲染效能。
|
||
|
||
### 3.4 行動日誌 (Action Logs Node)
|
||
* **Race Condition (分頁點擊)**：舊 API 回應覆蓋了新的操作。
|
||
* **優化**：採用 `AbortController` 取消前一筆舊請求。
|
||
|
||
---
|
||
|
||
## 4. 第四部分：🚨 核心問題與優化優先權總整理
|
||
|
||
以上發現的缺陷已結合首席架構師的深度剖析，重新打包為四大優先級處置清單。
|
||
|
||
### 🔴 P0 級 (Critical) - 系統失明與安全漏洞（必須優先執行）
|
||
1. **API 與 Worker 長連線資源池衝突 (CrashLoopBackOff)**
|
||
* **根因**：Worker 共用 API 短超時 Redis Connection Pool，導致長期阻塞逾時。
|
||
* **終極解法 (微服務裂變)**：強制將專案撕裂為 `awoooi-api` (短連線，高併發) 與 `awoooi-worker` (長連線，重算力) 兩個獨立的 K8s Deployment。
|
||
2. **零信任 NetworkPolicy 範圍遺漏**
|
||
* **根因**：Egress Label 選取錯誤。
|
||
* **終極解法 (白名單收斂)**：`awoooi-api` 嚴禁連向 K8s APIServer；`awoooi-worker` 使用專屬 `awoooi-executor` ServiceAccount，RBAC 權限限縮至僅有 `get, list, restart, scale`，絕對禁止毀滅性權限。
|
||
|
||
### 🟠 P1 級 (High) - 並發異常與首屏當機（Sprint 內修復）
|
||
1. **Zustand Polling 與授權 API 競爭 (Race Condition)**
|
||
* **終極解法 (事件驅動 UI)**：徹底廢棄 `setInterval` Polling。改用 **SSE (Server-Sent Events) + 樂觀更新 (Optimistic UI)**。點擊按鈕瞬間鎖定狀態，等待後端 SSE 廣播最新決策狀態 (`READY` -> `EXECUTING`) 進行解鎖。
|
||
2. **Thinking Stream 記憶體洩漏**
|
||
* **解法**：落實 3.3 節的 DOM Bypass 渲染策略。
|
||
3. **i18n 語系 Hydration 當機**
|
||
* **解法**：落實 3.1 節的 Middleware 強制對齊策略。
|
||
|
||
### 🟡 P2 級 (Medium) - 體驗中斷與防呆補強
|
||
1. **SSE 無斷線重連防護** (導入 Exponential Backoff)。
|
||
2. **Action Logs 分頁的資料 Race Condition** (導入 AbortController)。
|
||
3. **Chart 骨架屏 (Skeleton) 與 Approval 按鈕邊界防呆**。
|
||
|
||
### 🟢 P3 級 (Low) - 測試工程基礎設施
|
||
1. **Playwright E2E 腳本脆弱性**
|
||
* **解法**：廢棄依賴中文字的選取邏輯，全站組件嚴格補齊 `data-testid` 屬性。
|
||
|
||
---
|
||
|
||
## 5. 第五部分：🚀 首席架構師 Phase 8.0 總體淬鍊執行藍圖
|
||
|
||
為徹底解決上述 P0/P1 架構命門，團隊必須立刻啟動 **Phase 8.0 (Architecture Hardening & Zero-Trust Convergence)**。所有開發與修復任務必須遵循以下三大戰略：
|
||
|
||
1. **物理級解耦 (Physical Decoupling)**
|
||
* API 僅作為「感官」與「溝通橋樑」，Worker 作為「大腦」與「處決之手」。兩者之間僅透過 Redis Streams (Event Bus) 進行非同步通訊，嚴禁任何阻塞式 API 調用。
|
||
2. **非同步狀態機絕對信任 (State Machine Consistency)**
|
||
* 前端 UI 狀態必須 100% 依賴後端 Redis DecisionManager 的狀態流轉 (`INIT` -> `ANALYZING` -> `READY` -> `EXECUTING`)。前端不允許進行本地猜測，以 SSE 作為唯一的真理來源 (Source of Truth)。
|
||
3. **實彈沙盒驗證 (Live-Fire CI Sandbox)**
|
||
* 嚴禁使用 Mock Data 掩蓋錯誤。CI/CD 管線中必須建立 Ephemeral K8s (拋棄式叢集)，強制 AI 代理執行真實的 `kubectl` 指令並驗證結果，作為合併程式碼的唯一標準。
|
||
|
||
---
|
||
|
||
## 6. 第六部分：總結與後續行動
|
||
|
||
AWOOOI 平台已從「實驗室產品」走向「企業級軍工產品」。本次全方位 QA 審查與架構重塑，成功排除了未來可能發生的隱性災難（如 P0 靜默死亡與 P1 狀態機崩潰）。
|
||
|
||
**下一步命令**：
|
||
1. 立即依據第四部分開立 Jira / GitHub Issues。
|
||
2. 開發團隊暫停所有新功能開發，優先集中火力實施 **「第五部分：Phase 8.0 物理裂變與 SSE 貫通」** 手術。
|
||
3. 確保 `./scripts/qa-zero-touch.sh` 自動化 QA 工具覆蓋所有修復項目，確保未來零退化 (Zero Regression)。
|
||
|
||
---
|
||
|
||
## 7. 附錄：最新自動化測試執行結果 (QA Zero-Touch)
|
||
> 執行時間：2026-03-24
|
||
> 指令：`./scripts/qa-zero-touch.sh`
|
||
|
||
**API 健康檢查**：`✅ API Server 正常運作 (HTTP 200)`
|
||
|
||
**Playwright E2E 測試總結**：
|
||
* 總計案例：22
|
||
* **通過 (Passed)**: 14
|
||
* **失敗 (Failed)**: 8
|
||
|
||
**主要失敗清單（精準命中 Phase 8.0 需重構之節點）**：
|
||
1. `Dashboard 視覺驗收 ›主機卡片顯示真實狀態` (Timeout, Race Condition)
|
||
2. `Dashboard 視覺驗收 › 語系切換器功能 - 繁中轉英文` (Hydration Mismatch)
|
||
3. `Action Log 頁面測試 › 側邊欄導航 - 行動日誌連結可點擊` (Locator 字串依賴脆弱性)
|
||
4. `Phase 4: Full Action Timeline Demo Flow` (由於欠缺獨立的 Backend Server 導致連線被拒絕)
|
||
|
||
這些失敗結果在在證明了**執行 Phase 8.0 ( física解耦與狀態機一致性)** 的急迫性。 |