# AWOOOI 架構文檔

> 統帥鐵律：嚴禁臨時方案，所有架構決策必須符合長期維護性

## 核心架構原則

### Four Iron Laws (四大鐵律)

1. **Async-First** - 所有 Handler 必須是 `async def`
2. **CORS Whitelist** - 嚴格來源控制，禁止 wildcard (*)
3. **Pydantic Config** - 類型安全的設定驗證
4. **structlog** - 結構化 JSON 日誌

## HTTP Client 架構 (2026-03-21 架構回歸)

### 問題背景

原始實作使用 `subprocess.run(["curl", ...])` 作為 httpx 404 問題的臨時解法。
統帥明令禁止此類臨時方案，要求回歸原生 httpx AsyncClient。

### 永久解決方案

```
src/core/http_client.py - Lifespan 管理的連線池
├── get_clickhouse_client() - ClickHouse 專用 Client
├── get_general_client()    - Ollama/Gemini/Claude 通用 Client
├── init_all_http_clients() - 啟動時初始化
└── close_all_http_clients() - 關閉時清理
```

### 關鍵配置

```python
httpx.AsyncClient(
    base_url=settings.CLICKHOUSE_URL,
    timeout=httpx.Timeout(30.0, connect=10.0),
    trust_env=False,  # 🔧 禁止 HTTP_PROXY 干擾
    limits=httpx.Limits(max_connections=100, max_keepalive_connections=20),
)
```

### Lifespan 整合

```python
# src/main.py
@asynccontextmanager
async def lifespan(_app: FastAPI):
    # Startup
    await init_all_http_clients()  # ✅ 連線池建立
    yield
    # Shutdown
    await close_all_http_clients()  # ✅ 連線池回收
```

### 驗證結果

```
Status: 200
Elapsed: 28.71ms (< 50ms 目標)
Method: httpx_native
```

## 五主機架構

| 主機 | IP | 角色 | 服務 |
|-----|-----|------|------|
| DevOps | 192.168.0.110 | CI/CD | Harbor, GH Runner |
| Security | 192.168.0.112 | 安全掃描 | Kali Scanner |
| K3s Master | 192.168.0.120 | 容器編排 | K3s API Server |
| K3s Worker | 192.168.0.121 | 工作負載 | App Pods |
| AI+Web | 192.168.0.188 | AI/DB/Web | Ollama, PostgreSQL, Redis, SignOz |

## SignOz 整合架構

```
┌─────────────────────────────────────────────┐
│                 AWOOOI API                   │
│                 (port 8000)                  │
├─────────────────────────────────────────────┤
│  signoz_client.py                           │
│  └── get_clickhouse_client()                │
│      └── httpx.AsyncClient (Lifespan)       │
└─────────────────┬───────────────────────────┘
                  │ HTTP POST (< 50ms)
                  ▼
┌─────────────────────────────────────────────┐
│           ClickHouse HTTP API               │
│           192.168.0.188:8123                │
├─────────────────────────────────────────────┤
│  signoz_metrics.distributed_samples_v4      │
│  - signoz_calls_total (RPS)                 │
│  - signoz_latency_count (P99)               │
└─────────────────────────────────────────────┘
```

## AI Fallback 策略 (ADR-006)

```
Ollama (local) → Gemini (cloud) → Claude (cloud) → mock_fallback
     ↓              ↓                 ↓                ↓
   免費           $0.001/1K        $0.003/1K        開發用
   188:11434     API Key          API Key          無 LLM
```

## Phase 7: 視覺主權組件

### 已完成組件

| 組件 | 路徑 | 功能 |
|-----|------|------|
| GlobalPulseChart | `components/charts/global-pulse-chart.tsx` | 4 指標卡片 + Sparkline |
| AIProcessStepper | `components/charts/ai-process-stepper.tsx` | 5 步 AI 決策流程 |
| TimeSeriesChart | `components/charts/time-series-chart.tsx` | 通用趨勢圖 |

### Nothing.tech 設計語言

```css
/* 主色調 */
--nothing-white: #FFFFFF;
--nothing-gray-50: #FAFAFA;
--nothing-gray-900: #171717;
--nothing-red: #EF4444;

/* 玻璃效果 */
.glass-card {
  background: rgba(255, 255, 255, 0.7);
  backdrop-filter: blur(16px);
  border: 1px solid rgba(0, 0, 0, 0.05);
}
```

## Phase 6: 架構硬化 Roadmap (規劃中)

> **來源**: `docs/ARCHITECTURE_CODE_REVIEW.md` 技術債審查

| 項目 | 現狀 | 目標 | 優先級 |
|------|------|------|--------|
| Multi-Sig 持久化 | In-Memory dict | Redis Hash + Redlock | 🔴 P0 |
| GraphRAG 遷移 | In-Memory dict | Neo4j / Redis Graph | 🔴 P0 |
| SSE 容錯驗證 | ADR-004 已規劃 | 驗證實作 | 🟢 P2 |
| 水平擴展 | 單實例 | Redis Pub/Sub + Sticky Session | 🟡 P1 |

**依賴**: Phase 5 (OpenClaw 實體化) 完成後執行

## 變更紀錄

| 日期 | 版本 | 變更 |
|-----|------|------|
| 2026-03-22 | 1.1 | 新增 Phase 6 架構硬化 Roadmap (Code Review 來源) |
| 2026-03-21 | 1.0 | 架構回歸：移除 subprocess+curl，實作 httpx Lifespan |
| 2026-03-21 | 1.0 | Phase 7 視覺組件：GlobalPulseChart, AIProcessStepper |