template-monorepo/internal/model/permission/SDD.md

# Permission Service

# Permission Service — SRS/SDD Document

| Version | Version Date | Editor | Memo |
|---------|--------------|--------|------|
| 1.0.0 | 2026/05/21 | Gateway Team | 初版：Gateway Permission 模組 SDD（對齊 frontend Permission Service SDD 格式） |
| 1.1.0 | — | — | 新增 category 樹狀 Permission Catalog |
| 1.2.0 | — | — | 多租戶 B2B RBAC + Casbin + RoleMapping |

---

## 1. Introduction

### 1.1 Purpose

Permission 模組提供 Gateway **多租戶 B2B 自定義 RBAC**：平台級 Permission Catalog + 租戶級 Role / RolePermission / UserRole / RoleMapping，搭配 Casbin enforcer 進行 HTTP path/method 授權，並支援外部 IdP（ZITADEL / LDAP / SCIM）角色映射同步。

### 1.2 Scope

**範圍內（Multiple tenants）：**

- 平台 Permission Catalog（樹狀，dot notation）
- 租戶 Role CRUD（含 system role 防呆）
- Role ↔ Permission 多對多（含 parent closure）
- User ↔ Role 多對多（source: manual / zitadel / ldap / scim）
- 外部 group → 內部 Role.Key 映射（RoleMapping）
- Casbin policy 物化（Redis Set）+ 多 pod Pub/Sub reload
- GET /permissions/me 前端選單渲染

**範圍外：**

- JWT 簽發 → Auth 模組
- 會員資料 → Member 模組
- Platform admin bypass → middleware 預檢（保留 audit）

### 1.3 Definitions, Acronyms, and Abbreviation

| 縮寫 | 說明 |
|------|------|
| **RBAC** | Role-Based Access Control |
| **Permission** | 平台級權限節點（可為分類或 leaf API 權限） |
| **Role** | 租戶內角色，`key` 唯一且不可改 |
| **RolePermission** | Role 勾選的 Permission 集合 |
| **UserRole** | 使用者被指派的角色 |
| **RoleMapping** | 外部 IdP group/role → 內部 Role.Key |
| **Casbin** | 授權引擎，policy 存 Redis |
| **Leaf Permission** | 有 http_path + http_methods 的可 enforcement 節點 |

### 1.4 Technologies to be used

| 項目 | 技術 |
|------|------|
| Application Language | Go 1.22+ |
| Framework | go-zero |
| Cache / Policy Store | Redis（Casbin rules Set + Pub/Sub） |
| Database | MongoDB |
| Authorization Engine | Casbin（`keyMatch2` + `regexMatch`） |
| API Codegen | goctl / `.api` 檔 |

### 1.5 Overview

```mermaid
flowchart LR
    subgraph Platform["平台層"]
      Catalog[Permission Catalog]
    end
    subgraph Tenant["租戶層"]
      Role[Role]
      RP[RolePermission]
      UR[UserRole]
      RM[RoleMapping]
    end
    Catalog --> RP --> Role
    Role --> UR
    Role --> RM
    Tenant --> Casbin[(Casbin Enforcer<br/>Redis adapter)]
    Casbin --> MW[CasbinRBAC Middleware]
```

- Permission **平台 seed 全局**，租戶不可新增，只能勾選
- Role / RolePermission / UserRole **租戶獨立**
- Role.Key 一旦建立 **不可改**（外部 IdP 對應用）
- 多 pod 同步：**Redis Pub/Sub 即時 + cron 兜底**

---

## 2. System Overview

Permission 模組是 Gateway 授權子系統：

1. 平台維護 Permission Catalog（`cmd/permission-seed`）
2. 租戶管理員建立 Role、勾選 Permission
3. 指派 UserRole（手動或 SyncFromX 同步）
4. RBACUseCase 物化 Casbin policy → middleware 檢查 `(tenant, role.key, path, method)`

前端透過 `GET /permissions/me` 取得當前使用者的 role keys 與 permission map（含可選 tree）。

---

## 3. System Architecture

### 3.1 System Architecture

