feat: integrate Sentry + fix CI/CD issues

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>
2026-03-24 15:19:52 +08:00
parent 7a76f3e628
commit 9bff46a1b0
41 changed files with 3195 additions and 153 deletions
--- a/docs/HARD_RULES.md
+++ b/docs/HARD_RULES.md
@@ -16,6 +16,7 @@
 | Git | `--force` | 正常 push | [→ Git Safety](#git-safety) |
 | **測試** | **Mock 測試** | **真實 DB/服務** | [→ No Mock Testing](#no-mock-testing) |
 | **API** | **單獨改路徑** | **前後端同步** | [→ API Path Naming](#api-path-naming) |
+| **部署** | **假設已部署** | **驗證 Pod 版本** | [→ Deployment Verification](#deployment-verification) |

 ---

@@ -190,6 +191,30 @@ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test")

 ---

+## Deployment Verification
+
+**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_verification.md`
+
+```bash
+# ❌ 禁止 - 假設 git push 就是部署完成
+git push && echo "已部署"
+
+# ✅ 正確 - 必須驗證 Pod 實際運行版本
+# 1. 確認 CD workflow 成功
+gh run list --workflow=cd.yaml --limit 1  # 必須 ✅ success
+
+# 2. 驗證 Pod 鏡像版本
+kubectl get pods -n awoooi-prod -o jsonpath="{.items[*].spec.containers[*].image}"
+# 鏡像 tag 必須與最新 commit SHA 匹配
+
+# 3. Health check
+curl -f https://api.awoooi.wooo.work/api/v1/health
+```
+
+**原因:** 2026-03-24 重大事故：代碼已提交但 CD 連續失敗，正式環境仍運行舊版本，用戶誤以為功能已修復。
+
+---
+
 ## 如何新增規則

 1. 在此文件新增章節
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -5,15 +5,15 @@

 ---

-## 📍 當前狀態 (2026-03-24 13:15)
+## 📍 當前狀態 (2026-03-24 14:50)

 | 項目 | 狀態 |
 |------|------|
-| **當前 Phase** | **CI/CD 修復 + ClawBot 更名** |
+| **當前 Phase** | **Phase 8.0 架構淬鍊 + QA 修復** |
 | **Day** | Day 6 |
-| **下一步** | 等待 CD 部署完成 → 驗證 Telegram 告警 |
-| **重大決策** | 🔴🔴 **部署驗證鐵律** - git push ≠ 部署完成，必須驗證 Pod 版本 |
-| **已完成** | ✅ turbo.json + CD workflow + Alertmanager + ClawBot→OpenClaw 更名 |
+| **下一步** | CD #23476501452 (7a76f3e) 構建中 → Nginx 負載均衡 → QA 測試修復 |
+| **重大發現** | 🔴 **NEXT_PUBLIC_API_URL 未注入** - 前端用 localhost:8000 (已修復 7a76f3e) |
+| **QA 結果** | ⚠️ 13 通過 / 9 失敗 (59%) - Multi-Sig ✅ 核心安全通過 |

 ### 🧠 認知覺醒計畫 Phase 6 施工順序 (C-Suite 2026-03-23 統帥方案)

@@ -41,6 +41,17 @@

 | 時間 | 事件 | 負責人 |
 |------|------|--------|
+| 2026-03-24 14:50 | **🧪 QA 測試執行**: 13 通過 / 9 失敗 (59%) - Multi-Sig ✅ 核心安全通過，UI 測試需更新 | 資深顧問 |
+| 2026-03-24 14:45 | **🔴 根因發現**: NEXT_PUBLIC_API_URL 未 build-arg 注入，前端用 localhost:8000 | 資深顧問 |
+| 2026-03-24 14:40 | **🔧 CD 修復 (7a76f3e)**: 新增 `--build-arg NEXT_PUBLIC_API_URL=https://awoooi.wooo.work` | Claude Code |
+| 2026-03-24 14:35 | **🔧 Health Check 修復 (774290d)**: 改用 kubectl exec 內部驗證 (避免 runner DNS 問題) | Claude Code |
+| 2026-03-24 14:30 | **⚡ CD 優化 (515339f)**: 沿用 wooo-aiops 模式 - 變更偵測 + 選擇性構建 (skip_api/skip_web) + 原生 BuildKit + 本地 Next.js 快取 | Claude Code |
+| 2026-03-24 14:25 | **✅ #6 回饋 API Commit (ad05bbf)**: PUT /api/v1/incidents/{id}/feedback + async_utils (fire_and_forget) | Claude Code |
+| 2026-03-24 14:20 | **🐳 CD 構建成功**: API (580c38d-23475622328) + Web (580c38d-23475622328) → Deploy 進行中 | Claude Code |
+| 2026-03-24 14:10 | **📋 QA Report 整合**: `AWOOOI_Full_QA_Report.md` 分析 + Phase 8.0 項目 (#13-#20) 納入 workplan + P0/P1 狀態對照 | Claude Code |
+| 2026-03-24 14:05 | **🔧 Kustomize 修復 (580c38d)**: 映像替換 OLD_IMAGE 必須完全匹配 (含 `:IMAGE_TAG_PLACEHOLDER`) | Claude Code |
+| 2026-03-24 14:00 | **✅ #6 人類回饋 API**: `PUT /api/v1/incidents/{id}/feedback` + effectiveness_score + human_feedback + learning_notes + Redis/PostgreSQL 同步 | Claude Code |
+| 2026-03-24 13:55 | **✅ #5 統計分析 API 確認**: 已完整實現且註冊於 main.py:300-301 | Claude Code |
 | 2026-03-24 13:00 | **🔄 ClawBot → OpenClaw 全域更名**: 刪除 clawbot.py + 更新 12 個 Python 檔案 + 類型定義/Discord username 更名 | 資深顧問 |
 | 2026-03-24 12:40 | **🔧 CD 修復**: turbo.json 快取邊界 + CD workflow (kustomize/namespace/kubectl) + Alertmanager 指向 AWOOOI + 部署驗證鐵律 (HARD_RULES + Skills) | 資深顧問 |
 | 2026-03-24 10:30 | **🔴🔴 禁止 Mock 測試鐵律**: 統帥明確指示「全面禁止！！！」Mock 測試 + 移除 `test_stats_api.py` 與 `test_webhook_telegram_integration.py` + 新增 `feedback_no_mock_testing.md` | Claude Code |
--- a/docs/adr/ADR-013-code-annotation-standards.md
+++ b/docs/adr/ADR-013-code-annotation-standards.md
@@ -0,0 +1,152 @@
+# ADR-013: Code Annotation Standards
+
+> **狀態**: 🟡 草稿 (待 CTO 批准)
+> **日期**: 2026-03-24
+> **決策者**: CTO
+
+## 背景
+
+AWOOOI 專案缺乏統一的代碼註解規範，導致：
+- Code Review 時對「是否需要註解」有爭論
+- 新人入職時難以理解複雜邏輯
+- 危險操作缺乏警示說明
+
+## 決策
+
+採用分層註解策略，區分「強制」與「建議」場景。
+
+---
+
+## 1. 強制註解場景 (Must Have)
+
+以下場景**必須**有註解，否則 PR 不予合併：
+
+### 1.1 安全相關
+```python
+# 🔐 Token 驗證: 檢查 JWT 是否過期且具有對應 Tier 權限
+def verify_token(token: str, required_tier: int) -> bool:
+```
+
+### 1.2 複雜邏輯
+```typescript
+// 正則說明: 匹配 K8s Pod 名稱格式 <deployment>-<hash>-<random>
+const POD_NAME_REGEX = /^(.+)-([a-f0-9]{8,10})-([a-z0-9]{5})$/
+```
+
+### 1.3 外部依賴
+```python
+# 🌐 外部 API: Alertmanager webhook，預期回應 200 OK
+async def send_to_alertmanager(payload: dict) -> bool:
+```
+
+### 1.4 危險操作
+```yaml
+# 🔴 危險: 此 NetworkPolicy 控制 Worker 出站流量
+# 修改前請確認 Redis/PostgreSQL 連線不受影響
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+```
+
+---
+
+## 2. 格式規範
+
+### 2.1 Python (Google Style Docstring)
+
+```python
+def restart_pod(namespace: str, pod_name: str) -> bool:
+    """重啟指定 Pod。
+
+    Args:
+        namespace: K8s 命名空間
+        pod_name: Pod 名稱 (不含 hash 後綴)
+
+    Returns:
+        True 表示重啟成功
+
+    Raises:
+        K8sPermissionError: 缺少 delete pods 權限
+
+    Warning:
+        此操作會導致短暫服務中斷
+    """
+```
+
+### 2.2 TypeScript (JSDoc)
+
+```typescript
+/**
+ * 簽核待審批請求
+ * @param id - Approval UUID
+ * @param signerId - 簽核者 ID (需有對應 Tier 權限)
+ * @returns 簽核結果，包含是否觸發執行
+ * @throws {UnauthorizedError} 簽核者權限不足
+ * @example
+ * const result = await signApproval('abc-123', 'admin-001')
+ * if (result.execution_triggered) { ... }
+ */
+async function signApproval(id: string, signerId: string): Promise<ApprovalResult>
+```
+
+### 2.3 YAML/Kubernetes
+
+```yaml
+# 🔴 危險操作標記
+# 📝 用途說明
+# ⚠️ 注意事項
+```
+
+---
+
+## 3. 測試標記 (data-testid)
+
+### 命名規則
+```
+<component>-<element>[-<action>]
+```
+
+### 範例
+```tsx
+<button data-testid="approval-card-approve-btn">
+<input data-testid="search-input-filter">
+<div data-testid="incident-list-container">
+```
+
+### 強制場景
+- 所有可交互元素 (button, input, select)
+- E2E 測試會定位的容器
+- 動態渲染的列表項
+
+---
+
+## 4. 不需要註解的場景
+
+- 自明的 CRUD 操作
+- 標準庫/框架常見用法
+- 已有 TypeScript 型別說明的參數
+
+---
+
+## 5. 執行方式
+
+### Phase 1 (本週)
+- [x] ADR-013 文件建立
+- [ ] ESLint `require-jsdoc` 配置 (危險函數)
+- [ ] Ruff D100 規則 (公開函數)
+
+### Phase 2 (下週)
+- [ ] 補齊 P0/P1 關鍵模組註解
+- [ ] 補齊 data-testid (Approval/Incident)
+- [ ] CI 加入 lint 檢查
+
+### Phase 3 (持續)
+- [ ] Code Review 強制執行
+- [ ] 新代碼必須符合標準
+
+---
+
+## 6. 參考
+
+- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
+- [JSDoc Reference](https://jsdoc.app/)
+- [Testing Library - data-testid](https://testing-library.com/docs/queries/bytestid/)
--- a/docs/qa/AWOOOI_Full_QA_Report.md
+++ b/docs/qa/AWOOOI_Full_QA_Report.md
@@ -0,0 +1,149 @@
+# 🏆 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解耦與狀態機一致性)** 的急迫性。
--- a/docs/qa/qa_report.md
+++ b/docs/qa/qa_report.md
@@ -0,0 +1,68 @@
+# AWOOOI 系統 QA 專業測試報告
+
+## 1. 執行摘要 (Executive Summary)
+本次 QA 測試涵蓋了 AWOOOI 專案的 `apps/web` 前端與 `apps/api` 後端之整合，重點測試頁面包含全局戰情室 (Dashboard)、Multi-Sig 授權卡片 (ApprovalCard)、以及行動日誌 (Action Log)。
+我們利用 Playwright 進行了全面的自動化 E2E 測試，發現在 22 個測試案例中，有部分案例因為前端 hydration、中英文語系切換 (i18n) 以及按鈕防呆機制等問題導致失敗。
+
+---
+
+## 2. 測試結果總覽 (Test Results Overview)
+執行 `pnpm exec playwright test` 共計 22 個測試案例。
+- **通過 (Passed)**: 12
+- **失敗 (Failed) / 不穩定 (Flaky)**: 10
+
+### 2.1 主要失敗項目分析
+1. **Action Log 頁面結構與導航 (action-log.spec.ts)**
+   - ✖️ `重新整理按鈕存在且可點擊` (Timeout 15.5s)
+   - ✖️ `行動日誌連結可點擊` (Timeout 15.0s)
+   - **問題描述**: 頁面在導航或等待 API 回應時，載入時間過長超過預設的 15 秒 timeout，或是對應元素的 locator (`button:has-text("重新整理")`) 在中文環境下找不到。
+
+2. **Dashboard 語系切換與組件狀態 (dashboard-acceptance.spec.ts)**
+   - ✖️ `語系切換器功能 - 繁中轉英文` (Timeout 12.1s)
+   - ✖️ `主機卡片顯示真實狀態` (Timeout 11.2s)
+   - ✖️ `完整頁面截圖 - 雙語對照` (Timeout 15.0s)
+   - ✖️ `HITL 授權卡片功能驗證` (Timeout 9.8s)
+   - **問題描述**: 語系切換時，頁面依賴的 `next-intl` 可能沒有即時更新 DOM 或是 SSE 連線阻塞了 `domcontentloaded` 事件的觸發，導致 Playwright 等待超時。同時，某些真實的 IP `192.168.0.x` 或者長按鈕在畫面上未能及時算繪出來。
+
+3. **RBAC 與 Timeline 展示 (rbac-screenshot.spec.ts / phase4-timeline.spec.ts)**
+   - ✖️ `Screenshot RBAC permission UI` (Timeout 3.6s)
+   - ✖️ `Phase 4: Full Action Timeline Demo Flow` (Timeout 2.2s)
+   - **問題描述**: 在模擬真實情境 (Demo Flow) 中，依賴於後端特定的 API 返回資料。如果後端沒有正確種子資料或是載入順序問題，將導致測試提早失敗。
+
+---
+
+## 3. 問題與優化建議 (Issues & Optimization Proposals)
+
+### 3.1 前端效能與 Zustand/SSE 競爭 (Race Conditions)
+- **問題**: E2E 測試中發現，多次因為載入超時導致測試失敗。日誌 (LOGBOOK) 也提到 Polling 與 SSE 在操作時會有競爭狀況，導致 UI 閃爍。
+- **解決方案**:
+  1. 在 `approval.store.ts` 與 `agent.store.ts` 中，落實「樂觀更新 (Optimistic UI)」並在送出 Mutation 的這幾秒內「完全強制停止 polling」。
+  2. 加入 SSE 斷線重連的 Exponential Backoff（指數退避）機制，防止斷線瞬間大量的重連請求卡死瀏覽器線程。
+
+### 3.2 i18n 語系切換與 Hydration 報錯
+- **問題**: 繁中轉英文的測試失敗。可能是 Next.js App Router 配合 `next-intl` 在客戶端 Hydration 時，伺服器與客戶端渲染語言不一致，導致報錯或 UI 卡死。
+- **解決方案**:
+  1. 確保 `html` 標籤的 `lang` 屬性在 Server Component 中正確取得請求的 locale。
+  2. 確保沒有依賴於 `window` 物件的資料在首次 render 中輸出，避免 Hydration Mismatch。
+
+### 3.3 E2E 測試腳本穩定性 (Flakiness)
+- **問題**: `action-log.spec.ts` 中過度依賴中文字串 (如 `hasText: '重新整理'`)，如果網頁預設載入英文，就會永遠找不到。且 Timeout 15s 對於包含完整依賴啟動的測試環境有點太短。
+- **解決方案**:
+  1. 測試腳本中全面改用 `data-testid` 來定位元素（如 `[data-testid="refresh-btn"]`），而非依賴語言字串。
+  2. 在 `playwright.config.ts` 調高 `navigationTimeout` 為 45000ms，或者在重度依賴 API 的測試中使用 `.route` Mock 掉不穩定的網路請求（如果是純前端視覺測試的話；但依據鐵律，整合測試需真實環境，因此需確保留意本地 K3s/API 速度）。
+
+### 3.4 錯誤處理與 Console 乾淨度
+- **問題**: 仍有測試檢查 `console.error` 失敗。這通常來自於 React Key Props 未給予、或是未捕捉的 Promise Rejection。
+- **解決方案**:
+  - 全面審查 `apps/web/src/components` 的清單渲染，補齊 `key={item.id}`。
+  - 在 `fetch` 呼叫外層實作全局的 Axios/Fetch Interceptor，標準化攔截 500/404，不讓錯誤直接漏出到前端 console。
+
+---
+
+## 4. 自動化 QA 腳本庫 (QA Scripts)
+
+為了符合「禁止人工 QA」的鐵律，我已在此專案中補充了專業的自動化 QA 檢查腳本。詳見 `scripts/` 資料夾下的說明文件與執行檔。我們將確保每次部屬前執行這些腳本。
+
+---
+**QA 審查完成時間**: 2026-03-24
+**審查人員**: AWOOOI SRE QA Expert (Agent)