awoooi/docs/ARCHITECTURE_INVENTORY.md

AWOOOI 核心架構與程式碼最終盤點清單 (Core Architecture & Codebase Inventory)

專案名稱 (Project): AWOOOI 行動代號 (Operation): Operation Phoenix Rising (原 Cyber-Shell) 文件狀態 (Status): Active Development 建檔日期 (Date): 2026-03-19 (更新: 2026-03-20)

本文件記錄了 AWOOOI 系統從零到一的關鍵架構決策與防禦性實作（防雷紀錄），作為未來技術團隊接手、擴展與稽核的最高指導原則。 (This document records the key architectural decisions and defensive implementations of the AWOOOI system from zero to one, serving as the supreme guiding principle for future technical teams' handover, scaling, and auditing.)

---

Phase 0: Phoenix Rising (2026-03-20 戰略重構)

核心文檔與規範 (Core Documentation)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
API 開發 SOP docs/api/API_DEVELOPMENT_SOP.md	定義 Contract-First 開發流程，強制 OpenAPI + MD 同步更新，CI 阻擋不一致提交。快取 TTL 分層 (1h/5m/30s/0) 與日誌脫敏規範。 (Defined Contract-First workflow, enforced OpenAPI + MD sync updates with CI blocking. Cache TTL tiering and log sanitization rules.)
原子組件庫規格 docs/design/COMPONENT_LIBRARY.md	完整定義 Nothing.tech 純白工業風 Design Tokens (色彩/間距/字體/效果)。涵蓋 12 個核心組件規格 (StatusOrb/GlassCard/HostCard/ApprovalCard/CommandPalette 等)。 (Complete Nothing.tech pure white industrial Design Tokens. 12 core component specifications including StatusOrb, GlassCard, HostCard, ApprovalCard, CommandPalette.)
RBAC 權限架構 docs/security/RBAC_SCHEMA.md	簡化至 4 角色 (Owner/Admin/Member/Viewer) + 資源級權限。Multi-Sig 簽核機制與 Blast Radius 風險矩陣。完整資料庫 Schema 與遷移策略。 (Simplified to 4 roles + resource-level permissions. Multi-Sig approval mechanism with Blast Radius risk matrix. Complete DB schema and migration strategy.)
機密參考指南 docs/security/SECRETS_REFERENCE.md	解決「重複詢問帳密」痛點，記錄「去哪裡找」而非實際值。涵蓋開發 (.env.local)、CI (GitHub Secrets)、Prod (K8s Secrets) 三環境。 (Solved "repeated credential asking" pain point. Documents "where to find" not actual values. Covers dev, CI, and prod environments.)

---

Phase 1: 視覺與大腦 (前端與核心連線 / Visuals & AI Brain)

核心模組與檔案 (Core Modules)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
狀態管理 (State Management) agent.store.ts	採用 Zustand 封裝 SSE 串流與 AbortController，將網路請求與畫面渲染徹底解耦。 (Adopted Zustand to encapsulate SSE streaming and AbortController, completely decoupling network requests from UI rendering.)
數據鉗 UI (Data Pincer UI) data-pincer.tsx	落實 Nothing.tech 風格，使用 .glass-panel 與 Tailwind 狀態色碼，利用 Selector 避免無意義的重複渲染。 (Implemented Nothing.tech style using .glass-panel and Tailwind status colors, utilizing Selectors to prevent meaningless re-renders.)
大腦連線 (Brain Connection) agent.py	串接本地 Ollama 模型，實作「Token 累積緩衝（每 10 字符發送）」，確保前端打字機效果如絲綢般滑順。 (Integrated local Ollama models with "Token Accumulation Buffer", ensuring silky-smooth typewriter effects on the frontend.)

---

Phase 2: 人機協作與企業合規 (HITL & Enterprise Compliance)

核心模組與檔案 (Core Modules)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
授權卡片 (Approval Card) ApprovalCard.tsx	實作 Blast Radius (爆炸半徑) 視覺化，並針對 DESTRUCTIVE (毀滅性操作) 強制加入二次解鎖防呆機制。 (Visualized Blast Radius and enforced a secondary unlock mechanism for DESTRUCTIVE operations to prevent human error.)
預演引擎 (Dry-Run Engine) dry_run.py	實作 K8s Mock 驗證契約，涵蓋 RBAC、語法與資源檢查，確保「沒過 Dry-Run 絕對不准按批准」。 (Implemented K8s Mock validation contracts covering RBAC, syntax, and resource checks. Strict rule: No approval without passing Dry-Run.)
多重簽核 (Multi-Sig) approval.py	實作風險矩陣。阻斷 TOCTOU 漏洞：批准前強制重跑 Dry-Run；若狀態改變，簽章標記為 VOIDED (作廢) 以保留稽核軌跡，嚴禁物理刪除。 (Implemented Risk Matrix. Blocked TOCTOU Vulnerability: Forced Dry-Run re-evaluation before approval execution. Voided signatures on state changes to preserve audit trails; physical deletion is strictly prohibited.)
資料脫敏 (Privacy Shield) privacy_shield.py	實作企業級 Regex 攔截。導入 Consistent Hashing (一致性雜湊)，確保跨日誌的同 IP 獲得相同標籤，完美保留 AI 判斷上下文的能力。 (Enterprise-grade Regex interception. Introduced Consistent Hashing to ensure identical IPs across logs get the same label, preserving AI context reasoning.)

---

Phase 3: 企業護城河 (AI 擴充功能 / Enterprise Moats)

核心模組與檔案 (Core Modules)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
工具橋樑 (MCP Bridge) mcp_bridge.py	串接 MCP 協議。實作 Rehydration Engine (資安標籤還原器)，並要求按標籤長度或邊界匹配替換，嚴禁將還原後的參數寫入標準日誌。 (MCP Protocol integration. Implemented Rehydration Engine with strict boundary-matching replacement rules. Logging rehydrated parameters is strictly forbidden.)
信任引擎 (Trust Engine) trust_engine.py	實作漸進自治。導入 normalize_action_pattern 忽略 K8s Hash 碼；設定 Reject 瞬間歸零，且 CRITICAL 級別永遠不准降級。 (Progressive Autonomy. Introduced normalize_action_pattern to ignore K8s hash codes. Rejects instantly reset trust to zero, and CRITICAL levels can never be downgraded.)
成本優化 (FinOps Engine) cost_analyzer.py	實作 CFO 印鈔機。嚴格區分 Realizable (真實省錢) 與 Freed (釋放空間)；導入 SAFETY_BUFFER = 1.2，嚴防極限縮容導致 OOM 系統崩潰。 (The CFO Money Printer. Strictly distinguished Realizable vs Freed savings. Introduced SAFETY_BUFFER = 1.2 to prevent OOM system crashes from extreme downscaling.)
知識圖譜 (GraphRAG) graph_rag.py	實作 BFS 上下游追溯。加入 max_depth (最大深度限制) 防止爆炸半徑無限擴張；尋找 Root Cause 時優先收集所有異常的 DB/CACHE 節點。 (BFS upstream/downstream tracing. Added max_depth limit to prevent infinite blast radius expansion. Prioritized collecting all abnormal DB/CACHE nodes when seeking Root Causes.)

---

Phase 4: 最終門面 (展示與開源準備 / Final Polish & Open Source)

核心模組與檔案 (Core Modules)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
思考流終端機 (Thinking Terminal) ThinkingTerminal	導入 ASCII Art 動態渲染拓撲依賴圖與 FinOps 三欄式紅綠燈，極致提升硬核賽博龐克質感。 (Introduced dynamic ASCII Art rendering for topology dependency graphs and a 3-column FinOps traffic light system, maximizing the hardcore cyberpunk aesthetic.)
多語系引擎 (i18n Engine) next-intl & middleware.ts	導入 next-intl 實作動態語系路由，支援 zh-TW (預設) 與 en，完美對齊企業級 SaaS 國際化標準。 (Implemented dynamic locale routing with next-intl, supporting zh-TW (default) and en, perfectly aligning with enterprise SaaS i18n standards.)
開源門面 (Open Source README) README.md	定調 Slogan 與 Hero Section，完整包裝四大企業護城河，為 GitHub 開源與商業化做好全面準備。 (Defined Slogan and Hero Section, fully packaging the four enterprise moats, preparing for GitHub open-sourcing and commercialization.)

---

---

Phase 6: 架構硬化 (Horizontal Scaling / 規劃中)

核心模組與檔案 (Core Modules)	首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance)
Redis 狀態持久化 multi_sig_redis.py (規劃中)	將 MultiSigEngine 從 In-Memory 遷移至 Redis Hash，支援分散式部署與 7 天 TTL 稽核保留。導入 Redlock 演算法實現分散式鎖。 (Migrate MultiSigEngine from In-Memory to Redis Hash for distributed deployment. Implement Redlock algorithm for distributed locking.)
Neo4j 圖資料庫 graph_rag_neo4j.py (規劃中)	將 TopologyGraph 遷移至 Neo4j，支援複雜的 Blast Radius 與 Root Cause 圖遍歷查詢。解決大型叢集的效能瓶頸。 (Migrate TopologyGraph to Neo4j for complex Blast Radius and Root Cause graph traversal queries. Resolve performance bottlenecks in large clusters.)
SSE 容錯驗證 dashboard.store.ts	驗證 ADR-004 定義的企業級 SSE 實作：Exponential Backoff (1s→30s)、Heartbeat (30s)、Buffer 批次更新 (5s)。 (Validate ADR-004 enterprise SSE implementation: Exponential Backoff, Heartbeat, Buffer batch updates.)
水平擴展 K8s Service + Redis Pub/Sub	實作 SSE 多實例廣播 (Redis Pub/Sub) 與 Sticky Session，確保用戶連線一致性。 (Implement SSE multi-instance broadcast via Redis Pub/Sub and Sticky Session for connection consistency.)

來源: docs/ARCHITECTURE_CODE_REVIEW.md 技術債審查 (2026-03-22)

---

Zero-Touch Ops. Human-Centric Decisions. (零干預維運，以人為本的決策。)