7b9b0c490b
## Phase 19 Omni-Terminal (Wave 0-6 全部完成) ### 核心功能 - SSE 狀態機 (7-State 設計，10/10 分) - GenUI 動態渲染 (6 張卡片 + Zod Schema 驗證) - 核鑰 UX (長按授權 + 風險分級) - Terminal Telemetry (Sentry 整合) ### P0-P2 修復 - P0: Singleton → FastAPI Depends 依賴注入 - P1: Zod Schema 升級 (7 個驗證 Schema) - P1: 錯誤分類碼聚合 (Sentry fingerprint) - P2: Slow Query 監控 (5s 警告 / 10s 嚴重) ### 測試 - test_terminal_service.py: 54 項測試全通過 - 意圖分類: 42 個測試案例 (9 種 IntentType) ### 文檔 - ADR-031: SSE 架構實作紀錄 - ADR-032: GenUI 渲染實作紀錄 - Skills: v1.9 (後端 Terminal 章節) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
# 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`
|