feat(packages): Phase 6.4a-c leWOOOgo modular architecture

New packages: - packages/lewooogo-brain: AI reasoning & decision engine - IProposalEngine interface (ABC) - IIncidentProcessor interface (ABC) - Pydantic models: Proposal, Guardrails, Incident, Signal - packages/lewooogo-data: Memory provider abstraction - IMemoryProvider interface (ABC) - IDualMemoryProvider for Working + Episodic memory - Generic type support for flexible data models Documentation: - ADR-008: Python modular packages architecture decision - ARCHITECTURE_MEMORY.md: Module map index for AI developers - LOGBOOK.md: Updated milestones and Phase 6.4 status Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-23 09:32:07 +08:00
parent d050dd1ecc
commit 80d0ef4a8f
17 changed files with 1007 additions and 7 deletions
--- a/docs/ARCHITECTURE_MEMORY.md
+++ b/docs/ARCHITECTURE_MEMORY.md
@@ -0,0 +1,94 @@
+# AWOOOI 架構記憶地圖 (Architecture Memory)
+
+> AI 模組地圖索引 - 每次新增積木後必須登記
+
+**最後更新**: 2026-03-23
+**維護者**: Claude Code + C-Suite
+
+---
+
+## 📦 Python 積木 (packages/)
+
+| 積木名稱 | 職責 | 對外介面 | ADR |
+|----------|------|----------|-----|
+| **lewooogo-brain** | AI 推論與決策邏輯 | `IProposalEngine`, `IIncidentProcessor` | ADR-008 |
+| **lewooogo-data** | 資料抽象與持久化 | `IMemoryProvider`, `IDualMemoryProvider` | ADR-008 |
+
+### lewooogo-brain 模組結構
+
+```
+packages/lewooogo-brain/
+├── src/lewooogo_brain/
+│   ├── interfaces/           # ABC 定義
+│   │   ├── proposal_engine.py    → IProposalEngine
+│   │   └── incident_processor.py → IIncidentProcessor
+│   ├── engines/              # 推論引擎實作
+│   │   ├── proposal_engine.py    # 🔲 待實作
+│   │   └── incident_engine.py    # 🔲 待搬遷
+│   └── skills/               # Skill 動態載入
+│       └── loader.py             # 🔲 待實作
+```
+
+### lewooogo-data 模組結構
+
+```
+packages/lewooogo-data/
+├── src/lewooogo_data/
+│   ├── interfaces/           # ABC 定義
+│   │   └── memory_provider.py    → IMemoryProvider, IDualMemoryProvider
+│   └── providers/            # 具體實作
+│       ├── redis_memory.py       # 🔲 待實作
+│       ├── pg_memory.py          # 🔲 待實作
+│       └── dual_memory.py        # 🔲 待實作
+```
+
+---
+
+## 📦 TypeScript 積木 (packages/)
+
+| 積木名稱 | 職責 | 對外介面 | ADR |
+|----------|------|----------|-----|
+| **lewooogo-core** | 前端 Plugin 系統 | `LeWOOOgoPlugin`, `AgentProvider`, `DataAdapter` | ADR-003 |
+
+---
+
+## 🔗 模組依賴關係
+
+```
+apps/api (FastAPI BFF)
+    ├── lewooogo-brain (AI 積木)
+    │   └── lewooogo-data (資料積木)
+    └── lewooogo-data (直接引用)
+
+apps/web (Next.js)
+    └── lewooogo-core (TS 積木)
+```
+
+---
+
+## 📋 介面契約索引
+
+### Python 介面
+
+| 介面 | 位置 | 職責 |
+|------|------|------|
+| `IProposalEngine` | `lewooogo_brain.interfaces` | 決策提案生成 |
+| `IIncidentProcessor` | `lewooogo_brain.interfaces` | 事件聚合處理 |
+| `IMemoryProvider` | `lewooogo_data.interfaces` | 單層記憶體存取 |
+| `IDualMemoryProvider` | `lewooogo_data.interfaces` | 雙層記憶體 (Working + Episodic) |
+
+### HTTP API 契約
+
+| 端點 | 位置 | 職責 |
+|------|------|------|
+| `POST /api/v1/incidents/{id}/propose` | `apps/api/src/api/v1/incidents.py` | 生成決策提案 |
+| `GET /api/v1/incidents/{id}` | `apps/api/src/api/v1/incidents.py` | 取得事件詳情 |
+
+---
+
+## 🚨 AI 開發者注意事項
+
+1. **新增積木前**: 先讀取此檔案確認命名不衝突
+2. **新增積木後**: 必須在此檔案登記職責與對外介面
+3. **修改介面前**: 先讀取 `docs/adr/` 確認架構決策
+4. **跨模組引用**: 禁止直接 import，必須透過介面抽象
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -9,12 +9,12 @@

 | 項目 | 狀態 |
 |------|------|
