diff --git a/.agents/skills/02-lewooogo-backend-core.md b/.agents/skills/02-lewooogo-backend-core.md index 54db67eb..e489b28b 100644 --- a/.agents/skills/02-lewooogo-backend-core.md +++ b/.agents/skills/02-lewooogo-backend-core.md @@ -35,6 +35,7 @@ | v2.2 | 2026-03-30 | Claude Code | 🎯 新增 Phase 19.4 API 整合章節 (Approval + K8s 真實 API) | | v2.3 | 2026-03-30 | Claude Code | 🤖 新增 AI Fallback 順序章節 (NVIDIA 優先仲裁) | | v2.4 | 2026-03-31 | Claude Code | 🏛️ Phase 22 首席架構師審查通過 (Mock違規+分層修復全部完成) | +| v2.5 | 2026-04-01 | Claude Code | ♻️ Phase R-R2 完成 (legacy -971行) + R-R2.1 P0/P1修復 + ADR-046 型別統一 | --- diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 30d1a4e9..619df5a8 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -9,6 +9,9 @@ | 項目 | 狀態 | |------|------| +| **Phase R-R2.1** | ✅ **架構審查 P0+P1 修復** `d17b67c` (key prefix/型別/死碼) 80→92/100 | +| **Phase R-R3** | ✅ **已完成** (Phase 22 架構修復中建立, 9 repos) | +| **ADR-046** | 📋 **待統帥決策** 跨套件 Incident 型別統一 (Option B: IncidentConverter) | | **Phase R-R2** | ✅ **完成** (#121 #122 `c7b3f8f` -971 行 legacy code;#123 暫緩至 R-R3) | | **Phase R-R1** | ✅ **已實作** (絞殺者模式 + USE_NEW_ENGINE=True 已驗證) | | **首席架構師審查** | ✅ **78→85/100** (P0 NVIDIA型別 + P1 IAIRouter Interface) | diff --git a/docs/adr/ADR-024-api-layer-architecture.md b/docs/adr/ADR-024-api-layer-architecture.md index a56cc95b..107ccb03 100644 --- a/docs/adr/ADR-024-api-layer-architecture.md +++ b/docs/adr/ADR-024-api-layer-architecture.md @@ -2,7 +2,7 @@ | 項目 | 內容 | |------|------| -| **狀態** | ✅ 已採用 | +| **狀態** | ✅ 已採用 (Phase R-R2 完成,2026-04-01) | | **日期** | 2026-03-26 | | **決策者** | 首席架構師 + 統帥 | | **Phase** | Phase 16 | @@ -165,9 +165,22 @@ kubectl set env deployment/awoooi-api USE_NEW_LAYER=false - 短期開發成本增加 - 需要團隊學習新規範 +## 執行進度 + +| Phase | 任務 | 狀態 | Commit | +|-------|------|------|--------| +| R1 | 絞殺者包裝 (USE_NEW_ENGINE) | ✅ | Phase 16 R1 | +| R2 | 移除內嵌重複邏輯 | ✅ | `c7b3f8f` (2026-04-01) | +| R3 | 抽取 Repository 層 | ✅ | Phase 22 (repositories/) | +| R4 | 瘦身 Router 層 | 🔴 待執行 | - | + +> Phase R-R2.1 架構審查通過 (80/100)。P0+P1 已修復 (`d17b67c`)。 +> P2 技術債 (ADR-013 時間格式) 移至下個 Sprint。 + ## 相關文件 - ADR-005: BFF Architecture - ADR-003: leWOOOgo Module Architecture +- ADR-046: 跨套件 Incident 型別統一 (BrainIncident vs local Incident) - `feedback_strangler_fig_pattern.md` - `reference_phase16_architecture.md` diff --git a/docs/adr/ADR-046-incident-type-unification.md b/docs/adr/ADR-046-incident-type-unification.md new file mode 100644 index 00000000..f3a830d6 --- /dev/null +++ b/docs/adr/ADR-046-incident-type-unification.md @@ -0,0 +1,82 @@ +# ADR-046: 跨套件 Incident 型別統一治理 + +| 項目 | 內容 | +|------|------| +| **狀態** | 📋 待決策 | +| **日期** | 2026-04-01 | +| **決策者** | 首席架構師 + 統帥 | +| **觸發** | Phase R-R2.1 架構審查 P2-01 | + +## 背景 + +Phase R-R2 完成後,系統中同時存在兩種 Incident 型別: + +| 型別 | 來源 | 欄位 | +|------|------|------| +| `src.models.incident.Incident` | 本地 (apps/api) | decision_chain, outcome, ttl_days, vectorized, persisted_to_pg | +| `lewooogo_brain.interfaces.incident_processor.Incident` (BrainIncident) | lewooogo-brain 套件 | 精簡欄位,無 decision_chain 等 | + +### 問題根源 + +`IncidentDbAdapter._record_to_incident()` 返回 `BrainIncident`,但靜態型別宣告為本地 `Incident`。 +`IncidentMemoryAdapter` 的 `load_incident()` 通過 `brain.DualIncidentMemory` 返回 `BrainIncident`。 +部分 Service 層(如 `proposal_service.py`、`incident_service.py`)期望本地 `Incident` 型別, +導致 `AttributeError` 風險或靜態分析誤報。 + +## 三種方案 + +### Option A:本地 `Incident` 繼承 `BrainIncident` +```python +# src/models/incident.py +from lewooogo_brain.interfaces.incident_processor import Incident as BrainIncident + +class Incident(BrainIncident): + """AWOOOI 本地擴展 Incident""" + decision_chain: AIDecisionChain | None = None + ttl_days: int = 30 + vectorized: bool = False + persisted_to_pg: bool = False +``` +- ✅ 型別統一,靜態分析通過 +- ⚠️ 強依賴 lewooogo-brain 套件版本 +- ⚠️ BrainIncident 變更會影響本地 + +### Option B:建立 `IncidentConverter` 轉換層 +```python +# src/utils/incident_converter.py +def brain_to_local(brain_incident: BrainIncident) -> Incident: ... +def local_to_brain(local_incident: Incident) -> BrainIncident: ... +``` +- ✅ 兩者保持獨立,變更不互相影響 +- ✅ 轉換點明確,可審計 +- ⚠️ 每次跨邊界需顯式轉換,增加樣板代碼 + +### Option C:逐步廢棄本地 `Incident`,全面切換至 `BrainIncident` +- ✅ 最終架構最簡潔 +- 🔴 需要修改所有使用本地 `Incident` 的程式碼(30+ 處) +- 🔴 proposal_service、incident_service 等需要大規模重構 + +## 建議 + +**推薦 Option B**(IncidentConverter 轉換層),理由: +1. 套件邊界清晰,符合 leWOOOgo 積木化原則 +2. 遷移風險最低,可漸進式採用 +3. 若未來棄用 lewooogo-brain,只需修改 Converter + +短期緩解(已實施): +- `_record_to_incident` 返回型別標注為 `Any`(P0-01 修復) +- 不阻擋現有業務邏輯 + +## 後續行動 + +- [ ] 首席架構師決策選擇方案 +- [ ] 若選 Option B:建立 `src/utils/incident_converter.py` +- [ ] 更新 `IncidentDbAdapter._record_to_incident` 返回正確型別 +- [ ] 更新 `IncidentMemoryAdapter` 型別標注 + +## 相關文件 + +- ADR-024: API 分層架構 (Phase 16 絞殺者模式) +- ADR-003: leWOOOgo Module Architecture +- `feedback_lewooogo_modular_enforcement.md` +- Phase R-R2.1 架構審查報告 (commit `d17b67c`)