## 🛠️ 專業框架與方法論

### Ironclaw 角色系統架構模型

#### 三層角色模型（推薦基線）
```
┌─────────────────────────────────────┐
│  L3: Contextual Roles（情境角色）    │  ← 臨時委派、專案角色、時效授權
├─────────────────────────────────────┤
│  L2: Functional Roles（職能角色）    │  ← 對應業務職能（財務審批、內容發布）
├─────────────────────────────────────┤
│  L1: Core Roles（核心角色）          │  ← 基礎身份（員工、合作夥伴、訪客）
└─────────────────────────────────────┘
```

#### 角色解析管線（Resolution Pipeline）
1. **Identity Binding** → 綁定主體身份（User/Service Account/Group）
2. **Role Assignment** → 直接指派 + 群組繼承 + 動態屬性匹配
3. **Inheritance Expansion** → 展開繼承鏈，偵測循環依賴
4. **Constraint Evaluation** → 時間窗、IP 範圍、資源標籤、SoD 規則
5. **Permission Materialization** → 產出有效權限集合（含 deny 覆寫）
6. **Cache & Invalidate** → TTL 策略、事件驅動失效（角色變更、群組變更）

### 診斷框架：ROLE-HEALTH 六維評估

| 維度 | 檢查項 | 健康閾值（參考） |
|------|--------|------------------|
| **R**edundancy | 語意重複角色對 | < 5% 重複率 |
| **O**rphanage | 90 天零指派角色 | < 10% 幽靈角色 |
| **L**atency | P99 角色解析延遲 | < 50ms（快取命中） |
| **E**ntitlement | 過度授權帳號比例 | < 2% |
| **H**ierarchy | 繼承鏈最大深度 | ≤ 5 層 |
| **T**raceability | 變更無稽核紀錄比例 | 0% |

### 優化方法論

#### 1. 角色合併（Role Consolidation）
- 使用 **Jaccard 相似度** 比對權限集合
- 合併閾值：相似度 ≥ 0.85 且業務語意一致
- 保留別名映射至少一個發布週期

#### 2. 權限正規化（Permission Normalization）
- 採用 `resource:action:scope` 命名（例：`invoice:approve:department`）
- 建立 Permission Registry，禁止散落硬編碼
- 區分 **Data Permission** vs **Action Permission**

#### 3. 動態角色（Dynamic RBAC + ABAC 混合）
```yaml
# 範例：Policy-as-Code（Rego 風格概念）
allow {
  input.user.department == input.resource.owner_department
  input.user.roles[_] == "finance:reviewer"
  input.context.amount < 100000
}
```

#### 4. 遷移策略選型
| 策略 | 適用場景 | 風險 |
|------|----------|------|
| Shadow Mode | 新舊並行比對 | 低 |
| Blue-Green Roles | 完整切換 | 中 |
| Strangler Fig | 漸進替換模組 | 低-中 |
| Big Bang | 極小系統 | 高（需強制審批） |

### 效能優化清單
- **批次預計算**：離峰時段 materialize 高頻角色組合
- **分層快取**：L1 記憶體（熱角色）→ L2 Redis（用戶有效權限）→ L3 持久化
- **索引設計**：`(subject_id, tenant_id)`、`(role_id, effective_at)`
- **懶加載繼承**：僅在權限檢查失敗時展開完整繼承鏈

### 整合知識庫
- **NIST RBAC 模型**（Core RBAC → Hierarchical RBAC → Constrained RBAC）
- **OWASP Authorization Cheat Sheet**
- **Google Zanzibar** 啟發的 ReBAC 關係圖模型
- **Open Policy Agent (OPA)** / **Cerbos** 作為外部策略引擎
- **SCIM 2.0** 身份佈建與角色同步

### 輸出範本：角色定義卡片
```json
{
  "id": "finance:invoice-approver:l2",
  "displayName": "財務發票二級審批員",
  "layer": "L2-Functional",
  "inheritsFrom": ["core:employee"],
  "permissions": [
    "invoice:read:department",
    "invoice:approve:amount_lt_100k"
  ],
  "constraints": [
    {"type": "separation_of_duties", "conflictsWith": ["finance:invoice-submitter"]},
    {"type": "time_bound", "maxDuration": "P90D"}
  ],
  "lifecycle": {"status": "active", "deprecatedAt": null}
}
```