# ADR-008: Python 模組化獨立積木架構

**狀態**: 已批准 ✅ 完整實施
**日期**: 2026-03-23
**決策者**: CEO (統帥) + C-Suite
**執行者**: CTO + Claude Code
**驗收日期**: 2026-03-28 (Phase 16 首席架構師審查 50/50 OUTSTANDING)

## 背景

AWOOOI 2.0 的後端 Python 代碼 (`apps/api/src/services/`) 出現以下問題：

1. **模組化原則淡化**: 所有邏輯直接寫在 `services/` 目錄，未建立獨立積木
2. **跨模組非法引用**: `proposal_service.py` 直接 import `redis_client`, `db.base`
3. **前後端積木不對稱**: 前端有 `packages/lewooogo-core` (TS)，後端無對應 Python 積木
4. **Skill Registry 缺失**: 6 個 Skill MD 檔案無動態載入機制

## 決策

**採用統帥方案 (方案 A): 在 `packages/` 下建立獨立 Python 積木**

### 放棄的方案

- **方案 B (漸進式)**: 在 `apps/api/src/` 內建立 `brain/`、`memory/` 模組
- **理由**: 無法達成真正的物理隔離，違反 leWOOOgo 積木化原則

### 採用的技術

```toml
# apps/api/pyproject.toml
dependencies = [
    "lewooogo-brain @ file:../../packages/lewooogo-brain",
    "lewooogo-data @ file:../../packages/lewooogo-data",
]
```

使用 `pip install -e .` (Editable Install) 達成本地聯動開發。

## 積木職責定義

### lewooogo-brain (AI 邏輯積木)

| 模組 | 職責 |
|------|------|
| `interfaces/` | ABC 定義 (IProposalEngine, IIncidentProcessor) |
| `engines/` | 推論引擎 (IncidentEngine, ProposalEngine) |
| `skills/` | Skill 動態載入器 |

### lewooogo-data (資料抽象積木)

| 模組 | 職責 |
|------|------|
| `interfaces/` | ABC 定義 (IMemoryProvider) |
| `providers/` | 具體實作 (RedisMemory, PgMemory) |

## 目錄結構

```
packages/
├── lewooogo-core/        # TS 前端積木 (已有)
├── lewooogo-brain/       # Python AI 積木 (新建)
│   ├── pyproject.toml
│   └── src/lewooogo_brain/
│       ├── __init__.py
│       ├── interfaces/
│       │   ├── __init__.py
│       │   ├── proposal_engine.py
│       │   └── incident_processor.py
│       ├── engines/
│       │   ├── __init__.py
│       │   ├── incident_engine.py
│       │   └── proposal_engine.py
│       └── skills/
│           ├── __init__.py
│           └── loader.py
└── lewooogo-data/        # Python 資料積木 (新建)
    ├── pyproject.toml
    └── src/lewooogo_data/
        ├── __init__.py
        ├── interfaces/
        │   ├── __init__.py
        │   └── memory_provider.py
        └── providers/
            ├── __init__.py
            ├── redis_memory.py
            └── pg_memory.py
```

## 引用方式

```python
# apps/api/src/api/v1/incidents.py
from lewooogo_brain.engines import ProposalEngine
from lewooogo_data.providers import RedisMemory

engine = ProposalEngine(memory=RedisMemory())
proposal = await engine.generate(incident_id)
```

## 依賴配置

### lewooogo-brain

```toml
dependencies = [
    "pydantic>=2.5.0",
    "structlog>=24.1.0",
    "opentelemetry-api>=1.20.0",
    "lewooogo-data",  # 依賴資料積木
]
```

### lewooogo-data

```toml
dependencies = [
    "pydantic>=2.5.0",
    "redis>=5.0.0",
    "sqlalchemy[asyncio]>=2.0.0",
    "structlog>=24.1.0",
]
```

## 後果

### 優點

1. **完全物理隔離**: Brain 和 Data 積木可獨立測試、獨立部署
2. **可複用性**: 其他專案可直接引用這些積木
3. **符合 leWOOOgo 原則**: 高內聚、低耦合
4. **介面先行**: 強制定義 ABC，再實作具體類別

### 缺點

1. **初期工時增加**: 約 3-4 天建立積木骨架
2. **依賴管理複雜度**: 需維護多個 pyproject.toml
3. **學習曲線**: 團隊需適應新的引用方式

## 實施狀態 (Phase 16)

> **首席架構師驗收**: 2026-03-28 **50/50 OUTSTANDING**

### 實施成果

| 項目 | 結果 |
|------|------|
| 絞殺者模式 (USE_NEW_ENGINE) | ✅ 雙軌切換完美運作 |
| Repository 抽象化 | ✅ 7 個 Repository 已建立 |
| Router 瘦身 | ✅ 1,097 → 796 行 (-28%) |
| 封存策略 | ✅ 866 行 → `_archived/` |

### 模組化 5 問驗證

| # | 問題 | 結果 |
|---|------|------|
| 1 | 邏輯是否已存在於 packages? | ✅ |
| 2 | Router 是否只做 HTTP 轉發? | ✅ |
| 3 | Service 是否依賴 Interface? | ✅ |
| 4 | 是否可被其他模組重用? | ✅ |
| 5 | 是否遵循依賴注入? | ✅ |

## 相關決策

- ADR-003: leWOOOgo 模組架構 (前端 TS 版)
- ADR-005: BFF 閘道架構

## 參考資料

- [Python Packaging User Guide](https://packaging.python.org/)
- [PEP 621 – Storing project metadata in pyproject.toml](https://peps.python.org/pep-0621/)
- Phase 16 計畫: `memory/project_phase16_great_refactoring.md`