awoooi/docs/RED_ZONES.md

AWOOOI 紅區治理手冊

代碼防區化治理 (Codebase Zoning) 與爆炸半徑鎖死 (Blast Radius Containment)

---

文件資訊

欄位	值
版本	v1.0
建立日期	2026-03-26 12:30 (台北)
建立者	Claude Code
最後修改	2026-03-26 12:30 (台北)
修改者	Claude Code
審查週期	每月第一個週一

變更紀錄

版本	日期	執行者	變更內容
v1.0	2026-03-26	Claude Code	初始建立 - 紅區治理機制

---

紅區分級定義

等級	名稱	圖示	定義	變更後果
Tier 3	核心大腦	🔴	AI 決策、狀態機、Multi-Sig	系統決策失靈
Tier 2	基礎設施	🟠	DB Schema、K8s、CI/CD	部署/資料異常
Tier 1	業務邏輯	🟢	API 路由、UI 組件	功能異常 (可快速修復)

---

Tier 3 紅區清單 (8 個檔案)

1. 決策狀態機

檔案: apps/api/src/services/decision_manager.py
功能: OpenClaw AI 的決策核心，控制 PENDING→APPROVED→EXECUTED 狀態流轉
影響:
  - AI 無法做出決策
  - 審批流程卡死
  - 所有待處理告警無法推進

2. 信任評分引擎

檔案: apps/api/src/services/trust_engine.py
功能: 計算操作的信任分數，決定是否需要 Multi-Sig 審批
影響:
  - 危險操作被自動執行 (信任分數錯誤)
  - 低風險操作被過度審批
  - Multi-Sig 機制失效

3. 共識引擎

檔案: apps/api/src/services/consensus_engine.py
功能: Multi-Sig 多方簽核邏輯，確保關鍵操作需多人同意
影響:
  - 單點簽核繞過安全機制
  - 審批人數計算錯誤
  - 共識達成判斷失靈

4. 事件處理引擎

檔案: apps/api/src/services/incident_engine.py
功能: 告警接收、分類、派發的核心引擎
影響:
  - 告警無法被接收
  - 事件分類錯誤
  - Telegram 通知失敗

5. 分散式鎖服務

檔案: apps/api/src/services/multi_sig_redis.py
功能: Redis 分散式鎖，防止併發競爭
影響:
  - 同一事件被多次處理
  - 死鎖導致系統卡死
  - 資料不一致

6. 安全攔截器

檔案: apps/api/src/services/security_interceptor.py
功能: 權限驗證、危險操作攔截
影響:
  - 權限繞過漏洞
  - 危險操作未被攔截
  - 安全審計失效

7. 環境配置中心

檔案: apps/api/src/core/config.py
功能: 所有服務的連線配置 (Redis/PostgreSQL/Ollama/Telegram)
影響:
  - 所有外部連線中斷
  - 服務無法啟動
  - 環境變數解析失敗

8. OTEL 監控核心

檔案: apps/api/src/core/telemetry.py
功能: OpenTelemetry 追蹤與指標收集
影響:
  - SignOz 無法收到追蹤數據
  - 系統可觀測性失明
  - 問題排查極度困難

---

Tier 2 橙區清單

K8s 正式環境

目錄: k8s/awoooi-prod/*.yaml
功能: Kubernetes 正式環境部署檔案
影響: 正式環境部署失敗、NetworkPolicy 錯誤

資料庫 Schema

檔案: apps/api/src/db/models.py
功能: SQLAlchemy ORM 模型定義
影響: 資料庫結構不一致、Migration 衝突

CI/CD Pipeline

目錄: .github/workflows/*.yml
功能: GitHub Actions 自動化流程
影響: 自動部署中斷、可能產生帳單費用

Redis 連線池

檔案: apps/api/src/core/redis_client.py
功能: Redis 連線管理與 Stream 操作
影響: 快取服務中斷、Worker 無法接收任務

Telegram 閘道

檔案: apps/api/src/services/telegram_gateway.py
功能: Telegram Bot 訊息收發
影響: 告警通知無法送達、審批按鈕失效

---

🏛️ 首席架構師審查流程

警告觸發時

當 Git commit 觸及紅區/橙區檔案時，pre-commit hook 會顯示警告，並強制啟動首席架構師審查流程：

╔══════════════════════════════════════════════════════════════╗
║  🔴 TIER 3 紅區變更警告                                      ║
╚══════════════════════════════════════════════════════════════╝

[Tier 3 紅區] 決策狀態機
功能: OpenClaw AI 的決策核心
影響: ...

╔══════════════════════════════════════════════════════════════╗
║  🏛️  首席架構師審查必要                                       ║
╠══════════════════════════════════════════════════════════════╣
║  1. 停止 commit，呼叫首席架構師介入                          ║
║  2. 首席架構師進行架構與代碼 Review                          ║
║  3. 確認變更必要性、影響範圍、替代方案                       ║
║  4. 首席架構師簽核後，方可繼續                               ║
╚══════════════════════════════════════════════════════════════╝

首席架構師審查檢查項

項目	說明
變更必要性	為什麼需要修改此核心檔案？有無其他方案？
影響範圍	此變更會影響哪些上下游模組？
風險評估	最壞情況是什麼？如何緩解？
回滾計畫	若出問題，如何快速回滾？
測試覆蓋	是否有足夠的測試保護此變更？

首席架構師簽核格式

## 🏛️ 首席架構師審查簽核

**審查時間**: 2026-03-26 13:00 (台北)
**審查者**: 首席架構師 / Claude Code

### 變更摘要
- 檔案: decision_manager.py
- 原因: [說明]

### 審查結論
- [x] 變更必要性確認
- [x] 影響範圍可控
- [x] 回滾計畫完備
- [x] 測試覆蓋充足

### 簽核結果
✅ **批准** - 可繼續 commit

Claude Code 看到警告後必須

1. 立即停止自動 commit
2. 呼叫首席架構師介入
3. 首席架構師進行審查:
   • 變更必要性
   • 影響範圍評估
   • 替代方案評估
   • 回滾計畫
4. 首席架構師簽核後才能繼續 commit

---

定期審查機制

審查週期

項目	週期	負責人	下次審查
紅區清單	每週一	首席架構師	2026-03-31
Hook 腳本	每月第一個週一	首席架構師	2026-04-06
違規統計	每週一	Claude Code	2026-03-31

審查檢查項

• 是否有新的核心模組需要加入紅區？
• 是否有紅區檔案已重構/移除？
• Hook 警告訊息是否仍然準確？
• 是否有誤報需要調整？

更新流程

1. 修改 scripts/hooks/pre-commit 中的 TIER3_ZONES 或 TIER2_ZONES
2. 執行 bash scripts/setup-hooks.sh 重新安裝
3. 更新本文件 docs/RED_ZONES.md
4. 更新 Memory: feedback_red_zone_governance.md

---

相關文件

• HARD_RULES.md - 絕對禁止規則
• CLAUDE.md - AI 開發憲法
• scripts/hooks/pre-commit - Hook 腳本