```mermaid
flowchart TD
    Logic[logic/permission] --> SVC[svc.ServiceContext]
    SVC --> AuthQ[AuthorizationQueryUseCase]
    SVC --> Perm[PermissionUseCase]
    SVC --> Role[RoleUseCase]
    SVC --> RolePerm[RolePermissionUseCase]
    SVC --> UserRole[UserRoleUseCase]
    SVC --> Mapping[RoleMappingUseCase]
    SVC --> RBAC[RBACUseCase]

    RBAC --> Adapter[Casbin Redis Adapter]
    Adapter --> Redis[(Redis)]
    RBAC --> Pub[Redis Pub/Sub casbin:reload]

    Perm --> PermR[(permissions)]
    Role --> RoleR[(roles)]
    RolePerm --> RPR[(role_permissions)]
    UserRole --> URR[(user_roles)]
    Mapping --> RMR[(role_mappings)]
```

### 3.2 Decomposition Description

| 套件 | 職責 |
|------|------|
| `config/` | CasbinConfig、CacheConfig、ReloadConfig |
| `domain/entity/` | Permission、Role、RolePermission、UserRole、RoleMapping |
| `domain/enum/` | Status、PermissionType、RoleSource |
| `domain/repository/` | 5 個 Mongo repo 介面 + Casbin adapter port |
| `domain/usecase/` | 7 個 usecase 介面 + DTO |
| `repository/` | Mongo + Redis Casbin adapter |
| `usecase/` | 7 個 atomic usecase 實作 + permission_tree |
| `seed/` | catalog.json + Apply CLI |

### 3.3 RBAC Model

Casbin 模型（`etc/rbac.conf`）：

```ini
[request_definition]
r = tenant, role, path, method

[policy_definition]
p = tenant, role, path, methods, name

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

[matchers]
m = r.tenant == p.tenant && r.role == p.role && keyMatch2(r.path, p.path) && regexMatch(r.method, p.methods)
```

**授權檢查（any-allow）：** 使用者所有 open role 逐一 EnforceEx，任一 allow 即通過。

```mermaid
sequenceDiagram
    participant MW as CasbinRBAC Middleware
    participant RBAC as RBACUseCase
    participant URR as UserRoleRepository
    participant Enf as casbin.Enforcer

    MW->>RBAC: Check{tenant, uid, path, method}
    RBAC->>URR: ListByUser
    loop each open role
        RBAC->>Enf: EnforceEx(tenant, role.key, path, method)
        alt allow
            RBAC-->>MW: Allow
        end
    end
    RBAC-->>MW: Deny → 403
```

### 3.4 Permission Tree

```
member.info.management            ← 分類（無 HTTP）
├── member.basic.info
│   ├── member.info.select        GET   /api/v1/members/me
│   └── member.info.update        PATCH /api/v1/members/me
└── member.admin.list             GET   /api/v1/members

permission.role.management
├── permission.role.read          GET    /api/v1/permissions/roles
└── permission.role.write         POST/PUT/DELETE /api/v1/permissions/roles*
```

分類節點（無 `http_path`）不寫入 Casbin policy；Replace RolePermission 時自動補齊 parent closure。

### 3.5 Policy Reload（多 Pod）

```mermaid
sequenceDiagram
    participant PodA as Pod A
    participant Redis
    participant PodB as Pod B

    PodA->>PodA: RolePermission.Replace + LoadPolicy
    PodA->>Redis: PUBLISH casbin:reload {tenant_id}
    Redis-->>PodB: message
    PodB->>PodB: LoadPolicy(tenant)
```

---

## 4. Data Design

### 4.1 Data Dictionary

#### permissions（MongoDB — 平台全局）

| Field | Type | Comment | Index |
|-------|------|---------|-------|
| _id | ObjectId | PK | PK |
| parent | String | 父節點 ObjectId hex | parent |
| name | String | dot notation 唯一名稱 | Unique |
| http_methods | String | GET 或 GET\|POST\|PATCH | — |
| http_path | String | keyMatch2 path pattern | — |
| status | String | open / close | status |
| type | String | backend_user / frontend_user | type |
| create_at | Int64 | 建立時間 ms | — |
| update_at | Int64 | 更新時間 ms | — |

#### roles（MongoDB — 租戶範圍）

| Field | Type | Comment | Index |
|-------|------|---------|-------|
| _id | ObjectId | PK | PK |
| tenant_id | String | 租戶 ID | Unique(tenant_id, key) |
| key | String | 角色 key（不可改） | Unique(tenant_id, key) |
| display_name | String | 顯示名稱 | — |
| creator_uid | String | 建立者 UID | — |
| status | String | open / close | (tenant_id, is_system) |
| is_system | Bool | 平台預設角色 | (tenant_id, is_system) |
| create_at | Int64 | 建立時間 ms | — |
| update_at | Int64 | 更新時間 ms | — |

