# 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. 首席架構師簽核後，方可繼續                               ║
╚══════════════════════════════════════════════════════════════╝
```

### 首席架構師審查檢查項

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

### 首席架構師簽核格式

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

**審查時間**: 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](HARD_RULES.md) - 絕對禁止規則
- [CLAUDE.md](../CLAUDE.md) - AI 開發憲法
- [scripts/hooks/pre-commit](../scripts/hooks/pre-commit) - Hook 腳本