Files

OG T 7b9b0c490b feat(phase19): Omni-Terminal 100% 完成 + 首席架構師審查 47/50

## 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>

2026-03-28 18:04:12 +08:00

4.8 KiB

Raw Permalink Blame History

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/) 出現以下問題：

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

決策

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

放棄的方案

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

採用的技術

# 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

引用方式

# 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

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

lewooogo-data

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

後果

優點

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

缺點

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

實施狀態 (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	是否遵循依賴注入?	✅

參考資料

Python Packaging User Guide
PEP 621 – Storing project metadata in pyproject.toml
Phase 16 計畫: memory/project_phase16_great_refactoring.md

4.8 KiB Raw Permalink Blame History Unescape Escape