-| **當前 Phase** | **Phase 6.3 完成** - Incident Engine v1 (告警聚合核心) |
-| **Day** | Day 4 |
-| **下一步** | Phase 6.4 Decision Proposal API |
-| **重大變更** | 🧠 **認知覺醒計畫 6.0-6.3 竣工**: Event Bus + 海馬迴 + 聚合引擎全線貫通 |
+| **當前 Phase** | **Phase 6.4 實作中** - 模組化架構重整 + Decision Proposal |
+| **Day** | Day 5 |
+| **下一步** | Phase 6.4d MemoryProvider 實作 |
+| **重大變更** | 🚨 **生產事故修復**: Worker CrashLoopBackOff (7h) + 簽核卡片 Race Condition |

-### 🧠 認知覺醒計畫 Phase 6 施工順序 (C-Suite 2026-03-22 決議)
+### 🧠 認知覺醒計畫 Phase 6 施工順序 (C-Suite 2026-03-23 統帥方案)

 | 步驟 | 項目 | 部署位置 | 工時 | 狀態 |
 |------|------|---------|------|------|
@@ -23,8 +23,16 @@
 | 6.2.1 | Working Memory (Redis Hash) | .188 Redis | 1d | ✅ 完成 |
 | 6.2.2 | Episodic Memory (PostgreSQL) | .188 PostgreSQL | 1d | ✅ 完成 |
 | 6.3 | Incident Engine v1 | .188 API | 3d | ✅ 完成 |
-| 6.4 | Decision Proposal API | .188 API | 1d | 🔲 待辦 |
-| 6.5 | Sensor Agent (各主機) | .110/.112/.120 | 2d | 🔲 待辦 |
+| **6.4a** | **lewooogo-brain 骨架** | `packages/` | 1h | ✅ 完成 |
+| **6.4b** | **lewooogo-data 骨架** | `packages/` | 1h | ✅ 完成 |
+| **6.4c** | **Interface 定義 (ABC)** | `packages/` | 2h | ✅ 完成 |
+| **6.4d** | **MemoryProvider 實作** | `packages/` | 4h | 🔲 待辦 |
+| **6.4e** | **Engine 搬遷** | `packages/` | 4h | 🔲 待辦 |
+| **6.4f** | **SkillLoader** | `packages/` | 2h | 🔲 待辦 |
+| **6.4g** | **apps/api 引用更新** | `apps/api` | 2h | 🔲 待辦 |
+| **6.4h** | **Decision Proposal API** | .188 API | 4h | 🔲 待辦 |
+| 6.5 | Runner 整合 + 5+1 狀態機 | .188 API | 4h | 🔲 待辦 |
+| 6.6 | Sensor Agent (各主機) | .110/.112/.120 | 2d | 🔲 待辦 |

 ---

@@ -32,6 +40,11 @@

 | 時間 | 事件 | 負責人 |
 |------|------|--------|
+| 2026-03-23 09:30 | **🔧 NetworkPolicy 修復**: `allow-required-egress` podSelector 改為 `system=awoooi` (原本只允許 API pod) | Claude Code |
+| 2026-03-23 09:20 | **🚨 生產修復 #2**: Worker CrashLoopBackOff 92次 + `init_redis` → `init_redis_pool` 函數名修正 + 7h 無告警根因 | Claude Code |
+| 2026-03-23 09:15 | **🚨 生產修復 #1**: 簽核卡片閃爍消失 + Polling Race Condition + approval.store.ts 暫停/恢復機制 | Claude Code |
+| 2026-03-23 09:10 | **📚 Skills 更新**: 05-awoooi-sre-qa.md + 新增 CrashLoopBackOff 診斷 + Race Condition 偵測 + Telegram 健康檢查 | Claude Code |
+| 2026-03-23 10:30 | **🧱 C-Suite 模組化架構評審**: 統帥質疑積木化原則淡化 + 後端缺 lewooogo-brain/data 積木 + 方案 B 漸進式拆分 (Interface→Memory→Brain→Skill) + 2.5d 工時評估 + 施工順序重排 | C-Suite + Claude Code |
 | 2026-03-23 01:10 | **🚀 Signal Worker 啟用**: `replicas: 0→1` + Redis Streams Consumer 正式上線 + Incident Engine 處理鏈完整 | CTO + Claude Code |
 | 2026-03-23 01:05 | **🎯 實彈告警發射成功**: 4 發告警注入 Redis Streams (HarborOOMKilled/HighCPU/DBTimeout/RedisMemory) + message_id 確認 | CTO + Claude Code |
 | 2026-03-23 00:55 | **📊 GlobalPulse 脈搏恢復**: SignOz v3 表修正 + RPS 5.4/Error 25%/P99 3s 真實數據顯示 | CTO + Claude Code |
--- a/docs/adr/ADR-008-python-modular-packages.md
+++ b/docs/adr/ADR-008-python-modular-packages.md
@@ -0,0 +1,146 @@
+# ADR-008: Python 模組化獨立積木架構
+
+**狀態**: 已批准
+**日期**: 2026-03-23
+**決策者**: CEO (統帥) + C-Suite
+**執行者**: CTO + Claude Code
+
+## 背景
+
+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. **學習曲線**: 團隊需適應新的引用方式
+
+## 相關決策
+
+- 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/)