backend/pkg/permission/README.md

# Permission 權限管理模組 - Casbin 版

一個基於 **Casbin** 的現代化權限管理模組，完全整合你的專案技術棧，提供強大且靈活的 RBAC 權限控制。

## 🎯 為什麼選擇 Casbin？

你說得完全對！與其重新發明一個功能精簡的權限系統，**Casbin** 提供了：

### ✅ **社群驗證的成熟解決方案**
- 🌟 **6.7k+ GitHub Stars**，經過大量生產環境驗證
- 🔧 **功能完整**：支援 RBAC、ABAC、RESTful、通配符、正則表達式
- 📚 **文檔完善**：豐富的範例和最佳實踐
- 🛠️ **持續維護**：活躍的社群支持和定期更新

### ✅ **強大的功能特性**
- **通配符支援**: `/api/users/*` 一個規則覆蓋所有子路徑
- **正則表達式**: 靈活的權限匹配規則
- **角色繼承**: 複雜的組織架構支援
- **多種模型**: RBAC、ABAC、RESTful 等
- **策略持久化**: 自動保存到你的 MongoDB

## 📁 目錄結構

```
pkg/permission/
├── config/                    # Casbin 模型配置
│   └── rbac_model.conf       # RBAC 權限模型
├── domain/                    # 領域層
│   ├── entity/               # 實體定義
│   ├── repository/           # 倉庫介面
│   ├── usecase/              # 用例介面 (Casbin 增強)
│   └── config/               # 配置定義
├── repository/               # 倉庫實現
│   ├── casbin_adapter.go     # Casbin MongoDB 適配器
│   ├── client.go            # 客戶端管理
│   ├── role.go              # 角色管理
│   └── ...                  # 其他倉庫
├── usecase/                  # 用例實現 (Casbin API)
├── svc/                      # 初始化層
├── example/                  # Casbin 使用範例
└── README.md                 # 本文件
```

## 🚀 核心優勢

### **🔥 Casbin 強化功能**
- **通配符權限**: `GET /api/users/*` 覆蓋所有用戶子路徑
- **正則表達式**: `GET /api/users/\d+` 只允許數字 ID
- **角色繼承**: `admin` 繼承 `user` 的所有權限
- **策略分離**: 權限策略與業務邏輯完全分離
- **動態更新**: 運行時動態添加/移除權限，無需重啟

### **⚡ 技術整合**
- **MongoDB 適配器**: 策略自動持久化到你的 MongoDB
- **你的錯誤系統**: 完整的 `@errs/` 整合
- **緩存支援**: 使用你現有的 Redis 緩存
- **go-zero 整合**: 無縫整合到你的服務架構

## 🔧 Casbin 模型

```ini
# pkg/permission/config/rbac_model.conf
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && regexMatch(r.act, p.act)
```

這個模型支援：
- **keyMatch2**: 通配符匹配 (`/api/users/*`)
- **regexMatch**: 正則表達式匹配
- **角色繼承**: `g(user, role)` 關係

## 📦 快速整合

### 1. 在你的 ServiceContext 中添加

```go
// internal/svc/service_context.go
import "backend/pkg/permission/svc"

type ServiceContext struct {
    Config         config.Config
    AuthMiddleware rest.Middleware
    AccountUC      usecase.AccountUseCase
    PermissionUC   permission.PermissionUseCase  // ← Casbin 增強
    AuthUC         permission.AuthUseCase        
    RoleUC         permission.RoleUseCase        
    Validate       vi.Validate
}

func NewServiceContext(c config.Config) *ServiceContext {
    rds, err := redis.NewRedis(c.RedisConf)
    if err != nil {
        panic(err)
    }

    return &ServiceContext{
        Config:         c,
        AuthMiddleware: middleware.NewAuthMiddleware().Handle,
        AccountUC:      NewAccountUC(&c, rds),
        PermissionUC:   svc.NewPermissionUC(&c, rds),  // ← Casbin 自動初始化
        AuthUC:         svc.NewAuthUC(&c, rds),        
        RoleUC:         svc.NewRoleUC(&c),             
        Validate:       vi.MustValidator(),
    }
}
```

### 2. Casbin 強大功能使用

```go
// 🔥 通配符權限 - 一個規則覆蓋所有子路徑
err = permissionUC.AddPermissionForRole(ctx, "admin", "/api/users/*", ".*")

// ✅ 這些都會被允許:
// GET /api/users/123
// POST /api/users/123/profile  
// DELETE /api/users/123/avatar

// 🔥 正則表達式權限 - 精確控制
err = permissionUC.AddPermissionForRole(ctx, "viewer", "/api/users/\\d+", "GET")

// ✅ 只允許: GET /api/users/123 (數字ID)
// ❌ 拒絕: GET /api/users/abc (非數字ID)

// 🔥 角色繼承 - 組織架構支援
err = permissionUC.AddRoleForUser(ctx, "john", "admin")
err = permissionUC.AddRoleInheritance(ctx, "admin", "user")

// john 自動擁有 admin 和 user 的所有權限

// 🔥 動態權限檢查
hasPermission, err := permissionUC.CheckUserPermission(ctx, "john", "GET", "/api/users/123")
hasPattern, err := permissionUC.CheckPatternPermission(ctx, "john", "/api/users/456", "DELETE")
```

