awoooi/docs/ARCHITECTURE_CODE_REVIEW.md

AWOOOI 專案架構與程式碼審查報告 (Architecture & Code Review)

1. 專案總覽 (Project Overview)

AWOOOI 是一個由 AI 驅動的智能運維平台 (AI+WOOO Intelligent Operations Platform)，主打「Zero-Touch Ops. Human-Centric Decisions」。專案採用 Turborepo 建構的 Monorepo 架構，包含四大核心支柱：Privacy Shield (隱私保護)、GraphRAG (拓撲感知情報)、Multi-Sig & Dry-Run (多重簽核與防禦)、以及 Progressive Autonomy (漸進式自治)。

技術棧 (Tech Stack)

• Backend (apps/api): FastAPI, Python 3.11+, PostgreSQL, Redis, structlog, OpenTelemetry。
• Frontend (apps/web): Next.js 14, React 18, Tailwind CSS, Zustand, React-Query。
• Workspace: pnpm + Turborepo，抽出共用模組 @awoooi/lewooogo-core。

---

2. 核心架構審查 (Architecture Review)

2.1 Backend (leWOOOgo Engine)

API 服務設計為高度模組化的 BFF (Backend For Frontend) 架構，並嚴格遵循四大鐵律 (Async-First, CORS Whitelist, Pydantic Config, Structured Logging)。

• 可觀測性先行: 於 main.py 中，OpenTelemetry 的初始化被置於啟動流程與 Middleware 的最前方，確保 Request 全生命週期的追蹤，這是極其優秀的企業級實踐。
• 生命週期管理 (Lifespan): 妥善利用 FastAPI 的 @asynccontextmanager 來管理資料庫連線、HTTP Clients Pooling 以及 SSE Publisher 的啟動與優雅關閉 (Graceful Shutdown)，避免資源洩漏（Memory Leaks）。

2.2 Frontend (Web App)

• 狀態管理: 採用 zustand 進行元件外部的狀態管理 (agent.store.ts)，特別針對 Server-Sent Events (SSE) 實作了專屬的 Buffer 累積機制。這能有效防止 TCP 封包切斷導致後端流式輸出的 JSON 解析錯誤，這在串流顯示 AI 思考過程 (Thinking Stream) 時非常關鍵。
• 嚴謹的環境變數字典: 程式碼中 (如 getApiBaseUrl) 嚴格禁止了 Fallback IP 的濫用，強制拋出錯誤並依賴 NEXT_PUBLIC_API_URL，這確保了開發、測試與生產環境的絕對隔離。

---

3. 核心模組程式碼深潛審查 (Core Modules Deep Dive)

3.1 Multi-Sig Engine (approval.py)

• 亮點: 實作了極具資安意識的 TOCTOU (Time-of-Check to Time-of-Use) 防護。在收集完所有高權限使用者的簽章、準備真正執行指令前，系統會強制對目標資源再次呼叫 dry_run_engine.evaluate 來檢查狀態是否發生過偏移。
• 合規性稽核: 當發生 TOCTOU 衝突時，系統不會鴕鳥心態地直接清空簽章，而是將審批狀態明確標記為 VOIDED 並保留所有簽核歷史，完全符合金融與企業環境對資安稽核 (Audit Trail) 的要求。
• 設計模式: 採用清晰的 In-Memory 狀態機與 Strategy Pattern 來實作不同風險層級 (Risk Matrix) 的簽核門檻。

3.2 GraphRAG Engine (graph_rag.py)

• 亮點: 實作了強大且雙向的圖形遍歷演算法 (BFS-based traversal)。
  • Blast Radius (向上追溯): 準確計算「若特定服務掛掉，哪些上游服務將作為受災戶被連帶波及」。
  • Root Cause (向下追溯): 當服務報錯時，從異常節點往下找尋發生故障的根本原因，並具備優先權排序演算法 (DB > CACHE > QUEUE)。
• 效能考量: 演算法中引入了 max_depth 限制，防止在大型 Kubernetes 叢集中發生圖遍歷的無限遞迴擴散，顯示出高度的工程成熟度。

---

4. 總結與改進建議 (Conclusion & Recommendations)

AWOOOI 的整體程式碼品質極高，充分展現了「企業級系統」應有的嚴謹度，特別是在異常處理、資安防護與微服務架構解耦上做得很到位。

未來潛在改善點 (Tech Debt & Roadmap)：

1. 狀態持久化 (Persistence): 目前 MultiSigEngine 與 TopologyGraph 皆依賴 In-Memory (dict) 作為儲存。進入 Phase 4/5 生產環境硬化時，應盡快置換為 Redis (用於分散式鎖與簽核狀態共用) 與 Graph Database (如 Neo4j) 以應對多實例高可用部署 (Horizontal Scaling)。
2. 容錯與重試恢復 (Resilience): 在前端 SSE 串流部分，雖然處理了 AbortController 手動中斷，但可考慮加入對底層網路不穩時的自動重連機制與 Exponential Backoff 策略，進一步提升運維戰情室的體驗韌性。

