# AWOOOI 架構指引

> 架構相關的核心原則與規範

---

## 文件資訊

| 欄位 | 值 |
|------|-----|
| **版本** | v1.1 |
| **建立日期** | 2026-03-22 (台北) |
| **建立者** | Claude Code |
| **最後修改** | 2026-03-25 23:59 (台北) |
| **修改者** | Claude Code |

### 變更紀錄

| 版本 | 日期 | 執行者 | 變更內容 |
|------|------|--------|----------|
| v1.0 | 2026-03-22 | Claude Code | 初始建立 |
| v1.1 | 2026-03-25 | Claude Code | 加入文件資訊區塊 |

---

## 快速索引

| 主題 | 核心原則 | 詳細章節 |
|------|---------|---------|
| OpenClaw | 產品核心，只能增強不能移除 | [→ OpenClaw](#openclaw-核心架構) |
| 模組化 | Interface → Memory → Brain → Skill | [→ leWOOOgo](#lewooogo-模組化) |
| API 整合 | Props Mapping 五步驟檢查 | [→ API](#api-整合) |
| 防禦性 | 先質疑後實作 | [→ 防禦性工程](#防禦性工程) |

---

## OpenClaw 核心架構

**Memory 來源:** `feedback_architecture_openclaw_core.md`

### 原則

```
✅ OpenClaw 是 AWOOOI 產品核心
✅ 只能增強，不能移除
✅ 決策鏈必須可視化 (ThinkingTerminal)
✅ 雙軌決策: LLM + Expert System Fallback
```

### 決策流程

```
Signal → IncidentEngine → DecisionManager → Telegram/UI
                              ↓
                    LLM 提案 + Expert System 備援
```

### 命名規範

- ✅ 正確: OpenClaw, openclaw
- ❌ 禁止: OpenClaw, clawbot (舊稱)

---

## leWOOOgo 模組化

**Memory 來源:** `feedback_modular_architecture.md`, `feedback_modular_core_spirit.md`

### 四層架構

```
┌─────────────────────────────────────────┐
│  Skill Layer (技能層)                   │
│  - 特定領域知識                          │
│  - 可組合、可替換                        │
├─────────────────────────────────────────┤
│  Brain Layer (決策層)                   │
│  - LLM + Expert System                  │
│  - 決策邏輯                              │
├─────────────────────────────────────────┤
│  Memory Layer (記憶層)                  │
│  - Working: Redis (短期)                │
│  - Episodic: PostgreSQL (長期)          │
├─────────────────────────────────────────┤
│  Interface Layer (介面層)               │
│  - Telegram Gateway                     │
│  - REST API                             │
└─────────────────────────────────────────┘
```

### 核心精神

1. **Interface 先行** - 先定義清晰的介面契約
2. **Memory 分離** - Working Memory ≠ Episodic Memory
3. **Brain 獨立** - 決策邏輯不綁定特定 LLM
4. **Skill 可組合** - 技能可插拔、可替換

---

## API 整合

**Memory 來源:** `feedback_api_response_verification.md`

### Props Mapping 五步驟檢查

新增 API 欄位時，必須確認完整鏈路：

```
1. API Response 有該欄位 ✓
2. Mapper 函數有轉換該欄位 ✓  ← 最常遺漏！
3. TypeScript 型別有定義該欄位 ✓
4. 組件 Props 有接收該欄位 ✓
5. 組件有使用該欄位 ✓
```

### 快速診斷

```bash
# 確認 API 有回傳
curl -s API_URL | jq '.[0].decision'

# 確認 Mapper 有轉換
grep -n "decision" apps/web/src/app/*/page.tsx
```

### 2026-03-23 教訓

Y/n 按鈕灰色無法點擊，因為 `mapToDualState()` 遺漏傳遞 `decision` 欄位。

---

## 防禦性工程

**Memory 來源:** `feedback_defensive_engineering.md`

### 原則

```
1. 先質疑，後實作
2. 看到可疑代碼，先問為什麼存在
3. 不確定的變更，先問統帥
4. 任何刪除操作，三思後行
```

### 常見陷阱

- 「這段代碼看起來沒用」→ 先 grep 確認沒人用
- 「這個 TODO 很久了」→ 先確認是否已完成
- 「這個邏輯很奇怪」→ 可能是特殊 case 處理

---

## 相關 ADR

- [ADR-003: leWOOOgo 模組架構](adr/ADR-003-lewooogo-module-architecture.md)
- [ADR-006: AI Fallback 策略](adr/ADR-006-ai-fallback-strategy.md)
- [ADR-008: Python 模組化](adr/ADR-008-python-modular-packages.md)
- [ADR-009: OpenClaw Agent Teams](adr/ADR-009-openclaw-agent-teams.md)