## 🎯 實際使用場景

### **API 權限控制**
```go
// 中間件中使用
func PermissionMiddleware(permissionUC permission.PermissionUseCase) rest.Middleware {
    return func(next http.HandlerFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, r *http.Request) {
            userID := getUserIDFromJWT(r)
            
            // Casbin 自動處理通配符和正則表達式
            hasPermission, err := permissionUC.CheckUserPermission(
                r.Context(), userID, r.Method, r.URL.Path,
            )
            
            if err != nil || !hasPermission {
                httpx.WriteJsonCtx(r.Context(), w, 403, types.ErrorResp{
                    Code: 4030001,
                    Msg:  "權限不足",
                })
                return
            }
            
            next(w, r)
        }
    }
}
```

### **權限初始化**
```go
// 初始化基礎權限
func InitPermissions(ctx context.Context, permissionUC permission.PermissionUseCase) {
    // 🔥 管理員擁有所有 API 權限
    permissionUC.AddPermissionForRole(ctx, "admin", "/api/*", ".*")
    
    // 🔥 用戶只能查看和更新自己的資料
    permissionUC.AddPermissionForRole(ctx, "user", "/api/users/{{.UserID}}", "GET|PUT")
    
    // 🔥 訪客只能查看公開內容
    permissionUC.AddPermissionForRole(ctx, "guest", "/api/public/*", "GET")
}
```

## 📊 Casbin 策略儲存

### **MongoDB 自動持久化**
```javascript
// casbin_rules collection
{
  _id: ObjectId,
  ptype: "p",                    // 策略類型
  v0: "role_admin_001",          // 主體 (用戶/角色)
  v1: "/api/users/*",            // 對象 (資源)
  v2: ".*",                      // 行為 (動作)
  v3: "",                        // 擴展字段
  v4: "",                        // 擴展字段
  v5: ""                         // 擴展字段
}

// 角色關係
{
  ptype: "g",                    // 分組策略
  v0: "user_001",                // 用戶
  v1: "role_admin_001",          // 角色
  v2: "",
  ...
}
```

### **索引優化**
```javascript
// 自動創建的索引
db.casbin_rules.createIndex({"ptype": 1})
db.casbin_rules.createIndex({"ptype": 1, "v0": 1})
db.casbin_rules.createIndex({"ptype": 1, "v0": 1, "v1": 1})
```

## 🔥 Casbin vs 自建系統

| 功能 | 自建系統 | Casbin |
|-----|---------|--------|
| **通配符支援** | ❌ 需要自己實現 | ✅ 內建支援 `/api/users/*` |
| **正則表達式** | ❌ 需要自己實現 | ✅ 內建支援 `/api/users/\\d+` |
| **角色繼承** | ❌ 需要複雜邏輯 | ✅ 自動處理繼承鏈 |
| **策略語言** | ❌ 硬編碼邏輯 | ✅ 靈活的 DSL |
| **性能優化** | ❌ 需要自己優化 | ✅ 內建緩存和索引 |
| **社群支持** | ❌ 需要自己維護 | ✅ 活躍社群，持續更新 |
| **文檔和範例** | ❌ 需要自己寫文檔 | ✅ 豐富的官方文檔 |
| **測試覆蓋** | ❌ 需要自己測試 | ✅ 大量生產環境驗證 |

## 🚀 進階功能

### **ABAC 屬性權限**
```go
// 未來可以升級到 ABAC 模型
// 支援基於用戶屬性、資源屬性、環境屬性的權限控制
permissionUC.CheckPermissionWithAttributes(ctx, 
    map[string]interface{}{
        "user.department": "engineering",
        "resource.owner": "john",
        "time.hour": 9,
    })
```

### **策略管理 API**
```go
// 動態管理策略
policies, err := permissionUC.GetAllPolicies(ctx)
filtered, err := permissionUC.GetFilteredPolicies(ctx, 0, "role_admin")
```

## 🎯 遷移優勢

1. **立即獲得成熟功能** - 通配符、正則表達式、角色繼承
2. **減少維護成本** - 社群維護，無需自己投入開發時間  
3. **擴展性更強** - 支援複雜的權限模型，適應業務成長
4. **性能更好** - 內建優化，大量生產環境驗證
5. **學習成本低** - 豐富的文檔和社群範例

## 🔧 立即使用

```go
// 1. 初始化 (自動設置 Casbin)
PermissionUC: svc.NewPermissionUC(&c, rds),

// 2. 添加權限策略
permissionUC.AddPermissionForRole(ctx, "admin", "/api/users/*", ".*")

// 3. 分配角色
permissionUC.AddRoleForUser(ctx, "john", "admin")

// 4. 檢查權限 (自動處理通配符)
hasPermission, err := permissionUC.CheckUserPermission(ctx, "john", "GET", "/api/users/123")
```

現在你擁有了一個**功能完整、社群驗證、持續維護**的權限系統！🎯

**Casbin** 讓你專注於業務邏輯，而不是重新發明權限輪子。