---

5. 優化方案與解決策略 (Optimization Solutions)

5.1 問題與解決方案對照表

#	類別	問題	解決方案	優先級	規劃狀態
1	狀態持久化	MultiSigEngine 使用 In-Memory dict	改用 Redis 實作分散式鎖與簽核狀態共用	🔴 P0	⚪ Phase 6.1.1
2	狀態持久化	TopologyGraph 使用 In-Memory dict	導入 Neo4j / Redis Graph 支援多實例 HA	🔴 P0	⚪ Phase 6.1.2
3	容錯機制	SSE 串流無自動重連	加入 Exponential Backoff + Auto-Reconnect	🟡 P1	✅ ADR-004 已規劃
4	水平擴展	單實例限制	Redis 分散式鎖 + Sticky Session 或 Redis Pub/Sub	🟡 P1	⚪ Phase 6.3

備註: 第 3 項 SSE 容錯機制已在 ADR-004 定義完整規格 (Line 228-236)，待驗證實作狀態。

---

5.2 詳細解決方案 (Implementation Details)

5.2.1 Redis 狀態持久化 (Multi-Sig Engine)

# apps/api/src/services/multi_sig_redis.py
import redis.asyncio as redis
from pydantic import BaseModel
from datetime import datetime

class ApprovalState(BaseModel):
    request_id: str
    status: str  # PENDING | APPROVED | VOIDED
    signatures: list[dict]
    created_at: datetime

async def save_approval(r: redis.Redis, state: ApprovalState):
    key = f"approval:{state.request_id}"
    await r.hset(key, mapping=state.model_dump_json())
    await r.expire(key, 86400 * 7)  # 7 days TTL for audit

5.2.2 Neo4j 圖資料庫 (GraphRAG Engine)

# apps/api/src/services/graph_rag_neo4j.py
from neo4j import AsyncGraphDatabase

async def get_blast_radius(driver, service_id: str, max_depth: int = 5):
    query = """
    MATCH path = (s:Service {id: $service_id})<-[:DEPENDS_ON*1..$max_depth]-(affected)
    RETURN affected.id, length(path) as depth
    ORDER BY depth
    """
    async with driver.session() as session:
        result = await session.run(query, service_id=service_id, max_depth=max_depth)
        return [record async for record in result]

5.2.3 SSE 自動重連 + Exponential Backoff

// apps/web/src/hooks/useSSEReconnect.ts
import { useState, useCallback } from 'react';

export function useSSEWithReconnect(url: string) {
  const [retryCount, setRetryCount] = useState(0);
  const maxRetries = 5;

  const connect = useCallback(() => {
    const eventSource = new EventSource(url);

    eventSource.onerror = () => {
      eventSource.close();
      if (retryCount < maxRetries) {
        const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
        setTimeout(() => {
          setRetryCount(prev => prev + 1);
          connect();
        }, delay);
      }
    };

    eventSource.onopen = () => setRetryCount(0);
    return eventSource;
  }, [url, retryCount]);

  return { connect, retryCount };
}

---

5.3 實作優先順序 (Implementation Roadmap)

Phase	項目	預估工時	狀態	對應任務
Phase 6.1.1	Redis Multi-Sig 持久化	2 天	⚪ 規劃中	簽核狀態 + TTL 7d
Phase 6.1.2	Neo4j GraphRAG 遷移	3 天	⚪ 規劃中	Blast Radius 查詢
Phase 6.1.3	Redis 分散式鎖	1 天	⚪ 規劃中	Redlock 演算法
Phase 6.2	SSE 容錯驗證	1.5 天	✅ ADR-004	驗證 Backoff/Heartbeat
Phase 6.3	水平擴展	3 天	⚪ 規劃中	Redis Pub/Sub + Sticky Session

依賴: Phase 6 需等待 Phase 5 (OpenClaw 實體化) 完成後執行。

---

6. 審查結論 (Review Conclusion)

本次架構審查確認 AWOOOI 具備企業級系統的核心素質，主要技術債集中於 狀態持久化 與 水平擴展 兩大領域。

關鍵發現

類別	結論
SSE 容錯	✅ 已在 ADR-004 完整規劃，待驗證實作
狀態持久化	⚪ 新需求，已納入 Phase 6.1
水平擴展	⚪ 新需求，已納入 Phase 6.3

執行順序

Phase 5 (OpenClaw 實體化) → Phase 6 (架構硬化)
         ↓                          ↓
   Telegram Gateway         Redis + Neo4j + HA

審查日期: 2026-03-22 審查人員: Claude Code (Architecture Review Agent) 更新紀錄: Phase 6 任務已同步至 memory/project_phases.md