#### role_permissions（MongoDB）

| Field | Type | Comment | Index |
|-------|------|---------|-------|
| _id | ObjectId | PK | PK |
| tenant_id | String | 租戶 ID | Unique(tenant_id, role_id, permission_id) |
| role_id | String | Role ObjectId hex | (tenant_id, role_id) |
| permission_id | String | Permission ObjectId hex | (tenant_id, permission_id) |
| create_at | Int64 | 建立時間 ms | — |

#### user_roles（MongoDB）

| Field | Type | Comment | Index |
|-------|------|---------|-------|
| _id | ObjectId | PK | PK |
| tenant_id | String | 租戶 ID | Unique(tenant_id, uid, role_id) |
| uid | String | 會員 UID | (tenant_id, uid, source) |
| role_id | String | Role ObjectId hex | (tenant_id, role_id) |
| source | String | manual / zitadel / ldap / scim | (tenant_id, uid, source) |
| create_at | Int64 | 建立時間 ms | — |

#### role_mappings（MongoDB）

| Field | Type | Comment | Index |
|-------|------|---------|-------|
| _id | ObjectId | PK | PK |
| tenant_id | String | 租戶 ID | Unique(tenant_id, external_source, external_key) |
| external_source | String | zitadel / ldap / scim | Unique(tenant_id, external_source, external_key) |
| external_key | String | 外部 group/role key | Unique(tenant_id, external_source, external_key) |
| internal_role_id | String | 內部 Role ID | (tenant_id, internal_role_id) |
| create_at | Int64 | 建立時間 ms | — |
| update_at | Int64 | 更新時間 ms | — |

#### Redis Keys

| Key Pattern | 內容 | TTL |
|-------------|------|-----|
| permission:casbin:rules:{tenant_id} | Set of JSON Casbin rules | 永久 |
| perm:user_roles:{tenant_id}:{uid} | role keys 快取（預留） | 300s |
| perm:role_perms:{tenant_id}:{role_id} | permission names 快取（預留） | 300s |
| (channel) casbin:reload | Pub/Sub reload payload | — |

**Casbin rule 格式：** `[tenant, role.key, http_path, http_methods, perm.name]`

---

## 5. API Design

**Base Path：** `/api/v1/permissions`

| Method | Path | 說明 |
|--------|------|------|
| GET | `/catalog` | 全局 Permission Catalog（tree/list） |
| GET | `/me` | 當前 user 的 roles + permissions |
| GET | `/roles` | 租戶角色清單 |
| POST | `/roles` | 建立角色 |
| PATCH | `/roles/:id` | 更新 display_name / status |
| DELETE | `/roles/:id` | 刪除角色 |
| GET | `/roles/:id/permissions` | 角色 permission 集合 |
| PUT | `/roles/:id/permissions` | 全量取代 + parent closure + reload |
| GET | `/users/:uid/roles` | 使用者 role 列表 |
| POST | `/users/:uid/roles` | 指派角色 |
| DELETE | `/users/:uid/roles/:role_id` | 撤銷角色 |
| GET | `/role-mappings` | 外部映射列表 |
| PUT | `/role-mappings` | Upsert 外部映射 |
| DELETE | `/role-mappings` | 刪除外部映射 |
| POST | `/policy/reload` | 強制重載 policy（單租戶或 `*`） |

完整 schema 見 `generate/api/permission.api`。

---

## 6. Resource

| 資源 | 路徑 |
|------|------|
| API 定義 | `generate/api/permission.api` |
| Logic | `internal/logic/permission/` |
| Middleware | `internal/middleware/casbin_rbac.go` |
| 模組原始碼 | `internal/model/permission/` |
| 開發 README | `internal/model/permission/README.md` |
| Casbin 模型 | `etc/rbac.conf` |
| Seed 資料 | `internal/model/permission/seed/catalog.json` |
| Seed CLI | `cmd/permission-seed` |
| 設定範例 | `etc/gateway.dev.example.yaml` → `Permission` 區塊 |
| 設計參考 | `docs/identity-member-design.md` §6 / §7.3 / §13 |